diff --git a/ecs/demo/README.md b/ecs/demo/README.md deleted file mode 100644 index 803235204..000000000 --- a/ecs/demo/README.md +++ /dev/null @@ -1,107 +0,0 @@ -## Compose sample application - -### Python/Flask application - -``` -+--------------------+ +------------------+ -| | | | -| Python Flask | timestamps | Redis | -| Application |------------->| | -| | | | -+--------------------+ +------------------+ -``` - -### Things you'll need to do. - -There are a number of places you'll need to fill in information. You can find them with: - -``` -grep -r '<<<' ./* -./docker-compose.yml: x-aws-pull_credentials: <<>> -./docker-compose.yml: image: <<>>/timestamper -## Walk through -``` - -### Setup pull credentials for private Docker Hub repositories - -You should use a Personal Access Token (PAT) vs your default password. If you have 2FA enabled on your Hub account you will have to create a PAT. You can read more about managing access tokens here: https://docs.docker.com/docker-hub/access-tokens/ - -``` - docker ecs secret create -d MyKey -u myhubusername -p myhubpat -``` - -### Create an AWS Docker context and list available contexts - -``` -docker ecs setup -Enter context name: aws -✔ sandbox.devtools.developer -Enter cluster name: -Enter region: us-west-2 -✗ Enter credentials: - -docker context ls -NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR -aws -default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm -``` - -### Test locally - -``` -docker context use default -docker-compose up -open http://localhost:5000 -``` - -### Push images to hub for ecs (ecs cannot see your local image cache) - -``` -docker-compose push -``` - -### Switch to ECS context and launch the app - -``` -docker context use aws -docker ecs compose up -``` - -### Check out the CLI - -``` -docker ecs compose ps -docker ecs compose logs -``` - -### Check out the aws console - -- cloud formation -- cloud watch -- security groups -- Load balancers (ELB for this example / ALB if your app only uses 80/443) - -### Checkout cloudformation - -``` -docker ecs compose convert -``` - -### Stop the meters - -``` -docker ecs compose down - -``` - -## Using Amazon ECR instead of Docker Hub - -[Makefile](Makefile) has an example setup for creating an ECR repository and pushing to it. You'll need to have the AWS CLI installed and your AWS credentials available. - -``` -make create-ecr -REGISTRY_ID= make build-image -REGISTRY_ID= make push-image-ecr -``` - -If you want to use this often, you'll likely want to replace `PUT_ECR_REGISTRY_ID_HERE` with the value from above. diff --git a/ecs/demo/Makefile b/ecs/example/Makefile similarity index 100% rename from ecs/demo/Makefile rename to ecs/example/Makefile diff --git a/ecs/example/README.md b/ecs/example/README.md new file mode 100644 index 000000000..96e3e5261 --- /dev/null +++ b/ecs/example/README.md @@ -0,0 +1,178 @@ +## Compose sample application + +This sample application was demoed as part of the AWS Cloud Containers +Conference on 2020-07-09. It has been tested on Linux and macOS. + +Note that `$` is used to denote commands in blocks where the command and its +output are included. + +### Python/Flask application + +``` ++--------------------+ +------------------+ +| | | | +| Python Flask | timestamps | Redis | +| Application |------------->| | +| | | | ++--------------------+ +------------------+ +``` + +### Things you'll need to do + +There are a number of places you'll need to fill in information. +You can find them with: + +```console +$ grep -r '<<<' ./* +./docker-compose.yml: x-aws-pull_credentials: <<>> +./docker-compose.yml: image: <<>>/timestamper +## Walk through +``` + +### Setup pull credentials for private Docker Hub repositories + +You should use a Personal Access Token (PAT) rather than your account password. +If you have 2FA enabled on your Hub account you will need to create a PAT. +You can read more about managing access tokens here: +https://docs.docker.com/docker-hub/access-tokens/ + +```console +docker ecs secret create -d MyKey -u myhubusername -p myhubpat +``` + +### Create an AWS Docker context and list available contexts + +To initialize the Docker ECS integration, you will need to run the `setup` +command. This will create a Docker context that works with AWS ECS. + +```console +$ docker ecs setup +Enter context name: aws +✔ sandbox.devtools.developer +Enter cluster name: +Enter region: us-west-2 +✗ Enter credentials: +``` + +You can verify that the context was created by listing your Docker contexts: + +```console +$ docker context ls +NAME DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR +aws +default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm +``` + +### Test locally + +The first step is to test your application works locally. To do this, you will +need to switch to using the default local context so that you are targeting your +local machine. + +```console +docker context use default +``` + +You can then run the application using `docker-compose`: + +```console +docker-compose up +``` + +Once the application has started, you can navigate to http://localhost:5000 +using your Web browser using the following command: + +```console +open http://localhost:5000 +``` + +### Push images to Docker Hub for ECS (ECS cannot see your local image cache) + +In order to run your application in the cloud, you will need your container +images to be in a registry. You can push them from your local machine using: + +```console +docker-compose push +``` + +You can verify that this command pushed to the Docker Hub by +[logging in](https://hub.docker.com) and looking for the `timestamper` +repository under your user name. + +### Switch to ECS context and launch the app + +Now that you've tested the application works locally and that you've pushed the +container images to the Docker Hub, you can switch to using the `aws` context +you created earlier. + +```console +docker context use aws +``` + +Running the application on ECS is then as simple as doing a `compose up`: + +```console +docker ecs compose up +``` + +### Check out the CLI + +Once the application is running in ECS, you can list the running containers with +the `ps` command. Note that you will need to run this from the directory where +you Compose file is. + +```console +docker ecs compose ps +``` + +You can also read the application logs using `compose logs`: + +```console +docker ecs compose logs +``` + +### Check out the AWS console + +You can see all the AWS components created for your running application in the +AWS console. There you will find: + +- CloudFormation being used to manage all the infrastructure +- CloudWatch for logs +- Security Groups for network policies +- Load balancers (ELB for this example / ALB if your app only uses 80/443) + +### Checkout CloudFormation + +The ECS Docker CLI integration has the ability to output the CloudFormation +template used to create the application in the `compose convert` command. You +can see this by running: + +```console +docker ecs compose convert +``` + +### Stop the meters + +To shut down your application, you simply need to run: + +```console +docker ecs compose down +``` + +## Using Amazon ECR instead of Docker Hub + +If you'd like to use AWS ECR instead of Docker Hub, the [Makefile](Makefile) has +an example setup for creating an ECR repository and pushing to it. +You'll need to have the AWS CLI installed and your AWS credentials available. + +```console +make create-ecr +REGISTRY_ID= make build-image +REGISTRY_ID= make push-image-ecr +``` + +Note that you will need to change the name of the image in the +[Compose file](docker-compose.yml). + +If you want to use this often, you'll likely want to replace +`PUT_ECR_REGISTRY_ID_HERE` with the value from above. diff --git a/ecs/demo/app/Dockerfile b/ecs/example/app/Dockerfile similarity index 100% rename from ecs/demo/app/Dockerfile rename to ecs/example/app/Dockerfile diff --git a/ecs/demo/app/app.py b/ecs/example/app/app.py similarity index 100% rename from ecs/demo/app/app.py rename to ecs/example/app/app.py diff --git a/ecs/demo/app/requirements.txt b/ecs/example/app/requirements.txt similarity index 100% rename from ecs/demo/app/requirements.txt rename to ecs/example/app/requirements.txt diff --git a/ecs/demo/app/scripts/entrypoint.sh b/ecs/example/app/scripts/entrypoint.sh similarity index 100% rename from ecs/demo/app/scripts/entrypoint.sh rename to ecs/example/app/scripts/entrypoint.sh diff --git a/ecs/demo/app/templates/index.html b/ecs/example/app/templates/index.html similarity index 100% rename from ecs/demo/app/templates/index.html rename to ecs/example/app/templates/index.html diff --git a/ecs/demo/docker-compose.yml b/ecs/example/docker-compose.yml similarity index 81% rename from ecs/demo/docker-compose.yml rename to ecs/example/docker-compose.yml index 31152b2a7..9d08d45d7 100644 --- a/ecs/demo/docker-compose.yml +++ b/ecs/example/docker-compose.yml @@ -3,7 +3,7 @@ services: frontend: build: app x-aws-pull_credentials: <<>> - image: <<>>/timestamper + image: <<>>/timestamper ports: - "5000:5000" depends_on: