Secret

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

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 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 create a Secret using the following command:

kubectl create secret [TYPE] [NAME] [DATA]

[TYPE] can be one of the following:

  • generic: Create a Secret from a local file, directory, or literal value.
  • docker-registry: Creates 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 exist beforehand. The public key certificate must be .PEM encoded and match the given private key.

For most Secrets, you use the generic type.

[DATA] 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.

Alternatively, you can also create a Secret by defining a Secret object in a YAML manifest file and deploying the object using kubectl create -f [FILE]. For an example, refer to Distribute Credentials Securely Using 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.

--from-file

When you create the Secret using --from-file, the value of the Secret is the entire contents 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 [TYPE] [NAME] --from-file [/PATH/TO/FILE] --from-file [/PATH/TO/FILE2]

You can also pass in a directory containing multiple files:

kubectl create secret [TYPE] [NAME] --from-file [/PATH/TO/DIRECTORY]

For example, the following command creates a Secret called 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.

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. You can override the key by using extended syntax for --from-file:

kubectl create secret [TYPE] [NAME] --from-file=KEY=[/PATH/TO/DIRECTORY]

The following example is identical to the previous one, but sets the keys to username and password, rather than using the file names.

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

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

For example, the following command creates a Secret called credentials from a single file, credentials.txt, which contains multiple key-value pairs:

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

The Secret values are base64-encoded in Kubernetes.

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 Secret named literal-token with two key-value pairs:

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

You 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 the preceding output, observe that 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