Red Hat OpenShift Container Platform

Understanding how to create secrets

As an administrator you must create a secret before developers can create the pods that depend on that secret.

To use a secret, a pod needs to reference the secret. A secret can be used with a pod in three ways:

To populate environment variables for containers.
As files in a volume mounted on one or more of its containers.
By kubelet when pulling images for the pod.

Volume type secrets write data into the container as a file using the volume mechanism. Image pull secrets use service accounts for the automatic injection of the secret into all pods in a namespace.

When a template contains a secret definition, the only way for the template to use the provided secret is to ensure that the secret volume sources are validated and that the specified object reference actually points to a Secret object. Therefore, a secret needs to be created before any pods that depend on it. The most effective way to ensure this is to have it get injected automatically through the use of a service account.

Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace.

Individual secrets are limited to 1MB in size. This is to discourage the creation of large secrets that could exhaust apiserver and kubelet memory. However, creation of several smaller secrets could also exhaust memory.

Procedure

Create a secret object that contains the data you want to keep secret. The specific data required for each secret type is descibed in the following sections.
Example YAML object that creates an opaque secret
```
apiVersion: v1
kind: Secret
metadata:
  name: test-secret
type: Opaque
data:
  username: <username>
  password: <password>
stringData:
  hostname: myapp.mydomain.com
  secret.properties: |
    property1=valueA
    property2=valueB
```
where:

type

Specifies the type of secret.

data

Specifies encoded string and data.

stringData

Specifies decoded string and data.

Use either the data or stringdata fields, not both.
Update the pod’s service account to reference the secret:
YAML of a service account that uses a secret
```
apiVersion: v1
kind: ServiceAccount
 ...
secrets:
- name: test-secret
```

Create a pod, which consumes the secret as an environment variable or as a file (using a secret volume):

YAML of a pod populating files in a volume with secret data

apiVersion: v1
kind: Pod
metadata:
  name: secret-example-pod
spec:
  securityContext:
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: secret-test-container
      image: busybox
      command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ]
      volumeMounts:
          - name: secret-volume
            mountPath: /etc/secret-volume
            readOnly: true
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop: [ALL]
  volumes:
    - name: secret-volume
      secret:
        secretName: test-secret
  restartPolicy: Never

where:

spec.container.volumeMounts: Specifies configurations for the secret. Add a volumeMounts field to each container that needs the secret.
spec.container.volumeMounts.mountPath: Specifies an unused directory name where you want the secret to appear. Each key in the secret data map becomes the filename under mountPath.
spec.container.volumeMounts.readOnly: If set to true, specifies that the driver should provide a read-only volume.
spec.volumes.secret.secretName: Specifies the name of the secret.

YAML of a pod populating environment variables with secret data

apiVersion: v1
kind: Pod
metadata:
  name: secret-example-pod
spec:
  securityContext:
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: secret-test-container
      image: busybox
      command: [ "/bin/sh", "-c", "export" ]
      env:
        - name: TEST_SECRET_USERNAME_ENV_VAR
          valueFrom:
            secretKeyRef:
              name: test-secret
              key: username
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop: [ALL]
  restartPolicy: Never

where:

spec.containers.env.valueFrom.secretKeyRef: Specifies the environment variable that consumes the secret key.

YAML of a build config populating environment variables with secret data

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: secret-example-bc
spec:
  strategy:
    sourceStrategy:
      env:
      - name: TEST_SECRET_USERNAME_ENV_VAR
        valueFrom:
          secretKeyRef:
            name: test-secret
            key: username
      from:
        kind: ImageStreamTag
        namespace: openshift
        name: 'cli:latest'

where:

spec.strategy.sourceStrategy.env.valueFrom.secretKeyRef: Specifies the environment variable that consumes the secret key.

Creating an opaque secret

As an administrator, you can create an opaque secret, which allows you to store unstructured key:value pairs that can contain arbitrary values.

Procedure

Create a Secret object in a YAML file.

For example:

apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  username: <username>
  password: <password>

where:

type: Specifies an opaque secret.

Use the following command to create a Secret object:
```
$ oc create -f <filename>.yaml
```
To use the secret in a pod:
1. Update the pod’s service account to reference the secret, as shown in the "Understanding how to create secrets" section.
2. Create the pod, which consumes the secret as an environment variable or as a file (using a secret volume), as shown in the "Understanding how to create secrets" section.

Creating a legacy service account token secret

As an administrator, you can create a legacy service account token secret, which allows you to distribute a service account token to applications that must authenticate to the API.

It is recommended to obtain bound service account tokens using the TokenRequest API instead of using legacy service account token secrets. You should create a service account token secret only if you cannot use the TokenRequest API and if the security exposure of a nonexpiring token in a readable API object is acceptable to you.

Bound service account tokens are more secure than service account token secrets for the following reasons:

Bound service account tokens have a bounded lifetime.
Bound service account tokens contain audiences.
Bound service account tokens can be bound to pods or secrets and the bound tokens are invalidated when the bound object is removed.

Workloads are automatically injected with a projected volume to obtain a bound service account token. If your workload needs an additional service account token, add an additional projected volume in your workload manifest.

For more information, see "Configuring bound service account tokens using volume projection".

Procedure

Create a Secret object in a YAML file:
Example Secret object
```
apiVersion: v1
kind: Secret
metadata:
  name: secret-sa-sample
  annotations:
    kubernetes.io/service-account.name: "sa-name"
type: kubernetes.io/service-account-token
```
where:

