Skip to content

Init AWS credentials with hyops init aws

  • Purpose: Initialise AWS runtime credentials so Terraform/Terragrunt AWS stacks can run. Owner: Platform operations

  • Trigger: First-time environment bootstrap, new workstation/runner, or credential rotation.

  • Impact: Without AWS credentials, AWS stacks cannot apply.

  • Severity: P3 Pre-reqs: aws CLI installed; account access to target AWS resources.

  • Rollback strategy: Remove the generated credentials file under <root>/credentials/ and re-run init.

Context

hyops init aws writes:

  • Non-secret config: <root>/config/aws.conf
  • Sensitive credentials: <root>/credentials/aws.credentials.tfvars (mode 0600)
  • Readiness marker: <root>/meta/aws.ready.json

Credential resolution order:

  1. CLI flags (--access-key-id, --secret-access-key, --session-token)
  2. Shell env (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
  3. Runtime vault keys with same names

AWS_REGION/AWS_DEFAULT_REGION and AWS_PROFILE are also respected.

Preconditions and safety checks

  • Ensure you are targeting the correct environment:

    echo "HYOPS_ENV=$HYOPS_ENV"

  • Confirm required tool exists:

    command -v aws

  • If using runtime vault secrets (recommended):

    hyops vault status-verbose

  • Confirm AWS identity works before init:

    aws sts get-caller-identity

Steps

1) Generate the config template (first run only)

  • Command:

    hyops init aws --env dev

  • Expected result:

  • If config is missing, HyOps writes <root>/config/aws.conf and exits with guidance.
  • Edit and re-run.

2) Interactive workstation flow

  • If you use AWS SSO profile:

    aws configure sso --profile hybridops-dev aws sso login --profile hybridops-dev hyops init aws --env dev --profile hybridops-dev

  • Or allow HyOps to attempt SSO login when STS fails:

    hyops init aws --env dev --profile hybridops-dev --with-cli-login

3) Non-interactive/CI flow

  • Export credentials in runner environment (or inject via secret manager), then run:

    hyops init aws --env dev --non-interactive

  • Vault-backed alternative:

    hyops secrets set --env dev --from-env AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY hyops init aws --env dev --non-interactive

Verification

  • Confirm readiness marker exists:

    cat ~/.hybridops/envs/dev/meta/aws.ready.json

  • Confirm credentials file exists and is protected:

    ls -la ~/.hybridops/envs/dev/credentials/aws.credentials.tfvars

Troubleshooting

ERR: AWS identity validation failed; see run record

  • Confirm credentials/profile:

    aws sts get-caller-identity

  • If using SSO, login first:

    aws sso login --profile

  • Re-run init (optionally with --with-cli-login).

ERR: credentials file already exists (use --force ...)

  • Re-run with overwrite:

    hyops init aws --env dev --force

Preflight shows missing AWS credentials after init

  • Confirm file path:
  • ~/.hybridops/envs/<env>/credentials/aws.credentials.tfvars
  • Confirm module spec requires AWS credentials and you are using matching env (--env).

References

License: MIT-0 for code, CC-BY-4.0 for documentation