This page explains how to configure managed workload identities using the gcloud CLI.
This page also describes how to set up automatic provisioning and lifecycle management of managed workload identities for Compute Engine. You configure certificate authority (CA) pools to issue certificates using Certificate Authority Service. CA Service is a highly-available, scalable Google Cloud service that simplifies and automates the deployment, management, and security of CA services. You can create virtual machine instances (VMs) that are provisioned with X.509 credentials from the configured CA pool. These credentials can then be used to establish mTLS connections between workloads.
Before you begin
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
Understand managed workload identities.
Learn about certificate issuance using Certificate Authority Service.
Learn how to authenticate Compute Engine workloads using managed workload identities.
Enable the IAM and Certificate Authority Service APIs:
gcloud services enable iam.googleapis.com
privateca.googleapis.com Configure Google Cloud CLI to use the project that was added to the allowlist for billing and quota.
gcloud config set billing/quota_project PROJECT_ID
Replace PROJECT_ID with the ID of the project that was added to the allowlist for the managed workload identity preview.
Required roles
To get the permissions that you need to create managed workload identities and provision managed workload identity certificates, ask your administrator to grant you the following IAM roles on the project:
-
To create and configure managed workload identities:
-
IAM Workload Identity Pool Admin (
roles/iam.workloadIdentityPoolAdmin
) -
Service Account Admin (
roles/iam.serviceAccountAdmin
)
-
IAM Workload Identity Pool Admin (
-
To create and configure CA pools:
CA Service Admin (
roles/privateca.admin
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Alternatively, the IAM Owner (roles/owner
) basic
role also includes permissions to configure managed workload identities.
You should not grant basic roles in a production environment, but you can grant them in a
development or test environment.
Overview
To use managed workload identities for your applications, you must perform the following tasks:
Security Administrator:
- Create managed workload identities in a workload identity pool.
- Define a workload attestation policy and create a service account.
- Configure Certificate Authority Service to issue certificates for managed workload identities.
- Authorize managed workload identities to request certificates from the CA pool.
- Define the trust and certificate issuance config.
- Create a configuration file to upload the partner metadata for a VM.
Compute Administrator:
Enable managed workload identities for workloads running in Compute Engine:
Create managed workload identities
Managed workload identities enables Google Cloud to automatically provision credentials for workload identity pool identities onto your workloads. Workload identities are defined within a workload identity pool, and are organized into administrative boundaries called namespaces.
Create a workload identity pool
You must create a pool in TRUST_DOMAIN
mode to create managed
workload identities. To create a workload identity pool for managed
workload identities, use the workload-identity-pools create
command.
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --mode="TRUST_DOMAIN"
Replace the following:
POOL_ID
: the unique ID for the pool. The ID must be between 4 and 32 characters, and can contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a workload identity pool, you can't change its ID.
To verify that your workload identity pool was created in
TRUST_DOMAIN
mode, use the
workload-identity-pools describe
command.
gcloud iam workload-identity-pools describe POOL_ID \ --location="global"
The command output should look similar to the following:
mode: TRUST_DOMAIN name: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID state: ACTIVE
If mode: TRUST_DOMAIN
is not present in the command output, verify
that your project has been added to the allowlist for the managed workload identity
Preview and that you've correctly configured your
gcloud CLI to use the correct project for billing and quota. You
might need to update to a newer version of the gcloud CLI.
Create a namespace
The workload-identity-pools namespaces create
command
lets you create a namespace in a workload identity pool.
gcloud iam workload-identity-pools namespaces create NAMESPACE_ID \ --workload-identity-pool="POOL_ID" \ --location="global"
Replace the following:
NAMESPACE_ID
: the unique ID for the namespace. The ID must be between 2 and 63 characters, contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a namespace, you cannot change its ID.POOL_ID
: the workload identity pool ID that you created earlier.
Create a managed workload identity
The workload-identity-pools managed-identities create
command
lets you create a managed workload identity in a workload identity pool.
gcloud iam workload-identity-pools managed-identities create MANAGED_IDENTITY_ID \ --namespace="NAMESPACE_ID" \ --workload-identity-pool="POOL_ID" \ --location="global"
Replace the following:
MANAGED_IDENTITY_ID
: the unique ID for the managed identity. The ID must be between 2 and 63 characters, contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a managed workload identity, you cannot change its ID.NAMESPACE_ID
: the namespace ID that you created earlier.POOL_ID
: the workload identity pool ID that you created earlier.
Your managed workload identity ID is the SPIFFE identifier, which is formatted as follows:
spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID
Define a workload attestation policy
A workload attestation policy ensures that only trusted workloads can use the managed identity.
When the workload runs and requests a credential for the managed workload identity ID, Google Cloud IAM uses the attribute that you define in the attestation policy to verify the Compute Engine instance. Verification is based on one of the following attributes of the workload:
- VM instance ID
- Attached service account email address
- Attached service account UID
After verification, the workload receives a credential.
Define a workload attestation policy with attestation rules
To create an attestation policy that allows your workload to use the managed identity, do the following:
Decide whether you want to create an attestation policy that allows your workload to attest the managed identity by using its attached service account or by using its instance ID.
Create a JSON-formatted attestation policy file.
(Optional) To receive X.509 credentials on your Compute Engine instance, you must enable an attached service account. We recommend that you attach a new service account to your workload by first creating it using the following command:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Replace
SERVICE_ACCOUNT_NAME
with the name of the service accountCreate a JSON-formatted attestation policy file that attests based on the service account email address, service account UID, or instance ID.
Service account email address
To create an attestation policy file that attests based on the service account email address, create a file with the following contents:
{ "attestationRules": [ { "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.email/SERVICE_ACCOUNT_EMAIL" } ], }
Replace the following:
WORKLOAD_PROJECT_NUMBER
: the number of the project that contains the VM instance or service account
To get the project number of the project that contains the managed identity or the service account that you just created, run the following command:
gcloud projects describe $(gcloud config get-value project) \ --format="value(projectNumber)"
SERVICE_ACCOUNT_EMAIL
: the email address of the service account attached to the VM
Service account UID
To create an attestation policy file that attests based on the service account UID, create a file with the following contents:
{ "attestationRules": [ { "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.uid/SERVICE_ACCOUNT_UID" } ], }
Replace the following:
WORKLOAD_PROJECT_NUMBER
: the number of the project that contains the VM instance or service account
To get the project number of the project that contains the managed identity or the service account that you just created, run the following command:
gcloud projects describe $(gcloud config get-value project) \ --format="value(projectNumber)"
SERVICE_ACCOUNT_UID
: the UID of the service account attached to the VM
Instance ID
To create an attestation policy file that attests based on the instance ID, create a file with the following contents:
{ "attestationRules": [ { "googleCloudResource": "//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/uid/zones/ZONE/instances/INSTANCE_ID" } ], }
Replace the following:
WORKLOAD_PROJECT_NUMBER
: the number of the project that contains the VM instance or service account
To get the project number of the project that contains the managed identity or the service account that you just created, run the following command:
gcloud projects describe $(gcloud config get-value project) \ --format="value(projectNumber)"
INSTANCE_ID
: the Compute Engine VM instance ID
The value for an instance ID must come from an existing Compute Engine instance. To obtain your instance ID, run the following command:
gcloud compute instances describe INSTANCE_NAME --zone=ZONE --format="get(id)"
INSTANCE_NAME
: the Compute Engine VM instance nameZONE
: the Compute Engine VM zone
Create the attestation policy using the policy JSON file that you created earlier in this document:
gcloud iam workload-identity-pools managed-identities set-attestation-rules MANAGED_IDENTITY_ID \ --namespace=NAMESPACE_ID \ --workload-identity-pool=POOL_ID \ --policy-file=PATH_TO_POLICY_JSON_FILE \ --location=global
Replace the following:
MANAGED_IDENTITY_ID
: the unique ID for the managed identity. The ID must be between 2 and 63 characters, contain only lowercase alphanumeric characters and dashes, and start and end with an alphanumeric character. After you create a managed workload identity, you cannot change its ID.NAMESPACE_ID
: the namespace ID that you created earlier.POOL_ID
: the workload identity pool ID that you created earlier.PATH_TO_POLICY_JSON_FILE
: Path to the JSON file representing the attestation policy that you created earlier.
You can also update the policy by adding or removing attestation rules individually. To add an attestation to your attestation policy, run the following command:
gcloud iam workload-identity-pools managed-identities add-attestation-rule MANAGED_IDENTITY_ID \ --namespace=NAMESPACE_ID \ --workload-identity-pool=POOL_ID \ --google-cloud-resource='//compute.googleapis.com/projects/WORKLOAD_PROJECT_NUMBER/type/Instance/attached_service_account.uid/SERVICE_ACCOUNT_UID' \ --location=global
To learn about how to list or remove the attestation rules, run the following commands:
gcloud iam workload-identity-pools managed-identities list-attestation-rules --help gcloud iam workload-identity-pools managed-identities remove-attestation-rule --help
(Deprecated) Define a workload attestation policy with workload sources
To create an attestation policy that uses your service account as the single-attribute selector for your managed identity, run the following command:
Attest using VM instance ID
To create an attestation policy that uses your VM instance ID as the single-attribute selector for your managed identity, do the following:
- Configure your CA hierarchy.
- Define your trust and certificate issuance config.
- Start your managed instance group or individual VM. You can deploy your managed instance group or individual VM using either an explicitly defined service account or the Compute Engine default service account.
Run the following command to extract your instance ID:
gcloud compute instances describe INSTANCE_NAME --zone=ZONE --format="get(id)"
Use the returned instance ID in the following command:
gcloud iam workload-identity-pools managed-identities workload-sources create \ project-WORKLOAD_PROJECT_NUMBER \ --single-attribute-selectors="compute.googleapis.com/Instance.uid=projects/WORKLOAD_PROJECT_NUMBER/zones/ZONE/instances/INSTANCE_ID" \ --managed-identity=MANAGED_IDENTITY_ID \ --namespace=NAMESPACE_ID \ --workload-identity-pool=POOL_ID \ --location="global"
Replace the following:
WORKLOAD_PROJECT_NUMBER
: the project number for the project that contains your workload. The policy allows workloads within this project to use the managed workload identity.ZONE
: the zone where the workload is deployed.INSTANCE_ID
: the instance ID of the workload.MANAGED_IDENTITY_ID
: the unique ID for the managed identity.NAMESPACE_ID
: the namespace ID that you created earlier.POOL_ID
: the workload identity pool ID that you created earlier.
Attest using attached service account
To create an attestation policy that uses your service account as the single-attribute selector for your managed identity, run the following command:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Replace the following:
SERVICE_ACCOUNT_NAME
: the name of the service account
To create a workload attestation policy that allows your workloads with the service account attached to be issued credentials for the managed workload identity, run the following command:
gcloud iam workload-identity-pools managed-identities workload-sources create \ project-WORKLOAD_PROJECT_NUMBER \ --single-attribute-selectors="compute.googleapis.com/Instance.attached_service_account.email=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --managed-identity=MANAGED_IDENTITY_ID \ --namespace=NAMESPACE_ID \ --workload-identity-pool=POOL_ID \ --location="global"
Replace the following:
SERVICE_ACCOUNT_NAME
: the name of the service account.WORKLOAD_PROJECT_NUMBER
: the project number for the project that contains your workload. The policy allows workloads within this project to use the managed workload identity.PROJECT_ID
: the ID of the project containing the service account.MANAGED_IDENTITY_ID
: the unique ID for the managed identity.NAMESPACE_ID
: the namespace ID that you created. earlier.POOL_ID
: the workload identity pool ID that you created earlier.
For a given workload identity pool, you can define a maximum of 50 single attribute selectors for your workload project.
To learn about how to update or delete an attestation policy, run the following command:
gcloud iam workload-identity-pools managed-identities workload-sources --help
Configure Certificate Authority Service to issue certificates for managed workload identities
Create the recommended set up for root and subordinate certificate authorities (CAs) using Certificate Authority Service pools. The subordinate CA pool issues the X.509 workload identity certificates to VMs.
After configuring the CA pools, you then authorize the managed workload identities to request and receive the signed certificates from the CA pools.
Configure the root CA pool
Use the Google Cloud CLI interface to Certificate Authority Service to configure a root CA pool.
gcloud
Create the root CA pool.
Create the root CA pool in the Enterprise tier, which is meant for long-lived, low-volume certificate issuance using the
gcloud privateca pools create
command.gcloud privateca pools create ROOT_CA_POOL_ID \ --location=REGION \ --tier=enterprise
Replace the following:
- ROOT_CA_POOL_ID: a unique ID for the root CA pool. The ID can be up to 64 characters in length and must contain only lower and uppercase alphanumeric characters, underscores, or hyphens. The pool ID must be unique within the region.
- REGION: the region where the root CA pool is located.
For more information, see Creating CA pools.
Create a root CA in the root CA pool using the
gcloud privateca roots create
command. You might be prompted to enable the root CA if this is the only CA in the root CA Pool.For example, you might use a command similar to the following to create a root CA.
gcloud privateca roots create ROOT_CA_ID \ --pool=ROOT_CA_POOL_ID \ --subject "CN=ROOT_CA_CN, O=ROOT_CA_ORGANIZATION" \ --key-algorithm="ec-p256-sha256" \ --max-chain-length=1 \ --location=REGION
Replace the following:
- ROOT_CA_ID: a unique name for the root CA. The CA name can be up to 64 characters in length and must contain only lower and uppercase alphanumeric characters, underscores, or hyphens. The CA name must be unique within the region.
- ROOT_CA_POOL_ID: the ID of the root CA pool.
- ROOT_CA_CN: the common name of the root CA.
- ROOT_CA_ORGANIZATION: the organization of the root CA.
- REGION: the region where the root CA pool is located.
For more information, see Create a root certificate authority. For more information about the
subject
fields for the CA, see Subject.Optional: Repeat the previous steps to create an additional root CA in the root CA pool. This can be useful for root CA rotation.
Configure the subordinate CAs
Use the Google Cloud CLI interface to Certificate Authority Service to create a subordinate CA pool and subordinate CA.
If you have multiple certificate issuance scenarios, you can create a subordinate CA for each of those scenarios. Also, adding multiple subordinate CAs in a CA pool helps you achieve better load-balancing of certificate requests.
gcloud
Use the gcloud privateca pools create
command
to create a subordinate CA pool.
Create the subordinate CA pool in the DevOps tier, which is meant for high volume, short-lived certificate issuance .
gcloud privateca pools create SUBORDINATE_CA_POOL_ID \ --location=REGION \ --tier=devops
Replace the following:
- SUBORDINATE_CA_POOL_ID: a unique ID for the subordinate CA pool. The ID can be up to 64 characters in length and must contain only lowercase and uppercase alphanumeric characters, underscores, or hyphens. The pool ID must be unique within the region.
- REGION: the region in which to create the subordinate CA pool.
For more information, see Creating CA pools.
Create a subordinate CA in the subordinate CA pool using the
gcloud privateca subordinates create
command. Don't change the default config-based issuance mode.For example, you might use a command similar to the following to create a subordinate CA.
gcloud privateca subordinates create SUBORDINATE_CA_ID \ --pool=SUBORDINATE_CA_POOL_ID \ --location=REGION \ --issuer-pool=ROOT_CA_POOL_ID \ --issuer-location=REGION \ --subject="CN=SUBORDINATE_CA_CN, O=SUBORDINATE_CA_ORGANIZATION" \ --key-algorithm="ec-p256-sha256" \ --use-preset-profile=subordinate_mtls_pathlen_0
Replace the following:
- SUBORDINATE_CA_ID: a unique name for the subordinate CA. The name can be up to 64 characters in length and must contain only lowercase and uppercase alphanumeric characters, underscores, or hyphens. The pool name must be unique within the region.
- SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool.
- REGION: the region where the subordinate CA pool is located.
- ROOT_CA_POOL_ID: the ID of the root CA pool.
- REGION: the region of the root CA pool.
- SUBORDINATE_CA_CN: the common name of the subordinate CA.
- SUBORDINATE_CA_ORGANIZATION: the name of the subordinate CA issuing organization.
For more information, see Creating CA pools. For more information about the
subject
fields for the CA, see Subject.
Authorize managed workload identities to request certificates from the CA pool
The managed workload identities require permissions to request certificates from the CA Service and get the public certificates.
gcloud
Grant the CA Service Workload Certificate Requester (
roles/privateca.workloadCertificateRequester
) IAM role on each subordinate CA pool to the managed workload identity. The followinggcloud privateca pools add-iam-policy-binding
command authorizes the managed workload identity to request certificates from the CA Service certificate chains.gcloud privateca pools add-iam-policy-binding SUBORDINATE_CA_POOL_ID \ --location=REGION \ --role=roles/privateca.workloadCertificateRequester \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"
Replace the following:
- SUBORDINATE_CA_POOL_ID: the ID for the subordinate CA pool.
- REGION: the region of the subordinate CA pool.
- PROJECT_NUMBER: the project number of the project that contains the workload identity pool.
- POOL_ID: the ID of the workload identity pool.
Grant the CA Service Pool Reader (
roles/privateca.poolReader
) IAM role on the subordinate CA pools to the managed workload identity. This authorizes the managed workload identity to get the signed X.509 certificates from the CA's certificate chains.gcloud privateca pools add-iam-policy-binding SUBORDINATE_CA_POOL_ID \ --location=REGION \ --role=roles/privateca.poolReader \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*"
Replace the following:
- SUBORDINATE_CA_POOL_ID: the ID for the subordinate CA pool.
- REGION: the region of the subordinate CA pool.
- PROJECT_NUMBER: the project number of the project that contains the workload identity pool.
- POOL_ID: the ID of the workload identity pool.
Define the trust and certificate issuance config
You use this information to create a JSON file that is uploaded as partner data when creating a VM.
Define the certificate issuance config
The following certificate issuance config is required to enable managed workload identities for Compute Engine.
{ "primary_certificate_authority_config": { "certificate_authority_config": { "ca_pool": "projects/SUBORDINATE_CA_POOL_PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID" } }, "key_algorithm": "ALGORITHM", "workload_certificate_lifetime_seconds": DURATION, "rotation_window_percentage": ROTATION_WINDOW_PERCENTAGE }
Replace the following:
- SUBORDINATE_CA_POOL_PROJECT_ID: the ID of the project that contains the subordinate CA pool.
- REGION: the region where the subordinate CA pool is located.
- SUBORDINATE_CA_POOL_ID: the name of the subordinate CA pool
- ALGORITHM: the encryption algorithm used to generate the
private key. Valid values are
rsa-2048
(default),rsa-3072
,rsa-4096
,ecdsa-p256
andecdsa-p384
. - DURATION: Optional: The leaf certificate validity duration, in seconds. The value must be between 3600 and 315360000. If not specified, the default value of 86400 is used. The actually validity of the issued certificate also depends on the issuing CA, because it may restrict the lifetime of the issued certificate.
- ROTATION_WINDOW_PERCENTAGE: Optional: The percentage of the certificate's lifetime at which a renewal triggers. Value must be between 1 and 100. The default value is 66 percent. You must set the rotation window percentage in relation to the certificate lifetime so that certificate renewal occurs at least 7 days after the certificate has been issued and at least 7 days before it expires.
Define the trust config
The trust config contains the set of trust anchors for validating peer certificates. This includes the following:
- Trusted CA pool resource URIs: A set of CA pool resource URIs that are trusted to issue certificates in the same trust domain as the VMs belongs to.
- PEM formatted CA certificates: A set of PEM-formatted CA certificates trusted to issue certificates in the same trust domain as the VMs belongs to.
{ "POOL_ID.global.PROJECT_NUMBER.workload.id.goog": { "trust_anchors": [ { "ca_pool": "projects/SUBORDINATE_CA_POOL_PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID" }, { "pem_certificate": "PEM_ENCODED_CERTIFICATE" } ] } }
Replace the following:
- POOL_ID: the ID of the workload identity pool
- PROJECT_NUMBER: the project number of the project that that contains the workload identity pool
- SUBORDINATE_CA_POOL_PROJECT_ID: the ID of the project that contains the subordinate CA pool.
- REGION: the region where the subordinate CA pool is located
- SUBORDINATE_CA_POOL_ID: the ID of the subordinate CA pool
PEM_ENCODED_CERTIFICATE: Optional: a set of additional PEM-formatted CA certificates trusted to issue certificates in the same trust domain that the VMs belongs to. These certificates will be added to the subordinate CA pool's list of trust anchors. The following command can be used to encode a PEM-formatted
trust-anchor.pem
file into a one-line string:cat trust-anchor.pem | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g'
Create a configuration file to upload the partner metadata for a VM
Create a JSON file that contains the following:
- The configuration for the workload identity
- The information from Define the certificate issuance config
- The information from Define the trust config
Save this file as CONFIGS.json
. This file is used when creating VMs to
run applications that use managed workload identities.
Your CONFIGS.json
file should be similar to the following:
{ "wc.compute.googleapis.com": { "entries": { "certificate-issuance-config": { "primary_certificate_authority_config": { "certificate_authority_config": { "ca_pool": "projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID" } }, "key_algorithm": "ALGORITHM" }, "trust-config": { "POOL_ID.global.PROJECT_NUMBER.workload.id.goog": { "trust_anchors": [{ "ca_pool": "projects/PROJECT_ID/locations/REGION/caPools/SUBORDINATE_CA_POOL_ID" }] } } } }, "iam.googleapis.com": { "entries": { "workload-identity": "spiffe://POOL_ID.global.PROJECT_NUMBER.workload.id.goog/ns/NAMESPACE_ID/sa/MANAGED_IDENTITY_ID" } } }
What's next
- Configure workload to workload authentication using mTLS.
- Learn more about creating CA pools.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Get started for free