Managing Google Cloud Platform (GCP) service accounts is a critical component of modern DevOps and infrastructure-as-code workflows. Service accounts act as the digital identities for non-human entities, such as CI/CD pipelines, backend applications, and automation tools like Terraform. Unlike personal user accounts, service accounts are project-owned, allowing for precise permission scoping through Identity and Access Management (IAM). This article provides a comprehensive technical analysis of managing these identities using Terraform, focusing on the terraform-google-service-accounts module, authentication mechanisms, and security best practices for production environments.

The Role of Service Accounts in GCP Automation

A GCP service account is a special type of Google account that belongs to a specific project rather than an individual user. It serves as the standard identity for automated workloads, including Terraform execution, CI/CD pipelines, and distributed applications. Each service account is defined by three core components: a unique email address, typically formatted as NAME@PROJECT_ID.iam.gserviceaccount.com, a cryptographic key pair for authentication, and a set of IAM role bindings that dictate its operational permissions.

When deploying infrastructure in production, relying on personal user accounts for Terraform is insecure and unsustainable. Personal accounts lack the granular permission scoping required for least-privilege security models and cannot be easily rotated or audited in the context of automated deployments. Dedicated service accounts allow teams to assign specific roles, such as roles/compute.admin or roles/storage.admin, ensuring that the automation process only accesses the resources it needs. This separation of duties is fundamental to cloud security governance, enabling organizations to track changes to infrastructure while maintaining strict control over resource access.

The Terraform Service Accounts Module

For declarative management of these identities, the terraform-google-service-accounts module is the standard solution. Maintained as part of the Cloud Foundation Toolkit, this module follows Google Cloud best practices for infrastructure management. It addresses the operational overhead of manually managing service accounts by providing a modular architecture with distinct entry points for various workflows.

The root module utilizes Terraform’s for_each meta-argument to manage multiple service accounts and their associated IAM bindings simultaneously. This capability allows for the provisioning of a fleet of service accounts with consistent naming conventions and permission sets across an organization. The module is designed for Terraform 0.13 and later, with tested compatibility for Terraform 1.0 and above. For teams still using older versions, the last released version intended for Terraform 0.12.x is v3.0.1, though upgrading to newer Terraform versions is strongly recommended for compatibility and security reasons.

Module Architecture and Capabilities

The terraform-google-service-accounts module allows for the easy creation of one or more service accounts and the granting of basic roles. It automates the provisioning of service accounts, assignment of IAM roles at multiple scopes (project, organization, and billing), and optional key generation. The module also includes specialized submodules for simplified single-account creation and secure key distribution.

The module creates or triggers the following resources and services:
- One or more service accounts.
- Optional project-level IAM role bindings for each service account.
- One optional billing IAM role binding per service account, applicable at the organization or billing account level.
- Two optional organization-level IAM bindings per service account, specifically to enable the service accounts to create and manage Shared VPC networks.
- One optional service account key per service account.

The modular design supports complex configurations where different service accounts require different levels of access. For instance, one account might need broad roles/editor access for initial setup, while another requires strict roles/viewer access for monitoring purposes. The module’s ability to handle Shared VPC network management is particularly relevant for multi-project organizations that require central control over network resources.

Basic Usage and Configuration

Configuring the terraform-google-service-accounts module is straightforward. A basic implementation involves specifying the source version, the target project ID, and the desired roles. The following example demonstrates how to create two service accounts, "first" and "second", with specific project-level permissions.

```hcl
module "service_accounts" {
source = "terraform-google-modules/service-accounts/google"
version = "~> 4.0"

project_id = ""
prefix = "test-sa"
names = ["first", "second"]

project_roles = [
"project-foo=>roles/viewer",
"project-spam=>roles/storage.objectViewer",
]
}
```

In this configuration, the project_roles argument uses a syntax where the key is the target project ID and the value is the IAM role to assign. This allows for cross-project permission management, a common requirement in complex GCP architectures where service accounts in one project need access to resources in another. Functional examples are typically included in the module’s examples directory, providing further guidance for advanced use cases.

