Connecting an AWS account

OrkStage never stores AWS keys for your accounts. In each account, the worker assumes a deployment role with AssumeRole and an external id. It receives short lived credentials that last one hour (AWS_ROLE_SESSION_MINUTES), stay in memory and are never persisted or logged. Every OpenTofu run gets credentials that outlive its time limit, so a long apply never runs out halfway.

control plane identity (worker task role / IAM user)
      │  sts:AssumeRole  + ExternalId
      ▼
orkstage-deploy role in the customer account  ──▶  OpenTofu runner (credentials for that one container)

Give OrkStage its own identityCopy Anchor Link

The API and the worker call STS with their own AWS identity, found through the default credential chain. One identity serves every account you connect. Pick one:

• EC2 instance profile (recommended on AWS): attach a role to the instance that runs OrkStage. Containers reach the instance metadata only with a hop limit of 2: aws ec2 modify-instance-metadata-options --instance-id i-... --http-put-response-hop-limit 2 --http-tokens required.
• IAM user keys anywhere else: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION in the environment of the API and the worker (the .env of the production Compose file).
• An AWS CLI profile on the development stack: AWS_PROFILE=<name> pnpm platform:aws-real in the development workspace mounts your ~/.aws read only.

The identity needs only infra/aws/orkstage-control-plane-policy.json from the platform repository:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Sid": "AssumeDeploymentRoles", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::*:role/orkstage-deploy" },
    { "Sid": "ReadExternalIds", "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:*:*:secret:orkstage/*" }
  ]
}

Narrow sts:AssumeRole to the list of role ARNs when you know them, and drop the second statement when you use env:// references only. Its ARN is the ControlPlanePrincipalArn of every role stack below. Without an identity, Validate says so instead of reaching AWS.

Connect an accountCopy Anchor Link

aws cloudformation deploy \
  --stack-name orkstage-deployment-role \
  --template-file infra/aws/orkstage-deployment-role.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
      ControlPlanePrincipalArn=arn:aws:iam::111122223333:role/orkstage-worker \
      ExternalId="$EXTERNAL_ID"

aws-sm://orkstage/aws/prod-external-id          # AWS Secrets Manager (name or ARN, optional #jsonKey)
env://ORKSTAGE_AWS_PROD_EXTERNAL_ID             # environment variable of the API and worker

B=orkstage-tfstate-123456789012-us-east-1
aws s3api create-bucket --bucket "$B" --region us-east-1
aws s3api put-bucket-versioning --bucket "$B" --versioning-configuration Status=Enabled
aws s3api put-bucket-encryption --bucket "$B" \
  --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'
aws s3api put-public-access-block --bucket "$B" \
  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

POST /api/v1/cloud/targets
Content-Type: application/json

{
  "provider": "aws",
  "name": "aws-prod",
  "environment": "production",
  "config": {
    "accountId": "123456789012",
    "roleArn": "arn:aws:iam::123456789012:role/orkstage-deploy",
    "stateBucket": "orkstage-tfstate-123456789012-us-east-1",
    "dnsZone": "apps.example.com"
  },
  "credentialRef": "aws-sm://orkstage/aws/prod-external-id",
  "allowedRegions": ["us-east-1", "eu-west-1"],
  "defaultRegion": "us-east-1",
  "maxConcurrentDeployments": 3
}

Edit a target or rotate its credentialsCopy Anchor Link

Click Edit on the target, or call PATCH /api/v1/cloud/targets/:id. You can change the name, the role ARN, the credential reference, the DNS zone, the regions and the concurrency limit. The account id and the state bucket are fixed, because existing resources and their state live there: a different account is a new target. A region that still has resources, instances or profiles cannot be removed. Any change other than the name or the concurrency limit clears the last validation, so run Validate again.

To rotate the external id without downtime:

1. Update the role stack with the new ExternalId. From then on, only the new value works.
2. Store the new value under a new secret name, for example orkstage/aws/prod-external-id-2.
3. Edit the target and set the new reference, then Validate.

Deployments that start after the edit use the new reference at once; the old secret can go.

Several accountsCopy Anchor Link

Register one target per account and environment, each with its own role and external id, and create one profile per environment that points at them (a tenant profile replaces the shared one for that tenant when a customer has its own account). Targets in different accounts deploy at the same time without sharing credentials: each OpenTofu container receives only its own target's.

During a deploymentCopy Anchor Link

The Validate cloud targets phase repeats these checks for each target and region the deployment uses. This time it checks only the services being deployed, and it is strict. A missing permission fails the phase with AUTHORIZATION_ERROR before any resource is touched, and the error names the missing actions.

What OrkStage creates in your accountCopy Anchor Link

Every resource carries the platform's standard tags and a name of the form ork-<tenant>-<instance>-<resource>.