envctl

• npm @agilecustoms/envctl
• npm agilecustoms/packages (admin view)

usage

terraform init -backend-config=key=laxa1986
envctl deploy -var-file=versions.tfvars -var="log_level=debug"
envctl delete

setup/update

npm install -g @agilecustoms/envctl # same command for update
envctl --version
npm outdated -g
npm view @agilecustoms/envctl version # show latest version available (without installing)

npmjs setup

1. Login in npmjs.com
2. Create organization "agilecustoms" this will create scope @agilecustoms (one org => exactly one scope, also scope can be created w/o org)
3. Go to your user > Access Tokens > Generate New Token > Granular Access Token
   1. Token name: agilecustoms-ci
   2. Packages and scopes
      1. Permissions: Read and write
      2. Only select packages and scopes: @agilecustoms
   3. Organizations (keep as is)
4. Save token in repo Settings > Environments > release > Environment secrets > Add environment secret
   1. Name NPMJS_TOKEN
   2. Repository access: envctl only

History/motivation

env-api is a microservice hosted in 'maintenance' account and working as garbage collector: every environment first created in env-api and then 'managed' by env-api: it deletes env when it is not in use anymore OR can extend lifetime. Creation API yields unique ID, so you can safely manage env (delete, extend lifetime) via this ID. But creation API needs to be secured. There are two main use cases:

1. create an environment from CI (mainly ephemeral envs)
2. create env from a dev machine

I (Alex C) have chosen IAM authorization as a common denominator:

1. on CI — use OIDC to assume a role /ci/deployer
2. on dev machine — use SSO and profile chaining to assume role /ci/deployer

Then as /ci/deployer --call--> env-api HTTP API (exposed with API Gateway with IAM authorizer)

Now the problem is: any request needs to be signed with AWS signature v4. Originally I planned to use bash scripts, but it quickly became bulky and hard to maintain. Then I thought about Node.js - it is available on dev machines and in GitHub actions (namely in Ubuntu runners). How to distribute it? First I thought about using ncc to bundle in one big .js file (as I do for publish-s3 and gha-healthcheck) but it will be hard to use on dev machine...

So I ended up publishing this client as an npm package in npmjs

• CI environments can install it via GH action agilecustoms/envctl
• developer will install it globally via npm install -g @agilecustoms/envctl

terraform init

Terraform init first time (given state configured to be in S3)

1. backend state metadata
   1. terraform checks access to remote state (double-checked, tried to specify the wrong bucket, and it fails)
      • basically it tries s3:ListObjectsV2. But it looks like it does not check access to the file itself
   2. create file .terraform/terraform.tfstate with backend config (s3 bucket and key) (it does NOT download a state file itself!)
   3. so basically if you call terraform init two times with different keys, second time you get error "Backend configuration changed" and ask to migrate state or reconfigure
2. modules (can be called individually via terraform get -update)
   1. download modules, put them in .terraform/modules
   2. modules are loaded before providers bcz in modules can be more providers!
3. providers
   1. search for the latest provider satisfying conditions in .tf files
   2. download providers, put them in .terraform/providers/*
   3. create file .terraform.lock.hcl with provider versions and hashes