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