Skip to content

Latest commit

 

History

History
265 lines (177 loc) · 13.1 KB

PipelineDeployment.md

File metadata and controls

265 lines (177 loc) · 13.1 KB
Raw

Deploy CDK Application via CDK Pipelines

View this page in Japanese (日本語) | Back to Repository README

As an example of CI/CD with CDK, this document shows how to use sample code to deploy an application using [CDK Pipelines] (https://docs.aws.amazon.com/cdk/v2/guide/cdk_pipeline.html).

CDK Pipelines is a high-level construct library that makes it easy to set up a continuous deployment pipeline for CDK applications with AWS CodePipeline. By quickly building pipelines with CDK pipelines, you can simplify application development and focus on the areas you care about more.

Currently, we are offering the following samples.

  • Pipeline for deploying blea-gov-base-ct (multi-account baseline)
  • Pipeline for deploying blea-guest-ecs-app-sample (sample ECS application that accepts CloudFront SSL communication for unique domains)

The deployment of the operating environment itself is done by a pipeline. What you deploy yourself is a pipeline.

If you've already deployed each use case, deploying with CDK Pipelines will deploy the same application under a different stack name. To avoid duplicate billing and deployment failures, we recommend running npx cdk destroy to delete stacks that have already been deployed.

Pipeline Configuration

Setup (common) - Set up the necessary information for the pipeline

BLEA-deploy-setup

Make the necessary settings for CodePipeline to retrieve the source code.

Configuration pattern A: Deploy pipelines and applications within the same account

BLEA-deploy-tools

Deploy both the pipeline and application within the same account. Applications are deployed using pipelines as an opportunity to push against a Git repository. If you perform the required steps shown below, this is the configuration.

Configuration Pattern B: Deploying an Application from a Pipeline to Another Account

BLEA-deploy-dev

Deploy the application to a different account than the account that has the pipeline (Tools account). Of the procedures shown below, when Appendix A is also carried out, this is the configuration.

Configuration Pattern C: Deploying an Application to Multiple Accounts from a Pipeline

BLEA-deploy-prod

As an example of how to deploy an application to multiple accounts, an example of creating a pipeline for each account is shown. This configuration can be verified by performing the tasks required in configuration B for each account.

1. Governance-based deployment procedure for configuration pattern A (within the same account)

Overview of the environment to be built

  • Here, we will introduce the procedure for deploying a multi-account governance base (usecases/blea-gov-base-ct) through a pipeline
  • The pipeline and the governance base deployed from it are created in the same account Dev account ID 123456789012.
  • Pipeline parameters are devPipelineParameter and governance-based parameters are `devParameter'

1-1. Register the BLEA code in the GitHub repository

Please register the BLEA code in the Git repository. The pipeline monitors Git repositories and kicks the pipeline when the target branch is updated.

1-2. Connect to GitHub using AWS CodeStar Connections

The pipeline creates a connection to access the target Git repository.

  1. Log into the AWS Management Console for your Tools account
  2. Open the CodePipeline service
  3. Click Settings=> Connections at the bottom left of the navigation pane, then click Create Connection.

BLEA-deploy-1-console

  1. Choose GitHub, specify a Connection name, and then click Connect to GitHub

blea-deploy-2-chooseGitHub

  1. Click “Install a new app” to install “AWS Connector for GitHub”

blea-deploy-3-createConnection

  1. On the Install AWS Connector for GitHub screen, select your own repository and click Install. After this, the screen will return to the management console

blea-deploy-4-installApp

  1. On the Connect to GitHub page, click Connect

BLEA-deploy-5-connect

  1. Connection's ARN is now displayed on the screen. The format is as follows: Copy this for use after arn:aws:codestar-connections:ap-northeast-1: xxxxxxxxxxxx: connection/xxxxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx

BLEA-deploy-6-finished

1-3. Configuring AWS CLI Credentials

Set up an AWS CLI profile for deployment to guest account Dev. Here, the guest account ID is 123456789012

~/.aws/config

# For Guest Account
[profile ct-guest]
sso_start_url = https://d-90xxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 123456789012
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1

Note Administrator rights are required when bootstrapping the CDK and when deploying pipelines. From a security standpoint, it is recommended to remove administrator privileges once pipeline deployment is complete (see CDK Pipelines documentation).

1-4. Set pipeline parameters

Edit the target application's parameter.ts file (in this case, usecases/blea-gov-base-ct/parameters.ts) and specify the required information. Here, we assume that it will be deployed to the guest account specified with CLI credentials, and env is not explicitly specified.

// Parameter for Governance base in Dev account
export const devParameter: AppParameter = {
  envName: 'Development',
  securityNotifyEmail: 'notify-security@example.com',
  securitySlackWorkspaceId: 'T8XXXXXXX',
  securitySlackChannelId: 'C00XXXXXXXX',
  // env: { account: '123456789012', region: 'ap-northeast-1' },
};

// Parameter for Pipeline in Dev account
export const devPipelineParameter: PipelineParameter = {
  env: { account: '123456789012', region: 'ap-northeast-1' },
  envName: 'DevPipeline',
  sourceRepository: 'aws-samples/baseline-environment-on-aws',
  sourceBranch: 'main',
  sourceConnectionArn: 'arn:aws:codestar-connections:ap-northeast-1:xxxxxxxxxxxx:connection/example',
};

Pipeline-specific parameters are as follows.

  • sourceRepository: The name of the GitHub repository. If your own repository URL is' https://github.com/ownername/repositoryname.git ', specify ownername/repositoryname
  • sourceBranch: branch name to which the pipeline refers
  • sourceConnectionArn: GitHub Connection ARN obtained in the previous section

1-5. Deploy the pipeline

Deploy the pipeline to the target account by running the following command from your local environment.

npm ci
cd usecase/blea-gov-base-ct/
npx aws-cdk bootstrap --profile ct-guest  # If you haven't bootstrapped target account
npx aws-cdk deploy --profile ct-guest --app "npx ts-node --prefer-ts-exts bin/blea-gov-base-ct-via-cdk-pipelines.ts"

To check the pipeline created, go to the target account's management console and check the CodePipeline screen.

1-6. Update the application code, push the changes, and run the deployment

Once the pipeline deployment is complete, change the application (governance-based) code and commit/push. This will run the pipeline and deploy the application (governance-based).

Visit your Tools account to check how your pipeline is running.

Note In CDK Pipelines, by using a function called SelfMutation, deployment pipelines are also continuously deployed in response to repository updates It's possible. This makes it possible to deploy all stacks defined through the Tools account.

2. Configuration pattern B cross-account ECS application sample (multi-region) deployment instructions

CDK Pipelines makes it easy to implement pipelines that deploy applications across accounts and regions. The usecase/blea-guest-ecs-ecs-app-sample of this repository is a multi-region configuration where CloudFront is deployed to us-east-1 and application execution environments such as ALB and ECS are deployed in regions specified by users.

Here is the procedure for deploying using the pipeline bin/blea-guest-ecs-app-sample-via-cdk-pipelines.ts for cross-account deployment. Configure the pipeline to the Pipeline account 222222222222 and deploy the ECS application sample to the Dev account (ID: 111111111111.

Prerequisites

  • Dev and Pipeline accounts must be registered to the organization and credentials can be obtained using SSO
  • The Git repository where the pipeline is deployed is managed as a private repository, and third parties cannot access account information described in paramter.ts or pipeline stacks, etc.
  • Execution of steps 1-1, 1-2 above has been completed in the Pipeline account

Note In this sample, connection information to the destination account required when the pipeline is deployed must be described in the pipeline parameter file. We recommend that the Git repository that manages this information be a private repository for security reasons. Note that if you fork the aws-samples repository directly, you cannot manage it as a private repository. For example, when developing on GitHub, it is necessary to create a private repository by cloning and pushing this public repository.

2-1. Set parameters

Cross-account deployments require you to explicitly specify the target account and region. Set the commented out account ID of usecase/blea-guest-ecs-app-sample/parameter.ts appropriately.

// Parameters for Dev Account
export const devParameter: AppParameter = {
  env: {
    account: '111111111111', // Change here
    region: 'ap-northeast-1',
  },
  envName: 'Development',
  monitoringNotifyEmail: 'notify-security@example.com',
  monitoringSlackWorkspaceId: 'TXXXXXXXXXX',
  monitoringSlackChannelId: 'CYYYYYYYYYY',
  vpcCidr: '10.100.0.0/16',
  dashboardName: 'BLEA-ECS-App-Sample',
};

// Parameters for Pipeline Account
export const devPipelineParameter: PipelineParameter = {
  env: {
    account: '222222222222', // Change here
    region: 'ap-northeast-1',
  },
  sourceRepository: 'aws-samples/baseline-environment-on-aws',
  sourceBranch: 'main',
  sourceConnectionArn:
    'arn:aws:codestar-connections:us-west-2:222222222222:connection/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
};

Note If crossAccountKeys is set to true in the CodePipeline constructor, the evaluation of account information during testing will be more strict. Specifically, it is necessary to explicitly pass account information (without environment information) in the pipeline stack.

2-2. Set up Dev and Pipeline accounts

We will bootstrap so that we can deploy from the Pipeline account to the Dev account us-east-1 and ap-northeast-1.

  1. Configuring AWS CLI Credentials Set a Profile to ~/.aws/config so you can access your Dev and Pipeline accounts.
[profile blea-pipeline-dev]
sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 111111111111
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1

[profile blea-pipeline-tools]
sso_start_url = https://xxxxxxxxxxxx.awsapps.com/start#/
sso_region = ap-northeast-1
sso_account_id = 222222222222
sso_role_name = AWSAdministratorAccess
region = ap-northeast-1

Note Administrator rights are required when bootstrapping the CDK and when deploying pipelines. From a security standpoint, it is recommended to remove administrator privileges once pipeline deployment is complete (see CDK Pipelines documentation).

  1. Log in to your Dev account with SSO and perform bootstrapping
aws sso login --profile blea-pipeline-dev
npx aws-cdk bootstrap aws://111111111111/ap-northeast-1 aws://111111111111/us-east-1 --trust 222222222222 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --profile blea-pipeline-dev
  1. Log in to your Pipeline account with SSO and perform bootstrapping
aws sso login --profile blea-pipeline-tools
npx aws-cdk bootstrap aws://222222222222/ap-northeast-1 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --profile blea-pipeline-tools

2-3. Deploy the pipeline

Deploy a pipeline to a Pipeline account

cd usecase/blea-guest-ecs-app-sample
npx aws-cdk deploy --profile blea-pipeline-tools --app "npx ts-node --prefer-ts-exts bin/blea-guest-ecs-app-sample-via-cdk-pipelines.ts"

The pipeline deployed to this Pipeline account will build and deploy the application in the next step.

2-4. Update the application code, push the changes, and run the deployment

Once the pipeline deployment is complete, change the application (governance-based) code and commit/push. This will run the pipeline and deploy the application (governance-based).

Visit your Tools account to check how your pipeline is running.

See: https://aws.amazon.com/jp/blogs/news/deploying-a-cdk-application-using-the-cdk-pipelines-modern-api/