Skip to content

cyberark/conjur-k8s-csi-provider

Conjur Provider for Secrets Store CSI Driver

Conjur's integration for the Kubernetes Secrets Store CSI Driver, which injects secrets into Kubernetes environments via Container Storage Interface volumes.

Conjur Provider for Secrets Store CSI Driver is part of the CyberArk Conjur Open Source Suite of tools.

Certification level

This repo is a Trusted level project. It is supported by CyberArk and has been verified to work with Conjur Enterprise. For more detailed information on our certification levels, see our community guidelines.

Requirements

Dependency Minimum Version
Go 1.22.0
Kubernetes 1.19.0
Secrets Store CSI Driver 1.3.0
Conjur OSS / Enterprise 1.17.3 / 12.5

Openshift

The Conjur CSI Provider has been tested against the following Openshift versions:

Oldest Current
4.12 4.15

Usage

  1. Create and configure a JWT Authenticator instance in Conjur

    Load the following Conjur policy samples to setup AuthnJWT.

    Each workload in Kubernetes is represented as a Conjur host, specified by identifying annotations.

    - !host
      id: system:serviceaccount:app-namespace:default
      annotations:
        authn-jwt/kube/kubernetes.io/namespace: app-namespace
        authn-jwt/kube/kubernetes.io/serviceaccount/name: default

    The following policy YAML creates an AuthnJWT instance kube to authenticate workloads in Kubernetes using their ServiceAccount tokens, and permits the created host to authenticate with the service. The host ID is the value of the claim in the JWT token specified by the token-app-property authenticator variable.

    - !policy
      id: conjur/authn-jwt/kube
      body:
      - !webservice
    
      # Uncomment one of following variables depending on the public availability
      # of the Service Account Issuer Discovery service in Kubernetes:
      # If the service is publicly available, uncomment 'jwks-uri'.
      # If the service is not available, uncomment 'public-keys'.
      # - !variable
      #   id: jwks-uri
      - !variable
        id: public-keys
    
      # Used with 'jwks-uri'.
      # Uncomment ca-cert if the JWKS website cert isn't trusted by conjur
      # - !variable
      #   id: ca-cert
    
      # Used with 'public-keys'.
      # This variable contains what "iss" in the JWT.
      - !variable
        id: issuer
    
      # This variable contains what "aud" is the JWT.
      # - !variable
      #   id: audience
    
      # This variable tells Conjur which claim in the JWT to use to determine the
      # Conjur host identity.
      - !variable
        id: token-app-property # Most likely set to "sub" for Kubernetes
    
      # Used with 'token-app-property'.
      # This variable will hold the Conjur policy path that contains the Conjur
      # host identity found by looking at the claim entered in token-app-property.
      # - !variable
      #   id: identity-path
    
      - !permit
        role: !host /system:serviceaccount:app-namespace:default
        privilege: [ read, authenticate ]
        resource: !webservice

    Create variables that contain secret content required by your application, and permit the host to access them.

    - !policy
      id: db-credentials
      body:
      - &variables
        - !variable url
        - !variable username
        - !variable password
    
      - !permit
        role: !host /system:serviceaccount:app-namespace:default
        privileges: [ read, execute ]
        resource: *variables

    Refer to our documentation for more information on JWT Authentication.

  2. Install the Secrets Store CSI Driver Helm chart

    $ helm repo add secrets-store-csi-driver \
        https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts
    $ helm install csi-secrets-store \
        secrets-store-csi-driver/secrets-store-csi-driver \
        --wait \
        --namespace kube-system \
        --set 'tokenRequests[0].audience=conjur'

    Refer to the Secrets Store CSI Driver documentation for more information and best practices for installing the CSI Driver.

  3. Install the Conjur Provider Helm chart

    $ helm repo add cyberark \
        https://cyberark.github.io/helm-charts
    $ helm install conjur-csi-provider \
        cyberark/conjur-k8s-csi-provider \
        --wait \
        --namespace kube-system

    See the Helm chart configuration table for additional customization options.

  4. Create a SecretProviderClass

    Configuration is passed to the Conjur provider via a SecretProviderClass through the spec.parameters field.

    ---
    apiVersion: secrets-store.csi.x-k8s.io/v1
    kind: SecretProviderClass
    metadata:
      name: credentials-from-conjur
    spec:
      provider: conjur
      parameters:
        conjur.org/configurationVersion: 0.2.0
        account: myAccount
        applianceUrl: http://myorg.conjur.com
        authnId: authn-jwt/kube
        sslCertificate: |
          -----BEGIN CERTIFICATE-----
          MIIDhDCCAmy...njemCrVXIWw==
          -----END CERTIFICATE-----

    See the SecretProviderClass configuration table for additional customization options.

  5. Deploy an application

    Define secrets in the application pod's conjur.org/secrets annotation and reference the SecretProviderClass in the pod's volumes.

  ---
  apiVersion: v1
  kind: Pod
  metadata:
    name: app
    namespace: app-namespace
    annotations:
      conjur.org/secrets: |
        - "relative/path/fileA.txt": "db-credentials/url"
        - "relative/path/fileB.txt": "db-credentials/username"
        - "relative/path/fileC.txt": "db-credentials/password"
  spec:
    serviceAccountName: default
    containers:
      - name: app
        image: alpine:latest
        imagePullPolicy: Always
        command: [ "/bin/sh", "-c", "--" ]
        args: [ "while true; do sleep 30; done;" ]
        volumeMounts:
          - name: conjur-csi-provider-volume
            mountPath: /mnt/secrets-store
            readOnly: true
        securityContext:
          allowPrivilegeEscalation: false
    volumes:
      - name: conjur-csi-provider-volume
        csi:
          driver: 'secrets-store.csi.k8s.io'
          readOnly: true
          volumeAttributes:
            secretProviderClass: "credentials-from-conjur"

