designing-and-deploying-infrastructure

name	designing-and-deploying-infrastructure
description	This skill is used to design, assess, deploy, and troubleshoot cloud infrastructure using the Application Design Center (ADC).

Designing and Deploying Infrastructure

Index

1. Overview
2. Best Practices & Constraints
3. Phase 1: Infrastructure Design & Refinement
4. Phase 2: Best Practices Assessment & Design Iteration
5. Phase 3: Application Deployment
6. Phase 4: Get Deployed Resources
7. Phase 5: Troubleshoot Deployment Failures
8. Phase 6: Verification & E2E Testing

Overview

This skill provides a prescriptive, multi-loop workflow for the entire infrastructure lifecycle on Google Cloud Platform (GCP). It leverages the Gemini Application Designer (GAD) and Application Design Center (ADC) tools (like gemini_cloud_assist:design_infra and application_design_center:assess_best_practices) to intelligently design architectures, assess best practices, and automate deployment and troubleshooting. Always maintain the persona of a Principal Cloud Architect. Delegate all research and design to the specialized tools provided. Note: These tools are part of the gemini_cloud_assist and application_design_center MCP Servers. Tool names are qualified with their respective server names (e.g., gemini_cloud_assist:tool_name).

Best Practices & Constraints

• Delegation & No Manual Design: Delegate all architecture decisions and product selections to the gemini_cloud_assist:design_infra tool. Do not design manually or edit generated Terraform code. Request changes via the tool.
• Inputs: Always ask the user for required context like project ID, service accounts, etc. if necessary -- do not make assumptions or use placeholders.
• Visualization Power: Always render the Mermaid diagram from gemini_cloud_assist:design_infra in every implementation plan. Refresh the diagram after every design change. Do not create your own diagrams.
• Loop Discipline: Follow the workflow loops and exit criteria strictly. If you cannot follow the Infrastructure Lifecycle Workflow, you must exit and inform the user (for example, if the user cancels the process, or if you hit the maximum troubleshooting loop threshold in Phase 5).
• Application Template as the main resource: The application template is the main resource when generating and iterating on a design. Always look for the application template URI in the gemini_cloud_assist:design_infra response (serializedApplicationTemplateURI), and use that for the rest of the Infrastructure Lifecycle Workflow.
  • Application Template vs Application: Application template is a template that is used to create an application. Application is an instance of an application template. Do not confuse these two.
  • Never attempt to create an application template URI yourself; always use the URI returned from gemini_cloud_assist:design_infra.

Infrastructure Lifecycle Workflow

Phase 1: Infrastructure Design & Refinement

Goal: Transform vague user requirements into a concrete, approved architectural design.

1. Requirement Gathering: Capture user intent if it's vague (e.g., "3-tier web app with high availability"). Guidelines for initial design that you must follow:
   • Gather project ID (required) and ADC space ID (optional) from the user.
2. Codebase Analysis: Critically, before calling gemini_cloud_assist:design_infra, you must perform a thorough exhaustive analysis of the user's application codebase (if available). Do not stop at high-level documentation or configuration files at the surface level; you must inspect the full depth of the codebase, including business logic, to find hidden API clients, dependencies, environment variables, and other application code context required to design cloud infrastructure. The list below outlines critical checks you must perform. Do not limit your investigation to only these items:
   • If you scan the application code to provide additional context, summarize only the application's characteristics (e.g., languages, frameworks, statefulness) and do not assume or suggest specific infrastructure components or services (e.g., do not choose the product type (e.g. GKE, Cloud Run, etc) or network information unless the user explicitly requested them or they are specified in codebase).
   • NEVER rely solely on grep_search, os.environ, or summary documentation (like READMEs) to determine infrastructure needs. DO NOT make premature assumptions or over-optimize for speed. Accuracy is critical; you must inspect the entire codebase.
   • Identify required environment variables, secrets, ports exposed in application, and database connection patterns. Environment Variables may also be present in nginx config files. Environment variables are critical for architecture so double check you have identified all of them.
   • Identify all the dependencies on existing GCP services (e.g., Vertex AI API, pre-existing GCS buckets). Along with the rest of the codebase, you must read dependency files (e.g., requirements.txt, package.json, go.mod) to identify GCP SDKs used and scan source code for explicit GCP client initializations.
   • Scan the codebase (e.g., cloudbuild.yaml, Dockerfile, CI/CD configs) to extract container image URLs. If no image is found or if the identified image does not exist in the Artifact Registry, you must build and upload the image. Provide only the resulting URL to .

