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 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 by using the kubectl create secret
:
kubectl create secret type name data
where:
type can be one of the following:
generic
: Create a Secret from a local file, directory, or literal value.docker-registry
: Creates adockercfg
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.name is the name of the secret you are creating.
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
- a path to a directory containing one or more configuration files, indicated
using the
For more information about kubectl create
, refer to the
reference documentation.
Alternatively, you can create a Secret by defining a Secret object in a YAML manifest file and deploying the object using the following command:
kubectl create -f file-name.yaml
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 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.
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 creates a 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
--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 named 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.