Second round of updates for the Backstage quickstart

docs/sitemap.xml

@@ -2,78 +2,78 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/code-of-conduct/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/contributing/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/accelerating-migrations/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/automated-password-rotation/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/backstage/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/backstage/backstage-quickstart/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/CloudFunctions/cloudDeployApprovals/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/CloudFunctions/cloudDeployInteractions/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/CloudFunctions/cloudDeployOperations/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/CloudFunctions/createRelease/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/CloudRun/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/cloud_deploy_flow/WebsiteDemo/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/github-runners-gke/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/sandboxes/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/sandboxes/examples/cli/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/sandboxes/examples/gcp-sandboxes/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
     <url>
          <loc>https://googlecloudplatform.github.io/platform-engineering/reference-architectures/sandboxes/sandbox-modules/</loc>
-         <lastmod>2025-06-18</lastmod>
+         <lastmod>2025-07-16</lastmod>
     </url>
 </urlset>

reference-architectures/backstage/backstage-quickstart/README.md

@@ -86,15 +86,6 @@ In this section you prepare your project for deployment.
     gcloud storage buckets create gs://${BACKSTAGE_QS_STATE_BUCKET} --project ${PROJECT_ID}
     ```
 
-3.  Set the configuration variables
-
-    ```bash
-    sed -i "s/YOUR_STATE_BUCKET/${BACKSTAGE_QS_STATE_BUCKET}/g" ${BACKSTAGE_QS_BASE_DIR}/backend.tf
-    sed -i "s/YOUR_PROJECT_ID/${PROJECT_ID}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
-    sed -i "s/YOUR_IAP_USER_DOMAIN/${IAP_USER_DOMAIN}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
-    sed -i "s/YOUR_IAP_SUPPORT_EMAIL/${IAP_SUPPORT_EMAIL}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
-    ```
-
 ## Deploy Backstage
 
 Before running Terraform, make sure that the Service Usage API and Service
@@ -103,11 +94,59 @@ Management API are enabled.
 1.  Enable Service Usage API and Service Management API
 
     ```bash
-    gcloud services enable serviceusage.googleapis.com \
-    gcloud services enable servicemanagement.googleapis.com
+    gcloud services enable \
+      cloudresourcemanager.googleapis.com \
+      iap.googleapis.com \
+      serviceusage.googleapis.com \
+      servicemanagement.googleapis.com
+    ```
+
+2.  Setup the Identity Aware Proxy brand
+
+    ```bash
+    gcloud iap oauth-brands create \
+      --application_title="IAP Secured Backstage" \
+      --project="${PROJECT_ID}" \
+      --support_email="${IAP_SUPPORT_EMAIL}"
+    ```
+
+    Capture the brand name in an environment variable, it will be in the format
+    of: `projects/[your_project_number]/brands/[your_project_number]`.
+
+    ```bash
+    export IAP_BRAND=<your_brand_name>
+    ```
+
+3.  Using the brand name create the IAP client.
+
+    ```bash
+    gcloud iap oauth-clients create \
+      ${IAP_BRAND} \
+      --display_name="IAP Secured Backstage"
+    ```
+
+    Capture the client_id and client_secret in environment variables. For the
+    client_id we only need the last value of the string, it will be in the
+    format of:
+    `549085115274-ksi3n9n41tp1vif79dda5ofauk0ebes9.apps.googleusercontent.com`
+
+    ```bash
+    export IAP_CLIENT_ID="<your_client_id>"
+    export IAP_SECRET="<your_iap_secret>"
+    ```
+
+4.  Set the configuration variables
+
+    ```bash
+    sed -i "s/YOUR_STATE_BUCKET/${BACKSTAGE_QS_STATE_BUCKET}/g" ${BACKSTAGE_QS_BASE_DIR}/backend.tf
+    sed -i "s/YOUR_PROJECT_ID/${PROJECT_ID}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
+    sed -i "s/YOUR_IAP_USER_DOMAIN/${IAP_USER_DOMAIN}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
+    sed -i "s/YOUR_IAP_SUPPORT_EMAIL/${IAP_SUPPORT_EMAIL}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
+    sed -i "s/YOUR_IAP_CLIENT_ID/${IAP_CLIENT_ID}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
+    sed -i "s/YOUR_IAP_SECRET/${IAP_SECRET}/g" ${BACKSTAGE_QS_BASE_DIR}/backstage-qs.auto.tfvars
     ```
 
-2.  Create the resources
+5.  Create the resources
 
     ```bash
     cd ${BACKSTAGE_QS_BASE_DIR} && \