Phase 2: Best Practices Assessment & Design Iteration

Goal: Validate design alignment with security, cost, and reliability benchmarks prior to deployment.

1. Execution: Invoke assess_best_practices using the application template metadata (project, location, space and application template identifiers).
2. Analysis: You MUST present all findings to the user in a pretty tabular fashion per framework, detailing specific violations, and their associated severity levels - before proceeding to remediation.
3. Remediation Loop:
   • Pass identified findings as context to gemini_cloud_assist:design_infra(command="manage_app_design").
   • Strict Constraint: All modifications must be executed via the gemini_cloud_assist:design_infra tool; manual Terraform manipulation is prohibited.
   • Perform a diff-based comparison between current and updated Terraform code for user approval.
   • Re-assess post-update to verify the resolution of findings.
4. Exit Criteria:
   • Optimization: Zero findings remaining.
   • Convergence: gemini_cloud_assist:design_infra provides no further suggestions.
   • Threshold: Maximum of three (3) iterative attempts reached.
5. Transition: Proceed to Phase 3 deployment only upon loop termination.

Phase 3: Application Deployment

Goal: Deploy the application template to the GCP environment.

1. Deploy Application: Use the application_design_center:manage_application tool with the APPLICATION_OPERATION_DEPLOY operation to deploy the application.
   • Required Arguments: project, location, spaceId, applicationTemplateUri, applicationId, serviceAccount.
   • Note: This returns a Long-Running Operation (LRO). Inform the user that the deployment has started.
   • Example:

     {
       "project": "my-project",
       "location": "us-central1",
       "spaceId": "my-space",
       "applicationId": "my-app",
       "operation": "APPLICATION_OPERATION_DEPLOY",
       "applicationTemplateUri": "projects/my-project/locations/us-central1/spaces/my-space/applicationTemplates/my-template",
       "serviceAccount": "projects/my-project/serviceAccounts/[e-mail]"
     }
     

2. Monitor Deployment: Repeatedly poll the LRO (e.g., every 30-60 seconds) until done: true.
3. Handle Results:
   • Success: If done is true and there is no error field, proceed to Phase 4.
   • : If an field is present, proceed to Phase 5.

Phase 4: Get Deployed Resources

1. Retrieve Information: Call the application_design_center:manage_application tool with the APPLICATION_OPERATION_GET operation, providing project, location, spaceId and applicationId, to fetch the outputs and status of the deployed resources.
   • Example:

     {
       "project": "my-project",
       "location": "us-central1",
       "spaceId": "my-space",
       "applicationId": "my-app",
       "operation": "APPLICATION_OPERATION_GET"
     }
     

2. User Confirmation: Present the deployed resource information to the user and conclude the task.

Phase 5: Troubleshoot Deployment Failures

Goal: Diagnose and remediate deployment failures iteratively. When troubleshooting a failed application, follow these steps. Process:

1. Initiate Troubleshooting:
   • Action: Call gemini_cloud_assist:design_infra with applicationUri (format: projects/{project}/locations/{location}/spaces/{spaceId}/applications/{applicationId}) to get suggested fixes.
   • Convert the returned response to JSON. The value of a parameter may be a JSON string that needs to be parsed.
   • Expected Output Structure from Troubleshooting:

     {
       "summary": "...",
       "troubleshootingSteps": [
         {
           "description": "...",
           "gcloud_commands": ["gcloud ..."],
           "componentParameters": null
         },
         {
           "description": "...",
           "gcloud_commands": null,
           "componentParameters": [
             {
               "componentUri": "projects/.../components/comp-a",
               "parameters": 
                      
                      
               
             
           
         
       
     
     

• Mutating tool calls often return an LRO.
• Always poll LROs on behalf of the user; do not ask the user to run the polling command.
• Do not sleep during deployment status polling. Poll actively every 30-60 seconds until the LRO is done.
• Apply debug_deployment responses exactly as provided.
• For retries, disregard previous attempts and start from Step 2 again.
• Handle bad-gateway errors during commit with jittered retries and verify the template revision.
• Exclude PORT from being explicitly set as a Cloud Run environment variables as it is a reserved name.

Phase 6: Verification & E2E Testing

Following a successful deployment:

• Verify that services are using correct container image URLs and that each component is healthy.
• Conduct a simple demo test to ensure E2E functionality and validate the hosted services are working as expected.