Conjur Follower inside OpenShift/Kubernetes cluster

This topic describes how to set up a Conjur Follower inside your OpenShift/Kubernetes cluster using JWT-based or certificate(cert)-based authentication.

 
  • For all the options for deploying Followers inside OpenShift/Kubernetes cluster, see Deploy Follower for OpenShift/Kubernetes integration.

  • This procedure involves tasks for both the Conjur admin and the Kubernetes cluster admin. Make sure that both persona are available when performing these tasks.

  • Unless specifically noted otherwise, all references to Kubernetes apply to native Kubernetes as well as RedHat OpenShift (using JWT-based authentication only), GKE, and other supported Kubernetes-based implementations.

  • When using JWT-based authentication, note that all references to the Kubernetes namespaces intentionally include the OpenShift concept of project.

  • Followers for OpenShift/ Kubernetes integrations do not support data segregation per Follower.

Deploy the Follower

The environment is now ready for the app owner to set up applications to retrieve secrets from Conjur. For more information, see Set up workloads (JWT-based authentication).

Customize Conjur Follower in Kubernetes DNS name

If your Conjur Follower DNS name does not follow the default format of $FOLLOWER_HOSTNAME.$MY_POD_NAMESPACE.svc.cluster.local, you can use additional variables in the manifest to customize it. You must ensure that the Conjur Follower DNS name is correctly configured so that Conjur can identify the corresponding TLS certificate.

Use only one of the options from the following table to configure your Conjur Follower DNS name.

Variables to customize Conjur Follower domain name

Variable

Details

K8S_DNS_SUFFIX

Replaces the default suffix added to internal Kubernetes URLs. Add this variable to the manifest if the Conjur Follower URL ends with a suffix other than svc.cluster.local and set its value to the correct suffix. Do not remove any variables from the manifest when using this option.

FOLLOWER_FQDN

Replaces the entire fully qualified domain name  (FQDN) of the Conjur Follower, including the hostname and suffix. Add this variable to the manifest only if the Conjur Follower DNS name is not in the format $FOLLOWER_HOSTNAME.$POD_NAMESPACE.$K8S_DNS_SUFFIX.

If you add the FOLLOWER_FQDN variable:

  • Remove the FOLLOWER_HOSTNAME and K8S_DNS_SUFFIX variables from the manifest.

  • Keep the MY_POD_NAMESPACE variable in the manifest, even if it does not correspond with the FOLLOWER_FQDN value. The MY_POD_NAMESPACE variable is necessary for the configuration.

The environment is now ready for the app owner to set up applications to retrieve secrets from Conjur. For more information, see Set up workloads (cert-based authentication).

Troubleshoot the deployment

When deployed, a Conjur Follower Pod self-initializes from the Leader, a process that takes upwards of 30 seconds depending on processor speed and the amount of CPU resources specified in the manifest. The Readiness probe shows that the Pod is ready once initialization completes.

If the Conjur Follower shows errors or fails to start, start from the Pod and work backwards to the Leader, checking the following:

  • On the Conjur Follower configuration host:

    Check

    Description

    kubectl get events -n cyberark-conjur

    Ensure that the seed-fetcher init container started without errors. Image pull errors are common.

    Check the image name spelling in the manifest and ensure the image was pushed to the registry and referenced correctly.

    Ensure the user deploying the Conjur Follower has correct privileges to and can log in to the registry.

    kubectl logs <follower-pod-name> -c authenticator -n cyberark-conjur

    Ensure that the seed-fetcher started and authenticates successfully.

    Master key encryption errors

    When master key encryption is used, the Conjur Follower deployment may fail silently. To add entries for master key encryption failures to the log, add the SEEDFETCHER_DEBUG_MKE variable with a value of true to the conjur-appliance container in the manifest:

    containers:
          - name: conjur-appliance
            image: mycorp-registry/conjur-appliance:version
            command: ["/tmp/seedfile/start-follower.sh"]
            imagePullPolicy: Always
            env:
              - name: SEEDFILE_DIR
                value: /tmp/seedfile
              - name: CONJUR_AUTHENTICATORS
                value: authn-k8s/dev-cluster
              - name: SEEDFETCHER_DEBUG_MKE
                value: true 
  • On the Leader host:

    Check

    Description

    docker logs <MASTER_CONTAINER_NAME> --since 1m

    Display last minute’s worth of the Leader log to trace seed-fetcher authentication messages in the Leader log.

    Ensure that authentication requests appear in the log. If not, check possible network connection issue (firewall, security groups, etc.) or certificate validation failure.

    docker exec -it <MASTER_CONTAINER_NAME> evoke variable list CONJUR_AUTHENTICATORS

    Ensure authn-k8s/<SERVICE_ID>is present in list and spelled correctly, for example: authn-k8s/dev-cluster>