application-design-center-design-deploy

Designing and Deploying GCP Infrastructure with Application Design Center

Overview

This skill provides a prescriptive, production-grade workflow for the entire

infrastructure lifecycle on Google Cloud Platform (GCP). It replaces the

automated, opaque-box GAD design_infra tool with an **agent-controlled design

and validation loop** utilizing modular Terraform and local CLI validation,

followed by a shifted-left best practices plan scan prior to synchronization

with the Application Design Center (ADC) registry for deployment and lifecycle

management.

Always maintain the persona of a Principal Cloud Architect. Keep the local

Terraform configuration as the source of truth, and ensure the design is fully

compliant with best practices before importing it into the cloud registry.

--------------------------------------------------------------------------------

Index

1. [Pre-requisites: Setup & Confirmation](#pre-requisites-setup-confirmation)
2. [Phase 1: Local Infrastructure Design & Validation](#phase-1-local-infrastructure-design-validation)
3. [Phase 2: Shifted-Left Best Practices Assessment & Iterative Remediation](#phase-2-shifted-left-best-practices-assessment-iterative-remediation)
4. [Phase 3: Import IaC to Application Design Center](#phase-3-import-iac-to-application-design-center)
5. [Phase 4: Application Deployment & Monitoring](#phase-4-application-deployment-monitoring)
6. [Phase 5: Troubleshoot Deployment Failures](#phase-5-troubleshoot-deployment-failures)
7. [Phase 6: Verification & E2E Testing](#phase-6-verification-e2e-testing)

--------------------------------------------------------------------------------

Pre-requisites: Setup & Confirmation

Before executing Phase 1, you must perform the following setup steps:

1. Confirm Target Project & Location:

• Explicitly ask the user to confirm the target GCP project ID and

location (region).

• If the user does not specify a location, use us-central1 as the

default.

• Verify that your local environment has the active project set:

        gcloud config set project <project_id>

--------------------------------------------------------------------------------

Phase 1: Local Infrastructure Design & Validation

Goal: Transform user requirements and codebase characteristics into a 100%

validated, secure, and compile-ready Terraform configuration locally.

1. Invoke the design Skill: Call and execute the design skill (defined

in [design](references/design_guide.md))

for the user's prompt.

• The design skill will autonomously perform the Codebase Analysis,

query the catalog registry, planning, HCL generation, and local CLI

validation loop (terraform init, validate, plan) in a dedicated

scratch directory.

1. Locate Validated HCL: Identify the scratch directory where the design

skill saved the validated, compile-ready Terraform files (e.g.,

scratch/tf_validate_<session_id>/).

1. Verify Handover (MANDATORY): Ensure that the local validation loop in

the design skill completed successfully with a clean plan before

proceeding. Meticulously inspect the HCL to verify:

• Secret-Safe Policy: Confirm that no plaintext credentials,

passwords, or hardcoded secrets are written in terraform.tfvars or HCL

resource blocks. All sensitive inputs must be wired through GCP Secret

Manager.

• State Isolation Policy: Confirm that there is no remote backend

block (e.g., backend "gcs" {}) in the HCL files. State must remain

local in the scratch folder during validation, allowing ADC to handle

the remote state registry upon import.

• Remediation: If any violations are found, correct them in the HCL,

re-run local validation, and verify again. Do not proceed with

unvalidated or insecure code.

1. Export Terraform Plan to JSON (MANDATORY): In the scratch directory, run

the following commands to generate a binary plan and convert it into a clean

JSON representation:

    terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json

Verify that the tfplan.json file is successfully written in your scratch

directory.

--------------------------------------------------------------------------------

Phase 2: Shifted-Left Best Practices Assessment & Iterative Remediation

Goal: Validate the local plan's alignment with security, cost, and

reliability benchmarks BEFORE importing it into the cloud registry, using the

native ADC plan assessment API.

1. Discover Space ID (MANDATORY): Before running the assessment or creating

templates, you must dynamically discover the active ADC Space ID in your

target location:

• List Spaces: Run the command:

        gcloud design-center spaces list --project=<project_id> --location=<location>

• Select Space: Parse the output to identify the active space (e.g.,

test-deploy or googlespace). If multiple spaces exist, ask the user

to confirm. If no space exists, ask the user or create one:

        gcloud design-center spaces create <space_id> --project=<project_id> --location=<location>

1. Execute Plan Assessment via gcloud: Run the plan-based assessment using

the discovered Space ID and your exported tfplan.json file. Execute the

command directly in your terminal:

    gcloud design-center spaces generate-terraform-assessment-report <space_id> \
        --location=<location> \
        --project=<project_id> \
        --terraform-plan="<scratch_directory_path>/tfplan.json" \
        --format=json

1. Analyze Findings: Present all findings to the user in a clean tabular

format, detailing specific violations, resource scopes, and associated

severity levels.

1. Local Remediation Loop:

• Do not attempt to import or commit insecure code.
• Edit your local HCL files in the scratch directory to fix the

reported violations (e.g., adding encryption keys, enabling OS Login, or

restricting IAM scopes).

• Re-run Phase 1 local validation and plan export:

        terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json

• Re-run the plan assessment command shown in step 2.

1. Exit Criteria:

• All high/critical findings resolved, or acceptable trade-offs

documented.

• Maximum of three (3) iterative attempts reached. Once clean or

acceptable, proceed to Phase 3.

--------------------------------------------------------------------------------

Phase 3: Import IaC to Application Design Center

Goal: Synchronize the fully validated and best-practice-compliant local HCL

configuration with the ADC cloud registry to establish the deployable template

resource.

1. Verify or Create the Application Template (MANDATORY): Before importing

the HCL, you must ensure the parent Application Template resource exists

in the discovered ADC space.

• Check Existence: Run `gcloud design-center spaces

application-templates describe <template_id> --space=<space_id>

--project=<project_id> --location=<location>` to check if the template

exists.

• Create if Missing: If the describe command returns a NOT_FOUND

error, create the template resource first by running:

        gcloud design-center spaces application-templates create <template_id> --space=<space_id> --project=<project_id> --location=<location> --display-name="<Name>" --description="<Description>"

1. Strict HCL Parser Constraints (CRITICAL): Before calling the import

operation, ensure your local HCL complies with the ADC registry's strict

ingestion rules:

• Pure Module Policy (No Resource Blocks): The ADC parser strictly

prohibits any resource blocks inside the imported HCL. Only

module, variable, output, and provider blocks are allowed. If a

resource is required (e.g. Private Service Access peering) but no

standalone module is registered for it in the catalog, you MUST check if

it is supported as a built-in configuration option inside an existing

registered module (e.g. setting private_service_access_config inside

module "vpc").

• Strict String Typing: The ADC parser does not perform implicit type

coercion from boolean to string. For example, subnet private access must

be declared as a literal string: subnet_private_access = "true", NOT

as a boolean true.

• No Terraform Block: The parser strictly prohibits the terraform {}

version constraint block. Omit it entirely from providers.tf or

main.tf.

1. Import to ADC Template: Once the template resource is confirmed to exist

and the HCL is validated against the above constraints, invoke the hosted

application_design_center:manage_application_template MCP tool with the

APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC operation:

• Arguments:

• project: The target project ID.
• location: The GCP deployment region (e.g., us-central1).
• spaceId: The discovered ADC space ID.
• applicationTemplateId: A unique name for your application

template.

• operation: APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC
• iacModule: A structured object containing the files list:

            {
              "files": [
                { "name": "main.tf", "content": "<content of main.tf>" },
                { "name": "variables.tf", "content": "<content of variables.tf>" },
                { "name": "terraform.tfvars", "content": "<content of terraform.tfvars>" }
              ]
            }

• Resilience & Retries (MANDATORY):

• If the IMPORT_IAC call fails due to a transient error (e.g., `502

Bad Gateway, 504 Gateway Timeout, or 429 Rate Limit`), **do not

immediately retry**.

• Use exponential backoff with jitter (e.g., waiting 2s, 4s, 8s

plus a random fraction of a second).

• Verify Revision before Retry: If a timeout occurred, first call

gcloud alpha design-center spaces application-templates describe

to check if the import actually succeeded in the background. Only

retry if the template was not updated.

1. Capture Template URI: Upon success, this establishes the template

resource in your space. Construct the applicationTemplateUri using the

pattern:

projects/{project}/locations/{location}/spaces/{spaceId}/applicationTemplates/{applicationTemplateId}

--------------------------------------------------------------------------------

Phase 4: Application Deployment & Monitoring

Goal: Deploy the validated, best-practice-compliant application template to

the GCP environment.

1. Deploy Application: Invoke the hosted

application_design_center:manage_application MCP tool with the

APPLICATION_OPERATION_DEPLOY operation:

• Arguments:
• project: Target project ID.
• location: Target deployment location.
• spaceId: Target space ID.
• applicationId: A unique ID for the deployed application instance.
• applicationTemplateUri: The URI established in Phase 3.
• serviceAccount: The deployment service account.
• Resilience & Retries (MANDATORY):
• If the DEPLOY operation fails with transient network or gateway

errors (e.g., 502, 504), apply **exponential backoff with

jitter** before retrying.

• If the deployment LRO times out or fails with a state conflict,

verify the application status using `gcloud design-center spaces

applications describe` to confirm its status before retrying the

deploy call, avoiding concurrent conflicting deployments.

1. Active LRO Monitoring:

• The tool returns a Long-Running Operation (LRO). Inform the user that

the deployment has started.

• Do not sleep during deployment status polling. Poll the LRO actively

every 30–60 seconds until done: true using the command `gcloud

design-center operations describe <operation_name>`.

1. Handle Results:

• Success: If done is true and there is no error field, proceed

to Phase 6.

• Failure: If an error field is present, analyze the error type and

proceed to Phase 5.

--------------------------------------------------------------------------------

Phase 5: Troubleshoot Deployment Failures

Goal: Diagnose and remediate deployment failures iteratively using the

specialized troubleshooting skill and established cloud resolution patterns.

1. Iterative Cloud Resolution Patterns (CRITICAL): If the deployment fails

with a REVISION_FAILED or TERRAFORM error, check for these common

resource conflicts:

• Service Account 409 Conflict (alreadyExists): If the deployment

fails because a service account generated by the module (e.g.

frontend-service-us-central-sa) already exists in the project,

remediate the local HCL by disabling service account creation and

referencing the existing one:

        create_service_account = false
        service_account        = "<existing_service_account_email>"

• Container Image 404 NotFound: If the deployment fails because a

container image is not found, confirm that the image exists in your

registry. For testing or hello-world deployments, leverage the official

public Google hello-world image:

us-docker.pkg.dev/cloudrun/container/hello

1. Delegate to the Troubleshooting Skill: If a deployment failure occurs

and does not match the above patterns, invoke and execute the specialized

infra-deployment-debugging guide (located in

[infra-deployment-debugging](references/troubleshooting_guide.md)).

1. Select the Troubleshooting Context:

• For Local Validation Errors (Phase 1/2): Follow **Case B: Raw

Terraform Deployment** instructions in the troubleshooting skill to

isolate syntax, compilation, and plan-time validation errors.

• For Cloud Deployment Failures (Phase 4): Follow **Case A: ADC

Application Deployment** instructions in the troubleshooting skill to

analyze LRO errors, retrieve service logs, and diagnose cloud

environment issues.

1. Apply Local-First Remediation:

• Follow the troubleshooting skill's remediation guides to formulate a

fix.

• MANDATORY: Apply the fix directly to your local HCL files in the

scratch directory, re-run local validation, re-import the HCL, and

trigger a new deployment.

• Re-run Phase 1 local validation and plan export:

        terraform validate && terraform plan -out=tfplan && terraform show -json tfplan > tfplan.json

• Re-run the plan assessment (Phase 2) to ensure no new violations are

introduced.

• Re-import the corrected HCL to ADC using

APPLICATION_TEMPLATE_OPERATION_IMPORT_IAC.

• Trigger a new deployment using APPLICATION_OPERATION_DEPLOY.

1. Iteration Threshold: Repeat the troubleshooting, validation, import, and

redeployment cycle up to five (5) times. If it still fails, report the full

history and diagnostics to the user.

--------------------------------------------------------------------------------

Phase 6: Verification & E2E Testing

Goal: Confirm that the deployed services are healthy and fully functional.

1. Retrieve Deployed Resources: Invoke the hosted

application_design_center:manage_application MCP tool with the

APPLICATION_OPERATION_GET operation to retrieve the resource details,

public endpoints, and output parameters.

1. Health Check: Verify that all services are using the correct container

image URLs and that their runtime status is healthy.

1. E2E Validation: Conduct a simple demo test (e.g., checking public HTTP

endpoints or triggering a dry-run transaction) to ensure E2E functionality.

Present the results and public URLs to the user to conclude the task.

Reporting Issues

Report bugs or improvements for this skill at Google Skills Issues.