<strong>secrets</strong> | Developer Guide

Using secrets
secrets in Volumes and Environment Variables
Image Pull secrets
Source Clone secrets
Service Serving Certificate secrets
Restrictions
- Secret Data Keys
Examples
Troubleshooting

Using secrets

This topic discusses important properties of secrets and provides an overview on how developers can use them.

The Secret object type provides a mechanism to hold sensitive information such as passwords, OpenShift Dedicated client configuration files, dockercfg files, private source repository credentials, and so on. secrets decouple sensitive content from the pods. You can mount secrets into containers using a volume plug-in or the system can use secrets to perform actions on behalf of a pod.

YAML Secret Object Definition

apiVersion: v1
kind: Secret
metadata:
  name: test-secret
  namespace: my-namespace
type: Opaque (1)
data: (2)
  username: dmFsdWUtMQ0K (3)
  password: dmFsdWUtMg0KDQo=
stringData: (4)
  hostname: myapp.mydomain.com (5)

1	Indicates the structure of the secret’s key names and values.
2	The allowable format for the keys in the `data` field must meet the guidelines in the DNS_SUBDOMAIN value in the Kubernetes identifiers glossary.
3	The value associated with keys in the `data` map must be base64 encoded.
4	The value associated with keys in the `stringData` map is made up of plain text strings.
5	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. Create the secret from your local *.docker/config.json* file: $ oc create secret generic dockerhub \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjson This command generates a JSON specification of the secret named `dockerhub` and creates the object.

YAML Opaque Secret Object Definition

apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque (1)
data:
  username: dXNlci1uYW1l
  password: cGFzc3dvcmQ=

1	Specifies an opaque secret.

Docker Configuration JSON File Secret Object Definition

apiVersion: v1
kind: Secret
metadata:
  name: aregistrykey
  namespace: myapps
type: kubernetes.io/dockerconfigjson (1)
data:
  .dockerconfigjson:bm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg== (2)

1	Specifies that the secret is using a Docker configuration JSON file.
2	The output of a base64-encoded the Docker configuration JSON file

Properties of secrets

Key properties include:

Secret data can be referenced independently from its definition.
Secret data volumes are backed by temporary file-storage facilities (tmpfs) and never come to rest on a node.
Secret data can be shared within a namespace.

Creating secrets

You must create a secret before creating the pods that depend on that secret.

When creating secrets:

Create a secret object with secret data.
Update the pod’s service account to allow the reference to the secret.
Create a pod, which consumes the secret as an environment variable or as a file (using a secret volume).

You can use the create command to create a secret object from a JSON or YAML file:

$ oc create -f <filename>

Types of secrets

The value in the type field indicates the structure of the secret’s key names and values. The type can be used to enforce the presence of user names and keys in the secret object. If you do not want validation, use the opaque type, which is the default.

Specify one of the following types to trigger minimal server-side validation to ensure the presence of specific key names in the secret data:

kubernetes.io/service-account-token. Uses a service account token.
kubernetes.io/dockercfg. Uses the .dockercfg file. for required Docker credentials.
kubernetes.io/dockerconfigjson. Uses the .docker/config.json file for required Docker credentials.
kubernetes.io/basic-auth. Use with Basic Authentication.
kubernetes.io/ssh-auth. Use with SSH Key Authentication.
kubernetes.io/tls. Use with TLS certificate authorities

Specify type= Opaque if you do not want validation, which means the secret does not claim to conform to any convention for key names or values. An opaque secret, allows for unstructured key:value pairs that can contain arbitrary values.

You can specify other arbitrary types, such as example.com/my-secret-type. These types are not enforced server-side, but indicate that the creator of the secret intended to conform to the key/value requirements of that type.

For examples of differet secret types, see the code samples in Using secrets.

Updating secrets

When you modify the value of a secret, the value (used by an already running pod) will not dynamically change. To change a secret, you must delete the original pod and create a new pod (perhaps with an identical PodSpec). When you mount a secret as a volume, your secret automatically gets updated.

Updating a secret follows the same workflow as deploying a new container image. You can use the kubectl rolling-update command.

The resourceVersion value in a secret is not specified when it is referenced. Therefore, if a secret is updated at the same time as pods are starting, then the version of the secret will be used for the pod will not be defined.

Currently, it is not possible to check the resource version of a secret object that was used when a pod was created. It is planned that pods will report this information, so that a controller could restart ones using a old resourceVersion. In the interim, do not update the data of existing secrets, but create new ones with distinct names.

secrets in Volumes and Environment Variables

