Deploy Conjur Kubernetes Follower

The Conjur Kubernetes Follower is designed for deployment inside your OpenShift/Kubernetes cluster. This topic describes how to deploy the Conjur Kubernetes Follower inside your cluster.

A Follower is a read only replica of the Leader. Followers are horizontally-scaling components that are typically configured behind a load balancer to handle all types of read requests, including authentication, permission checks, and secret fetches.

The Conjur Kubernetes Follower is specifically designed for deployment inside an OpenShift/Kubernetes cluster. It is unique in that it is a collection of microservices that run as separate containers as unprivileged (non-root) users within a Pod and, together, provide a scalable way to access the secrets stored in Conjur. For more information about the Conjur Kubernetes Follower and its architecture, see Conjur Kubernetes Follower.

Setup flow

1. Install the Follower Operator

   This is done only once per Conjur version. When a new version of Conjur is released, the corresponding Follower Operator must be installed.

2. Deploy the Conjur Kubernetes Follower

Step 1: Install the Follower Operator

The Conjur Follower Operator adds a ConjurFollower custom resource definition to your Kubernetes cluster. This resource enables deployment of the Conjur Kubernetes Follower inside your OpenShift/Kubernetes cluster.

In addition, the Conjur Follower Operator manages the lifecycle of the ConjurFollower Deployment created in the Kubernetes API. When a ConjurFollower custom resource is created, updated, or deleted, the Operator reconciles these changes in the ConjurFollower Deployment in Kubernetes.

To install the Conjur Follower Operator:

Step 2: Deploy the Conjur Kubernetes Follower

This section describes how to deploy the Conjur Kubernetes Follower inside the Kubernetes cluster.

1. Before you begin

   Make sure that you have the following:

   Conjur admin

   A Kubernetes Authenticator or JWT Authenticator must be configured and enabled (allowlisted) in Conjur. For details, see: JWT-based Kubernetes authentication Certificate-based Kubernetes authentication A certificate for the Conjur Kubernetes Follower.   If you are using self-signed certificates, the seed generation webservice generates this certificate. If you are using certificates signed by a third party, a Follower certificate with a subject name matching the FQDN of the service in Kubernetes (for example <service>.<namespace>.svc.cluster.local) needs to be loaded on the Leader. If such a certificate has not been loaded into the Leader, the Follower will fail to start successfully. This is because Conjur is not able to generate a valid certificate for the Follower when the Follower starts. For more information, contact CyberArk Customer Support

   Kubernetes cluster admin

   The Conjur Follower Operator must be installed in your Kubernetes cluster. See Install the Follower Operator. Access to the kubectl CLI (or oc for OpenShift). Access to a running Conjur cluster. If your Conjur cluster deployment uses a load balancer, you need access to the load balancer.

2. Define an identity in Conjur for the Conjur Kubernetes Follower

   Conjur admin: To enable the Conjur Kubernetes Follower to connect to Conjur, it first needs to authenticate to Conjur.

   1. In this step, you give the Conjur Kubernetes Follower an identity in Conjur using policy.

      Save the following policy as conjur-follower-host.yaml:

      • JWT-based authn
      • Cert-based authn

      The policy:

      • Defines the Conjur Kubernetes Follower by its namespace, cyberark-conjur and by its service account, conjur-follower.

        These definitions are defined in the host annotations. For guidelines on how to define annotations, see Workload identity for Kubernetes (JWT-based authentication).

      • Gives the Conjur Kubernetes Follower permission to authenticate to Conjur and to use the seed service using the dev-cluster JWT Authenticator.

      - !host
          id: system:serviceaccount:cyberark-conjur:conjur-follower
          annotations:
            authn-jwt/dev-cluster/kubernetes.io/namespace: cyberark-conjur
            authn-jwt/dev-cluster/kubernetes.io/serviceaccount/name: conjur-follower
      
      - !grant
        roles:
        - !group conjur/authn-jwt/dev-cluster/apps
        - !group conjur/seed-generation/consumers
        members:
        - !host system:serviceaccount:cyberark-conjur:conjur-follower

      The policy:

      • Defines the Conjur Kubernetes Follower by its namespace, cyberark-conjur, and its authentication container name, configurator.

        The Conjur Kubernetes Follower can also be defined by its service account, conjur-follower.

        These definitions are defined in the host annotations in the policy. For guidelines on how to define annotations, see Workload identity for Kubernetes (cert-based authentication).

      • Gives the Conjur Kubernetes Follower permission to authenticate to Conjur and to use the seed service using the dev-cluster Kubernetes Authenticator.

      - !host
        id: conjur-follower
        annotations:
          authn-k8s/namespace: cyberark-conjur
          authn-k8s/service-account: conjur-follower
          authn-k8s/authentication-container-name: configurator
         
      - !grant
        roles:
        - !group conjur/authn-k8s/dev-cluster/consumers
        - !group conjur/seed-generation/consumers
        members:
        - !host conjur-follower

   2. Load the policy file to root:

      $ conjur policy load -f conjur-ocp-follower.yaml -b root

