AWS Environments - Enterprise-CMCS/macpro-mako GitHub Wiki

Deploy

Deploy a Stage

Description

How-to deploy a new or existing stage to AWS. This deploys the entire application, so the entire stage, to AWS.

Prerequisites:

Procedure

cd macpro-mako
nvm use
run deploy --stage foo

Deploy an Individual Service

Description

This will deploy a single service for a given stage. All other services on which your target service is dependent must already be deployed for the stage. For example: if service B depends on service A, and you want to use this procedure to deploy only service B, then service A must have already been deployed.

Prerequisites:

Procedure

cd macpro-mako
nvm use
run deploy --stage foo

Deploy using GitHub Actions

Description

This project uses GitHub Actions as its CI/CD tool. For the most part, this project also adheres to GitOps. That said…

Each branch pushed to the macpro-mako git repository is automatically deployed to AWS. GitHub Actions sees the ‘push’ event of a new branch, and runs our Deploy.yml workflow. After a few minutes, the branch will be fully deployed. This 1:1 relationship between git branches and deployed stages is the reason why ‘stage’ and ‘branch’ are sometimes used interchangeably to refer to a deployed set of the application.

Prerequisites:

  • Git repo write access; complete the Git access request portion of onboarding

Procedure

cd macpro-mako
git checkout main
git pull
git checkout -b foo
git push --set-upstream origin foo
  • Monitor the status of your branch’s deployment in the repo’s Actions area.

Destroy

Destroy a Stage

Description

How-to destroy a stage in AWS. This destroys an entire application, so the entire stage, to AWS.

Prerequisites:

Procedure

[!warning] Stop and think about what you are doing. Destroying is a lot easier to avoid then to undo.

cd macpro-mako
nvm use
run destroy --stage foo

Notes

  • After running the above destroy command, the script will output any Cloudformation stacks that will be deleted, and ask you to verify the stage name to proceed with destruction. If you'd like to proceed, re-enter the stage name and hit enter.
  • The destroy script will hold your terminal process open until all stacks report as DESTROY_COMPLETE in cloudformation. If a stack fails to delete, or if there is a timeout, the script will fail. You may retry the script again, but it may be worth investigating the failure.
  • Please be mindful of what you are doing.

Destroy an individual service

Description

This will destroy a single service for a given stage.

Prerequisites:

Procedure

[!warning] Stop and think about what you are doing. Destroying is a lot easier to avoid then to undo.

cd macpro-mako
nvm use
run destroy --service bar --stage foo

Notes

  • All notes from the Destroy a Stage section (above) hold true for destroying an individual service.

Destroy using GitHub Actions - branch deletion

Description

GitHub Actions is usually the best way to destroy a stage. A Destroy workflow exists for this project, which will neatly take down any and all infrastructure related to a branch/stage, as well as deactivate the GitHub Environment, if it exists.

In most cases, stages are deployed from a branch in the git repo. If this is the case, and if the branch can be safely deleted, destroying using GitHub Actions and branch deletion is the preferred approach.

Prerequisites

  • Git repo write access; complete the Git access request portion of onboarding

Procedure

[!warning] Stop and think about what you are doing. Destroying is a lot easier to avoid then to undo.

cd macpro-mako
git push --delete origin foo
  • Monitor the status of your stage's destruction in the repo's [Actions area](https://github.com/{{ site.repo.org }}/{{ site.repo.name }}/actions).

Notes

  • None

Destroy using GitHub Actions - manual dispatch

Description

The same GitHub Actions workflow referenced above can be triggered manually. This is primarily useful if there is AWS infrastructure that still exists for a branch that has been deleted, and you don't want to go to the trouble of running destroy from your Mac. Or, if you want to do a clean deploy of a stage, but you don't want to delete the branch, this can also be handy.

Prerequisites

  • Git repo write access; complete the Git access request portion of onboarding

Procedure

[!warning] Stop and think about what you are doing. Destroying is a lot easier to avoid then to undo.

  • In a browser, go to the repo
  • Click the Actions tab
  • Click Destroy, located on the left hand side of the screen.
  • Click 'Run workflow'
    • Leave 'Use workflow from' set to main.
    • Enter the name of the stage you wish to destroy in the free text field.
    • Click 'Run workflow'
  • Monitor the status of your stage’s destruction in the repo’s Actions area.

Alerts

Subscribing to Alerts

Description

How-to to subscribe to alerts from a stage. This project uses SNS for near real time alerting of application health and performance. Subscriptions to this topics are not made automatically, for a few reasons (see alerts service details). This will guide you in how to create a sbuscription.

Prerequisites:

Procedure

  • Go to the AWS Console
  • Choose your region in the top right drop down.
  • Navigate to SNS
  • Click topics (see left hand side hamburger menu) and select your stage's topic
  • Click add subscription and follow the prompts.
  • If you control the inbox for the subscription you just added, go to the inbox and click through the confirmation email from AWS.
  • Repeat these steps for the application's other region.