Helm Chart for Conjur Kubernetes Cluster Preparation

Helm Chart for Conjur Kubernetes Cluster Preparation

Overview

This Helm chart is used to create per-cluster Kubernetes objects that are necessary to support Conjur Kubernetes authentication on a Kubernetes cluster.

The objects that are created by this Helm chart do not include objects that are required on a per-application-Namespace basis for Conjur Kubernetes authentication support. Those objects are created using a separate application Namespace preparation Helm chart as each Conjur-enabled application is being deployed.

Objects Created

The per-Kubernetes-cluster resources that are created by this Helm chart include:

"Golden" ConfigMap

The Golden ConfigMap keeps a reference copy of Conjur connection/configuration information that can be used later for:
- Running an automated test to validate the configured Conjur connection information by using various openssl and curl commands to check connectivity with the target Conjur instance, verify its SSL certificate, and optionally attempt to authenticate with the Conjur instance.
- Creating Kubernetes objects in application Namespaces as required to support Conjur authentication for applications in those Namespaces. These objects are created via the Application Namespace Preparation Helm chart.
Conjur Authenticator ServiceAccount

This ServiceAccount is used as a Kubernetes identity by the Conjur authenticator plugin (also known as authn-k8s). This identity allows the Conjur Authenticator to authenticate with the Kubernetes API controller, so that it can validate the identity of applications.
A Conjur authenticator ClusterRole

This ClusterRole is used to provide a list of Kubernetes API access permissions that the Conjur authenticator will require in order to validate application identities.

Preparing the Kubernetes Cluster for Conjur Authentication

This workflow is performed once per Conjur instance / per authn-k8s authenticator, typically by a Kubernetes administrator. The steps are as follows:

Gather Conjur configuration information.

Collect the following prerequisite information from your Conjur administrator:
- Conjur appliance URL:
  The URL of the Conjur Enterprise Follower or Conjur OSS server that will be used to authenticate your applications. The Conjur appliance URL could be an address that is either internal or external with respect to the Kubernetes cluster. Examples include:
  - https://conjur.example.com (external address)
  - https://conjur-oss.conjur-oss.svc.cluster.local (internal address)
- Conjur account:
  The conjur account to be used by the authenticator
- Conjur authenticator ID:
  The Conjur authenticator ID that was configured in Conjur security policy in order to enable Kubernetes authentication for the Conjur instance.
- (OPTIONAL) Existing ServiceAccount to reuse for Conjur authentication:
  If a Conjur-related ServiceAccount already exists in the Namespace to which you intend to deploy this Helm chart (for example, if you're using the same Namespace to which Conjur OSS has been deployed, and you'd like to reuse the existing Conjur ServiceAccount), then you have the option of simply reusing that ServiceAccount.
- (OPTIONAL) Existing ClusterRole to reuse for Conjur authentication:
  If a ClusterRole with the appropriate permissions for performing Conjur authentication already exists in the Kubernetes cluster, then you have the option of simply reusing that ClusterRole.

Retrieve the Conjur SSL certificate.

There is a script in the 'bin' directory called 'get-conjur-cert.sh' that can be used to retrieve the certificate of a Conjur appliance based on its URL, and write the certificate to a local file.

This script can also optionally verify the certificate after it has been retrieved by running a curl command to attempt to access the Conjur instance.

This script can be used for Conjur instances that are either internal or external to the Kubernetes cluster.

The syntax for this command is as follows:

./get-conjur-cert.sh -u <Conjur appliance URL> [Options]

Options:
 -d <k8s test deployment name>  Kubernetes deployment name to use for
                                an openssl test pod. This only applies
                                if the '-i' command option is used. This
                                defaults to 'openssl-test'.
 -f <destination filepath>      Destination file for writing certificate.
                                If not set, certificate will be written
                                to 'files/conjur-cert.pem'.
 -h                             Show help
 -i                             Conjur appliance URL is a Kubernetes
                                cluster internal address.
 -u <Conjur appliance URL>      Conjur appliance URL (required)
 -v                             Verify the certificate

For example:

./bin/get-conjur-cert.sh -v -u conjur.conjur-ns.svc.cluster.local -i

A file conjur-cert.pem is created and the contents should look similar to below:

Create a Namespace for the authn-k8s authenticator.