metadata.annotations

Specifies an existing service account name. If you are creating both the ServiceAccount and the Secret objects, create the ServiceAccount object first.

type

Specifies a service account token secret.
Use the following command to create the Secret object:
```
$ oc create -f <filename>.yaml
```
To use the secret in a pod:
1. Update the pod’s service account to reference the secret, as shown in the "Understanding how to create secrets" section.
2. Create the pod, which consumes the secret as an environment variable or as a file (using a secret volume), as shown in the "Understanding how to create secrets" section.

Creating a basic authentication secret

As an administrator, you can create a basic authentication secret, which you can use to store the credentials needed for basic authentication.

When using this secret type, the data parameter of the Secret object must contain the following keys encoded in the base64 format:

username: the user name for authentication
password: the password or token for authentication

You can use the stringData parameter to use clear text content.

Procedure

Create a Secret object in a YAML file:
Example secret object
```
apiVersion: v1
kind: Secret
metadata:
  name: secret-basic-auth
type: kubernetes.io/basic-auth
data:
stringData:
  username: admin
  password: <password>
```
where:

type

Specifies a basic authentication secret.

stringData

Specifies the basic authentication values to use.
Use the following command to create the Secret object:
```
$ oc create -f <filename>.yaml
```
To use the secret in a pod:
1. Update the pod’s service account to reference the secret, as shown in the "Understanding how to create secrets" section.
2. Create the pod, which consumes the secret as an environment variable or as a file (using a secret volume), as shown in the "Understanding how to create secrets" section.

Creating an SSH authentication secret

As an administrator, you can create an SSH authentication secret, which you can use to store data used for SSH authentication.

When using this secret type, the data parameter of the Secret object must contain the SSH credential to use.

Procedure

Create a Secret object in a YAML file on a control plane node:
Example secret object
```
apiVersion: v1
kind: Secret
metadata:
  name: secret-ssh-auth
type: kubernetes.io/ssh-auth 
data:
  ssh-privatekey: | 
          MIIEpQIBAAKCAQEAulqb/Y ...
```
where:

type

Specifies an SSH authentication secret.

data.ssh-privatekey

Specifies the SSH key/value pair as the SSH credentials to use.
Use the following command to create the Secret object:
```
$ oc create -f <filename>.yaml
```
To use the secret in a pod:
1. Update the pod’s service account to reference the secret, as shown in the "Understanding how to create secrets" section.
2. Create the pod, which consumes the secret as an environment variable or as a file (using a secret volume), as shown in the "Understanding how to create secrets" section.

Creating a Docker configuration secret

As an administrator, you can create a Docker configuration secret, which allows you to store the credentials for accessing a container image registry.

kubernetes.io/dockercfg. Use this secret type to store your local Docker configuration file. The data parameter of the secret object must contain the contents of a .dockercfg file encoded in the base64 format.
kubernetes.io/dockerconfigjson. Use this secret type to store your local Docker configuration JSON file. The data parameter of the secret object must contain the contents of a .docker/config.json file encoded in the base64 format.

Procedure

Create a Secret object in a YAML file.

Example Docker configuration secret object

apiVersion: v1
kind: Secret
metadata:
  name: secret-docker-cfg
  namespace: my-project
type: kubernetes.io/dockerconfig
data:
  .dockerconfig:bm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==

where:

type: Specifies that the secret is using a Docker configuration file.
data: Specifies the output of a base64-encoded Docker configuration file.

Example Docker configuration JSON secret object

apiVersion: v1
kind: Secret
metadata:
  name: secret-docker-json
  namespace: my-project
type: kubernetes.io/dockerconfig
data:
  .dockerconfigjson:bm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==

where:

type: Specifies that the secret is using a Docker configuration file.
data: Specifies the output of a base64-encoded Docker configuration file.

Use the following command to create the Secret object
```
$ oc create -f <filename>.yaml
```
To use the secret in a pod:
1. Update the pod’s service account to reference the secret, as shown in the "Understanding how to create secrets" section.
2. Create the pod, which consumes the secret as an environment variable or as a file (using a secret volume), as shown in the "Understanding how to create secrets" section.

Creating a secret using the web console

You can secure sensitive information, such as passwords or tokens, in a secret and add the information to a workload by using the web console. By using secrets, you can manage application credentials and configuration files without including them in your container images.

Procedure

Navigate to Workloads → Secrets.
Click Create → From YAML.
1. Edit the YAML manually to your specifications, or drag and drop a file into the YAML editor. For example:
  apiVersion: v1 kind: Secret metadata: name: example namespace: <namespace> type: Opaque data: username: <base64 encoded username> password: <base64 encoded password> stringData: hostname: myapp.mydomain.com
  where:
  
  type
  
  Specifies an opaque secret. However, you may see other secret types such as service account token secret, basic authentication secret, SSH authentication secret, or a secret that uses Docker configuration.
  
  stringData
  
  Specifies the value associated with keys in the data map. The value associated with keys in the stringData map is made up of plain text strings. Entries in the stringData map are converted to base64 and the entry will then be moved to the data map automatically. This field is write-only; the value will only be returned via the data field.
Click Create.
Click Add Secret to workload.
1. From the drop-down menu, select the workload to add.
2. Click Save.