Providing sensitive data to pods

    As an administrator, you can use objects to provide this information without exposing that information in clear text.

    The Secret object type provides a mechanism to hold sensitive information such as passwords, OKD client configuration 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.

    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.

    YAML Secret object definition

    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).

    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/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 different secret types, see the code samples in Using Secrets.

    Example secret configurations

    The following are sample secret configuration files.

    YAML Secret object that creates four files

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

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

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: secret-example-pod
    5. spec:
    6.   containers:
    7.     - name: secret-test-container
    8.       image: busybox
    9.       command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ]
    10.       volumeMounts:
    11.           # name must match the volume name below
    12.           - name: secret-volume
    13.             mountPath: /etc/secret-volume
    14.             readOnly: true
    15.   volumes:
    16.     - name: secret-volume
    17.       secret:
    18.         secretName: test-secret
    19.   restartPolicy: Never

    YAML of a pod populating environment variables with secret data

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4. spec:
    5.   containers:
    6.     - name: secret-test-container
    8.       command: [ "/bin/sh", "-c", "export" ]
    9.       env:
    10.         - name: TEST_SECRET_USERNAME_ENV_VAR
    11.           valueFrom:
    12.             secretKeyRef:
    13.               name: test-secret
    14.               key: username
    15.   restartPolicy: Never
    1. apiVersion: v1
    2. kind: BuildConfig
    3. metadata:
    4.   name: secret-example-bc
    5. spec:
    6.   strategy:
    7.     sourceStrategy:
    8.       env:
    9.       - name: TEST_SECRET_USERNAME_ENV_VAR
    10.         valueFrom:
    11.           secretKeyRef:
    12.             name: test-secret
    13.             key: username

    Secret keys must be in a DNS subdomain.

    As an administrator you must create a secret before developers can create 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).

    Secret creation 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. 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 a number of smaller secrets could also exhaust memory.

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

    Procedure

    1. Create a Secret object in a YAML file on master.

      For example:

      1. apiVersion: v1
      2. kind: Secret
      3. metadata:
      4.   name: mysecret
      5. type: Opaque (1)
      6. data:
      7.   username: dXNlci1uYW1l
      8.   password: cGFzc3dvcmQ=
      1Specifies an opaque secret.

    2. Use the following command to create a Secret object:

    3. To use the secret in a pod:

      1. Update the service account for the pod where you want to use the secret to allow the reference to the secret.

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

    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).

    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, the version of the secret that is used for the pod is not defined.

    To secure communication to your service, you can configure OKD to generate a signed serving certificate/key pair that you can add into a secret in a project.

    A service serving certificate secret is 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.

    Service Pod spec configured for a service serving certificates secret.

    1. apiVersion: v1
    2. kind: Service
    3. metadata:
    4.   name: registry
    5.   annotations:
    6.     service.alpha.openshift.io/serving-cert-secret-name: registry-cert(1)
    7. # ...
    1Specify the name for the certificate

    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.

    Generating signed certificates for use with secrets

    To use a signed serving certificate/key pair with a pod, create or edit the service to add the service.alpha.openshift.io/serving-cert-secret-name annotation, then add the secret to the pod.

    Procedure

    To create a service serving certificate secret:

    1. Edit the Pod spec for your service.

    2. Add the service.alpha.openshift.io/serving-cert-secret-name annotation with the name you want to use for your secret.

      1. kind: Service
      2. apiVersion: v1
      3.   name: my-service
      4.   annotations:
      5.       service.alpha.openshift.io/serving-cert-secret-name: my-cert (1)
      6. spec:
      8.     app: MyApp
      9.   ports:
      10.   - protocol: TCP
      11.     port: 80
      12.     targetPort: 9376

      The certificate and key are in PEM format, stored in tls.crt and tls.key respectively.

    3. Create the service:

      1. $ oc create -f <file-name>.yaml

    4. View the secret to make sure it was created:

      1. View a list of all secrets:

        1. $ oc get secrets

        Example output

        1. NAME                     TYPE                                  DATA      AGE
        2. my-cert                  kubernetes.io/tls                     2         9m

      2. View details on your secret:

        Example output

        1. Name:         my-cert
        2. Namespace:    openshift-console
        3. Labels:       <none>
        4. Annotations:  service.alpha.openshift.io/expiry: 2023-03-08T23:22:40Z
        5.               service.alpha.openshift.io/originating-service-name: my-service
        6.               service.alpha.openshift.io/originating-service-uid: 640f0ec3-afc2-4380-bf31-a8c784846a11
        7.               service.beta.openshift.io/expiry: 2023-03-08T23:22:40Z
        9. Type:  kubernetes.io/tls
        11. Data
        12. ====
        13. tls.key:  1679 bytes
        14. tls.crt:  2595 bytes

    5. Edit your Pod spec with that secret.

      1. apiVersion: v1
      2. kind: Pod
      3. metadata:
      4.   name: my-service-pod
      5. spec:
      6.   containers:
      7.   - name: mypod
      8.     image: redis
      9.     volumeMounts:
      10.     - name: foo
      11.       mountPath: "/etc/foo"
      12.   volumes:
      13.   - name: foo
      14.     secret:
      15.       secretName: my-cert
      16.       items:
      17.       - key: username
      18.         path: my-group/my-username
      19.         mode: 511

      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/key pair is automatically replaced when it gets close to expiration. View the expiration date in the service.alpha.openshift.io/expiry annotation on the secret, which is in RFC3339 format.

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

    1. 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:

    1. Delete the secret:

      1. $ oc delete secret <secret_name>