Backstage on Google Cloud Quickstart¶

This quick-start deployment guide can be used to set up an environment to familiarize yourself with the architecture and get an understanding of the concepts related to hosting Backstage on Google Cloud.

NOTE: This environment is not intended to be a long lived environment. It is intended for temporary demonstration and learning purposes. You will need to modify the configurations provided to align with your orginazations needs.

Architecture¶

For more information about the architecture, see the Backstage on Google Cloud:Architecture document.

Requirements¶

Project¶

In this guide you can choose to bring your project (BYOP) or have Terraform create a new project for you. The requirements are different based on the option that you choose.

Option 1: Bring your own project (BYOP)¶

Project ID of a Google Cloud Project
roles/owner IAM permissions on the project
GitHub Personal Access Token, steps to create the token are provided below

Option 2: Terraform managed project¶

Billing account ID
Organization or folder ID
roles/billing.user IAM permissions on the billing account specified
roles/resourcemanager.projectCreator IAM permissions on the organization or folder specified
GitHub Personal Access Token, steps to create the token are provided below

Pull the source code¶

NOTE: This tutorial is designed to be run from Cloud Shell in the Google Cloud Console.

Clone the repository and change directory to the guide directory

git clone https://github.com/GoogleCloudPlatform/platform-engineering && \
cd platform-engineering/reference-architectures/backstage/backstage-quickstart

Set environment variables

export BACKSTAGE_QS_BASE_DIR=$(pwd) && \
sed -n -i -e '/^export BACKSTAGE_QS_BASE_DIR=/!p' -i -e '$aexport  \
BACKSTAGE_QS_BASE_DIR="'"${BACKSTAGE_QS_BASE_DIR}"'"' ${HOME}/.bashrc

Project Configuration¶

You only need to complete the section for the option that you have selected (either option 1 or 2).

Option 1: Bring your own project config (BYOP)¶

Set the project environment variables in Cloud Shell

Replace the following values

<PROJECT_ID> is the ID of your existing Google Cloud project

export BACKSTAGE_QS_PROJECT_ID="<PROJECT_ID>"
export BACKSTAGE_QS_STATE_BUCKET="${BACKSTAGE_QS_PROJECT_ID}-terraform"

Set the default gcloud project

gcloud config set project ${BACKSTAGE_QS_PROJECT_ID}

Authorize gcloud

gcloud auth login --activate --no-launch-browser --quiet --update-adc

Create a Cloud Storage bucket to store the Terraform state

gcloud storage buckets create gs://${BACKSTAGE_QS_STATE_BUCKET} --project ${BACKSTAGE_QS_PROJECT_ID}

Set the configuration variables

sed -i "s/YOUR_STATE_BUCKET/${BACKSTAGE_QS_STATE_BUCKET}/g" ${BACKSTAGE_QS_BASE_DIR}/backend.tf
sed -i "s/YOUR_PROJECT_ID/${BACKSTAGE_QS_PROJECT_ID}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars

You can now the Create the resources.

Option 2: Terraform managed project config¶

Set the configuration variables

nano ${BACKSTAGE_QS_BASE_DIR}/initialize/initialize.auto.tfvars

environment_name  = "qs"
iapUserDomain = ""
iapSupportEmail = ""
project = {
  billing_account_id = "XXXXXX-XXXXXX-XXXXXX"
  folder_id          = "############"
  name               = "backstage"
  org_id             = "############"
}

environment_name: the name of the environment (defaults to qs for quickstart)
iapUserDomain: the root domain of the GCP Org that the Backstage users will be in
iapSupportEmail: support contact for the IAP brand
project.billing_account_id: the billing account ID
project.name: the prefix for the display name of the project, the full name will be <project.name>-<environment_name>

Enter either project.folder_id OR project.org_id

project.folder_id: the Google Cloud folder ID
project.org_id: the Google Cloud organization ID
Authorize gcloud

gcloud auth login --activate --no-launch-browser --quiet --update-adc

Create a new project

cd ${BACKSTAGE_QS_BASE_DIR}/initialize
terraform init && \
terraform plan -input=false -out=tfplan && \
terraform apply -input=false tfplan && \
rm tfplan && \
terraform init -force-copy -migrate-state && \
rm -rf state

Set the project environment variables in Cloud Shell

BACKSTAGE_QS_PROJECT_ID=$(grep environment_project_id \
${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars | awk -F"=" '{print $2}' | xargs)

You can now the Create the resources.

Create the resources¶

Before running Terraform, make sure that the Service Usage API and Service Management API are enabled.

Enable Service Usage API

gcloud services enable serviceusage.googleapis.com

Enable Service Management API

gcloud services enable servicemanagement.googleapis.com

In situations where you have run this quickstart before and then cleaned-up the resources but are re-using the project, it might be neccasary to restore the endpoints from a deleted state first.

BACKSTAGE_QS_PREFIX=$(grep environment_name \
${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars | awk -F"=" '{print $2}' | xargs)
BACKSTAGE_QS_PROJECT_ID=$(grep environment_project_id \
${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars | awk -F"=" '{print $2}' | xargs)
gcloud endpoints services undelete \
${BACKSTAGE_QS_PREFIX}.endpoints.${BACKSTAGE_QS_PROJECT_ID}.cloud.goog \
--quiet 2>/dev/null

Create the resources

cd ${BACKSTAGE_QS_BASE_DIR} && \
terraform init && \
terraform plan -input=false -out=tfplan && \
terraform apply -input=false tfplan && \
rm tfplan

This will take a while to create all of the required resources, figure somewhere between 15 and 20 minutes.

Cleanup¶

Resources¶

Destroy the resources

cd ${BACKSTAGE_QS_BASE_DIR} && \
terraform init && \
terraform destroy -auto-approve && \
rm -rf .terraform .terraform.lock.hcl

Project Deletion¶

You only need to complete the section for the option that you have selected.

Option 1: Bring your own project deletion (BYOP)¶

Delete the project

gcloud projects delete ${BACKSTAGE_QS_PROJECT_ID}

Option 2: Terraform managed project deletion¶

Destroy the project

cd ${BACKSTAGE_QS_BASE_DIR}/initialize && \
TERRAFORM_BUCKET_NAME=$(grep bucket backend.tf | awk -F"=" '{print $2}' |
xargs) && \
cp backend.tf.local backend.tf && \
terraform init -force-copy -lock=false -migrate-state && \
gsutil -m rm -rf gs://${TERRAFORM_BUCKET_NAME}/* && \
terraform init && \
terraform destroy -auto-approve  && \
rm -rf .terraform .terraform.lock.hcl state/

Environment configuration¶

Remove Terraform files and temporary files

cd ${BACKSTAGE_QS_BASE_DIR} && \
rm -rf \
.terraform \
.terraform.lock.hcl \
initialize/.terraform \
initialize/.terraform.lock.hcl \
initialize/backend.tf.local \
initialize/state

Reset the TF variables file

cd ${BACKSTAGE_QS_BASE_DIR} && \
cp backstage-qs-auto.tfvars.local backstage-qs.auto.tfvars

Remove the environment variables

sed \
-i -e '/^export BACKSTAGE_QS_BASE_DIR=/d' \
${HOME}/.bashrc