If your container uses a secret as an environment variable, you must restart the container to see the updated secret. See examples of YAML files with secret data.

After you create a secret, you can:

Create the pod to reference your secret:
```
$ oc create -f <your_yaml_file>.yaml
```
Get the logs:
```
$ oc logs secret-example-pod
```
Delete the pod:
```
$ oc delete pod secret-example-pod
```

Image Pull secrets

See Using Image Pull secrets for more information.

Source Clone secrets

See Build Inputs for more information about using source clone secrets during a build.

Service Serving Certificate secrets

Service serving certificate secrets are intended to support complex middleware applications that need out-of-the-box certificates. It has the same settings as the server certificates generated by the administrator tooling for nodes and masters.

Table 1. Service serving certificate **secrets**
Namespace	Secret
`default`	`router-metrics-tls`
`kube-service-catalog`	`controllermanager-ssl`
`openshift-ansible-service-broker`	`asb-tls`
`openshift-console`	`console-serving-cert`
`openshift-infra`	`heapster-certs`
`openshift-logging`	`prometheus-tls`
`openshift-monitoring`	`alertmanager-main-tls`
	`grafana-tls`
	`kube-state-metrics-tls`
	`node-exporter-tls`
	`prometheus-k8s-tls`
`openshift-template-service-broker`	`apiserver-serving-cert`
`openshift-web-console`	`webconsole-serving-cert`

To secure communication to your service, have the cluster generate a signed serving certificate/key pair into a secret in your namespace. To do this, set the service.alpha.openshift.io/serving-cert-secret-name annotation on your service with the value set to the name you want to use for your secret. Then, your PodSpec can mount that secret. When it is available, your pod will run. The certificate will be good for the internal service DNS name, <service.name>.<service.namespace>.svc.

The certificate and key are in PEM format, stored in tls.crt and tls.key respectively. The certificate/key pair is automatically replaced when expiration is within one hour. View the expiration date in the service.alpha.openshift.io/expiry annotation on the secret, which is in RFC3339 format.

Other pods can trust cluster-created certificates (which are only signed for internal DNS names), by using the CA bundle in the /var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt file that is automatically mounted in their pod.

The signature algorithm for this feature is x509.SHA256WithRSA. To manually rotate, delete the generated secret. A new certificate is created.

Restrictions

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. imagePullsecrets use service accounts for the automatic injection of the secret into all pods in a namespaces.

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 an object of type Secret. 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 would exhaust apiserver and kubelet memory. However, creation of a number of smaller secrets could also exhaust memory.

Secret Data Keys

Secret keys must be in a DNS subdomain.

Examples

Example 1. YAML Secret That Will Create Four Files

apiVersion: v1
kind: Secret
metadata:
  name: test-secret
data:
  username: dmFsdWUtMQ0K     (1)
  password: dmFsdWUtMQ0KDQo= (2)
stringData:
  hostname: myapp.mydomain.com (3)
  secret.properties: |-     (4)
    property1=valueA
    property2=valueB

1	File contains decoded values.
2	File contains decoded values.
3	File contains the provided string.
4	File contains the provided data.

Example 2. YAML of a Pod Populating Files in a Volume with Secret Data

apiVersion: v1
kind: Pod
metadata:
  name: secret-example-pod
spec:
  containers:
    - name: secret-test-container
      image: busybox
      command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ]
      volumeMounts:
          # name must match the volume name below
          - name: secret-volume
            mountPath: /etc/secret-volume
            readOnly: true
  volumes:
    - name: secret-volume
      secret:
        secretName: test-secret
  restartPolicy: Never

Example 3. YAML of a Pod Populating Environment Variables with Secret Data

apiVersion: v1
kind: Pod
metadata:
  name: secret-example-pod
spec:
  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
  restartPolicy: Never

Example 4. YAML of a Build Config Populating Environment Variables with Secret Data

apiVersion: 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

Troubleshooting

If a service certificate generations fails with (service’s service.alpha.openshift.io/serving-cert-generation-error annotation contains):

secret/ssl-key references serviceUID 62ad25ca-d703-11e6-9d6f-0e9c0057b608, which does not match 77b6dd80-d716-11e6-9d6f-0e9c0057b60

The service that generated the certificate no longer exists, or has a different serviceUID. You must force certificates regeneration by removing the old secret, and clearing the following annotations on the service service.alpha.openshift.io/serving-cert-generation-error, service.alpha.openshift.io/serving-cert-generation-error-num:

$ oc delete secret <secret_name>
$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-
$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-num-

The command removing annotation has a - after the annotation name to be removed.