3. Create a ConfigMap for the Conjur certificate

   You need Kubernetes admin permissions to create a ConfigMap.

   The Conjur Kubernetes Follower connects to the Conjur cluster using a TLS protected connection. This includes verifying the Conjur cluster with a Conjur certificate issued by your organization's Certificate Authority, for example conjur.pem.

   To enable the Conjur Kubernetes Follower to use this certificate, it must be stored in a ConfigMap.

   If you do not have a file containing the Conjur certificate, you can retrieve the Conjur certificate and save it to a file, for example, conjur.pem, with the command:

   openssl s_client -connect $CONJUR_MASTER_HOSTNAME:443 \
     -showcerts </dev/null 2> /dev/null | \
     awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/ {print $0}' \
     > "conjur.pem"

   The following command stores the Conjur certificate, conjur.pem, in the cyberark-conjur namespace in a ConfigMap called conjur-cert:

   kubectl create configmap -n cyberark-conjur conjur-cert \
     --from-file=conjur.pem

4. (OPTIONAL) Create a ConfigMap for the Conjur configuration file

   You need Kubernetes admin permissions to create a ConfigMap.

   If you have a Conjur configuration file (conjur.yml) that you want to apply to the Conjur Kubernetes Follower, you must store it in a Kubernetes ConfigMap or Secret.

   The following command stores the configuration file in the cyberark-conjur namespace, in a ConfigMap called conjur-config:

   kubectl create configmap -n cyberark-conjur conjur-config \
     --from-file=conjur.yml

