Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edits to two deploy and hosting guides #6651

Merged
merged 1 commit into from
Dec 13, 2023
Merged

Edits to two deploy and hosting guides #6651

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 38 additions & 38 deletions ...es/gen2/deploy-and-host/fullstack-branching/cross-account-deployments/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
export const meta = {
title: 'Cross account deployments',
title: 'Cross-account deployments',
description:
'Setup a cross account deployment pipeline powered by Amazon CodeCatalyst and AWS Amplify Hosting.'
'Set up a cross-account deployment pipeline powered by Amazon CodeCatalyst and AWS Amplify Hosting.'
};

export function getStaticProps(context) {
Expand All @@ -12,49 +12,49 @@ export function getStaticProps(context) {
};
}

This guide walks you through how to create a trunk-based, multi-region deployment pipeline for your AWS Amplify Gen 2 applications. In this tutorial, we will be using Amazon CodeCatalyst and AWS Amplify Hosting, but you can choose any CI/CD provider.
This guide walks you through how to create a trunk-based, multi-region deployment pipeline for applications built using AWS Amplify (Gen 2). We will be using Amazon CodeCatalyst and AWS Amplify Hosting in this guide, but you can choose any CI/CD provider.

<Callout info>

**Note**: You can deploy this custom pipeline either in us-west-2 or eu-west-1 region because Amazon CodeCatalyst is currently only available in these [AWS regions](https://docs.aws.amazon.com/general/latest/gr/codecatalyst.html).
**Note**: You can deploy this custom pipeline either in the us-west-2 or eu-west-1 Regions, as Amazon CodeCatalyst is currently only available in those two [AWS Regions](https://docs.aws.amazon.com/general/latest/gr/codecatalyst.html).

</Callout>

### Step 1: Setup an Amazon CodeCatalyst space
### Step 1: Set up an Amazon CodeCatalyst space

Please refer to this Amazon CodeCatalyst [guide](https://docs.aws.amazon.com/codecatalyst/latest/userguide/setting-up-topnode.html) for a detailed step-by-step walkthrough to setup your [space](https://docs.aws.amazon.com/codecatalyst/latest/userguide/spaces.html).
Please refer to this Amazon CodeCatalyst [guide](https://docs.aws.amazon.com/codecatalyst/latest/userguide/setting-up-topnode.html) for a detailed step-by-step walkthrough to set up your [space](https://docs.aws.amazon.com/codecatalyst/latest/userguide/spaces.html).

### Step 2: Deploy an Amplify Gen 2 app
### Step 2: Deploy an app using Amplify (Gen 2)

- Sign into the [AWS Management Console](https://console.aws.amazon.com/).
- Navigate to the [Amplify Gen 2 app creation page](https://us-west-2.console.aws.amazon.com/amplify/create).
- Sign in to the [AWS Management Console](https://console.aws.amazon.com/).
- Navigate to the [app creation page](https://us-west-2.console.aws.amazon.com/amplify/create) for Amplify (Gen 2).
- Select the **Next.js-Amplify starter** app, then select **Next**.
- Review the details on the **Create Git Repository** page, then select **Save and Deploy**.
- Done! You have successfully deployed a Amplify Gen 2 app and you can review the status of the app deployment in the Amplify Gen 2 console.
- Review the details on the **Create Git Repository** page, then select **Save and deploy**.
- Done! You have successfully deployed a Gen-2 app. You can review the status of the app deployment in the Amplify (Gen 2) console.

![](images/gen2/cross-account-deployments/pipeline1.png)
![Screenshot of completed deployment in AWS Amplify (Gen 2) console](images/gen2/cross-account-deployments/pipeline1.png)

### Step 3: Update build specification

Add the `npx amplify generate config --branch $AWS_BRANCH --app-id $AWS_APP_ID` command to the buildSpec and comment out the `npx amplify pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID` command. `amplify pipeline-deploy` runs a script to deploy backend updates, while `amplify generate config` fetches the latest `amplifyconfiguration.json` for the specified environment.
Add the `npx amplify generate config --branch $AWS_BRANCH --app-id $AWS_APP_ID` command to the build spec and comment out the `npx amplify pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID` command. `amplify pipeline-deploy` runs a script to deploy backend updates, while `amplify generate config` fetches the latest `amplifyconfiguration.json` for the specified environment.

![](images/gen2/cross-account-deployments/pipeline10.png)
![Screenshot of Build image settings section in AWS Amplify (Gen 2) console, with details about the app build specification](images/gen2/cross-account-deployments/pipeline10.png)

### Step 4: Disable automatic builds on the branch

You can configure Amplify to disable automatic builds on every code commit. Navigate to the app in the Gen 2 console, under **App settings**, select **Repository settings**. From the **Branches** section, select the branch and then choose **Disable auto build** from the **Actions** dropdown menu.
You can configure Amplify to disable automatic builds on every code commit. Navigate to the app in the Amplify (Gen 2) console. Under **App settings**, select **Repository settings**. From the **Branches** section, select the branch and then choose **Disable auto build** from the **Actions** dropdown menu.

![](images/gen2/cross-account-deployments/pipeline9.png)
![Screenshot of the Repository settings section in the Amplify (Gen 2) console, highlighting the selection of Disable auto build in the Actions dropdown menu](images/gen2/cross-account-deployments/pipeline9.png)

### Step 5: Create an incoming webhook

You can setup an incoming webhook to trigger a build without committing code to your Git repository. Currently, the Amplify Gen 2 console does not support creation of incoming webhooks. That being said, you can create a webhook for a Gen 2 app using the AWS CLI by running the [`create-webhook`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/amplify/create-webhook.html) command:
You can set up an incoming webhook to trigger a build without committing code to your Git repository. Currently, the Amplify (Gen 2) console does not support creation of incoming webhooks. However, you can create a webhook for a Gen-2 app using the AWS CLI by running the [`create-webhook`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/amplify/create-webhook.html) command:

```bash
aws amplify create-webhook --app-id <value> --branch-name <value> --region <value>
```

Upon successfully execution of this command, you should observe a response similar to this:
After running this command successfully, you should see a response similar to the following:

```
{
Expand All @@ -69,7 +69,7 @@ Upon successfully execution of this command, you should observe a response simil
}
```

Next, you will need to construct a `curl` command utilizing the `webhookId` to trigger a build:
Next, you will need to construct a `curl` command that uses the `webhookId` to trigger a build:

```
curl -X POST -d {} "`webhookUrl`&operation=startbuild" -H "Content-Type:application/json"
Expand All @@ -81,62 +81,62 @@ Please refer to this Amazon CodeCatalyst [guide](https://docs.aws.amazon.com/cod

<Callout info>

**Note**: When creating your project, select the **amplify-nextjs-starter-app** GitHub repository which was used to deploy the Amplify Gen 2 app as stated in Step 2.
**Note**: When creating your project, select the **amplify-nextjs-starter-app** GitHub repository, which we used to deploy the Gen-2 app in Step 2.

</Callout>

![](images/gen2/cross-account-deployments/pipeline2.png)
![Screenshot of CodeCatalyst console showing Source repositories section](images/gen2/cross-account-deployments/pipeline2.png)

### Step 7: Setup the resources in a different or target AWS account
### Step 7: Set up the resources in a different or target AWS account

You will need to implement steps 1 through 6 that are outlined in this guide above in a different AWS account (for example: `production` account) to achieve the cross account deployment strategy.
To achieve a cross-account deployment, you will need to implement Steps 1 through 6 outlined previously in this guide in a different AWS account (for example, `production` account).

### Step 8: Add the target AWS account to the CodeCatalyst space

Navigate to the CodeCatalyst space created as part of Step 1, select **Settings** and then select **AWS accounts**. Add the target **AWS account ID** (Step 7) to it and select **Associate AWS account**.
Navigate to the CodeCatalyst space created as part of Step 1, select **Settings**, and then select **AWS accounts**. Add the target **AWS account ID** (Step 7) to it and select **Associate AWS account**.

![](images/gen2/cross-account-deployments/pipeline12.png)
![Screenshot of CodeCatalyst console showing details of the Associate AWS account section](images/gen2/cross-account-deployments/pipeline12.png)

You will also need to create an IAM role in the target AWS account which will be assumed by the `staging` environment to perform actions and deploy resources in the `production` environment. As a best practice, we would recommend attaching the [`AmplifyBackendDeployFullAccess`](https://docs.aws.amazon.com/amplify/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmplifyBackendDeployFullAccess) AWS managed policy to the IAM role as it contains all the required permissions to deploy Amplify Gen 2 based resources in your account. You can learn more about adding IAM roles to account connections in the CodeCatalyst [documentation](https://docs.aws.amazon.com/codecatalyst/latest/userguide/ipa-connect-account-addroles.html).
You will also need to create an IAM role in the target AWS account which will be assumed by the `staging` environment to perform actions and deploy resources in the `production` environment. As a best practice, we recommend attaching the [`AmplifyBackendDeployFullAccess`](https://docs.aws.amazon.com/amplify/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmplifyBackendDeployFullAccess) AWS managed policy to the IAM role as it contains all the required permissions to deploy Gen-2 resources in your account. You can learn more about adding IAM roles to account connections in the CodeCatalyst [documentation](https://docs.aws.amazon.com/codecatalyst/latest/userguide/ipa-connect-account-addroles.html).

### Step 9: Create a workflow in the Amazon CodeCatalyst project

A workflow is an automated procedure that describes how to build, test, and deploy your code as part of a continuous integration and continuous delivery (CI/CD) system. You can learn more about workflows [here](https://docs.aws.amazon.com/codecatalyst/latest/userguide/flows.html).
A workflow is an automated procedure that describes how to build, test, and deploy your code as part of a continuous integration and continuous delivery (CI/CD) system. You can learn more about workflows in the [Amazon CodeCatalyst User Guide](https://docs.aws.amazon.com/codecatalyst/latest/userguide/flows.html).

- Within the CodeCatalyst project, navigate to the **CI/CD** feature and select **Workflows**.
- Select **Create Workflow**.
- Select **Create workflow**.
- Choose the **amplify-nextjs-starter-app** GitHub repository and the branch **main** from the dropdown menu.
- Next, select **Create**.

![](images/gen2/cross-account-deployments/pipeline3.png)
![Screenshot of the CodeCatalyst console showing details of the Create workflow dialog box](images/gen2/cross-account-deployments/pipeline3.png)

Once you create the workflow, you should see a **yaml** editor in the CodeCatalyst console.

![](images/gen2/cross-account-deployments/pipeline4.png)
![Screenshot of yaml editor in CodeCatalyst console](images/gen2/cross-account-deployments/pipeline4.png)

Switch the experience in the console to the **Visual** editor. Select the **Actions** button to see a list of workflow actions that you can add to your workflow.

![](images/gen2/cross-account-deployments/pipeline5.png)
![Screenshot of CodeCatalyst console showing the Workflows section with +Actions highlighted](images/gen2/cross-account-deployments/pipeline5.png)

Add the **Build** action to the workflow and select the **Add variable** button in the **Inputs** section. Add the following environment variables to it:

- AWS_APP_ID_STAGING: `amplify app id for staging app`
- AWS_APP_ID_PRODUCTION: `amplify app id for production app`
- AWS_BRANCH: `git branch name`

![](images/gen2/cross-account-deployments/pipeline13.png)
![Screenshot of CodeCatalyst console showing the Workflows section, focusing on Inputs for the build](images/gen2/cross-account-deployments/pipeline13.png)

Add another **Build** action to the workflow and select the **Depends on** button in the **Inputs** section. From the dropdown menu, select the name of the previous build action to setup the pipeline.
Add another **Build** action to the workflow and select the **Depends on** button in the **Inputs** section. From the dropdown menu, select the name of the previous build action to set up the pipeline.

![](images/gen2/cross-account-deployments/pipeline14.png)
![Screenshot of CodeCatalyst console showing the Workflows section, focusing on the visual workflow and the Inputs section](images/gen2/cross-account-deployments/pipeline14.png)

Next, select the **Configuration** section and add the following information to each of the build actions:

- Environment information (optional): `staging, production, etc.`
- AWS account connection: `your account connection`
- Role: `role setup with your account connection`

![](images/gen2/cross-account-deployments/pipeline8.png)
![Screenshot of CodeCatalyst console showing the Workflows section, focusing on the Configuration section](images/gen2/cross-account-deployments/pipeline8.png)

You will then need to add the following shell commands to each of the build actions:

Expand All @@ -158,12 +158,12 @@ You can now run **Validate** to ensure your workflow definition `yaml` file is v

<Callout info>

**Note**: Since workflows are saved with commits, and because the workflow has a code push trigger configured, saving the workflow starts a workflow run automatically.
**Note**: Since workflows are saved as commits, and this workflow has a code push trigger enabled, committing the workflow will automatically start a new workflow run.

</Callout>

Next, you can review the result of the workflow run from the **Runs** tab:

![](images/gen2/cross-account-deployments/pipeline11.png)
![Screenshot of CodeCatalyst console showing the Workflows section, focusing on the Runs tab](images/gen2/cross-account-deployments/pipeline11.png)

Done! You have successfully setup a custom cross account pipeline to deploy your frontend and backend for Amplify Gen 2 apps. To summarize, this custom pipeline will enable you to deploy your backend initially with your `staging` environment using `amplify pipeline-deploy` in the CodeCatalyst workflow and `amplify generate config` will generate the `amplifyconfiguration.json` file for the `main` branch and Amplify Hosting will not deploy backend resources as part of the build and instead will use the deployed backend resources from the `main` branch. Once the staging environment deploys successfully, a similar process will be followed to deploy your `production` environment in a different AWS account.
Done! You have successfully set up a custom cross-account pipeline to deploy your frontend and backend for apps built using Amplify (Gen 2). To summarize, this custom pipeline will enable you to deploy your backend initially with your `staging` environment using `amplify pipeline-deploy` in the CodeCatalyst workflow and `amplify generate config` will generate the `amplifyconfiguration.json` file for the `main` branch. Amplify Hosting will not deploy backend resources as part of the build and instead will use the deployed backend resources from the `main` branch. Once the staging environment deploys successfully, a similar process will be followed to deploy your `production` environment in a different AWS account.
Loading
Loading