deploy-lock/docs/developing.md

Developing

Contents

• Developing
  • Contents
  • Building
  • Testing
  • Messaging
    • Friendly Types
  • TODOs
    • Features
    • Questions

Building

1. Clone with git clone git@github.com:ssube/deploy-lock.git
2. Switch into the project directory with cd deploy-lock
3. Run a full lint, build, and test with make ci
4. Run the program's help with make run-help or node out/src/index.js --help

Testing

You can test locally without a real DDB table using https://hub.docker.com/r/amazon/dynamodb-local.

1. Launch DynamoDB Local with podman run --rm -p 8000:8000 docker.io/amazon/dynamodb-local
2. Create a profile with aws configure --profile localddb
   1. placeholder tokens
   2. us-east-1 region
   3. json output
3. Create a locks table with aws dynamodb --endpoint-url http://localhost:8000 --profile localddb create-table --attribute-definitions 'AttributeName=path,AttributeType=S' --table-name locks --key-schema 'AttributeName=path,KeyType=HASH' --billing-mode PAY_PER_REQUEST
4. Run commands using AWS_PROFILE=localddb deploy-lock --storage dynamo --table locks --endpoint http://localhost:8000 ...

Messaging

• create a new lock: locked ${path} for ${type:friendly} until ${expires_at:datetime}

  • Locked apps/acceptance/a for a deploy until Sat 31 Dec, 12:00

  • Locked gitlab/production for an incident until Sat 31 Dec, 12:00

• error, existing lock: error: ${path} is locked until ${expires_at:datetime} by ${type:friendly} in ${source}

  • Error: apps/acceptance is locked until Sat 31 Dec, 12:00 by an automation run in testing/staging.

Friendly Types

Friendly strings for type:

• automation: An automation run
• deploy: A deploy
• freeze: A release freeze
• incident: An incident
• maintenance: A maintenance window

TODOs

Features

1. Infer lock source from arguments/environment, like CI_ variables
2. SQL data store, with history (don't need to remove old records)
3. S3 data store
4. Kubernetes admission controller with configurable paths

Other potential data stores could include: flat file, kubernetes configmap, etcd itself, consul, redis.

Questions

1. In the deploy path, should account come before region or region before account?
   1. aws/us-east-1/staging vs aws/staging/us-east-1
   2. This is purely a recommendation in the docs, lock.path and lock.source will both be slash-delimited or array paths.
2. Should there be an update or replace command?
   1. Probably not, at least not without lock history or multi-party locks.
   2. When the data store can keep old locks, replace could expire an existing lock and create a new one
   3. With multi-party locks, update could update the expires_at and add a new author
3. Should --recursive be available for lock and unlock, or only check?
   1. TBD
   2. A recursive lock would write multiple records
   3. A recursive unlock could delete multiple records
4. Should locks have multiple authors?
   1. TBD
   2. It doesn't make sense to have more than one active lock for the same path
      1. Or does it?
      2. Different levels can use --allow without creating multiple locks
   3. But having multiple authors would allow for multi-party locks
      1. for CI: [gitlab, $GITLAB_USER_NAME]
      2. for an incident: [first-responder, incident-commander]
   4. Each author has to unlock before the lock is removed/released
5. Should LockData.env be a string/array, like LockData.path?
   1. Done
   2. Very probably yes, because otherwise it will need env.cloud, env.network, etc, and those are not always predictable/present.
6. Should there be an --allow/LockData.allow field?
   1. Probably yes
   2. When running check --type, if LockData.allow includes --type, it will be allowed
      1. freeze should allow automation, but not deploy
      2. incident could allow deploy, but not automation
7. Wildcards in paths?
   1. Probably no, it will become confusing pretty quickly, and KV stores do not support them consistently (or at all).
8. Authz for API mutations?
   1. If there is a REST API, it might need authn/authz.
   2. Keeping the API private could work.
   3. Authorization should be scoped by path.
9. How should the AdmissionReview fields be mapped to path?
   1. This could vary by user and may need to be configurable.
   2. Probably using an argument, --admission-path
   3. Will eventually need to use jsonpath for access to userInfo.groups list or maps