Google Kubernetes Engine (GKE) uses instance metadata to configure node virtual machines (VMs), but some of this metadata is potentially sensitive and should be protected from workloads running on the cluster.
Before you begin
Before you start, make sure you have performed the following tasks:
- Enable the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI.
Configure node service account
Each node's service account credentials continue to be exposed to workloads. By default, your nodes use the Compute Engine default service account. You should configure a minimally-privileged service account for your nodes to use instead of the Compute Engine default service account. Then, attach this service account to your nodes, so that an attacker cannot circumvent GKE metadata protections by using the Compute Engine API to access the underlying VM instances directly.
For more information, refer to Use least privilege node service accounts.
To create a minimally privileged node service account, perform the following steps:
Create a new Identity and Access Management (IAM) service account and save the email address in an environment variable:
gcloud iam service-accounts create NODE_SA_NAME \ --display-name="DISPLAY_NAME" export NODE_SA_EMAIL=$(gcloud iam service-accounts list --format='value(email)' \ --filter='displayName:DISPLAY_NAME')
Replace the following:
NODE_SA_NAME: the name of your new node service account.
DISPLAY_NAME: the display name of the new service account.
The node service account email address has the format
Configure your service account with the minimum roles and permissions to run your GKE nodes:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:$NODE_SA_EMAIL \ --role=roles/monitoring.metricWriter gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:$NODE_SA_EMAIL \ --role=roles/monitoring.viewer gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:$NODE_SA_EMAIL \ --role=roles/logging.logWriter
PROJECT_IDwith your Google Cloud project ID.
Additionally, if your cluster pulls private images from Artifact Registry, add the
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:$NODE_SA_EMAIL \ --role=roles/artifactregistry.reader
GKE metadata concealment protects some potentially sensitive system metadata from user workloads running on your cluster.
In Kubernetes v1.9.3 and higher, you can enable metadata
concealment to prevent user Pods from accessing certain VM metadata in your
cluster's nodes, such as kubelet credentials and VM instance information.
Specifically, metadata concealment protects access to
kube-env (which contains
Kubelet credentials) and the VM's instance identity token.
Metadata concealment firewalls traffic from user Pods (Pods not running on
HostNetwork) to the cluster metadata server, only allowing safe queries. The
firewall prevents user Pods from using kubelet credentials for privilege
escalation attacks, or from using VM identity for instance escalation attacks.
You can only enable metadata concealment when creating a new cluster, or when adding a new node pool to an existing cluster.
- Metadata concealment only protects access to
kube-envand the node's instance identity token.
- Metadata concealment does not restrict access to the node's service account.
- Metadata concealment does not restrict access to other related instance metadata.
- Metadata concealment does not restrict access to other legacy metadata APIs.
Creating a new cluster or node pool with metadata concealment
After creating a service account, you can create a new cluster or node pool with metadata concealment enabled by using the Google Cloud CLI.
Create a new cluster
To create a cluster with metadata concealment enabled, run the following command:
gcloud beta container clusters create CLUSTER_NAME \ --workload-metadata-from-node=SECURE \ --service-account=$NODE_SA_EMAIL
CLUSTER_NAME with the name of your new cluster.
--workload-metadata-from-node flag takes the following values:
SECURE: enable metadata concealment.
UNSPECIFIED: disable metadata concealment.
Create a new node pool
To create a node pool with metadata concealment enabled, run the following command:
gcloud beta container node-pools create NODE_POOL_NAME \ --cluster=CLUSTER_NAME \ --workload-metadata-from-node=SECURE \ --service-account=$NODE_SA_EMAIL
NODE_POOL_NAME with the name of the new node
Verifying identity token metadata concealed from cluster's workload
When you conceal metadata, it should not be possible to request a signature
via the node's instance identity token. To verify that requests explicitly
inform users of concealed metadata, you can run a
curl command from
within a Pod:
curl -H "Metadata-Flavor: Google" \ 'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://www.example.com'
The output is similar to the following:
This metadata endpoint is concealed.
Disabling and transitioning from legacy metadata APIs
v1beta1 Compute Engine metadata server endpoints were deprecated
and shutdown on September 30, 2020.
For the shutdown schedule, refer to
v1beta1 metadata server endpoints deprecation.