diff options
Diffstat (limited to 'doc/ci/cloud_deployment/index.md')
| -rw-r--r-- | doc/ci/cloud_deployment/index.md | 70 |
1 files changed, 53 insertions, 17 deletions
diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 29ce8bdf625..355bc7813d9 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -81,11 +81,12 @@ path to point to your ECR image. ### Deploy your application to the AWS Elastic Container Service (ECS) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207962) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207962) in GitLab 12.9. +> - The `Deploy-ECS.gitlab-ci.yml` template was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/220821) to `AWS/Deploy-ECS.gitlab-ci.yml` in GitLab 13.2. GitLab provides a series of [CI templates that you can include in your project](../yaml/README.md#include). To automate deployments of your application to your [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (AWS ECS) -cluster, you can `include` the `Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file. +cluster, you can `include` the `AWS/Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file. GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `gitlab-ci.yml` file to simplify working with AWS: @@ -96,11 +97,25 @@ Before getting started with this process, you need a cluster on AWS ECS, as well components, like an ECS service, ECS task definition, a database on AWS RDS, etc. [Read more about AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html). -After you're all set up on AWS ECS, follow these steps: +The ECS task definition can be: + +- An existing task definition in AWS ECS +- A JSON file containing a task definition. Create the JSON file by using the template provided in + the [AWS documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html#task-definition-template). + Copy the task definition into a new file in your project, for example `<project-root>/ci/aws/task-definition.json`. + [Available](https://gitlab.com/gitlab-org/gitlab/-/issues/222618) in GitLab 13.3 and later. + +After you have these prerequisites ready, follow these steps: 1. Make sure your AWS credentials are set up as environment variables for your project. You can follow [the steps above](#run-aws-commands-from-gitlab-cicd) to complete this setup. -1. Add these variables to your project's `.gitlab-ci.yml` file: +1. Add these variables to your project's `.gitlab-ci.yml` file, or in the project's + [CI/CD settings](../variables/README.md#create-a-custom-variable-in-the-ui): + + - `CI_AWS_ECS_CLUSTER`: The name of the AWS ECS cluster that you're targeting for your deployments. + - `CI_AWS_ECS_SERVICE`: The name of the targeted service tied to your AWS ECS cluster. + - `CI_AWS_ECS_TASK_DEFINITION`: The name of an existing task definition in ECS tied + to the service mentioned above. ```yaml variables: @@ -109,19 +124,37 @@ After you're all set up on AWS ECS, follow these steps: CI_AWS_ECS_TASK_DEFINITION: my-task-definition ``` - Three variables are defined in this snippet: - - - `CI_AWS_ECS_CLUSTER`: The name of your AWS ECS cluster that you're - targeting for your deployments. - - `CI_AWS_ECS_SERVICE`: The name of the targeted service tied to - your AWS ECS cluster. - - `CI_AWS_ECS_TASK_DEFINITION`: The name of the task definition tied - to the service mentioned above. - You can find these names after selecting the targeted cluster on your [AWS ECS dashboard](https://console.aws.amazon.com/ecs/home):  + Alternatively, if you want to use a task definition defined in a JSON file, use + `CI_AWS_ECS_TASK_DEFINITION_FILE` instead: + + ```yaml + variables: + CI_AWS_ECS_CLUSTER: my-cluster + CI_AWS_ECS_SERVICE: my-service + CI_AWS_ECS_TASK_DEFINITION_FILE: ci/aws/my_task_definition.json + ``` + + You can create your `CI_AWS_ECS_TASK_DEFINITION_FILE` variable as a + [file-typed environment variable](../variables/README.md#custom-environment-variables-of-type-file) instead of a + regular environment variable. If you choose to do so, set the variable value to be the full contents of + the JSON task definition. You can then remove the JSON file from your project. + + In both cases, make sure that the value for the `containerDefinitions[].name` attribute is + the same as the `Container name` defined in your targeted ECS service. + + CAUTION: **Warning:** + `CI_AWS_ECS_TASK_DEFINITION_FILE` takes precedence over `CI_AWS_ECS_TASK_DEFINITION` if both these environment + variables are defined within your project. + + NOTE: **Note:** + If the name of the task definition you wrote in your JSON file is the same name + as an existing task definition on AWS, then a new revision is created for it. + Otherwise, a brand new task definition is created, starting at revision 1. + 1. Include this template in `.gitlab-ci.yml`: ```yaml @@ -129,12 +162,15 @@ After you're all set up on AWS ECS, follow these steps: - template: AWS/Deploy-ECS.gitlab-ci.yml ``` - The `Deploy-ECS` template ships with GitLab and is available [on + The `AWS/Deploy-ECS` template ships with GitLab and is available [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml). 1. Commit and push your updated `.gitlab-ci.yml` to your project's repository, and you're done! Your application Docker image will be rebuilt and pushed to the GitLab registry. + If your image is located in a private registry, make sure your task definition is + [configured with a `repositoryCredentials` attribute](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html). + Then the targeted task definition will be updated with the location of the new Docker image, and a new revision will be created in ECS as result. @@ -143,17 +179,17 @@ After you're all set up on AWS ECS, follow these steps: application. CAUTION: **Warning:** -The [`Deploy-ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml) +The [`AWS/Deploy-ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/AWS/Deploy-ECS.gitlab-ci.yml) template includes both the [`Jobs/Build.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Build.gitlab-ci.yml) and [`Jobs/Deploy/ECS.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml) "sub-templates". Do not include these "sub-templates" on their own, and only include the main -`Deploy-ECS.gitlab-ci.yml` template. The "sub-templates" are designed to only be +`AWS/Deploy-ECS.gitlab-ci.yml` template. The "sub-templates" are designed to only be used along with the main template. They may move or change unexpectedly causing your pipeline to fail if you didn't include the main template. Also, the job names within these templates may change. Do not override these jobs names in your own pipeline, as the override will stop working when the name changes. -Alternatively, if you don't wish to use the `Deploy-ECS.gitlab-ci.yml` template +Alternatively, if you don't wish to use the `AWS/Deploy-ECS.gitlab-ci.yml` template to deploy to AWS ECS, you can always use our `aws-base` Docker image to run your own [AWS CLI commands for ECS](https://docs.aws.amazon.com/cli/latest/reference/ecs/index.html#cli-aws-ecs). |