Cloud deployment

Before getting started with this process, you need a cluster on AWS ECS, as well as related components, like an ECS service, ECS task definition, a database on Amazon RDS, and so on. .

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 . Copy the task definition into a new file in your project, for example <project-root>/ci/aws/task-definition.json.

  After you have these prerequisites ready, follow these steps:

  1. Make sure your AWS credentials are set up as CI/CD variables for your project. You can follow the steps above to complete this setup.

  2. Add these variables to your project’s .gitlab-ci.yml file, or in the project’s CI/CD settings:

     • 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.

     variables:
       CI_AWS_ECS_CLUSTER: my-cluster
       CI_AWS_ECS_SERVICE: my-service
       CI_AWS_ECS_TASK_DEFINITION: my-task-definition
     

     You can find these names after selecting the targeted cluster on your :

     

     Alternatively, if you want to use a task definition defined in a JSON file, use CI_AWS_ECS_TASK_DEFINITION_FILE instead:

     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 CI/CD variable instead of a regular CI/CD 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.

     CI_AWS_ECS_TASK_DEFINITION_FILE takes precedence over CI_AWS_ECS_TASK_DEFINITION if both these variables are defined within your project.
     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.

  3. Include this template in .gitlab-ci.yml:

     include:
       - template: AWS/Deploy-ECS.gitlab-ci.yml
     

     The AWS/Deploy-ECS template ships with GitLab and is available on GitLab.com.

  4. Commit and push your updated .gitlab-ci.yml to your project’s repository, and you’re done!

     Your application Docker image is rebuilt and pushed to the GitLab registry. If your image is located in a private registry, make sure your task definition is .

     Then the targeted task definition is updated with the location of the new Docker image, and a new revision is created in ECS as result.

     Finally, your AWS ECS service is updated with the new revision of the task definition, making the cluster pull the newest version of your application.

  The AWS/Deploy-ECS.gitlab-ci.yml template includes both the Jobs/Build.gitlab-ci.yml and Jobs/Deploy/ECS.gitlab-ci.yml “sub-templates”. Do not include these “sub-templates” on their own, and only include the main 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 stops working when the name changes.

  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 .

  deploy:
    stage: deploy
    image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
    script:
      - aws ecs register-task-definition ...
  

  Provision and deploy to your AWS Elastic Compute Cloud (EC2)

  You can use the AWS/CF-Provision-and-Deploy-EC2 CI template to perform the following actions within the same pipeline:

  1. Create stack: Provision your own infrastructure by leveraging the Push to S3: Push your previously-built artifact to an Deploy to EC2: Deploy this pushed content onto an

     

     Run the AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml template

     To run the AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml template, you must pass three JSON input objects, based on existing templates:

     1. The AWS documentation provides templates for the Create stack and Deploy to EC2 steps (links below). We provide the template for the remaining step, Push to S3:

        • .

        • Template for the Push to S3 step. Note that source is where a preceding build job built your application, exporting the build through artifacts:paths:

          {
            "applicationName": "string",
            "source": "string",
            "s3Location": "s3://your/bucket/project_built_file...]"
          }
          

        • .

     2. After you have completed these three templates based on your requirements, you have two ways to pass in these JSON objects:

        • They can be three actual files located in your project. You must specify their path relative to your project root in your .gitlab-ci.yml file, using the following CI/CD variables. For example, if your files are in a <project_root>/aws folder:

          variables:
            CI_AWS_CF_CREATE_STACK_FILE: 'aws/cf_create_stack.json'
            CI_AWS_S3_PUSH_FILE: 'aws/s3_push.json'
            CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json'
          

        • Alternatively, you can provide these JSON objects as file-typed CI/CD variables. In your project, go to Settings > CI/CD > Variables and add the three variables listed above as file-typed CI/CD variables. For each variable, set the value to its corresponding JSON object.

     3. Provide the name of the stack you’re creating and/or targeting, as a CI/CD variable:

        variables:
          CI_AWS_CF_STACK_NAME: 'YourStackName'
        

     4. Add this CI template to your .gitlab-ci.yml:

        include:
          - template: AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml
        

     When running your project pipeline at this point:

     • Your AWS CloudFormation stack is created based on the content of your CI_AWS_CF_CREATE_STACK_FILE file/variable. If your stack already exists, this step is skipped, but the provision job it belongs to still runs.
     • Your built application is pushed to your S3 bucket then and deployed to your EC2 instance, based on the related JSON object’s content. The deployment job finishes whenever the deployment to EC2 is done or has failed.

     Custom build job for Auto DevOps

     To leverage Auto DevOps for your project when deploying to AWS EC2, first you must define your AWS credentials as CI/CD variables.

     Next, define a job for the build stage. To do so, you must reference the Auto-DevOps.gitlab-ci.yml template and include a job named build_artifact in your .gitlab-ci.yml file. For example:

     # .gitlab-ci.yml
     
     include:
       - template: Auto-DevOps.gitlab-ci.yml
     
     variables:
       AUTO_DEVOPS_PLATFORM_TARGET: EC2
     
     build_artifact:
       stage: build
       script:
         - <your build script goes here>
       artifacts:
         paths:
           - <built artifact>
     

     For a video walkthrough of this configuration process, see Auto Deploy to EC2.

     Deploy to Amazon EKS

     Deploy to Google Cloud