Configuration

Conjur Provider Helm chart

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

Parameter Description Default
daemonSet.name Name given to Provider DaemonSet and child Pods conjur-k8s-csi-provider
daemonSet.image.repo Conjur Provider Docker image repository cyberark/conjur-k8s-csi-provider
daemonSet.image.tag Conjur Provider Docker image tag latest
daemonSet.image.pullPolicy Pull Policy for Conjur Provider Docker image IfNotPresent
provider.name Name used to reference Conjur Provider instance conjur
provider.healthPort Port to expose Conjur Provider health server 8080
provider.socketDir Directory of socket connections to the Secrets Store CSI Driver /var/run/secrets-store-csi-providers
securityContext Security configuration to be applied to Conjur Provider container
{
privileged: false,
allowPrivilegeEscalation: false
}
serviceAccount.create Controls whether or not a ServiceAccout is created true
serviceAccount.name Name of the ServiceAccount associated with Provider Pods conjur-k8s-csi-provider
labels Map of labels applied to Provider DaemonSet and child Pods {}
annotations Map of annotations applied to Provider DaemonSet and child Pods {}

SecretProviderClass

The following table lists the configurable parameters on the Conjur Provider's SecretProviderClass instances.

Field Description Example
spec.parameters.account Conjur account used during authentication myAccount
spec.parameters.applianceUrl Conjur Appliance URL https://myorg.conjur.com
spec.parameters.authnId Type and service ID of desired Conjur authenticator authn-jwt/service-id
spec.parameters.conjur.org/configurationVersion Conjur CSI Provider configuration version 0.2.0
spec.parameters.identity Conjur identity used during authentication and authorization (Optional. Only used when token-app-property authenticator field is not used.) botApp
spec.parameters.secrets Multiline string describing map of relative filepaths to Conjur variable IDs. NOTE: This parameter is ignored when conjur.org/configurationVersion is 0.2.0 or higher. Instead use application pod annotations.
- "relative/path/fileA.txt": "conjur/path/varA"
- "relative/path/fileB.txt": "conjur/path/varB"
spec.parameters.sslCertificate Conjur Appliance certificate
-----BEGIN CERTIFICATE-----
MIIDhDCCAmy...njemCrVXIWw==
-----END CERTIFICATE-----

Contributing

Please read our Contributing Guide.

Community Support

Our primary channel for support is through our CyberArk Commons community here.

Code Maintainers

CyberArk Conjur Team

License

Copyright (c) 2023 CyberArk Software Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For the full license text see LICENSE.