Authentication Methods for Terraform

Once service accounts are provisioned, the next critical step is configuring Terraform to authenticate with them. There are several methods available, each with different security implications and operational requirements. The choice of authentication method depends on whether Terraform is running on-premises, on a different cloud provider, or within GCP itself.

Method 1: Service Account Key File

The most traditional method involves generating a JSON key and pointing Terraform at it. This approach is suitable for on-premises environments where other identity providers are not available. To use this method, first generate and download a key file using the gcloud CLI.

```bash

Create and download a key file

gcloud iam service-accounts keys create terraform-key.json \
--iam-account="terraform@${PROJECT_ID}.iam.gserviceaccount.com"
```

The resulting file contains private key material and must be handled securely. It is recommended to restrict file permissions immediately after creation.

```bash

Restrict permissions to owner only

chmod 600 terraform-key.json
```

In the Terraform configuration, the google provider can be configured to use this file directly.

hcl provider "google" { project = var.project_id region = "us-central1" credentials = file("terraform-key.json") }

Alternatively, and preferably, the credentials can be provided via environment variables to avoid hardcoding file paths or credentials in the Terraform code.

```bash

Set the credentials via environment variable

export GOOGLE_CREDENTIALS=$(cat terraform-key.json)

Or point to the file path

export GOOGLEAPPLICATIONCREDENTIALS="/path/to/terraform-key.json"
```

When using environment variables, the credentials argument can be omitted from the provider configuration, as Terraform will automatically read from GOOGLE_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS.

