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/log-level

LOG_LEVEL

The detail level of the log files.

Valid values are: debug, info, warn, and error.

Default: info

Do not use the debug log level 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>
[content-type: <type>]

    where alias represents the name of the secret to write to the secrets file. The content-type parameter is optional and can be either text or base64. The default content-type is text.
    For more information about the content-type annotation, see Decode Base64-encoded secrets (cert-based) or Decode Base64-encoded secrets (JWT-based).

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

Given the relationship between conjur.org/conjur-secrets.{secret-group} and conjur.org/conjur-secrets-policy-path.{secret-group}, the following sets of annotations retrieve the same secrets from Conjur:

conjur.org/conjur-secrets.db: |
  - url: policy/path/api-url
  - policy/path/username
  - policy/path/password
conjur.org/conjur-secrets-policy-path.db: policy/path/
conjur.org/conjur-secrets.db: |
  - url: api-url
  - username
  - password

This sections provides examples how a secrets files is rendered based on the selected file format.

When the conjur.org/secret-file-format.{secret-group} annotation is set to yaml the secrets file is rendered in the following format:

"api-url": "dev/redis/api-url"
"admin-username": "dev/redis/username"
"admin-password": "dev/redis/password"

When the conjur.org/secret-file-format.{secret-group} annotation is set to json the secrets file is rendered in the following format:

{"api-url":"dev/redis/api-url","admin-username":"dev/redis/username","admin-password
":"dev/redis/password"

When the conjur.org/secret-file-format.{secret-group} annotation is set to bash the secrets file is rendered in the following format:

     export api-url="dev/redis/api-url"
     export admin-username="dev/redis/username"
     export admin-password="dev/redis/password"

When the conjur.org/secret-file-format.{secret-group} annotation is set to dotenv the secrets file is rendered in the following format:

api-url="dev/redis/api-url"
admin-username="dev/redis/username"
admin-password="dev/redis/password"

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

You can inject Conjur secrets into custom templates using the custom template function secret. The action shown below renders the value associated with <secret-alias> in the secrets-file.

{{ secret "<secret-alias>" }}

Custom templates support global functions native to Go's text/template package. The following example uses template function to HTML escape/encode a secret value:

{{ secret "alias" | html }}
{{ secret "alias" | urlquery }}

If the value retrieved from Conjur for alias is "<Hello@World!>", the following file content will be rendered, each HTML escaped and encoded, respectively:

&lt;Hello;@World!&gt;
%3CHello%40World%21%3E

For a full list of global Go text template functions, reference the official text/template documentation.

Custom templates also support a limited number of additional functions.

Function

Description

b64enc

Base64 encode a value. For example:

{{ secret "alias" | b64enc }}

b64dec

Base64 decode a value. For example:

{{ secret "alias" | b64dec }}

The value retrieved from Conjur must be a valid Base64-encoded string.

To avoid leaking sensitive secret data to logs, and to ensure that a misconfigured Push-to-File workflow fails fast, Push-to-File implements a "double-pass" execution of custom templates. The template "first-pass" runs before secrets are retrieved from Conjur, and validates that the provided custom template successfully executes given "REDACTED" for each secret value. Redacting secret values allows for secure, complete error logging for malformed templates. The template "second-pass" runs when rendering secret files, and error messages during this stage are sanitized. Custom templates that pass the "first-pass" and fail the "second-pass" require experimenting locally to identify bugs.

Custom templates should not branch conditionally on secret values. This may result in a template first-pass execution that doesn't validate all branches of the custom template.

The following is an example of using a custom template to render secret data by referencing secrets directly using the custom template function secret.

conjur.org/secret-file-path.direct-reference: ./direct.txt
conjur.org/secret-file-template.direct-reference: |
  username | {{ secret "db-username" }}
  password | {{ secret "db-password" }}

Assuming that the following secrets have been retrieved for secret group direct-reference:

db-username: admin
db-password: my$ecretP@ss!

the Secrets Provider renders the following content for /conjur/secrets/direct.txt:

username | admin
password | my$ecretP@ss!

The following is an example of using a custom template to render secret data using an iterative process instead of referencing all variables directly:

conjur.org/secret-file-path.iterative-reference: ./iterative.txt
conjur.org/secret-file-template.iterative-reference: |
  {{- range $index, $secret := .SecretsArray -}}
  {{- $secret.Alias }} | {{ $secret.Value }}
  {{- end -}}

Here, .SecretsArray is a reference to the Secrets Provider's internal array of secrets that have been retrieved from Conjur. For each entry in this array, there is a secret Alias and Value field that can be referenced in the custom template.

Assuming that the following secrets have been retrieved for secret group iterative-reference:

db-username: admin
db-password: my$ecretP@ss!

The Secrets Provider renders the following content for /conjur/secrets/iterative.txt:

db-username | admin
db-password | my$ecretP@ss!

The following is an example of using a custom template to render a secrets file containing a PostgreSQL connection string.

For a secret group described by the following annotations:

conjur.org/secret-file-path.postgres: ./pg-connection-string.txt
conjur.org/secret-file-template.postgres: |
  postgresql://{{ secret "dbuser" }}:{{ secret "dbpassword" }}@{{ secret "hostname" }}:{{ secret "hostport" }}/{{ secret "dbname" }}??sslmode=require

and assuming that the following secrets have been retrieved for secret group postgres:

dbuser:     "my-user"
dbpassword: "my-secret-pa$$w0rd"
dbname:     "postgres"
hostname:   "database.example.com"
hostport:   5432

the Secrets Provider renders the following content for /conjur/secrets/pg-connection-string.txt:

postgresql://my-user:my-secret-pa$$w0rd@database.example.com:5432/postgres??sslmode=require

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