5. Deploy the Conjur Kubernetes Follower

   In this step, you deploy the Conjur Kubernetes Follower. If you installed the Follower Operator from the OperatorHub in OpenShift, use the OLM method to deploy the Conjur Kubernetes Follower. Otherwise use the manual deployment.

   • Manual
   • OLM (OpenShift only)

   In this step you deploy the Conjur Kubernetes Follower by applying a manifest.

   1. Go to the set of extracted Conjur Kubernetes Follower files (see Prerequisites).

   2. Under samples, open the ConjurFollower manifest, *ConjurFollower.yaml.

   3. Modify the values in the manifest as follows:

      Fields in Conjur Kubernetes Follower spec	Description
      images: (Mandatory)	The paths to the Docker registries containing the Conjur Kubernetes Follower container images.
      master: (Mandatory)	Details about the Conjur cluster. account - The account name used when setting up the Conjur cluster Example: myorg authentication - The type of authentication: For cert-based authn: authn-k8s (default) For JWT-based authn: authn-jwt (mandatory) audience - (JWT-based authn only) The token's audience. This is required only if the JWT Authenticator was defined with an audience variable, and the value must match the value that the variable was populated with, for example https://conjur.host.name/. For details, see Populate the policy variables. Otherwise audience is optional. Corresponds to the aud claim in the JWT. authenticatorID - The service ID of the authenticator Example: dev-cluster authLogin - (Use this for Cert-based authn only. Do not use for JWT-based authn) The name given to the application identity (host) that represents the Conjur Kubernetes Follower in Conjur, including the host/ prefix Example: host/conjur-ocp-follower caCertificateFrom - Under From a ConfigMap enter ConfigMap key and name that you created earlier. Example: key: conjur.pem name: conjur-cert hostname - The Conjur Leader FQDN. If there is a load balancer in front of the Conjur cluster, this is the load balancer FQDN. Example: lb.production.example.com
      configFileFrom: (Optional)	Under From a ConfigMap enter ConfigMap key and name that you created earlier. Example: Key: conjur.yml Name: conjur-config
      replicas: (Mandatory)	The number of Conjur Kubernetes Followers to deploy Default: 1 This value can be updated after initially deploying the Conjur Kubernetes Follower
      resourceNames: (Optional)	Modify the default Kubernetes resource names created for the Conjur Kubernetes Follower. Default value for each of these resources: conjur-follower
      Advanced Configuration (Optional)	Advanced Conjur Kubernetes Follower configuration options: Set up Conjur Kubernetes Follower environment variables Modify the default Conjur Kubernetes Follower container resource limits Determine the Conjur Kubernetes Follower image pull policy

      For example:

      • JWT-based authn
      • Cert-based authn

      apiVersion: conjur.cyberark.com/v1
      kind: ConjurFollower
      metadata:
        name: my-conjur-follower
        namespace: cyberark-conjur
        labels:
          app: conjur-follower
      spec:
        replicas: 1
        master:
          hostname: conjur-master.mycompany.local
          account: demo
          authentication: authn-jwt
          audience: https://conjur.host.name/
          authenticatorID: my-authenticator-id
          caCertificateFrom:
            configMapKeyRef:
              name: conjur-master-ca.crt
              key: ca.crt
        images:
          conjur: cyberark/conjur-kubernetes-follower-conjur
          info: cyberark/conjur-kubernetes-follower-info
          nginx: cyberark/conjur-kubernetes-follower-nginx
          postgres: cyberark/conjur-kubernetes-follower-postgres
          configurator: cyberark/conjur-kubernetes-follower-configurator
          syslogNg: cyberark/conjur-kubernetes-follower-syslog-ng

      apiVersion: conjur.cyberark.com/v1
      kind: ConjurFollower
      metadata:
        name: follower
        namespace: cyberark-conjur
        labels:
          app: conjur-follower
      spec:
        replicas: 1
        master:
          hostname: lb.production.example.com
          account: myorg
          authenticatorID: dev-cluster
          authnLogin: host/conjur-follower
          caCertificateFrom:
            configMapKeyRef:
              name: conjur-cert
              key: conjur.pem
        # optional
        configFileFrom:
          configMapKeyRef:
            name: conjur-config
            key: conjur.yml
        # optional (conjur-follower is the default value for each of these fields)
        resourceNames:
          serviceAccount: conjur-follower
          service: conjur-follower
          deployment: conjur-follower
        images:
          conjur: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/conjur
          info: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/info
          nginx: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/nginx
          postgres: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/postgres
          configurator: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/configurator
          syslogNg: image-registry.openshift-image-registry.svc:5000/cyberark-conjur/syslog-ng

   4. Load the manifest into the cyberark-conjur namespace.

   1. In Red Hat, go to the installed Conjur Follower Operator.

   2. Select the ConjurFollower tab, and click Create Conjur Follower.

   3. Complete the following details in the form—these are marked with a red asterisk (*):

      Field	Description
      Image paths (Mandatory)	The paths to the Docker registries containing the Conjur Kubernetes Follower container images.
      Conjur Cluster Configuration (Mandatory)	Details about the Conjur cluster. Conjur Account - The account name used when setting up the Conjur cluster Example: myorg authentication - The type of authentication: For cert-based authn: authn-k8s (default) For JWT-based authn: authn-jwt (mandatory) audience - (JWT-based authn only) The token's audience. This is required only if the JWT Authenticator was defined with an audience variable, and the value must match the value that the variable was populated with, for example https://conjur.host.name/. For details, see Populate the policy variables. Otherwise audience is optional. Corresponds to the aud claim in the JWT. Authenticator Service ID - The service ID of the authenticator Example: dev-cluster Application Identity - The name given to the application identity (host) that represents the Conjur Kubernetes Follower in Conjur, including the host/ prefix Example: host/conjur-ocp-follower CA Certificate - Under From a ConfigMap enter ConfigMap key and name that you created earlier. Example: Key: conjur.pem Name: conjur-cert Conjur Cluster FQDN - The Conjur Leader FQDN. If there is a load balancer in front of the Conjur cluster, this is the load balancer FQDN. Example: lb.production.example.com
      Conjur Config File (Optional)	Under From a ConfigMap enter ConfigMap key and name that you created earlier. Example: Key: conjur.yml Name: conjur-config
      Replicas (Mandatory)	The number of Conjur Kubernetes Followers to deploy Default: 1 This value can be updated after initially deploying the Conjur Kubernetes Follower
      Advanced Configuration (Optional)	Advanced Conjur Kubernetes Follower configuration options: Set up Conjur Kubernetes Follower environment variables Modify the default Conjur Kubernetes Follower container resource limits Determine the Conjur Kubernetes Follower image pull policy Modify the default Kubernetes resource names created for the Conjur Kubernetes Follower

   4. Click Create.

6. Verify that the Conjur Kubernetes Follower was successfully deployed

   On the Conjur Follower Operator page, check the status of the Conjur Kubernetes Follower you just deployed.

   A healthy Conjur Kubernetes Follower has the status, Ready.

7. (Optional) Update the number of replicated Conjur Kubernetes Follower Pods

   After creating the Conjur Kubernetes Follower, you can update the number of replicas at any time. On the Conjur Follower Operator page, click the Conjur Kubernetes Follower to open the Follower's details and update the Replicas value.

Operator FAQs