Add a cross-Region action in CodePipeline
AWS CodePipeline includes a number of actions that help you configure build, test, and deploy resources for your automated release process. You can add actions to your pipeline that are in an AWS Region different from your pipeline. When an AWS service is the provider for an action, and this action type/provider type are in a different AWS Region from your pipeline, this is a cross-Region action.
Cross-region actions are supported and can only be created in those AWS Regions where CodePipeline is supported. For a list of the supported AWS Regions for CodePipeline, seeQuotas in AWS CodePipeline.
You can use the console, AWS CLI, or AWS CloudFormation to add cross-Region actions in pipelines.
Certain action types in CodePipeline may only be available in certain AWS Regions. Also note that there may be AWS Regions where an action type is available, but a specific AWS provider for that action type is not available.
When you create or edit a pipeline, you must have an artifact bucket in the pipeline Region and then you must have one artifact bucket per Region where you plan to execute an action. For more information about theArtifactStores parameter, seeCodePipeline pipeline structure reference.
CodePipeline handles the copying of artifacts from one AWS Region to the other Regions when performing cross-region actions.
If you use the console to create a pipeline or cross-Region actions, default artifact buckets are configured by CodePipeline in the Regions where you have actions. When you use the AWS CLI, AWS CloudFormation, or an SDK to create a pipeline or cross-Region actions, you provide the artifact bucket for each Region where you have actions.
You must create the artifact bucket and encryption key in the same AWS Region as the cross-Region action and in the same account as your pipeline.
You cannot create cross-Region actions for the following action types:
Source actions
Third-party actions
Custom actions
When using cross-Region Lambda invoke action in CodePipeline, the status of the lambda execution using thePutJobSuccessResult andPutJobFailureResult should be sent to the AWS Region where the Lambda function is present and not to the Region where CodePipeline exists.
When a pipeline includes a cross-Region action as part of a stage, CodePipeline replicates only the input artifacts of the cross-Region action from the pipeline Region to the action's Region.
The pipeline Region and the Region where your CloudWatch Events change detection resources are maintained remain the same. The Region where your pipeline is hosted does not change.
Manage cross-Region actions in a pipeline (console)
You can use the CodePipeline console to add a cross-Region action to an existing pipeline. To create a new pipeline with cross-Region actions using the Create pipeline wizard, seeCreate a custom pipeline (console).
In the console, you create a cross-Region action in a pipeline stage by choosing the action provider and theRegion field, which lists the resources you have created in that region for that provider. When you add a cross-Region action, CodePipeline uses a separate artifact bucket in the action's region. For more information about cross-Region artifact buckets, seeCodePipeline pipeline structure reference.
Add a cross-Region action to a pipeline stage (console)
Use the console to add a cross-Region action to a pipeline.
If the pipeline is running when changes are saved, that execution does not complete.
To add a cross-Region action
Sign in to the console athttp://console.aws.amazon.com/codesuite/codepipeline/home.
Select your pipeline, and then chooseEdit.
At the bottom of the diagram, choose+ Add stage if you are adding a new stage, or chooseEdit stage if you want to add the action to an existing stage.
OnEdit: <Stage>, choose+ Add action group to add a serial action. Or choose+ Add action to add a parallel action.
On theEdit action page:
InAction name, enter a name for the cross-Region action.
InAction provider, choose the action provider.
InRegion, choose the AWS Region where you have created or plan to create the resource for the action. When the Region is selected, the available resources for that Region are listed for selection. TheRegion field designates where the AWS resources are created for this action type and provider type. This field only displays for actions where the action provider is an AWS service. TheRegion field defaults to the same AWS Region as your pipeline.
InInput artifacts choose the appropriate input from the previous stage. For example, if the previous stage is a source stage, chooseSourceArtifact.
Complete all the required fields for the action provider you are configuring.
InOutput artifacts choose the appropriate output to the next stage. For example, if the next stage is a deployment stage, chooseBuildArtifact.
ChooseSave.
OnEdit: <Stage>, chooseDone.
ChooseSave.
Edit a cross-Region action in a pipeline stage (console)
Use the console to edit an existing cross-Region action in a pipeline.
If the pipeline is running when changes are saved, that execution does not complete.
To edit a cross-Region action
Sign in to the console athttp://console.aws.amazon.com/codesuite/codepipeline/home.
Select your pipeline, and then chooseEdit.
ChooseEdit stage.
OnEdit: <Stage>, choose the icon to edit an existing action.
On theEdit action page, make changes to the fields, as appropriate.
OnEdit: <Stage>, chooseDone.
ChooseSave.
Delete a cross-Region action from a pipeline stage (console)
Use the console to delete an existing cross-Region action from a pipeline.
If the pipeline is running when changes are saved, that execution does not complete.
To delete a cross-Region action
Sign in to the console athttp://console.aws.amazon.com/codesuite/codepipeline/home.
Select your pipeline, and then chooseEdit.
ChooseEdit stage.
OnEdit: <Stage>, choose the icon to delete an existing action.
OnEdit: <Stage>, chooseDone.
ChooseSave.
Add a cross-Region action to a pipeline (CLI)
You can use the AWS CLI to add a cross-Region action to an existing pipeline.
To create a cross-Region action in a pipeline stage with the AWS CLI, you add the configuration action along with an optionalregion field. You must also have already created an artifact bucket in the action's region. Instead of providing theartifactStore parameter of the single-region pipeline, you use theartifactStores parameter to include a listing of each Region's artifact bucket.
In this walkthrough and its examples,RegionA is the Region where the pipeline is created. It has access to theRegionA Amazon S3 bucket used to store pipeline artifacts and the service role used by CodePipeline.RegionB is the region where the CodeDeploy application, deployment group, and service role used by CodeDeploy are created.
Prerequisites
You must have created the following:
A pipeline in
RegionA.An Amazon S3 artifact bucket in
RegionB.The resources for your action, such as your CodeDeploy application and deployment group for a cross-Region deploy action, in
RegionB.
Add a cross-Region action to a pipeline (CLI)
Use the AWS CLI to add a cross-Region action to a pipeline.
To add a cross-Region action
For a pipeline in
RegionA, run theget-pipeline command to copy the pipeline structure into a JSON file. For example, for a pipeline namedMyFirstPipeline, run the following command:aws codepipeline get-pipeline --nameMyFirstPipeline>pipeline.jsonThis command returns nothing, but the file you created should appear in the directory where you ran the command.
Add the
regionfield to add a new stage with your cross-Region action that includes the Region and resources for your action. The following JSON sample adds a Deploy stage with a cross-Region deploy action where the provider is CodeDeploy, in a new regionus-east-1.{ "name": "Deploy", "actions": [{ "inputArtifacts": [{ "name": "SourceArtifact" } ], "name": "Deploy", "region": "RegionB", "actionTypeId":{ "category": "Deploy", "owner": "AWS", "version": "1", "provider": "CodeDeploy" }, "outputArtifacts": [], "configuration":{ "ApplicationName": "name", "DeploymentGroupName": "name" }, "runOrder": 1 }In the pipeline structure, remove the
artifactStorefield and add theartifactStoresmap for your new cross-Region action. The mapping must include an entry for each AWS Region in which you have actions. For each entry in the mapping, the resources must be in the respective AWS Region. In the example below,ID-Ais the encryption key ID forRegionA, andID-Bis the encryption key ID forRegionB."artifactStores":{ "RegionA":{ "encryptionKey":{ "id":"ID-A", "type":"KMS" }, "location":"Location1", "type":"S3" }, "RegionB":{ "encryptionKey":{ "id":"ID-B", "type":"KMS" }, "location":"Location2", "type":"S3" }}The following JSON example shows the us-west-2 bucket as
my-storage-bucketand adds the new us-east-1 bucket namedmy-storage-bucket-us-east-1."artifactStores":{ "us-west-2":{ "type": "S3", "location": "my-storage-bucket" }, "us-east-1":{ "type": "S3", "location": "my-storage-bucket-us-east-1" } },If you are working with the pipeline structure retrieved using theget-pipeline command, remove the
metadatalines from the JSON file. Otherwise, theupdate-pipeline command cannot use it. Remove the"metadata":{ }lines and the"created","pipelineARN", and"updated"fields.For example, remove the following lines from the structure:
"metadata":{ "pipelineArn": "arn:aws:codepipeline:region:account-ID:pipeline-name", "created": "date", "updated": "date" }Save the file.
To apply your changes, run theupdate-pipeline command, specifying the pipeline JSON file:
Be sure to include
file://before the file name. It is required in this command.aws codepipeline update-pipeline --cli-input-json file://pipeline.jsonThis command returns the entire structure of the edited pipeline. The output is similar to the following.
{ "pipeline":{ "version": 4, "roleArn": "ARN", "stages": [{ "name": "Source", "actions": [{ "inputArtifacts": [], "name": "Source", "actionTypeId":{ "category": "Source", "owner": "AWS", "version": "1", "provider": "CodeCommit" }, "outputArtifacts": [{ "name": "SourceArtifact" } ], "configuration":{ "PollForSourceChanges": "false", "BranchName": "main", "RepositoryName": "MyTestRepo" }, "runOrder": 1 } ] },{ "name": "Deploy", "actions": [{ "inputArtifacts": [{ "name": "SourceArtifact" } ], "name": "Deploy", "region": "us-east-1", "actionTypeId":{ "category": "Deploy", "owner": "AWS", "version": "1", "provider": "CodeDeploy" }, "outputArtifacts": [], "configuration":{ "ApplicationName": "name", "DeploymentGroupName": "name" }, "runOrder": 1 } ] } ], "name": "AnyCompanyPipeline", "artifactStores":{ "us-west-2":{ "type": "S3", "location": "my-storage-bucket" }, "us-east-1":{ "type": "S3", "location": "my-storage-bucket-us-east-1" } } }}Theupdate-pipeline command stops the pipeline. If a revision is being run through the pipeline when you run theupdate-pipeline command, that run is stopped. You must manually start the pipeline to run that revision through the updated pipeline. Use the
start-pipeline-executioncommand to manually start your pipeline.After you update your pipeline, the cross-Region action is displayed in the console.
Add a cross-Region action to a pipeline (AWS CloudFormation)
You can use AWS CloudFormation to add a cross-Region action to an existing pipeline.
To add a cross-Region action with AWS CloudFormation
Add the
Regionparameter to theActionDeclarationresource in your template, as shown in this example:ActionDeclaration: Type: Object Properties: ActionTypeId: Type: ActionTypeId Required: true Configuration: Type: Map InputArtifacts: Type: Array ItemType: Type: InputArtifact Name: Type: String Required: true OutputArtifacts: Type: Array ItemType: Type: OutputArtifact RoleArn: Type: String RunOrder: Type: IntegerRegion:Type: StringUnder
Mappings, add the region map as shown in this example for a mapping namedSecondRegionMapthat maps values for the keysRegionAandRegionB. Under thePipelineresource, under theartifactStorefield, add theartifactStoresmap for your new cross-Region action as follows:Mappings: SecondRegionMap:RegionA: SecondRegion: "RegionB"RegionB: SecondRegion: "RegionA"... Properties: ArtifactStores: - Region:RegionBArtifactStore: Type: "S3" Location: test-cross-region-artifact-store-bucket-RegionB- Region:RegionAArtifactStore: Type: "S3" Location: test-cross-region-artifact-store-bucket-RegionAThe following YAML example shows the
RegionAbucket asus-west-2and adds the newRegionBbucket,eu-central-1:Mappings: SecondRegionMap: us-west-2: SecondRegion: "eu-central-1" eu-central-1: SecondRegion: "us-west-2"... Properties: ArtifactStores: - Region: eu-central-1 ArtifactStore: Type: "S3" Location: test-cross-region-artifact-store-bucket-eu-central-1 - Region: us-west-2 ArtifactStore: Type: "S3" Location: test-cross-region-artifact-store-bucket-us-west-2Save the updated template to your local computer, and then open the AWS CloudFormation console.
Choose your stack, and then chooseCreate Change Set for Current Stack.
Upload the template, and then view the changes listed in AWS CloudFormation. These are the changes to be made to the stack. You should see your new resources in the list.
ChooseExecute.
