Cloud access

Cloud access lets a stack authenticate to a cloud provider without storing long-lived credentials in its code or variables. GantryCD creates short-lived credentials for each run and passes them to the runner.

Each provider has its own identity and setup. AWS is currently supported.

AWS

For AWS, GantryCD assumes one or more IAM roles when a run starts. Each role is available to OpenTofu as a named AWS profile.

Create the IAM role

Create a role in the AWS account the stack will manage. Attach the permissions needed by its OpenTofu code.

The role must trust the GantryCD runtime principal. Ask your GantryCD administrator for its AWS principal ARN, then use it in the role trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<gantrycd-runtime-principal-arn>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": [
            "gantrycd@<org-id>@<stack-id>@plan",
            "gantrycd@<org-id>@<stack-id>@apply",
            "gantrycd@<org-id>@<stack-id>@destroy",
            "gantrycd@<org-id>@<stack-id>@refresh",
            "gantrycd@<org-id>@<stack-id>@raw"
          ]
        }
      }
    }
  ]
}

Replace every value in angle brackets. Match the full external IDs; do not use a wildcard for the organization or stack. The example allows every current run mode. Remove a value if that role should reject that mode.

Add the role to the stack

Open Stack → Edit → Cloud, enable AWS, and add:

• Name: the AWS profile name used by the stack.
• AWS Role ARN: the role created above.
• Inline session policy: optional JSON that further limits this stack.

Use the name default for a normal AWS provider:

provider "aws" {
  region = "eu-west-1"
}

GantryCD does not set an AWS region. Set it in the provider or with the stack’s AWS_REGION variable.

Use more than one role

Add another named role when a stack works across AWS accounts. Every role must trust the same GantryCD principal and the same stack external IDs.

Declare both roles on the stack:

resource "gantrycd_aws_cloud_integration" "payments" {
  stack_id = gantrycd_stack.payments.id

  role {
    name     = "default"
    role_arn = "arn:aws:iam::123456789012:role/payments"
  }

  role {
    name     = "network"
    role_arn = "arn:aws:iam::444455556666:role/network"
  }
}

The role names become AWS profiles. Select them in the AWS provider:

provider "aws" {
  region = "eu-west-1"
}

provider "aws" {
  alias   = "network"
  profile = "network"
  region  = "eu-west-1"
}

The first provider uses the role named default. The second uses the role named network. If a profile has no matching role, the run fails instead of using credentials from the runner.

Limit a shared role

Several stacks can use the same IAM role. The role defines the most access any of those stacks can receive.

Set aws_inline_policy on each stack’s cloud integration to limit its temporary credentials:

resource "gantrycd_aws_cloud_integration" "payments" {
  stack_id = gantrycd_stack.payments.id

  role {
    name     = "default"
    role_arn = var.shared_role_arn

    aws_inline_policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        Effect   = "Allow"
        Action   = "s3:*"
        Resource = [
          "arn:aws:s3:::payments-assets",
          "arn:aws:s3:::payments-assets/*"
        ]
      }]
    })
  }
}

Another stack can use the same role_arn with a policy for its own resources. AWS allows only actions permitted by both the IAM role and the inline session policy. If you leave aws_inline_policy out, the stack receives all permissions from the role.

The same inline session policy is used for plan, apply, destroy, refresh, and raw. Pull request previews and local plans use plan.