From b96967cd2d84b242b4b9b49bc86b9c6a1f9e3494 Mon Sep 17 00:00:00 2001 From: Jason Jackson Date: Mon, 18 Mar 2024 14:50:47 -0400 Subject: [PATCH 1/2] reformat to basic markdown --- README.md | 62 ++++++++++++++++++++++++++----------------------------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 4f9ff1b..5721b19 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,16 @@ -ecs-deploy -================= +# ecs-deploy ![Status for silinternational/ecs-deploy](https://github.com/silinternational/ecs-deploy/actions/workflows/build-and-deploy.yml/badge.svg?branch=master) This script uses the Task Definition and Service entities in Amazon's ECS to instigate an automatic blue/green deployment. -NOTE: Maintenance Only ----------------------- +## NOTE: Maintenance Only `ecs-deploy` is now in maintenance mode. In other words, we are considering it "feature complete" and will generally only consider PRs if they are bugfixes or are to add support for new AWS CLI features. -Usage ------ +## Usage One of the following is required: -n | --service-name Name of service to deploy @@ -87,21 +84,19 @@ Usage Notes: - If a tag is not found in image and an ENV var is not used via -e, it will default the tag to "latest" -Installation ------------- +## Installation + +- Install and configure [aws-cli](http://docs.aws.amazon.com/cli/latest/userguide/tutorial-ec2-ubuntu.html#install-cli) +- Install [jq](https://github.com/stedolan/jq/wiki/Installation) +- Install ecs-deploy: -* Install and configure [aws-cli](http://docs.aws.amazon.com/cli/latest/userguide/tutorial-ec2-ubuntu.html#install-cli) -* Install [jq](https://github.com/stedolan/jq/wiki/Installation) -* Install ecs-deploy: ``` curl https://raw.githubusercontent.com/silinternational/ecs-deploy/master/ecs-deploy | sudo tee /usr/bin/ecs-deploy sudo chmod +x /usr/bin/ecs-deploy ``` - -How it works ------------- +## How it works _Note: Some nouns in the next paragraphs are capitalized to indicate that they are words which have specific meanings in AWS_ @@ -129,11 +124,11 @@ _Naturally, enough computing resources must be available in the ECS cluster for Consequently, all that is needed to deploy a new version of an application is to update the Service which is running its Tasks to point at a new version of the Task Definition. `ecs-deploy` uses the python `aws` utility to do this. It, - * Pulls the JSON representation of the in-use Task Definition; or the most recently created if using `--use-latest-task-def` - * Edits it - * Defines a new version, with the changes - * Updates the Service to use the new version - * Waits, querying Amazon's API to make sure that the Service has been able to create a new Task +- Pulls the JSON representation of the in-use Task Definition; or the most recently created if using `--use-latest-task-def` +- Edits it +- Defines a new version, with the changes +- Updates the Service to use the new version +- Waits, querying Amazon's API to make sure that the Service has been able to create a new Task The second step merits more explanation: since a Task Definition [may] define multiple containers, the question arises, "what must be changed to create a new revision?" Empirically, the surprising answer is nothing; Amazon allows you to create a new @@ -169,8 +164,8 @@ Or perhaps just obtain read the docker tag from another file in your development In any case, just make sure your process builds, tags, and pushes the docker image you use to the repository before running this script. -Use Environment Variable for tag name value -------------------------------------------- +## Use Environment Variable for tag name value + In some cases you may want to use an environment variable for the tag name of your image. For example, we want to use a unique docker image/tag for each task definition. This gives us the ability to revert/rollback changes by just selecting a previous task @@ -183,8 +178,8 @@ For example: ecs-deploy -c CLUSTERNAME -n SERVICENAME -i my.private.repo.com/frontend_container -e CI_TIMESTAMP -AWS IAM Policy Configuration -------------------------------------------- +## AWS IAM Policy Configuration + Here's an example of a suitable custom policy for [AWS IAM](https://aws.amazon.com/documentation/iam/): ```json @@ -212,15 +207,15 @@ Here's an example of a suitable custom policy for [AWS IAM](https://aws.amazon.c } ``` -Troubleshooting ---------------- - - You must provide AWS credentials in one of the supported formats. If you do - not, you'll see some error output from the AWS CLI, something like: +## Troubleshooting - You must specify a region. You can also configure your region by running "aws configure". +- You must provide AWS credentials in one of the supported formats. If you do + not, you'll see some error output from the AWS CLI, something like: + + You must specify a region. You can also configure your region by running "aws configure". + +## Testing -Testing -------- Automated tests are performed using [bats](https://github.com/sstephenson/bats). The goal of testing is to ensure that updates/changes do not break core functionality. Unfortunately not all of `ecs-deploy` is testable since portions interact with @@ -229,9 +224,10 @@ is tested. Any new functionality and pull requests should come with tests as well (if possible). -Github Actions Support -------- -Github Actions support is available. Add a code block similar to that below to your actions yaml file. Parameters are passed to the ecs-deploy tool under 'with' section. For each parameter, the parameter name followed by _cmd must be called with the appropriate parameter option like '--aws-access-key' in addition to supplying the parameter aws_access_key with the appropriate value. +## Github Actions Support + +Github Actions support is available. Add a code block similar to that below to your actions yaml file. Parameters are passed to the ecs-deploy tool under 'with' section. For each parameter, the parameter name followed by \_cmd must be called with the appropriate parameter option like '--aws-access-key' in addition to supplying the parameter aws_access_key with the appropriate value. + ``` deploy_to_ecs: name: 'Deploy updated container image via blue/green deployment to ECS service.' From f97e9a8c9a501e32fa10ff2ce39a2c3b4131ef9f Mon Sep 17 00:00:00 2001 From: Jason Jackson Date: Mon, 18 Mar 2024 14:53:38 -0400 Subject: [PATCH 2/2] use more generic names --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5721b19..fb00ba2 100644 --- a/README.md +++ b/README.md @@ -63,19 +63,19 @@ are to add support for new AWS CLI features. Examples: Simple deployment of a service (Using env vars for AWS settings): - ecs-deploy -c production1 -n doorman-service -i docker.repo.com/doorman:latest + ecs-deploy -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container:latest All options: - ecs-deploy -k ABC123 -s SECRETKEY -r us-east-1 -c production1 -n doorman-service -i docker.repo.com/doorman -m 50 -M 100 -t 240 -D 2 -e CI_TIMESTAMP -v + ecs-deploy -k ABC123 -s SECRETKEY -r us-east-1 -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container -m 50 -M 100 -t 240 -D 2 -e CI_TIMESTAMP -v Updating a task definition with a new image: - ecs-deploy -d open-door-task -i docker.repo.com/doorman:17 + ecs-deploy -d my-task-definition -i my.private.repo.com/frontend_container:17 Using profiles (for STS delegated credentials, for instance): - ecs-deploy -p PROFILE -c production1 -n doorman-service -i docker.repo.com/doorman -t 240 -e CI_TIMESTAMP -v + ecs-deploy -p my-profile -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container -t 240 -e CI_TIMESTAMP -v Update just the tag on whatever image is found in ECS Task (supports multi-container tasks): @@ -147,7 +147,7 @@ be an unlikely use case._ This behavior allows two possible process to specify which images, and therefore which configurations, to deploy. First, you may set the tag to always be `latest` (or some other static value), like so: - ecs-deploy -c CLUSTERNAME -n SERVICENAME -i my.private.repo.com/frontend_container:latest + ecs-deploy -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container:latest This will result in identical new versions of the Task Definition being created, but the Service will still do a blue/green deployment, and will so will pull down the latest version (if you previously pushed it into the registry). @@ -155,11 +155,11 @@ deployment, and will so will pull down the latest version (if you previously pus Alternatively, you may specify some other means of obtaining the tag, since the script `eval`s the image string. You could use git tags as a map to docker tags: - ecs-deploy -c CLUSTERNAME -n SERVICENAME -i 'my.private.repo.com/frontend_container:`git describe`' + ecs-deploy -c my-cluster-name -n my-service-name -i 'my.private.repo.com/frontend_container:`git describe`' Or perhaps just obtain read the docker tag from another file in your development: - ecs-deploy -c CLUSTERNAME -n SERVICENAME -i 'my.private.repo.com/frontend_container:$(< VERSION)' + ecs-deploy -c my-cluster-name -n my-service-name -i 'my.private.repo.com/frontend_container:$(< VERSION)' In any case, just make sure your process builds, tags, and pushes the docker image you use to the repository before running this script. @@ -176,7 +176,7 @@ holds the value you wish to use for the tag. For example: - ecs-deploy -c CLUSTERNAME -n SERVICENAME -i my.private.repo.com/frontend_container -e CI_TIMESTAMP + ecs-deploy -c my-cluster-name -n my-service-name -i my.private.repo.com/frontend_container -e CI_TIMESTAMP ## AWS IAM Policy Configuration