Which method ensures least-privilege authentication across Terramate stacks?

The Recommended Authentication Pattern

Terramate does not provide a native identity provider or a built-in mechanism to map stacks to IAM roles during the generation phase. Because Terramate is an orchestration layer that generates HCL, the responsibility for least-privilege authentication remains with the underlying cloud provider's IAM system and the execution environment (CI/CD runner).

The most secure method for ensuring least-privilege across stacks is to combine stack-based directory isolation with OIDC-based role assumption at the execution level.

Implementation Strategy

To prevent credential leakage and avoid overly permissive identities, follow these steps:

• Isolate Stack Identities: Define distinct IAM roles for each stack (e.g., role-network-prod, role-db-prod). Do not use a single "orchestrator" role with administrative access to all resources.
• Leverage OIDC: Configure your CI/CD provider (GitHub Actions, GitLab CI, etc.) to use OpenID Connect. Map the CI/CD job's identity to a specific IAM role based on the stack being deployed.
• Dynamic Provider Configuration: Instead of hardcoding credentials in templates, use the default provider block and rely on the environment to provide the identity. For multi-account setups, use the assume_role block within the provider:

# Generated Terraform Provider Block
provider "aws" {
  region = var.region
  assume_role {
    role_arn = var.stack_iam_role_arn
  }
}

Explanation of Behavior

By passing the stack_iam_role_arn as a stack-specific variable via Terramate's variable propagation, you ensure that the generated Terraform code requests a short-lived token for a role scoped specifically to that stack's resources. This prevents the "long-running orchestration" problem because the cloud provider handles the token refresh and expiration independently of the Terramate generation process.

Verification and Safety

To verify that least-privilege is active, run the following check on your generated HCL files:

# Ensure no static access keys are present in generated files
grep -r "access_key" ./*.tf

Note: If you are using a local execution environment rather than a CI/CD runner, ensure you are using a tool like aws-vault or direnv to swap profiles between stack executions.

Diagnostic Detail Needed: Are you executing these stacks via a centralized CI/CD runner or through distributed local developer environments? This determines whether the solution should focus on OIDC trust relationships or local profile switching.