Application Requirements

This topic describes step-by-step how to enable applications in a Kubernetes environment. It is important to complete each step in the order they are described.

Integrate the Kubernetes authenticator client

To enable an application to authenticate with Conjur, the application manifest must be modified to include:

  • The Kubernetes Authenticator Client as either a sidecar or init container

  • A volume mounted to both containers to share the Conjur authentication token

  • Application environment variables containing connection information for the Conjur appliance

  • Configure the authenticator client container and add the container name to policy

Create service account for your app

If you are using service accounts to authenticate and you have not created one yet, you will need to do so now. The following example assumes that you are using test-app as the name for your service account.

 
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: test-app

Make sure that this service account name matches both policy for authenticator identities in Conjur as well as manifests below wherever < APP_SERVICE_ACCOUNT_NAME > is used.

Add the authenticator image

The Authenticator Client is a public image available on DockerHub . It can be added to the manifest as either a sidecar or init container.

To use the authenticator as a sidecar, insert its image spec alongside the application container image spec. See the Sidecar application manifest example .

To use an init container, insert the authenticator spec under the initContainers property of the pod spec. See the Init container application manifest example . The authenticator client must be configured with the following variables:

Paremeter

Description

CONTAINER_MODE

Specify whether a sidecar or init container is used for the authenticator client. The value is sidecar or init. If this variable is not set, the mode defaults to sidecar.

MY_POD_NAME

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated fron the app container info.

MY_POD_NAMESPACE

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated fron the app container info.

MY_POD_IP

This variable identifies the pod where your application runs. Use the Downward API to insert this information into the manifest. In the example manifests, this value is auto-populated fron the app container info.

CONJUR_VERSION

The Conjur release number. This currently is either 5 or 4.

CONJUR_AUTHN_URL

Specify the credential service used to log into Conjur. For Conjur v4 use https://conjur-follower.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/api/authn-k8s/<AUTHENTICATOR_ID> and for Conjur v5 use https://conjur-follower.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>. If you have deployed Conjur OSS version through the Helm chart or GKE marketplace app, change conjur-follower in these examples to the name of the service (eg. https://conjur-open-source-k8s-conjur-oss.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>)

CONJUR_ACCOUNT

The account name designated to the Conjur appliance during initial configuration. You most likely set this environment variable before running the deployment scripts. If so, you can use $CONJUR_ACCOUNT for the value here. In most default installations, this account name is default but your configuration may vary.

CONJUR_AUTHN_LOGIN

Specify the Conjur host (Kubernetes resource) that authenticates to Conjur. Set this value to a host id that is defined in policy. See Machine Identity for the host id syntax and the list of Kubernetes resources that can be declared as hosts.

CONJUR_SSL_CERTIFICATE

The public SSL certificate value required for connecting to the Conjur follower service. We recommend using a ConfigMap to store the value.

The SSL certificate is generated during Conjur appliance configuration and stored in a .pem file located in the root folder where Conjur was created. The file name is conjur-account.pem, where account is the account name provided for the Conjur appliance.

For example, use:

 
kubectl create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The equivalent OpenShift command is:

 
oc create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The above commands create a ConfigMap that loads the certificate value into it:

 
configMapKeyRef:
    name: conjur-cert        #ConfigMap name
    key: ssl_certificate  #the key into the ConfigMap

Add a shared volume

The authenticator uses a volume shared with the application container to provide a token to authenticate with Conjur and retrieve secrets. The application manifest should define a memory-only volume and then mount it to /run/conjur on both the application and authenticator containers.

Add Conjur connection information

The application must be configured with environment variables that contain connection information for the Conjur appliance. Add the following variables to the application environment:

Paremeter

Description

CONJUR_VERSION

The Conjur release number. This currently is either 5 or 4.

CONJUR_AUTHN_URL

Specify the credential service used to log into Conjur. For Conjur v4 use https://conjur-follower.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/api/authn-k8s/<AUTHENTICATOR_ID> and for Conjur v5 use https://conjur-follower.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>. If you have deployed Conjur OSS version through the Helm chart or GKE marketplace app, change conjur-follower in these examples to the name of the service (eg. https://conjur-open-source-k8s-conjur-oss.<CONJUR_NAMESPACE_NAME>.svc.cluster.local/authn-k8s/<AUTHENTICATOR_ID>)

CONJUR_ACCOUNT

The account name designated to the Conjur appliance during initial configuration. You most likely set this environment variable before running the deployment scripts. If so, you can use $CONJUR_ACCOUNT for the value here. In most default installations, this account name is default but your configuration may vary.

CONJUR_AUTHN_TOKEN_FILE

Identifies the complete path and filename where the authentication container should write the Conjur access token that it obtains on behalf of the application.

CONJUR_SSL_CERTIFICATE

The public SSL certificate value required for connecting to the Conjur follower service. We recommend using a ConfigMap to store the value.

The SSL certificate is generated during Conjur appliance configuration and stored in a .pem file located in the root folder where Conjur was created. The file name is conjur-account.pem, where account is the account name provided for the Conjur appliance.

For example, use:

 
kubectl create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The equivalent OpenShift command is:

 
oc create configmap conjur-cert --from-file=ssl-certificate="/path/to/ssl/cert"

The above commands create a ConfigMap that loads the certificate value into it:

 
configMapKeyRef:
    name: conjur-cert        #ConfigMap name
    key: ssl_certificate  #the key into the ConfigMap

Configure the authenticator client container name

 

In pre-v5.2.4 deployments, the container name must be the value authenticator. Starting with v5.2.4, there are no restrictions on the authenticator client container name.

Assign the authenticator client container name in the application manifest, in the -image section for the authenticator client. Here is the relevant section in the manifest:

 
- image: cyberark/conjur-kubernetes-authenticator
        imagePullPolicy: Always
        name: <AUTHENTICATOR_CLIENT_CONTAINER_NAME>

The container name that you assign here must be added into Conjur policy. It must be referenced in the annotation associated with the whitelist of applications that can authenticate to Conjur. See Policy for authentication identities. Here is the relevant section in the policy.

 
 - !host
     id: <TEST_APP_NAMESPACE_NAME>/*/*
     annotations:
       kubernetes/authentication-container-name: <AUTHENTICATOR_CLIENT_CONTAINER_NAME>

Define application policy

Use a Conjur policy to define the following:

  • An identity for our application linked to the authentication identities we defined in Policy for authentication identities

  • Variables to hold the secrets for our application that can be written to by at least one human user and read by our application identity

Prepare applications to retrieve secrets

Use either the Conjur API or Summon to enable applications to retrieve secrets from Conjur.

Load initial secret values into Conjur

For each secret defined in an application policy, load the initial secret value. You can use the Conjur API, the UI, or the CLI for this step.

This is an example using the CLI:

 
$ conjur variable value cluster-1/db/password abc$xyz

Start the application

To start the application, use this Kubernetes command:

 
kubectl create -f your-manifest.yaml

The equivalent OpenShift command is:

 
oc create -f your-manifest.yaml
 
10.5