The integration between Secret Manager and Google Kubernetes Engine (GKE) lets you store sensitive data such as passwords and certificates used by GKE clusters as secrets in Secret Manager.
This page explains how you can use the Secret Manager add-on to access the secrets stored in Secret Manager as volumes mounted in Kubernetes Pods.
This process involves the following steps:
- Install the Secret Manager add-on on a new or existing GKE cluster.
- Configure applications to authenticate to the Secret Manager API.
- Define which secrets to mount onto Kubernetes Pods using a
SecretProviderClass
YAML file. - Create a volume where the secrets will be mounted. After the volume is attached, applications in the container can access the data in the container file system.
The Secret Manager add-on is derived from the open source Kubernetes Secrets Store CSI Driver and the Google Secret Manager provider. If you're using the open source Secrets Store CSI Driver to access secrets, you can migrate to the Secret Manager add-on. For information, see Migrate from the existing Secrets Store CSI Driver.
Benefits
The Secret Manager add-on provides the following benefits:
- You can use a fully managed and supported solution to access Secret Manager secrets from within GKE without any operational overhead.
- You don't have to write custom code to access secrets stored in Secret Manager.
- You can store and manage all your secrets centrally in Secret Manager and selectively access secrets from GKE pods using the Secret Manager add-on. By doing this, you can use features offered by Secret Manager such as CMEK encryption, fine-grained access control, managed rotation, lifecycle management, and audit logs, along with using Kubernetes features such as passing secrets to containers in the form of mounted volumes.
- The Secret Manager add-on is supported on both Standard clusters and Autopilot clusters.
- The Secret Manager add-on supports
linux/arm64
andlinux/amd64
deployments.
Limitations
This Preview release of the Secret Manager add-on doesn't support the following features that are available in the open source Secrets Store CSI Driver:
Before you begin
-
Enable the Secret Manager and Google Kubernetes Engine APIs.
If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the
gcloud components update
command.Ensure that your cluster runs GKE version 1.29 or later with a Linux node image. The Secret Manager add-on doesn't support Windows Server nodes.
Install the Secret Manager add-on
You can install the Secret Manager add-on on both Standard clusters as well as Autopilot clusters. Ensure that Workload Identity Federation for GKE is enabled on the Standard cluster. Workload Identity Federation for GKE is enabled by default on an Autopilot cluster. Kubernetes Pods use workload identity to authenticate to the Secret Manager API.
Install the Secret Manager add-on on a new GKE cluster
To install the Secret Manager add-on on cluster creation, follow these steps:
Standard cluster
To enable the Secret Manager add-on on a new Standard cluster, run the following command:
gcloud beta container clusters create CLUSTER_NAME \ --enable-secret-manager \ --location=LOCATION \ --cluster-version=VERSION \ --workload-pool=PROJECT_ID.svc.id.goog
Replace the following:
CLUSTER_NAME
: the name of your cluster.LOCATION
: the Compute Engine region or zone for the cluster.VERSION
: the specific GKE version that you want to use. Ensure that your cluster runs GKE version 1.29 or later. If the default release channel doesn't include this version, use the--release-channel
flag to choose a release channel that does.PROJECT_ID
: the ID of your Google Cloud project.
Autopilot cluster
To enable the Secret Manager add-on on a new Autopilot cluster, run the following command:
gcloud beta container clusters create-auto CLUSTER_NAME \ --enable-secret-manager \ --cluster-version=VERSION \ --location=LOCATION
Replace the following:
CLUSTER_NAME
: the name of your clusterVERSION
: the specific GKE version that you want to use. Ensure that your cluster runs GKE version 1.29 or later. If the default release channel doesn't include this version, use the--release-channel
flag to choose a release channel that does.LOCATION
: the region for your cluster, such asus-central1
.
After you have enabled the Secret Manager add-on, you
can use the Secrets Store CSI Driver in Kubernetes volumes using the driver
and provisioner name: secrets-store-gke.csi.k8s.io
.
Install the Secret Manager add-on on an existing GKE cluster
To enable the Secret Manager add-on on an existing cluster, run the following command:
gcloud beta container clusters update CLUSTER_NAME \
--enable-secret-manager \
--location=LOCATION
Replace the following:
CLUSTER_NAME
: the name of your existing clusterLOCATION
: the region for your cluster, such asus-central1
.
Configure applications to authenticate to the Secret Manager API
The Google Secret Manager provider uses the workload identity of the Pod that a secret is mounted onto when authenticating to the Secret Manager API. To allow your applications to authenticate to the Secret Manager API using Workload Identity Federation for GKE, follow these steps:
Create a new Kubernetes ServiceAccount or use an existing Kubernetes ServiceAccount in any namespace, including the default Kubernetes ServiceAccount.
Create an Identity and Access Management (IAM) allow policy for the secret in Secret Manager.
Pods that use the configured Kubernetes ServiceAccount automatically authenticate as the IAM principal identifier that corresponds to the Kubernetes ServiceAccount when accessing the Secret Manager API.
Create a new Kubernetes ServiceAccount
Save the following manifest as
service-account.yaml
:apiVersion: v1 kind: ServiceAccount metadata: name: KSA_NAME namespace: NAMESPACE
Replace the following:
KSA_NAME
: the name of your new Kubernetes ServiceAccountNAMESPACE
: the name of the Kubernetes namespace for the ServiceAccount
Apply the manifest:
kubectl apply -f service-account.yaml
Create an IAM allow policy that references the new Kubernetes ServiceAccount and grant it permission to access the secret:
gcloud secrets add-iam-policy-binding SECRET_NAME \ --role=roles/secretmanager.secretAccessor \ --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
Replace the following:
SECRET_NAME
: the name of the secret in Secret ManagerPROJECT_NUMBER
: your numerical Google Cloud project numberPROJECT_ID
: the project ID of the Google Cloud project that contains your GKE clusterNAMESPACE
: the name of the Kubernetes namespace for the ServiceAccountKSA_NAME
: the name of your existing Kubernetes ServiceAccount
Use an existing Kubernetes ServiceAccount
Create an IAM allow policy that references the existing Kubernetes ServiceAccount and grant it permission to access the secret:
gcloud secrets add-iam-policy-binding SECRET_NAME \
--role=roles/secretmanager.secretAccessor \
--member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
Replace the following:
SECRET_NAME
: the name of the secret in Secret ManagerPROJECT_NUMBER
: your numerical Google Cloud project numberPROJECT_ID
: the project ID of the Google Cloud project that contains your GKE clusterNAMESPACE
: the name of the Kubernetes namespace for the ServiceAccountKSA_NAME
: the name of your existing Kubernetes ServiceAccount
Define which secrets to mount
To specify which secrets to mount as files in the Kubernetes Pod, create a
SecretProviderClass
YAML manifest and list the secrets to mount and the filename to
mount them as. Follow these steps:
Save the following manifest as
app-secrets.yaml
:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: SECRET_PROVIDER_CLASS_NAME spec: provider: gke parameters: secrets: | - resourceName: "projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION" path: "FILENAME.txt"
Replace the following:
SECRET_PROVIDER_CLASS_NAME
: the name for yourSecretProviderClass
objectPROJECT_ID
: your project IDSECRET_NAME
: the secret nameSECRET_VERSION
: the secret versionFILENAME.txt
: the filename where the secret value will be mounted. You can create multiple files using theresourceName
andpath
variables.
Apply the manifest:
kubectl apply -f app-secrets.yaml
Verify that the
SecretProviderClass
object is created:kubectl get SecretProviderClasses
Configure a volume where the secrets will be mounted
Save the following configuration as
my-pod.yaml
:apiVersion: v1 kind: Pod metadata: name: POD_NAME namespace: default spec: serviceAccountName: KSA_NAME containers: - image: IMAGE_NAME imagePullPolicy: IfNotPresent name: POD_NAME resources: requests: cpu: 100m stdin: true stdinOnce: true terminationMessagePath: /dev/termination-log terminationMessagePolicy: File tty: true volumeMounts: - mountPath: "/var/secrets" name: mysecret volumes: - name: mysecret csi: driver: secrets-store-gke.csi.k8s.io readOnly: true volumeAttributes: secretProviderClass: SECRET_PROVIDER_CLASS_NAME
Replace the following:
POD_NAME
: the name of the Kubernetes Pod where the secret is mountedKSA_NAME
: the Kubernetes ServiceAccount that you set up in the step Set up the workload identity service accountIMAGE_NAME
: name of the container imageSECRET_PROVIDER_CLASS_NAME
: the name for yourSecretProviderClass
object
Apply the configuration to your cluster.
kubectl apply -f my-pod.yaml
This step mounts a volume mysecret
at /var/secrets
using the CSI driver
(secrets-store-gke.csi.k8s.io). This volume references the SecretProviderClass
object
which acts as the provider.
Migrate from the existing Secrets Store CSI Driver
If you're migrating to the Secret Manager add-on from your existing installation of the Secrets Store CSI Driver, update your Pod manifest as follows:
Update the name of your
SecretProviderClass
and theprovider
as described in the following manifest:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: app-secrets-gke spec: provider: gke parameters: secrets: | - resourceName: "projects/<project_id>/secrets/<secret_name>/versions/<secret_version>" path: "good1.txt"
Update the
driver
and thesecretProviderClass
for your Kubernetes volume as described in the following manifest:volumes: - name: mysecret csi: driver: secrets-store-gke.csi.k8s.io readOnly: true volumeAttributes: secretProviderClass: "app-secrets-gke"
Disable the Secret Manager add-on
To disable the Secret Manager add-on on an existing Standard cluster or on an Autopilot cluster, run the following command:
gcloud beta container clusters update CLUSTER_NAME \
--no-enable-secret-manager \
--region=REGION
Replace the following:
CLUSTER_NAME
: the name of your clusterREGION
: the region of your cluster, such asus-central1