GCP
Prerequisites
To manage any Cloud Account using the instructions below, you need:
-
The humctl CLI installed
-
Authentication against the Platform Orchestrator via
humctl login
-
The
gcloud
CLI installed -
These environment variables set:
export HUMANITEC_ORG=<your-humanitec-org-id>
GCP Service account impersonation
Credentials: temporary
Available Inputs
/Outputs
: see the Cloud Account types reference
How it works
GCP temporary credentials make use of IAM Service account impersonation in conjunction with OIDC-based Workload identity federation. You need to first create a workload identity pool and then add a policy binding between the pool principal and a GCP service account.
The setup involves the Humanitec Platform Orchestrator OIDC provider.
Prepare your environment
-
Define the Google Cloud project ID where to create the IAM objects:
export GCP_PROJECT_ID=<my-gcp-project-id>
Create an identity pool
-
Create a workload identity pool:
gcloud iam workload-identity-pools create humanitec-wif-pool \ --location="global" \ --project ${GCP_PROJECT_ID}
-
Create a new OIDC workload identity pool provider in that pool:
gcloud iam workload-identity-pools providers create-oidc humanitec-wif \ --location="global" \ --workload-identity-pool="humanitec-wif-pool" \ --issuer-uri="https://idtoken.humanitec.io" \ --attribute-mapping="google.subject=assertion.sub" \ --project=${GCP_PROJECT_ID}
Create the Cloud Account for temporary credentials
-
Create a GCP service account to be used by the Humanitec Cloud Account:
Define the service account name:
export SERVICE_ACCOUNT_NAME=my-gcp-temp-cloud-account
Create the service account:
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME} \ --description="Used by Humanitec Platform Orchestrator Cloud Account" \ --display-name=${SERVICE_ACCOUNT_NAME} \ --project=${GCP_PROJECT_ID}
-
Define the naming of the new Cloud Account:
export CLOUD_ACCOUNT_NAME="My GCP Temporary Cred Account" export CLOUD_ACCOUNT_ID=my-gcp-temp-cloud-account
-
Add this policy binding between the service account and workload identity federation principal to enable it for service account impersonation:
export GCP_PROJECT_NUMBER=$(gcloud projects describe ${GCP_PROJECT_ID} --format='get(projectNumber)') gcloud iam service-accounts add-iam-policy-binding ${SERVICE_ACCOUNT_NAME}@${GCP_PROJECT_ID}.iam.gserviceaccount.com \ --member=principal://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/humanitec-wif-pool/subject/${HUMANITEC_ORG}/${CLOUD_ACCOUNT_ID} \ --role=roles/iam.workloadIdentityUser \ --format=json
-
Create a Cloud Account in the Platform Orchestrator.
If you haven’t already done so (see Prerequisites), define these environment variables:
export HUMANITEC_ORG=<your-humanitec-org-id>
Create the Cloud Account:
Create a file defining the Cloud Account you want to create:
cat << EOF > gcp-identity-cloudaccount.yaml apiVersion: entity.humanitec.io/v1b1 kind: Account metadata: id: ${CLOUD_ACCOUNT_ID} entity: name: ${CLOUD_ACCOUNT_NAME} type: gcp-identity credentials: gcp_service_account: ${SERVICE_ACCOUNT_NAME}@${GCP_PROJECT_ID}.iam.gserviceaccount.com gcp_audience: //iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/humanitec-wif-pool/providers/humanitec-wif EOF
Use the
humctl create
command to create the Cloud Account in the Organization defined by your configured context:humctl apply -f gcp-identity-cloudaccount.yaml rm gcp-identity-cloudaccount.yaml
Using the Humanitec Terraform Provider:
resource "humanitec_resource_account" "gcp-identity" { id = var.gcp_service_account_temporary_account_id name = var.gcp_service_account_temporary_account_name type = "gcp-identity" credentials = jsonencode({ "gcp_service_account" = "${var.gcp_service_account_temporary_account_id}@${var.gcp_project_id}.iam.gserviceaccount.com" "gcp_audience" = "//iam.googleapis.com/projects/${var.gcp_project_number}/locations/global/workloadIdentityPools/humanitec-wif-pool/providers/humanitec-wif" }) }
Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.
-
Assign the required roles to the Service Account.
The Cloud Account is now ready for use by any Drivers supporting the
gcp-identity
Account type. Remember to assign the required permissions to the Service Account on the target GCP services depending on the kind of operations it needs to perform.For access to a GKE cluster, refer to the Kubernetes page for guidance.
-
Test the Cloud Account.
The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type
gcp-identity
, the GCP IAM Principal identifier will be displayed.The check operation can be called using the specific CLI command.
humctl resources check-account ${CLOUD_ACCOUNT_ID}
Note that this check does not validate permissions assigned to the Service Account that may be used to provision or connect infrastructure during deployments.
Example: connect to a GKE cluster using temporary credentials
This example Resource Definition uses the GKE cluster Driver to connect to an GKE cluster. It includes a Cloud Account of type gcp-identity
via the driver_account
setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.
gke-temporary-credentials.yaml
(view on GitHub)
:
# Connect to a GKE cluster using temporary credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
id: gke-temporary-credentials
entity:
name: gke-temporary-credentials
type: k8s-cluster
# The driver_account references a Cloud Account of type "gcp-identity"
# which needs to be configured for your Organization.
driver_account: gcp-temporary-creds
driver_type: humanitec/k8s-cluster-gke
driver_inputs:
values:
loadbalancer: 35.10.10.10
name: demo-123
zone: europe-west2-a
project_id: my-gcp-project
GCP Service account keys
Credentials: static
Available Inputs
/Outputs
: see the Cloud Account types reference
Create the Cloud Account for static credentials
-
Create a GCP service account which will be used by the Humanitec Platform Orchestrator.
export SERVICE_ACCOUNT_NAME="humanitec-sa" gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \ --description="Used by Humanitec Platform Orchestrator" \ --display-name=$SERVICE_ACCOUNT_NAME export SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list --filter="displayName:$SERVICE_ACCOUNT_NAME" --format=json | jq -rM '.[0].email') gcloud iam service-accounts keys create key.json \ --iam-account=$SERVICE_ACCOUNT_EMAIL
Export the values needed for the Cloud Account:
export SERVICE_ACCOUNT_KEY=$(yq -o yaml key.json | sed 's/^/ /') rm ./key.json
-
Create a Cloud Account in the Platform Orchestrator.
Define the name and id of the new Cloud Account:
export CLOUD_ACCOUNT_NAME="My GCP Cred Account" export CLOUD_ACCOUNT_ID=my-gcp-cred
If you haven’t already done so (see Prerequisites), define these environment variables:
export HUMANITEC_ORG=<your-humanitec-org-id>
Create the Cloud Account:
Create a file defining the Cloud Account you want to create:
cat << EOF > gcp-cloudaccount.yaml apiVersion: entity.humanitec.io/v1b1 kind: Account metadata: id: ${CLOUD_ACCOUNT_ID} entity: name: ${CLOUD_ACCOUNT_NAME} type: gcp credentials: ${SERVICE_ACCOUNT_KEY} EOF
Use the
humctl create
command to create the Cloud Account in the Organization defined by your configured context:humctl apply -f gcp-cloudaccount.yaml rm gcp-cloudaccount.yaml
Using the Humanitec Terraform Provider:
resource "humanitec_resource_account" "gcp" { id = var.cloud_account_id name = var.cloud_account_name type = "gcp" credentials = jsonencode(var.service_account_key) }
Inside the API, Cloud Accounts are called Resource Accounts, both represent the same entity.
-
Assign the required roles to the Service Account.
The Cloud Account is now ready for use by any Drivers supporting the
gcp
Account type. Remember to assign the required permissions to the Service Account on the target GCP services depending on the kind of operations it needs to perform.For access to a GKE cluster, refer to the Kubernetes page for guidance.
-
Test the Cloud Account.
The Humanitec Platform Orchestrator provides a mechanism for testing the Cloud Account and ensuring that the credential meets the input and output schema requirements and that any token exchange succeeds. The output will provide any errors or warnings that prevent the Cloud Account from being used and will also include any identifiers of the token identity or target account. For accounts of type
gcp
, the GCP IAM Principal identifier will be displayed.The check operation can be called using the specific CLI command.
humctl resources check-account ${CLOUD_ACCOUNT_ID}
Note that this check does not validate permissions assigned to the Service Account that may be used to provision or connect infrastructure during deployments.
Example: connect to a GKE cluster using static credentials
This example Resource Definition uses the GKE cluster Driver to connect to an GKE cluster. It includes a Cloud Account of type gcp
via the driver_account
setting. The Cloud Account credentials will be automatically picked up by the Driver with no further configuration required.
gke-static-credentials-cloudaccount.yaml
(view on GitHub)
:
# Connect to a GKE cluster using static credentials defined via a Cloud Account
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
id: gke-static-credentials-cloudaccount
entity:
name: gke-static-credentials-cloudaccount
type: k8s-cluster
# The driver_account references a Cloud Account of type "gcp"
# which needs to be configured for your Organization.
driver_account: gcp-static-creds
driver_type: humanitec/k8s-cluster-gke
driver_inputs:
values:
loadbalancer: 35.10.10.10
name: demo-123
zone: europe-west2-a
project_id: my-gcp-project