Notes on Backend Configuration for Amplify Console Previews

What I wanted to achieve

• Use Amplify for both the frontend and backend. I also want to handle CD with Amplify.
• Use Amplify's preview feature for the frontend.
  • Because it makes verification easy.
• Do not use Amplify's preview feature for the backend.
  • Because it would be problematic if a large number of backend AWS resources were created.

Prerequisites...

Static Web Hosting with Amplify Console

Using Amplify Console makes hosting SPAs and static sites from GitHub, as well as building CI/CD, very easy. It's super convenient!!
https://docs.aws.amazon.com/ja_jp/amplify/latest/userguide/getting-started.html
https://amplify-sns.workshop.aws/ja/70_multi_env/10_amplify_console/connect_github.html

Amplify Console Preview Feature

By turning on the preview feature in Amplify Console, a preview environment is hosted the moment you submit a pull request on GitHub. It's super convenient!!
https://docs.aws.amazon.com/ja_jp/amplify/latest/userguide/pr-previews.html
https://amplify-sns.workshop.aws/ja/70_multi_env/30_preview_autodetection.html

Backend Deployment with Amplify Console

Adding backend CD settings to amplify.yaml, the build configuration file for Amplify Console, will also set up CD for the backend. It's super convenient!!

backend:
  phases:
    build:
      commands:
        - amplifyPush --simple

https://docs.aws.amazon.com/ja_jp/amplify/latest/userguide/build-settings.html

Backend preview feature??

What happens to the backend CD when the Amplify Console preview feature is turned on?
You can choose from two patterns in the preview settings.

• If you select Create new backend environment for every Pull Request, a new environment is created every time you submit a pull request.
  • At first glance, this seems good, but for the backend, things won't work properly without various initial settings like DB and Cognito. Setting up a whole new set of environments for every pull request is quite painful. Even if you automate the initial setup well, creating various resources like APIs, Cognito, and S3 for every pull request is also burdensome in terms of cost.
• If you select Point all Pull Requests for this branch to an existing environment, an existing backend is used.
  • At first glance, this seems good, but the existing backend will be overwritten with the content of the pull request. In other words, it's possible to delete Cognito just by submitting a pull request. Wait, what?

How to use an existing backend without overwriting it

So, here is the main topic. I will introduce a method to use an existing backend without overwriting it.

1. In the preview feature settings, select Point all Pull Requests for this branch to an existing environment to use an existing backend.

2. Create a script file for the build

./script/deploy_backend.sh

if [ $AWS_BRANCH = $USER_BRANCH ]
then
  echo 'start deploy backend'
  amplifyPush --simple
  echo 'end deploy backend'
else
  echo 'skip deploy backend'
fi

• $AWS_BRANCH : GitHub branch name
• $USER_BRANCH : Backend environment
  • By the way, this variable is not listed in the Amplify manual, so I'm not sure if this explanation is accurate.
• During a preview, $USER_BRANCH becomes the target branch of the pull request, so if [ $AWS_BRANCH = $USER_BRANCH ] becomes false, and amplifyPush is not executed.
• When it's not a preview, if [ $AWS_BRANCH = $USER_BRANCH ] becomes true and amplifyPush is executed.

3. Call the build script file from amplify.yml

amplify.yml

backend:
  phases:
    build:
      commands:
        - chmod +x ./script/deploy_backend.sh
        - ./script/deploy_backend.sh

Supplementary Information

• Even if you write - if [ $AWS_BRANCH = $USER_BRANCH ]; then amplifyPush --simple; fi inside amplify.yml, for some reason the if statement is ignored and amplifyPush is executed anyway, so an external script is necessary. It's a mystery.
• The Amplify documentation mentions an environment variable called AMPLIFY_SKIP_BACKEND_BUILD that seems relevant, but I couldn't figure out how to use it.
  • (Update) Even if you don't define backend in amplify.yml, if backend resources exist (exact conditions unknown), unnecessary processing may be performed on the backend, leading to errors and build failures. In such cases, setting this environment variable allowed it to build only the frontend.
    • If only the frontend clearly exists, it might be better to include this option.

References

• Amplify environment variable documentation. I tried reading it for reference, but it wasn't very helpful. $USER_BRANCH is not even listed...
  https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html

Challenges

The problem of how to handle operational verification when the backend is modified still remains.

Added on 2022/05/24

An issue that seems related to $USER_BRANCH.
https://github.com/aws-amplify/amplify-hosting/issues/500