An application is a group of related services, environments, and pipelines. Whether you have one service that does everything or a constellation of micro-services, Copilot organizes the service(s), and the environments into which they can be deployed, into an "application."
Let's walk through an example. We want to build a voting app which needs to collect votes and aggregate the results.
To set up our vote app with two services, we can run
copilot init twice. The first time we run
copilot init, we'll be asked what we should call the application this service will belong to. Since we're trying to build a voting system, we can call our application "vote" and our first service "collector". The next time we run
init, we'll be asked if we want to add our new service to the existing “vote” app, and we’ll name the new service "aggregator".
Your application configuration (which services and environments belong to it) is stored in your AWS account, so any other users in your account will be able to develop on the “vote" app as well. This means that you can have a teammate work on one service while you develop the other.
Creating an App
If you have an existing
copilot/ directory that you created for other purposes, you may find Copilot creating files in that directory. If this happens, you can make an empty directory also named
copilot/ closer to your working directory. Copilot will use this empty directory instead.
To set up an application, you can just run
copilot init. You'll be asked if you want to set up an app or choose an existing app.
Once you've created an application, Copilot stores that application in SSM Parameter store in your AWS account. The account used to set up your application is known as the "application account". This is where your app's configuration lives, and anyone who has access to this account can use this app.
All resources created within this application will be tagged with the
copilot-app aws resource tag. This helps you know which app resources in your account belong to.
The name of your application has to be unique within your account (even across region).
Additional App Configurations
You can also provide more granular configuration for your application by running
copilot app init. This includes options to:
- Tag all application, service and environment resources with an additional set of aws resource tags
- Use a custom domain name for Load Balanced services
- Pass in an existing IAM policy with which to set a permissions boundary for all roles created within the application.
$ copilot app init \
--domain my-awesome-app.aws \
--resource-tags department=MyDept,team=MyTeam \
While the bulk of the infrastructure Copilot provisions is specific to an environment and service, there are some application-wide resources as well.
ECR Repositories are regional resources which store your service images. Each service has its own ECR Repository per region in your app.
In the above diagram, the app has several environments spread across three regions. Each of those regions has its own ECR repository for every service in your app. In this case, there are three services.
Every time you add a service, we create an ECR Repository in every region. We do this to maintain region isolation (if one region goes down, environments in other region won't be affected) and to reduce cross-region data transfer costs.
These ECR Repositories all live within your app's account (not the environment accounts) - and have policies which allow your environment accounts to pull from them.
For every region represented in your app, we create a KMS Key and an S3 bucket. These resources are used by CodePipeline to enable cross-region and cross-account deployments. All pipelines in your app share these same resources.
Similar to the ECR Repositories, the S3 bucket and KMS keys have policies which allow for all of your environments, even in other accounts, to read encrypted deployment artifacts. This makes your cross-account, cross-region CodePipelines possible.
Digging into your App
Now that we've set up an app, we can check on it using Copilot. Below are a few common ways to check in on your app.
What applications are in my account?
To see all the apps in your current account and region you can run
copilot app ls.
$ copilot app ls
What's in my application?
copilot app show will show you a summary of your application, including all the services and environments in your app.
$ copilot app show
Name AccountID Region
---- --------- ------
test 000000000000 us-east-1
Name Type Environments
---- ---- ------------
collector Load Balanced Web Service prod
aggregator Backend Service test, prod