hcl provider "google" { project = var.project_id region = "us-central1" # Reads from GOOGLE_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS }

It is important to note that service account keys are long-lived credentials. They do not expire automatically and must be rotated manually. This makes them a security risk if compromised. Therefore, this method should be used only when necessary, such as in air-gapped environments or legacy systems that do not support modern authentication protocols.

Method 2: Service Account Impersonation

Service account impersonation is a more secure approach that avoids the need to manage static key files. It allows a user or another identity to assume the identity of a service account. This method requires the principal performing the impersonation to have the roles/iam.serviceAccountTokenCreator IAM role on the service account being impersonated.

To set up local authentication using impersonation, you can create a local Application Default Credentials (ADC) file. Terraform uses these credentials automatically.

bash gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

For scenarios where users need to share a primary authentication source but use a different service account per environment, the impersonate_service_account field can be set in the Terraform provider configuration.

hcl provider "google" { project = var.project_id region = "us-central1" impersonate_service_account = "SERVICE_ACCT_EMAIL" }

This approach is particularly useful in multi-environment setups where the same developer needs to deploy to dev, staging, and production projects, each with a different service account identity. The developer authenticates once with their user account, which has the necessary permissions to impersonate all three service accounts.

Method 3: Workload Identity Federation

For workloads running outside of Google Cloud, such as in AWS, Azure, or on-premises Kubernetes clusters, Workload Identity Federation (WIF) is the preferred authentication method. WIF allows external Identity Providers (IdP) to exchange credentials for GCP access without needing to manage static keys or service account keys.

This method eliminates the risk of key leakage and provides dynamic, short-lived credentials. To use WIF, you must configure a workload identity pool and provider in GCP, then map the external identity to a GCP service account. The Terraform provider supports WIF by reading the credentials from the standard ADC file or environment variables set by the external workload environment.

IAM Role Binding and Least Privilege

Assigning the correct IAM roles to service accounts is as important as creating the accounts themselves. Overly permissive roles, such as roles/editor or roles/owner, can lead to security vulnerabilities and unexpected costs. The principle of least privilege should guide all role assignments.

For a general-purpose Terraform service account, it may be necessary to use a broad role like roles/editor during initial setup to avoid permission errors while building out complex infrastructure. However, this access should be tightened as soon as possible. A more secure approach is to assign specific roles based on the resources being managed.

```bash

Grant specific roles

gcloud projects add-iam-policy-binding $PROJECTID \
--member="serviceAccount:terraform@${PROJECTID}.iam.gserviceaccount.com" \
--role="roles/cloudsql.admin"
```

To audit current permissions, you can list the roles assigned to a specific service account.

bash gcloud projects get-iam-policy $PROJECT_ID \ --flatten="bindings[].members" \ --filter="bindings.members:terraform@${PROJECT_ID}.iam.gserviceaccount.com" \ --format="table(bindings.role)"

When a Terraform run fails due to permission issues, the error message typically indicates the specific permission that is missing. In such cases, add only the necessary role rather than granting broad access. Common roles for Terraform include roles/compute.admin for managing VMs, roles/storage.admin for managing buckets, and roles/container.admin for managing GKE clusters.

Running Terraform on Google Cloud

When Terraform runs within Google Cloud itself, authentication is simplified. In environments such as Cloud Shell, Terraform uses the credentials provided when the user signed in for authentication. For resources running on Compute Engine, App Engine, or Cloud Run functions, you can attach a user-managed service account to the resource. Generally, attaching a service account is supported when the service’s resources can run or include application code.

In these cases, the service account attached to the virtual machine or function acts as the identity for the Terraform process. You do not need to manage keys or environment variables; the metadata server or container runtime provides the credentials automatically. This is the most secure and operationally efficient way to run Terraform in GCP, as it leverages the platform’s built-in identity management.

Common Troubleshooting Scenarios

Despite best practices, users may encounter errors when working with service accounts and Terraform. Understanding common error messages and their resolutions can save significant time.

"API not Enabled"

GCP requires you to enable APIs before using them. If Terraform fails with an "API not enabled" error, you must enable the required services.

bash gcloud services enable compute.googleapis.com gcloud services enable container.googleapis.com gcloud services enable sqladmin.googleapis.com gcloud services enable storage.googleapis.com

"Service account does not exist"

This error usually indicates a typo in the service account email address. Ensure the format is NAME@PROJECT_ID.iam.gserviceaccount.com. The project ID must match the one where the service account was created.

Permission Denied

If you receive a permission denied error, verify that the service account has the necessary IAM roles. Use the audit command mentioned earlier to check the current bindings. Remember that IAM changes can take a few minutes to propagate.

Security Best Practices

To ensure secure and efficient management of GCP service accounts with Terraform, adhere to the following best practices:

• Prefer keyless authentication methods such as Workload Identity Federation or service account impersonation over static key files.
• Keep credentials out of Terraform code by using environment variables or the provider’s built-in credential chain.
• Use the least privilege principle when assigning IAM roles, avoiding broad roles like roles/owner unless absolutely necessary.
• Regularly audit service account permissions and remove unused accounts and keys.
• Use organization-level IAM bindings for Shared VPC networks to maintain central control.
• Rotate service account keys if they must be used, and monitor their usage.

Conclusion

The management of GCP service accounts is a foundational aspect of secure and scalable cloud infrastructure. The terraform-google-service-accounts module provides a robust, declarative interface for creating and managing these identities, supporting complex scenarios such as multi-project IAM bindings and Shared VPC network management. By combining this module with secure authentication methods like Workload Identity Federation and service account impersonation, organizations can eliminate the risks associated with static keys and enforce strict least-privilege access controls.

Terraform’s integration with GCP’s IAM system allows for precise control over the permissions granted to automated workloads. Whether running Terraform on-premises or within GCP itself, the choice of authentication method and IAM roles should be tailored to the specific security and operational requirements of the environment. As cloud architectures grow in complexity, the ability to manage service accounts programmatically and securely becomes increasingly critical. By following the practices outlined in this article, teams can ensure that their infrastructure automation is both efficient and secure.

Sources

1. DeepWiki - Terraform Google Modules - Service Accounts
2. OneUptime - How to Configure GCP Provider with Service Account
3. Google Cloud Documentation - Terraform Authentication
4. GitHub - Terraform Google Modules - Service Accounts