@agilecustoms/envctl v0.22.3

envctl

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

usage

envctl deploy --env alexc -var-file=versions.tfvars -var="env=alexc" -var="log_level=debug"

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 > New 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 GitHub > org > Settings > Secrets and variables > Actions > Secrets > New organization 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 environment from CI (mainly ephemeral envs) 2. create env from dev machine

I (Alex C) chosen IAM authorization as common denominator: 1. on CI - use OIDC to assume 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 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 gha-upload-3 and gha-healthcheck) but it will be hard to use on dev machine...

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

• CI environments can install & run it with one command via npx
• developer will install it globally via npm install -g @agilecustoms/envctl