kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/ci/cloud_deployment/index.md

8.2 KiB
Raw Blame History

stage group info type
Release Progressive Delivery To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers howto

Cloud deployment

Interacting with a major cloud provider may have become a much needed task that's part of your delivery process. GitLab is making this process less painful by providing Docker images that come with the needed libraries and tools pre-installed. By referencing them in your CI/CD pipeline, you'll be able to interact with your chosen cloud provider more easily.

AWS

GitLab provides Docker images that you can use to run AWS commands from GitLab CI/CD, and a template to make it easier to deploy to AWS.

Run AWS commands from GitLab CI/CD

Introduced in GitLab 12.6.

GitLab's AWS Docker image provides the AWS Command Line Interface, which enables you to run aws commands. As part of your deployment strategy, you can run aws commands directly from .gitlab-ci.yml by specifying GitLab's AWS Docker image.

Some credentials are required to be able to run aws commands:

  1. Sign up for an AWS account if you don't have one yet.

  2. Log in onto the console and create a new IAM user.

  3. Select your newly created user to access its details. Navigate to Security credentials > Create a new access key.

    NOTE: Note: A new Access key ID and Secret access key pair will be generated. Please take a note of them right away.

  4. In your GitLab project, go to Settings > CI / CD. Set the following as environment variables (see table below):

    Env. variable name Value
    AWS_ACCESS_KEY_ID Your Access key ID
    AWS_SECRET_ACCESS_KEY Your Secret access key
    AWS_DEFAULT_REGION Your region code

  5. You can now use aws commands in the .gitlab-ci.yml file of this project:

    deploy:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest # see the note below
  script:
    - aws s3 ...
    - aws create-deployment ...

    NOTE: Note: The image used in the example above (registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest) is hosted on the GitLab Container Registry and is ready to use. Alternatively, replace the image with one hosted on AWS ECR.

Use an AWS Elastic Container Registry (ECR) image in your CI/CD

Instead of referencing an image hosted on the GitLab Registry, you can reference an image hosted on any third-party registry, such as the Amazon Elastic Container Registry (ECR).

To do so, push your image into your ECR repository. Then reference it in your .gitlab-ci.yml file and replace the image path to point to your ECR image.

Deploy your application to the AWS Elastic Container Service (ECS)

  • Introduced in GitLab 12.9.
  • The Deploy-ECS.gitlab-ci.yml template was deprecated in favor of AWS/Deploy-ECS.gitlab-ci.yml template in GitLab 13.2.

GitLab provides a series of CI templates that you can include in your project. To automate deployments of your application to your Amazon Elastic Container Service (AWS ECS) cluster, you can include the AWS/Deploy-ECS.gitlab-ci.yml template in your .gitlab-ci.yml file.

GitLab also provides Docker images that can be used in your gitlab-ci.yml file to simplify working with AWS:

  • Use registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest to use AWS CLI commands.
  • Use registry.gitlab.com/gitlab-org/cloud-deploy/aws-ecs:latest to deploy your application to AWS ECS.

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 AWS RDS, etc. Read more about AWS ECS.

After you're all set up on AWS ECS, follow these steps:

  1. Make sure your AWS credentials are set up as environment 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:

    variables:
  CI_AWS_ECS_CLUSTER: my-cluster
  CI_AWS_ECS_SERVICE: my-service
  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:

    AWS ECS dashboard

  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 will be rebuilt and pushed to the GitLab registry. 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.

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

CAUTION: Warning: 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 will stop 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 AWS CLI commands for ECS.

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