Secrets Provider configuration reference

This reference describes the information required to define the Secrets Provider in the application deployment manifest.

Pod annotation / EnvVar reference

This reference is relevant for the Secrets Provider as either an sidecar/init container or as an application container.

  • Use environment variables and Kubernetes annotations to create a mapping to Kubernetes Secrets.

  • Use Kubernetes annotations PLUS the MY_POD_NAME and MY_POD_NAMESPACE environment variables for pushing Conjur secrets to a secrets file in a shared volume (also referred to as Push-to-File).

    Push-to-File supports Secrets Provider sidecar/init container only.

Push-to-File annotations / Kubernetes Secrets envVars

This section describes information for defining the Secrets Provider in Push-to-File or Kubernetes Secrets mode.

Annotation

(Push-to-File mode)

Environment variable

(Kubernetes Secrets mode)

Description

conjur.org/authn-identity

(Required)

CONJUR_AUTHN_LOGIN

(Required)

The Conjur host that authenticates to Conjur.

Set this value to the host id that you defined in the application policy. This value must include the host/ prefix, for example, host/test-app

conjur.org/container-mode

(Required)

CONTAINER_MODE

(Required)

The mode of the Secrets Provider for Kubernetes container

Possible values:

  • init (default)

  • sidecar

  • application

For Push-to-File, use sidecar or init only.

To refresh secrets automatically (after rotation of modification), set to sidecar.

conjur.org/secrets-destination

(Required)

SECRETS_DESTINATION

(Required)

Required destination for the Conjur secrets, to be retrieved by the application container.

Supported values:

  • Push-to-File: file

  • Kubernetes Secrets: k8s_secrets

conjur.org/retry-count-limit

RETRY_COUNT_LIMIT

The number of times the Secrets Provider retries to run if it fails.

Default: 5 (retries)

conjur.org/retry-interval-sec

RETRY_INTERVAL_SEC

The interval between retries.

Default: 1 (sec)

conjur.org/debug-logging

DEBUG

Enables DEBUG logs.

Supported values: true

Default: false

Do not include this parameter in a production environment.

conjur.org/secrets-refresh-enabled

None. Use annotation instead.

A value of true enables updating secrets in a shared volume/Kubernetes Secrets.

When enabled, the Secrets Provider sidecar checks if there are any changes in secrets values in Conjur These changes could be due to secrets rotation or other updates, including deletions. If a change is detected, the change is pushed to the shared volume/Kubernetes Secrets.

Default: false

For sidecar container mode only.

conjur.org/secrets-refresh-interval

None. Use annotation instead.

The interval at which secret values are updated.

Valid time units are s (seconds), m (minutes), and h(hours)

Minimum: 1s (one second)

Default: 5m (five minutes)

Examples of valid values:

  • 5m

  • 2h30m

  • 48h

  • For sidecar container mode only.

  • When the refresh interval is configured, secret updates are implicitly enabled conjur.org/secrets-refresh-enabled = true.

    If the refresh interval is configured while conjur.org/secrets-refresh-enabled = false, an error will occur.

conjur.org/remove-deleted-secrets-enabled

None. Use annotation instead.

Enables deletion of secrets files from the shared volume/Kubernetes Secrets when a secret is deleted from Conjur or if access to the secret is revoked.

Set to false to disable this feature.

Default: true

For sidecar container mode only.

None. Use environment variable instead.

(Required)

MY_POD_NAME

(Required)

The name of the Pod where your application runs, populated automatically by the Kubernetes Downward API.

None. Use environment variable instead.

(Required)

MY_POD_NAMESPACE

(Required)

The name of the namespace where your application runs, populated automatically by the Kubernetes Downward API.

Additional environment variables for Kubernetes Secrets mode

This section describes additional environment variables for defining the Secrets Provider to push Conjur secrets to Kubernetes Secrets.

Environment Variable

Description

K8S_SECRETS

(Required)

A comma-separated list of Kubernetes secret names that the applications in the Pod consume and whose value is sourced from Conjur.

For example:

 
name: K8S_SECRETS
value: db-credentials,other-secret

Additional annotations for Push-to-File mode

This section describes additional annotations for defining the Secrets Provider (sidecar/init container only) to push Conjur secrets to secrets files.

Kubernetes Annotation

Description

conjur.org/conjur-secrets.{secret-group}

(Required)

List of secrets to be retrieved from Conjur. Each entry can be one of the following:

  • A Conjur variable path

  • A key/value pair in the following format:

    <alias>: <Conjur variable path>

    where alias represents the name of the secret to be written to the secrets file

conjur.org/conjur-secrets-policy-path.{secret-group}

Defines a common Conjur policy path assumed to be relative to the root policy.

