Secrets

This page describes the Secret object in Kubernetes and its use in Google Kubernetes Engine (GKE).

What is a Secret?

Secrets are secure objects which store sensitive data, such as passwords, OAuth tokens, and SSH keys in your clusters. Storing sensitive data in Secrets is more secure than in plaintext ConfigMaps or in Pod specifications. Using Secrets gives you control over how sensitive data is used, and reduces the risk of exposing the data to unauthorized users.

You can also encrypt Secrets at the application layer using a key you manage in Cloud KMS. To learn more, see Application-layer Secrets Encryption.

Creating a Secret

You can create a Secret using the command-line or a YAML file.

kubectl

To create a Secret, run the following command:

kubectl create secret SECRET_TYPE SECRET_NAME DATA

Replace the following:

• SECRET_TYPE: the Secret type, which can be one of the following:

  • generic: Create a Secret from a local file, directory, or literal value.
  • docker-registry: Create a dockercfg Secret for use with a Docker registry. Used to authenticate against Docker registries.
  • tls: Create a TLS secret from the given public/private key pair. The public/private key pair must already exist. The public key certificate must be .PEM encoded and match the given private key.

  For most Secrets, you use the generic type.

• SECRET_NAME: the name of the Secret you are creating.

• DATA: the data to add to the Secret, which can be one of the following:

  • a path to a directory containing one or more configuration files, indicated using the --from-file or --from-env-file flags.
  • key-value pairs, each specified using --from-literal flags.

For more information about kubectl create, refer to the reference documentation.

YAML file

To create a Secret using a YAML file, define a Secret object in the file and deploy the object using the following command:

kubectl create -f FILE_NAME.yaml

For an example, refer to Distribute Credentials Securely Using Secrets.

Creating Secrets from files

To create a Secret from one or more files, use --from-file or --from-env-file. The file must be plaintext, but the extension of the file does not matter.

Create a Secret using --from-file

When you create the Secret using --from-file, the value of the Secret is the content of the file. If the value of your Secret contains multiple key-value pairs, use --from-env-file instead.

You can pass in a single file or multiple files:

kubectl create secret SECRET_TYPE SECRET_NAME \
  --from-file PATH_TO_FILE1 \
  --from-file PATH_TO_FILE2

Replace the following:

• SECRET_TYPE: the Secret type, which can be one of the following:

  • generic: Create a Secret from a local file, directory, or literal value.
  • docker-registry: Create a dockercfg Secret for use with a Docker registry. Used to authenticate against Docker registries.

  • tls: Create a TLS secret from the given public/private key pair. The public/private key pair must already exist. The public key certificate must be .PEM encoded and match the given private key.

    For most Secrets, you use the generic type.

• SECRET_NAME: the name of the Secret you are creating.

• PATH_TO_FILE: the path to the file.

You can also pass in a directory containing multiple files:

kubectl create secret SECRET_TYPE SECRET_NAME \
  --from-file PATH_TO_DIRECTORY

Replace PATH_TO_DIRECTORY with the path to the directory.

For example, the following command creates a generic type Secret named credentials from two files, username.txt and password.txt, and sets the keys to username.txt and password.txt respectively:

kubectl create secret generic credentials \
  --from-file ./username.txt \
  --from-file ./password.txt

The Secret values are base-64 encoded in Kubernetes.

Warning: Don't leave plaintext files containing sensitive data on disk. After loading the Secret, remove the plaintext file or move it to secure storage.

Running kubectl get secret credentials -o yaml returns the following output:

apiVersion: v1
data:
  password.txt: MTIzNAo=
  username.txt: YWRtaW4K
kind: Secret
metadata:
  creationTimestamp: ...
  name: credentials
  namespace: default
  resourceVersion: "2011810"
  selfLink: /api/v1/namespaces/default/secrets/credentials
  uid: ...
type: Opaque

By default, the key is the filename. In this example, the keys are password.txt and username.txt. You can override the default key by using extended syntax in the --from-file flag:

kubectl create secret SECRET_TYPE SECRET_NAME \
  --from-file=KEY_NAME=PATH_TO_DIRECTORY

Replace KEY_NAME with the name you want to set for the key.

The following example creates a generic type Secret named credentials from two files, username.txt and password.txt, and sets the keys to username and password, rather than using the filenames:

kubectl create secret generic credentials \
  --from-file=username=./username.txt \
  --from-file=password=./password.txt

Create a Secret using--from-env-file

To load multiple key-value pairs into a single Secret, store the key-value pairs in one or more plaintext files and load them using --from-env-file instead of --from-file. You can load multiple files by specifying the flag multiple times. The same limitations as --from-file apply.

The following example creates a generic type Secret called credentials from a single file, credentials.txt, which contains multiple key-value pairs.

1. Create the credentials.txt file:

   # Each of these key-value pairs is loaded into the Secret
   username=jane
   password=d7xnNss7EGCFZusG
   

   The Secret values are base64-encoded in Kubernetes.

   Warning: Don't leave plaintext files containing sensitive data on disk. After loading the Secret, remove the plaintext file or move it to secure storage.

2. Create the Secret:

   kubectl create secret generic credentials \
     --from-env-file ./credentials.txt
   

Running kubectl get secret credentials -o yaml returns the following output:

apiVersion: v1
data:
  password: ZDd4bk5zczdFR0NGWnVzRw==
  username: amFuZQ==
kind: Secret
metadata:
  creationTimestamp: 2019-06-04T15:39:27Z
  name: credentials
  namespace: default
  resourceVersion: "14507319"
  selfLink: /api/v1/namespaces/default/secrets/credentials
  uid: efce376b-86de-11e9-9742-42010a80022f
type: Opaque

Limitations

Non-regular files, such as symlinks, devices, and pipes, are ignored by kubectl. Subdirectories are also ignored; kubectl create secret does not recurse into subdirectories.

From literal values

To create a Secret from literal values, use --from-literal.

For example, the following command creates a generic type Secret named literal-token with two key-value pairs:

kubectl create secret generic literal-token \
  --from-literal user=admin \
  --from-literal password=1234

Specify --from-literal for each key-value pair. The values are automatically base64-encoded.

Running kubectl get secret literal-token -o yaml returns the following output:

apiVersion: v1
data:
  password: MTIzNA==
  user: YWRtaW4=
kind: Secret
metadata:
  creationTimestamp: ...
  name: literal-token
  namespace: default
  resourceVersion: "2012831"
  selfLink: /api/v1/namespaces/default/secrets/literal-token
  uid: ...
type: Opaque

In this output, both password and user are base64-encoded. The base64 encoding makes the information digestible by apps and services that can't handle certain characters. The base64 encoding does not provide security.

Using a Secret

To use a Secret with your workloads, you can specify environment variables that reference the Secret's values, or mount a volume containing the Secret.

To learn about using Secrets, refer to Using Secrets.

What's next

• Read more about Secrets in the Kubernetes documentation.