credctl setup aws

Synopsis

credctl setup aws [flags]

Description

credctl setup aws is the all-in-one command for configuring AWS with credctl. It handles:

OIDC hosting — creates an S3 bucket and uploads OIDC discovery documents (.well-known/openid-configuration and keys.json)
IAM OIDC provider — configured to trust the S3-hosted issuer URL
IAM role — trusts the OIDC provider, with the specified policy attached
AWS CLI profile — adds a credential_process entry to ~/.aws/config

Configuration is written to ~/.credctl/config.json.

If an OIDC issuer URL already exists in your config (e.g., from credctl setup gcp), the command reuses it and skips S3 bucket creation. This means adding AWS after GCP is just one command — no need to copy-paste issuer URLs.

Requires the AWS CLI to be installed and configured with sufficient IAM permissions.

Flags

Flag	Type	Default	Description
`--policy-arn`	string	—	IAM managed policy ARN to attach to the created role. Required.
`--role-name`	string	`credctl-device-role`	Name for the IAM role to create.
`--region`	string	`us-east-1`	AWS region.
`--profile`	string	`credctl`	AWS CLI profile name to create in `~/.aws/config`.
`--cloudfront`	bool	`false`	Deploy via CloudFormation with S3 + CloudFront instead of S3-only. Adds CDN caching and DDoS protection.
`--stack-name`	string	`credctl-infra`	CloudFormation stack name (only used with `--cloudfront`).
`--issuer-url`	string	—	Use an existing OIDC issuer URL. Skips S3/CloudFront creation and creates only the IAM resources and profile.

Examples

Basic setup

credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

Creating S3 bucket 'credctl-oidc-123456789012'...
Uploading OIDC documents...
Creating IAM OIDC provider...
Creating IAM role 'credctl-device-role'...
Attaching policy...
Configuring AWS CLI profile 'credctl'...

AWS setup complete.
  Issuer URL: https://credctl-oidc-123456789012.s3.us-east-1.amazonaws.com
  Role ARN:   arn:aws:iam::123456789012:role/credctl-device-role
  Profile:    credctl

Test it:
  AWS_PROFILE=credctl aws sts get-caller-identity

With CloudFront

credctl setup aws \
  --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy \
  --cloudfront

This deploys a CloudFormation stack with S3, CloudFront, IAM OIDC provider, and IAM role. The CloudFront distribution URL becomes the issuer URL.

Custom role name and region

credctl setup aws \
  --policy-arn arn:aws:iam::123456789012:policy/StagingPolicy \
  --role-name credctl-staging-role \
  --region eu-west-1

Adding AWS after GCP

If you already ran credctl setup gcp, the OIDC issuer is already configured. Just run:

credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

The command detects the existing issuer URL and reuses it — no S3 bucket creation needed.

With an external OIDC issuer

If you have a custom OIDC endpoint, use --issuer-url:

credctl setup aws \
  --issuer-url https://my-custom-oidc-endpoint.example.com \
  --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

Exit codes

Code	Meaning
0	AWS infrastructure created and configured successfully
1	Error (device not initialised, permission denied, or other error)