GCP Authentication
To deploy infrastructure on Google Cloud Platform (GCP) using Terraform, you must authenticate Terraform to your GCP project. This guide covers real-life scenarios for local development, CI/CD pipelines, and multi-project setups, with best practices for security and automation.
1. Local Development: gcloud CLI & Application Default Credentials
The recommended way to authenticate locally is to use the Google Cloud SDK (gcloud
).
gcloud auth application-default login
This command creates an Application Default Credentials (ADC) file at ~/.config/gcloud/application_default_credentials.json
.
Provider block example:
provider "google" {
project = var.gcp_project
region = var.gcp_region
}
Terraform will automatically use ADC if no credentials are specified.
Best Practice: Use named configurations for multiple projects:
gcloud config configurations create dev
# Set project, region, etc.
gcloud config set project my-dev-project
gcloud config set compute/region us-central1
gcloud config configurations activate dev
2. Service Account Key File (for CI/CD and Automation)
For automation (GitHub Actions, GitLab CI, Azure Pipelines), use a GCP Service Account with the required IAM roles. Download its JSON key and store it securely (never commit to code).
Set the environment variable:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
Provider block example:
provider "google" {
credentials = file(var.gcp_credentials_file)
project = var.gcp_project
region = var.gcp_region
}
GitHub Actions Example:
jobs:
terraform:
runs-on: ubuntu-latest
env:
GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GCP_CREDENTIALS }}
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3
- name: Write GCP credentials
run: echo "$GOOGLE_APPLICATION_CREDENTIALS" > /tmp/account.json
- run: export GOOGLE_APPLICATION_CREDENTIALS=/tmp/account.json && terraform init
- run: export GOOGLE_APPLICATION_CREDENTIALS=/tmp/account.json && terraform apply -auto-approve
GitLab CI Example:
variables:
GOOGLE_APPLICATION_CREDENTIALS: /tmp/account.json
before_script:
- echo "$GCP_CREDENTIALS" > /tmp/account.json
stages:
- apply
apply:
stage: apply
image: hashicorp/terraform:1.7.5
script:
- terraform init
- terraform apply -auto-approve
3. Workload Identity Federation (OIDC for CI/CD)
For passwordless, keyless authentication in CI/CD, use Workload Identity Federation. This is the most secure and recommended approach for production pipelines.
Configure a Workload Identity Pool and Provider in GCP.
Grant the pool access to the required GCP resources.
Use OIDC tokens from GitHub Actions, GitLab, or Azure DevOps to authenticate.
GitHub Actions Example:
jobs:
terraform:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v4
- uses: google-github-actions/auth@v2
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
service_account: 'terraform-ci@my-project.iam.gserviceaccount.com'
- uses: hashicorp/setup-terraform@v3
- run: terraform init
- run: terraform apply -auto-approve
4. NixOS: Declarative GCP Credentials
Add credentials as environment variables in your NixOS configuration:
# configuration.nix
{
environment.variables = {
GOOGLE_APPLICATION_CREDENTIALS = "/etc/nixos/gcp-service-account.json";
};
}
Or use agenix for encrypted secrets.
Best Practices
Use Workload Identity Federation (OIDC) for CI/CD pipelines (no static keys)
Store service account keys in secret managers (never in code)
Grant least privilege IAM roles to service accounts
Rotate and audit service account keys regularly
Use named gcloud configurations for multi-project workflows
Never use user credentials in automation
References
Tip: For secure, auditable, and cloud-native deployments, prefer OIDC-based authentication for CI/CD and never commit service account keys to your repository.
- [Authenticating Terraform with GCP](pages/terraform/gcp/gpc_auth_terraform.md)
Last updated