operate-aws
Use when operating AWS by CLI — SSO profiles, explicit profile and region, caller-identity check first, least privilege without long-lived keys, CloudTrail and cost lookups, Session Manager over SSH,
SKILL.mdskills/ops/operate-aws/SKILL.md
GitHubOperate AWS
Read-only by default. Never change prd by hand when the resource is IaC-managed; change the code
and promote it (set-up-terraform-pipeline).
Every command names its --profile and --region explicitly — no defaults, no surprises.
1. Audit — who am I, and where (change nothing)
aws --version
aws sts get-caller-identity --profile <profile> --region <region> # FIRST — account, user or role
aws configure list --profile <profile> # region and its source
aws configure list-profiles # SSO profiles that exist
get-caller-identity answers the three questions that break everything when wrong: which
account, which principal, which permission set. Run it before anything else, every session.
Organizations view (management or delegated admin profile only):
aws organizations list-accounts --profile <mgmt-profile>.
2. Decide
- Read-only investigation (default) —
describe-*,list-*, CloudTrail lookups, cost calls. - The resource is IaC-managed (Terraform state, CDK stack, CloudFormation stack) — change the code and promote it. A hand edit drifts from the stack and the next deploy reverts it or fails.
- One-off CLI change with a record — security-group closing, tag fix, snapshot cleanup. Exact command and JSON output into the ticket; the revert named before running.
3. Detect the track
| Signal | Track | Then |
|---|---|---|
tofu -chdir=terraform/envs/<env> state list | grep aws_, or the resource is in *.tf |
Terraform | Read-only here; change via set-up-terraform-pipeline |
cdk.json / cdk.out in the repo |
CDK | Change the app code, cdk diff, deploy through the pipeline |
aws cloudformation list-stacks (step 1 profile) shows the stack |
CloudFormation | Change the template, not the resource |
| None of the above | CLI-managed | One-off change with a record |
4. Install only what is missing
brew install awscli # verify version before pinning (../_shared/stack-versions.md)
brew install --cask session-manager-plugin # for aws ssm start-session
npm install -g aws-cdk # only for CDK repos — keep in lockstep with aws-cdk-lib
brew install aws-sam-cli # only for serverless repos
Optional profile helpers: granted, aws-vault — cli-toolbox.
5. Do the work
Sign in through SSO, one profile per account and role:
aws configure sso # once — wizard writes a named profile
aws sso login --profile <profile>
aws sts get-caller-identity --profile <profile> --region <region>
No long-lived access keys. If a tool needs env vars, export into a subshell only:
( eval "$(aws configure export-credentials --profile <profile> --format env)" && <tool-command> ) # subshell: the exports die with it, nothing lands in argv
CloudTrail — "who changed what":
aws cloudtrail lookup-events --lookup-attributes AttributeKey=ResourceName,AttributeValue=<name> \
--profile <profile> --region <region> --query 'Events[].{time:EventTime, who:Username, what:EventName}' --output table
Cost:
aws ce get-cost-and-usage --time-period Start=<yyyy-mm-dd>,End=<yyyy-mm-dd> --granularity MONTHLY \
--metrics UnblendedCost --profile <billing-profile> # billing access lives on the payer/management account
Session Manager, not SSH:
aws ssm describe-instance-information --query 'InstanceInformationList[].{id:InstanceId, name:PingStatus}' \
--profile <profile> --region <region> -o table
aws ssm start-session --target <instance-id> --profile <profile> --region <region>
Tagging (group and audit by tags, same scheme as Azure): aws resourcegroupstaggingapi get-resources --tag-filters Key=env,Values=prd --profile <profile> --region <region>.
Region trap: the console and the CLI each remember a region, separately. "The instance is
gone" almost always means "the instance is in another region" — check aws configure get region --profile <profile> and the console's region selector before concluding anything.
CDK skew: the CDK CLI and aws-cdk-lib must move together — a lib bump with an old CLI (or
the reverse) fails on cloud-assembly schema mismatch. Bump both in one PR.
Organizations: Identity Center administration works only from the management account or a delegated admin account. The AWS MCP server, when present, is preferred for exploration; scripts stay on the CLI.
6. Wire
- CI access to AWS is an OIDC role per environment trusting
token.actions.githubusercontent.comwithsub = repo:<org>/<repo>:environment:<env>— generated per pipeline run, no keys: set-up-terraform-pipeline. - Keys and secrets never in
~/.aws/credentialsfor humans — SSO profiles instead; anything that must persist goes to manage-secrets. - Account IDs and role names are identifiers, not secrets — real values in the IaC repo's env config, placeholders in docs and tickets.
- Tools and versions: cli-toolbox, stack-versions.
7. Verify
aws sts get-caller-identity --profile <profile> --region <region> --query Account -o tsv | grep -q <account-id> && echo right-account
aws configure get region --profile <profile> # the region you intended
aws ce get-cost-and-usage --time-period Start=<yyyy-mm-dd>,End=<yyyy-mm-dd> --granularity MONTHLY \
--metrics UnblendedCost --profile <billing-profile> --query 'ResultsByTime[0].Total.UnblendedCost.Amount' -o tsv
aws resourcegroupstaggingapi get-resources --tag-filters Key=env,Values=prd --profile <profile> --region <region> --query 'ResourceTagMappingList | length(@)'
Expected: right-account, the intended region, a cost figure, and a tag count you can explain.
After a session: no keys exported in the current shell (env | grep AWS_ is empty, or scoped to
the subshell that already exited).
References
- aws-patterns.md: the traps — identity-first, region mismatch, key-free auth, OIDC role trust, Session Manager, CDK lockstep, Identity Center admin scope.
- cli-toolbox, stack-versions.
- manage-secrets, set-up-terraform-pipeline.
- security-baseline.