Skip to content

Init annex: AWS

Status: Stable (Public)
Version: 1.0

This annex defines AWS-specific requirements and outputs for hyops init aws.

Global rules are defined in hyops init contract.

1. Config

Default config path:

  • <root>/config/aws.conf

Config format is line-oriented KEY=value.

1.1 Required keys (non-secret)

No required non-secret keys are mandated by this annex.

1.2 Optional keys (non-secret)

  • AWS_REGION (default: us-east-1)
  • AWS_PROFILE
  • AWS_TFVARS_OUT (override credentials tfvars output path)

2. Vault keys

Default vault path:

  • <root>/vault/bootstrap.vault.env

Optional secrets used:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN

Rules:

  • Credentials MAY be provided via CLI flags, shell env, or vault.
  • Vault usage is optional but recommended for workstation persistence.

3. Behaviour

3.1 Identity validation

The implementation MUST validate caller identity using:

  • aws sts get-caller-identity

When --with-cli-login is set and AWS_PROFILE is present, implementation MAY invoke:

  • aws sso login --profile <AWS_PROFILE>

3.2 Non-interactive mode

When --non-interactive is set:

  • interactive prompts MUST NOT be used
  • init MUST fail fast with guidance when credentials are unavailable/invalid

3.3 Output overwrite guard

If credentials output exists, init MUST fail unless --force is set.

4. Outputs

4.1 Credentials tfvars

Default path:

  • <root>/credentials/aws.credentials.tfvars

The file MUST be mode 0600.

The tfvars file SHOULD include:

  • aws_region
  • aws_profile (when present)
  • aws_access_key_id (when present)
  • aws_secret_access_key (when present)
  • aws_session_token (when present)

4.2 Readiness marker

Default path:

  • <root>/meta/aws.ready.json

The marker MUST reflect status=ready only when:

  • STS identity validation succeeds, and
  • credentials tfvars writing succeeds.

4.3 Evidence

Evidence MUST be written under:

  • <root>/logs/init/aws/<run_id>/

Evidence MUST NOT include secret values.

5. Failure semantics

  • If AWS identity validation fails, init MUST fail with exit code 20.
  • If vault decrypt fails in --non-interactive mode, init MUST fail with exit code 21.
  • If credentials file writing fails, init MUST fail with exit code 30.