NOTE: If a Conjur Namespace already exists, and only one authn-k8s authenticator is being used in this cluster, then that Conjur Namespace can be reused as the authenticator Namespace).
Run ‘helm install’ using Kubernetes Cluster Prep Helm chart.

For examples of how you can the helm install command, see the "Examples: Running Helm Install" section below.

When helm install command completes, you should see the following Kubernetes objects created in your current (authenticator) Namespace:
- Golden ConfigMap
- Authenticator ServiceAccount
- Authenticator ClusterRole

Examples: Running Helm Install

Optional: Creating a Local Copy of This Helm Chart

For brevity, the example commands below assume that the helm install ... command is run using a local copy of the Helm chart. You can use git clone ... to create a local copy of the Helm chart, e.g.:

cd
git clone https://github.com/cyberark/conjur-authn-k8s-client
cd conjur-authn-k8s-client/deploy/charts/kubernetes-cluster-prep

Helm Install Using A Conjur Certificate From a File

helm install my-conjur-release . \
     --set conjur.applianceUrl="https://conjur.example.com" \
     --set conjur.certificateFilePath="files/conjur-cert.pem" \
     --set authnK8s.authenticatorID="my-authenticator-id"

Helm Install Using A Base64-Encoded Conjur Certificate

helm install my-conjur-release . \
     --set conjur.applianceUrl="https://conjur.example.com" \
     --set conjur.certificateBase64="<Base64-encoded Conjur Cert>" \
     --set authnK8s.authenticatorID="my-authenticator-id"

Helm Install Reusing An Existing Conjur ClusterRole

helm install my-conjur-release . \
     --set conjur.applianceUrl="https://conjur.example.com" \
     --set conjur.certificateFilePath="tests/test-cert.pem" \
     --set authnK8s.authenticatorID="my-authenticator-id" \
     --set authnK8s.clusterRole.create=false \
     --set authnK8s.clusterRole.name="existing-conjur-clusterrole"

Helm Install Reusing An Existing Conjur ServiceAccount

helm install my-conjur-release . \
     --set conjur.applianceUrl="https://conjur.example.com" \
     --set conjur.certificateFilePath="tests/test-cert.pem" \
     --set authnK8s.authenticatorID="my-authenticator-id" \
     --set authnK8s.serviceAccount.create=false \
     --set authnK8s.serviceAccount.name="existing-conjur-serviceaccount"

Helm Install Using a Custom Values YAML File

cat > my-custom-values.yaml << EOT
conjur:
  account: "my-conjur-account"
  applianceUrl: "https://conjur-oss.conjur-oss.svc.cluster.local"
  certificateFilePath: "files/conjur-cert.pem"

authnK8s:
  authenticatorID: "my-authenticator-id"
EOT

helm install my-conjur-release . -f my-custom-values.yaml

Configuration

The following table lists the configurable parameters of the Conjur OSS chart and their default values.

Parameter	Description	Default	Mandatory
`conjur.account`	Conjur account to be used by the Kubernetes authenticator	`"default"`
`conjur.applianceUrl:`	Conjur Appliance URL		Yes
`conjur.ssl.certificateFile`	Path to a Conjur certificate file		Either certificateFile or certificateBase64
`conjur.ssl.certificateBase64`	Base64-encoded Conjur certificate file		Either certificateFile or certificateBase64
`authnK8s.authenticatorID`	Conjur authn-k8s authenticator ID to use for authentication		Yes
`authnK8s.configMap.create`	Flag to generate the Golden ConfigMap	`true`
`authnK8s.configMap.name`	The name of the authenticator ConfigMap	`"authn-k8s-configmap"`
`authnK8s.clusterRole.create`	Flag to generate the ClusterRole	`true`
`authnK8s.clusterRole.name`	The name of the authenticator ClusterRole to use or create	`Defaults to authn-k8s-clusterrole when 'authnK8s.clusterRole.create' is set to 'true'`	Mandatory if authnK8s.clusterRole.create is set to 'false'
`authnK8s.serviceAccount.create`	Flag to generate the ServiceAccount	`true`
`authnK8s.serviceAccount.name`	The name of the authenticator ServiceAccount to use or create	`Defaults to authn-k8s-serviceaccount when 'authnK8s.ServiceAccount.create`	Mandatory if authnK8s.ServiceAccount.create is set to 'false'

rpothier/cluster-helm-README.md