When this annotation is set, the policy paths defined by conjur.org/conjur-secrets.{secret-group} are relative to this common path.

When this annotation is not set, the policy paths defined by conjur.org/conjur-secrets.{secret-group} are themselves relative to the root policy.

See Example: Common Policy Path

conjur.org/secret-file-path.{secret-group}

The relative path to the secrets file or directory. This path is assumed to be relative to the respective mount path for the shared secrets volume for each container.

If conjur.org/secret-file-format.{secret-group} is set to template, this secrets file path defaults to {secret-group}.out. For example, if the secret group name is my-app, the secrets file path defaults to my-app.out.

Otherwise, this secrets file path defaults to {secret-group}.{secret-group-file-format}. For example, if the secret group name is my-app, and the secrets file format is set to YAML, the secrets file path defaults to my-app.yaml.

conjur.org/secret-file-permissions.{secret-group}

Explicitly defines the secrets file permissions.

Defaults to -rw-r--r-- (Octal 644)

Value must be formatted as a valid permission string, where the directory bit is optional.

Examples:

-rw-rw-r--

rw-rw-r--

The owner must have at a minimum read/write permissions (-rw-------)

conjur.org/secret-file-format.{secret-group}

Secrets File defaults to the specified file format.

Allowed values:

  • yaml (default)

  • json

  • dotenv

  • bash

  • template - for custom templates

See Example: Secrets File Formats

conjur.org/secret-file-template.{secret-group}

Defines, in Golang text template format, a custom template to use to render the secrets file content.

See Custom templates for secrets files - Push-to-File only

Additional Push-to-File references

This section describes additional information for Push-to-File.

Custom templates for secrets files - Push-to-File only

In addition to offering standard file formats, Push-to-File allows you to define your own custom secrets file templates. These templates adhere to Go's text template formatting. Providing custom templates requires the following:

  • The conjur.org/secret-file-format.{secret-group} annotation must be set to template

  • The conjur.org/secret-file-path.{secret-group} annotation must be set, an must specify a file name

The custom template must be provided using either a Pod annotation or a volume-mounted ConfigMap.

Providing a template using both methods or neither method fails before retrieving secrets from Conjur.

Custom templates can be defined using the Pod annotation, conjur.org/secret-file-template.{secret-group}. The following annotations describe a valid secret group that uses a custom template defined in Pod annotations:

conjur.org/secret-group.example: |
  - admin-username: <variable-policy-path>
  - admin-password: <variable-policy-path>
conjur.org/secret-file-format.example: "template"
conjur.org/secret-file-template.example: |
  "database": {
    "username": {{ secret "admin-username" }},
    "password": {{ secret "admin-password" }},
  }

Custom templates can be provided as fields in a ConfigMap. This requires the following:

  • The ConfigMap containing the template files must be mounted in the Secrets Provider container at /conjur/templates

  • Each template's key in the ConfigMap's data field must be formatted as {secret-group}.tpl

The following ConfigMap example defines a custom Go template for a secret group, example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-custom-template
data:
  example.tpl: |
    "database": {
      "username": {{ secret "admin-username" }},
      "password": {{ secret "admin-password" }},
    }

The following annotations describe a valid secret group that uses a custom template defined in the above ConfigMap:

conjur.org/secret-group.example: |
  - admin-username: <variable-policy-path>
  - admin-password: <variable-policy-path>
conjur.org/secret-file-format.example: "template"

In order for Secrets Provider to consume the templates, another volume needs to be added to the application's deployment manifest, populated with the contents of the ConfigMap:

volumes:
- name: conjur-templates
  configMap:
    name: my-custom-template

Mount the ConfigMap-populated volume to the Secrets Provider sidecar/init container at /conjur/templates:

volumeMounts:
- name: conjur-templates
  mountPath: /conjur/templates

Secrets file attributes

By default, the Secrets Provider creates secrets files with the following file attributes:

Attribute Value Notes
User

secrets-provider

--
Group

root

OpenShift requires that any files/directories that are shared between containers in a Pod must use a GID of 0 (i.e. GID for the root group). For simplicity, the Secrets Provider uses a GID of 0 for secrets files even for non-OpenShift platforms.

UID

777

--
GID

0

--
Permissions

rw-rw-r--

As shown in the table, the Secrets Provider creates secrets files that are world readable. This means that the files readable from any other container in the same Pod that mounts the Conjur secrets shared volume.

The file attributes can be overridden by defining a PodSecurityContext for the application Pod.

For example, to have containers run as the nobody user (UID 65534) and nobody group (GID 65534), and have secrets files created with the corresponding GID, the Pod SecurityContext would be as follows:

    securityContext:
      runAsUser: 65534
      runAsGroup: 65534
      runAsNonRoot: true
      fsGroup: 65534