@@ -117,9 +156,91 @@ Management API are enabled.
     rm tfplan
     ```
 
+    Initial run of the Terraform may result in errors due to they way the API
+    services are asyrchonously enabled. Re-running the terraform usually
+    resolves the errors.
+
     This will take a while to create all of the required resources, figure
     somewhere between 15 and 20 minutes.
 
+6.  Build the container image for Backstage
+
+    ```bash
+    cd manifests/cloudbuild
+    gcloud builds submit .
+    ```
+
+    The output of that command will include a fully qualified image path similar
+    to:
+    `us-central1-docker.pkg.dev/[your_project]/backstage-qs/backstage-quickstart:d747db2a-deef-4783-8a0e-3b36e568f6fc`
+    Using that value create a new environment variable.
+
+    ```bash
+    export IMAGE_PATH="<your_image_path>"
+    ```
+
+    This will take approximately 10 minutes to build and push the image.
+
+7.  Configure Cloud SQL postgres user for password authentication.
+
+    ```bash
+    gcloud sql users set-password postgres --instance=backstage-qs --prompt-for-password
+    ```
+
+8.  Grant the backstage workload service account create database permissions.
+
+    a. In the Cloud Console, navigate to `SQL`
+
+    b. Select the database instance
+
+    c. In the left menu select `Cloud SQL Studio`
+
+    d. Choose the `postgres` database and login with the `postgres` user and
+    password you created in step 4.
+
+    e. Run the following sql commands, to grant create database permissions
+
+    ```sql
+    ALTER USER "backstage-qs-workload@[your_project_id].iam" CREATEDB
+    ```
+
+9.  Perform an initial deployment of Kubernetes resources.
+
+    ```bash
+    cd ../k8s
+    sed -i "s%CONTAINER_IMAGE%${IMAGE_PATH}%g" deployment.yaml
+    gcloud container clusters get-credentials backstage-qs --region us-central1 --dns-endpoint
+    kubectl apply -f .
+    ```
+
+10. Capture the IAP audience, the Backend Service may take a few minutes to
+    appear.
+
+    a. In the Cloud Console, navigate to `Security` > `Identity-Aware Proxy`
+
+    b. Verify the IAP option is set to enabled. If not enable it now.
+
+    b. Choose `Get JWT audience code` from the three dot menu on the right side
+    of your Backend Service.
+
+    c. The value will be in the format of:
+    `/projects/<your_project_number>/global/backendServices/<numeric_id>`. Using
+    that value create a new environment variable.
+
+    ```bash
+    export IAP_AUDIENCE_VALUE="<your_iap_audience_value>"
+    ```
+
+11. Redeploy the Kubernetes manifests with the IAP audience
+
+    ```bash
+    sed -i "s%IAP_AUDIENCE_VALUE%${IAP_AUDIENCE_VALUE}%g" deployment.yaml
+    kubectl apply -f .
+    ```
+
+12. In a browser navigate to you backstage endpoint. The URL will be similar to
+    `https://qs.endpoints.[your_project_id].cloud.goog`
+
 ## Cleanup
 
 1.  Destroy the resources using Terraform destroy

reference-architectures/backstage/backstage-quickstart/backstage-qs.auto.tfvars

@@ -1,4 +1,5 @@
 environment_name       = "qs"
 iap_user_domain        = "YOUR_IAP_USER_DOMAIN"
-iap_support_email      = "YOUR_IAP_SUPPORT_EMAIL"
+iap_client_id          = "YOUR_IAP_CLIENT_ID"
+iap_client_secret      = "YOUR_IAP_SECRET"
 environment_project_id = "YOUR_PROJECT_ID"

reference-architectures/backstage/backstage-quickstart/db.tf

@@ -31,16 +31,29 @@ resource "google_sql_database_instance" "instance" {
         psc_enabled               = true
         allowed_consumer_projects = [var.environment_project_id]
       }
+      ssl_mode = "ENCRYPTED_ONLY"
     }
   }
   timeouts {
     create = "30m"
     update = "30m"
     delete = "30m"
   }
+}
 
+resource "google_sql_database" "database" {
+  name     = "backstage"
+  instance = google_sql_database_instance.instance.name
 }
 
+resource "google_sql_user" "iam_service_account_user" {
+  # Note: for Postgres only, GCP requires omitting the ".gserviceaccount.com" suffix
+  # from the service account email due to length limits on database usernames.
+
+  name     = trimsuffix(google_service_account.workloadSa.email, ".gserviceaccount.com")
+  instance = google_sql_database_instance.instance.name
+  type     = "CLOUD_IAM_SERVICE_ACCOUNT"
+}
 
 resource "null_resource" "sqlIamDelay" {
   provisioner "local-exec" {
@@ -50,3 +63,13 @@ resource "null_resource" "sqlIamDelay" {
     "before" = "${google_sql_database_instance.instance.id}"
   }
 }
+
+resource "local_file" "app_config_production_yaml" {
+  content = templatefile(
+    "${path.module}/manifests/templates/app-config.production.tftpl.yaml",
+    {
+      endpoint_url = local.backstageExternalUrl
+    }
+  )
+  filename = "${path.module}/manifests/cloudbuild/app-config.production.yaml"
+}

reference-architectures/backstage/backstage-quickstart/endpoints.tf

@@ -18,7 +18,7 @@ locals {
 
 resource "google_endpoints_service" "backstageQsEndpoint" {
   openapi_config = templatefile(
-    "${path.module}/backstage-qs-endpoint-spec-tftpl.yaml",
+    "${path.module}/manifests/templates/backstage-qs-endpoint-spec-tftpl.yaml",
     {
       endpoint   = local.backstageExternalUrl,
       ip_address = google_compute_global_address.backstageQsEndpointAddress.address
@@ -27,3 +27,11 @@ resource "google_endpoints_service" "backstageQsEndpoint" {
   project      = var.environment_project_id
   service_name = local.backstageExternalUrl
 }
+
+resource "google_compute_managed_ssl_certificate" "backstageCert" {
+  name = "backstage-qs-cert"
+
+  managed {
+    domains = [local.backstageExternalUrl]
+  }
+}

reference-architectures/backstage/backstage-quickstart/gke.tf

@@ -28,7 +28,6 @@ resource "google_container_cluster" "hostingCluster" {
     }
   }
 
-
   logging_config {
     enable_components = ["SYSTEM_COMPONENTS", "WORKLOADS"]
   }
@@ -64,5 +63,4 @@ resource "google_container_cluster" "hostingCluster" {
     update = "30m"
     delete = "30m"
   }
-
 }