ایمن کردن برنامه بااستفاده از افزایه «توسعه‌دهنده Google Cloud» در Antigravity

۱. مقدمه

در این codelab، برنامه وب ماشین‌حساب gCurrenC را در Google Cloud می‌سازید و مستقر می‌کنید، سپس آن را دربرابر دسترسی ناخواسته ایمن می‌کنید. بااستفاده از Google Antigravity، افزونه Google Cloud Developer، و سرور Developer Knowledge (DK) MCP، معماری امنیتی‌ای را طراحی و پیاده‌سازی می‌کنید که کنترل می‌کند چه کسانی می‌توانند به برنامه دسترسی داشته باشند و از آن دربرابر استفاده غیرمجاز محافظت می‌کند.

درطول این آزمایشگاه، Google Antigravity را به سرور DK MCP متصل می‌کنید که Antigravity را در مستندات رسمی و هم‌زمان Google Cloud زمینه‌سازی می‌کند. ‫Antigravity به‌جای تکیه بر داده‌های آموزشی ایستا یا وزن‌های مدل قدیمی، الگوهای معماری فعلی، جدیدترین نحو gcloud CLI، و پارامترهای امنیتی را به‌طور پویا بازیابی می‌کند، که این امر توهمات را کاهش می‌دهد و پاسخ‌ها را براساس دانش به‌روز ارائه می‌دهد.

آنچه خواهید ساخت

  • حجم کاری رایانش خصوصی: دو ماشین مجازی (VM) در Compute Engine که برنامه وب ماشین‌حساب gCurrenC را در شبکه سفارشی Virtual Private Cloud (VPC) بدون نشانی‌های IP عمومی اجرا می‌کنند.
  • خط لوله ورودی ایمن: یک «ترازکننده بار برنامه» خارجی جهانی با زیرشبکه اختصاصی فقط پراکسی که ترافیک اینترنت را ازطریق Google Front Ends (GFEs) به ماشین‌های مجازی خصوصی شما هدایت می‌کند، بدون اینکه آن‌ها را درمعرض اینترنت عمومی قرار دهد.
  • خط لوله خروجی ایمن: یک روتر Cloud و درگاه Cloud NAT که با دیوار آتش نسل بعدی Cloud‏ (Cloud NGFW) Enterprise در سطح پروژه و سرویس مرجع صدور گواهینامه (CAS) جفت شده‌اند تا بازرسی امنیت لایه انتقال (TLS) و اسکن «سرویس جلوگیری از نفوذ» (IPS) را به‌طور هم‌زمان روی ترافیک خروجی میانای برنامه‌سازی کاربردی تبدیل ارز HTTPS انجام دهند.

آنچه خواهید آموخت

  • افزونه google-cloud-developer را بااستفاده از Antigravity CLI نصب کنید و سرور DK MCP را در Antigravity پیکربندی کنید.
  • مستقر کردن و آزمایش کردن برنامه وب خصوصی مجزا در Compute Engine بااستفاده از بازارسال TCP در Identity-Aware Proxy (IAP).
  • از پیام‌واره چندنوبتی زمینه‌سازی‌شده در Antigravity برای طراحی معماری امنیتی ورودی و خروجی در سطح پروژه استفاده کنید.
  • تولید، خودبازرسی، و اجرای اسکریپت استقرار bash برای «تراز کردن بار برنامه خارجی جهانی»، Cloud NAT،‏ CAS، و Cloud NGFW Enterprise.

۲. قبل‌از شروع

پیش‌نیازها

قبل‌از شروع این codelab، مطمئن شوید که موارد زیر را دارید:

  1. «حساب Google» و مرورگر Google Chrome.
  2. پروژه Google Cloud جدید با صورت‌حساب فعال. شناسه پروژه (PROJECT_ID) خود را یادداشت کنید، زیرا در سراسر این codelab برای فعال کردن میاناهای برنامه‌سازی کاربردی، ایجاد کلید میانای برنامه‌سازی کاربردی، و استقرار منابع Google Cloud از آن استفاده می‌کنید.
  3. اجازه‌های «مدیریت هویت و دسترسی‌ها» (IAM) در پروژه Google Cloud شما برای ایجاد کلیدهای میانای برنامه‌سازی کاربردی، منابع Compute Engine، شبکه‌های VPC، استخرهای CAS، تونل IAP، و نقطه‌های پایانی Cloud NGFW.
  4. با gcloud CLI اصالت‌سنجی کنید، پروژه Google Cloud فعال خود را تنظیم کنید، و میاناهای برنامه‌سازی کاربردی لازم را فعال کنید:
    1. در پایانه یا Cloud Shell، بررسی کنید که قبلاً اصالت‌سنجی شده‌اید:
      gcloud auth list
      
      اگر لازم است حسابتان را اصالت‌سنجی کنید، فرمان زیر را اجرا کنید:
      gcloud auth login
      
    2. تأیید کنید که gcloud CLI برای استفاده از پروژه شما پیکربندی شده است:
      gcloud config list project
      
      اگر پروژه‌تان تنظیم نشده است یا اگر پروژه دیگری فعال است، شناسه پروژه‌تان را تنظیم کنید. PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید:
      export PROJECT_ID=PROJECT_ID
      gcloud config set project PROJECT_ID
      
    3. میاناهای برنامه‌سازی کاربردی لازم را در پروژه Google Cloud خود فعال کنید:
      gcloud services enable \
         compute.googleapis.com \
         iap.googleapis.com \
         networksecurity.googleapis.com \
         privateca.googleapis.com \
         developerknowledge.googleapis.com \
         apikeys.googleapis.com
      
  5. Antigravity 2.0 را از صفحه بارگیری Google Antigravity در سیستم محلی‌تان نصب کنید.

نصب کردن افزایه Google Cloud Developer بااستفاده از Antigravity CLI

برای نصب افزونه Google Cloud Developer بااستفاده از Antigravity CLI، کارهای زیر را انجام دهید:

  1. برای نصب Antigravity CLI در ایستگاه کاری محلی خود، مراحل زیر را دنبال کنید:
    1. پایانه محلی‌تان را باز کنید.
    2. دستورگان نصب‌کننده را اجرا کنید:
      curl -fsSL https://antigravity.google/cli/install.sh | bash
      
    3. جلسه پایانه را ببندید و دوباره باز کنید تا Antigravity CLI دودویی agy در سیستم شما PATH دردسترس قرار گیرد.
  2. در پایانه محلی‌تان، فرمان زیر را برای نصب افزایه google-cloud-developer اجرا کنید:
    agy plugin install https://github.com/google/skills/plugins/cloud/google-cloud-developer
    
    بروندادی مشابه زیر می‌بینید:
    Cloning plugin from https://github.com/google/skills.git...
      [ok]    google-cloud-developer
              ✔ skills      : 5 processed
              - agents      : skipped (not found)
              - commands    : skipped (not found)
              ✔ mcpServers  : 1 processed
              - hooks       : skipped (not found)
    
    برای آشنایی با همه مهارت‌ها و ویژگی‌های موجود در افزونه، به سندافزار افزونه Google Cloud Developer و کدلب شروع به کار با افزونه Google Cloud Developer مراجعه کنید.

۳. راه‌اندازی کردن Antigravity و سرور DK MCP

در این بخش، سرور DK MCP را در Antigravity بااستفاده از کلید محدودشده Google Cloud API پیکربندی می‌کنید.

  1. Antigravity را باز کنید، /goal را تایپ کنید و کلید ورود را فشار دهید تا حالت هدف فعال شود، سپس پیام‌واره زیر را جای‌گذاری کنید تا کلید میانای برنامه‌سازی کاربردی محدودشده‌ای ایجاد شود و سرور DK MCP پیکربندی شود. PROJECT_ID را با شناسه پروژه Google Cloud خود از بخش پیش‌از شروع جایگزین کنید. برای اطلاعات بیشتر، افزونه google-cloud-developer را ببینید.
    Set up Antigravity to use the Developer Knowledge MCP server on my local machine. Run the necessary terminal commands to complete the following:
    
    1. Create a restricted API key named 'DKP-MCP-Key' that can only target the Developer Knowledge API. Use the PROJECT_ID to create the API key.
    2. Retrieve the actual key string of the newly created API key.
    3. Create or safely update my ~/.gemini/config/mcp_config.json file (preserve any existing MCP servers) with the correct JSON structure to connect the developer-knowledge server using that API key in the headers.
    You MUST use the following JSON structure for the new server:
    
       "developer-knowledge": {
          "serverUrl": "https://developerknowledge.googleapis.com/mcp",
          "headers": {
          "x-goog-api-key": "<INSERT_RETRIEVED_API_KEY_HERE>"
          }
       }
    
    When you are done, confirm that the setup is complete.
    
  2. برای تأیید اینکه سرور DK MCP فعال است، پیام‌واره زیر را در پنجره گپ Antigravity وارد کنید:
    Which MCP servers are available?
    
    Antigravity developer-knowledge و ابزارهای دردسترس آن (search_documents، answer_query، و get_documents) را فهرست می‌کند:درستی‌سنجی کردن سرورهای MCP دردسترس در Antigravity

۴. ایجاد و استقرار برنامه

در این بخش، برنامه ماشین‌حساب gCurrenC را در دو ماشین مجازی Compute Engine خصوصی در یک شبکه VPC سفارشی مستقر می‌کنید.

این برنامه موارد زیر را ارائه می‌دهد:

  • یک مبدل ارز زنده که از USD، EUR، GBP، JPY، CAD، INR، و AUD بااستفاده از کتابخانه استاندارد داخلی http.server پایتون در درگاه 8080 با نقطه پایانی بررسی سلامت /healthz پشتیبانی می‌کند.
  • کنسول درستی‌سنجی امنیتی برای اجرای اتصال‌پذیری API برون‌مرزی هم‌زمان و کاوشگرهای پیشگیری از تهدید رمزگذاری‌شده.
  • یک قانون دیوار آتش ورودی که به محدوده IAP‏ Google اجازه می‌دهد بدون افشای نشانی‌های IP عمومی، برای آزمایش اداری به درگاه‌های 22 و 8080 دسترسی پیدا کند.

استقرار برنامه

  1. در پنجره گپ Antigravity،‏ /goal را وارد کنید و سپس پیام‌واره زیر را اجرا کنید:
    You are a Cloud developer. Deploy the "gCurrenC calculator" app onto two (2) Compute Engine VMs with no external IP addresses (`--no-address`) inside a dedicated custom VPC network and private subnet.
    
    CRITICAL INSTRUCTIONS ON OUTPUT:
    - The VMs are strictly private with no external IP addresses and the local IAP tunnel has NOT been started yet. Any web URL is completely unreachable and will fail with a connection error.
    - In your final response, simply confirm that the private VMs and Managed Instance Group are deployed, and state that the user should establish the IAP tunnel. Do not output, format, or suggest any web preview link or URL (such as http://localhost:8080 or internal IP addresses) in your final response.
    
    Run this script in the terminal:
    
    ```bash
    #!/usr/bin/env bash
    set -euxo pipefail
    
    # Disable any interactive confirmation prompts so execution never hangs
    export CLOUDSDK_CORE_DISABLE_PROMPTS=1
    
    # --- User Configuration ---
    PROJECT_ID="[PROJECT_ID]"
    REGION="us-central1"
    ZONE="us-central1-a"
    NETWORK="gcurrenc-vpc"
    SUBNET="gcurrenc-app-subnet"
    SUBNET_RANGE="10.10.1.0/24"
    # --------------------------
    
    echo "==> [1/5] Configuring project, default region/zone, and enabling APIs..."
    gcloud config set project "${PROJECT_ID}"
    gcloud config set compute/region "${REGION}"
    gcloud config set compute/zone "${ZONE}"
    gcloud services enable compute.googleapis.com
    
    echo "==> [2/5] Creating custom VPC network and private workload subnet..."
    gcloud compute networks create "${NETWORK}" \
       --subnet-mode=custom \
       --description="Dedicated VPC for currency exchange app demo" 2>/dev/null || true
    
    gcloud compute networks subnets create "${SUBNET}" \
       --network="${NETWORK}" \
       --region="${REGION}" \
       --range="${SUBNET_RANGE}" \
       --enable-private-ip-google-access \
       --description="Private subnet hosting backend compute instances" 2>/dev/null || true
    
    echo "==> [3/5] Generating standalone Python standard-library startup script..."
    cat << 'STARTUP_EOF' > /tmp/private_app_startup.sh
    #!/bin/bash
    set -euxo pipefail
    
    mkdir -p /opt/gcurrenc-app
    
    # Pure Python standard-library application (zero pip/apt dependencies needed at boot)
    cat << 'APPEOF' > /opt/gcurrenc-app/app.py
    import os
    import sys
    import json
    import socket
    import urllib.request
    import urllib.parse
    import ssl
    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
    
    SUPPORTED_CURRENCIES = ["USD", "EUR", "GBP", "JPY", "CAD", "INR", "AUD"]
    
    class CurrencyAppHandler(BaseHTTPRequestHandler):
       def address_string(self):
          return str(self.client_address[0])
    
       def do_GET(self):
          parsed = urllib.parse.urlparse(self.path)
          path = parsed.path
          params = urllib.parse.parse_qs(parsed.query)
    
          if path == "/favicon.ico":
                self.send_response(204)
                self.end_headers()
                return
    
          if path == "/healthz":
                self.send_response(200)
                self.send_header("Content-Type", "text/plain")
                self.end_headers()
                self.wfile.write(b"OK")
                return
    
          if path == "/api/security-test":
                mode = params.get("mode", ["safe"])[0]
                target = "https://secure.eicar.org/eicar.com.txt" if mode == "threat" else "https://api.frankfurter.dev/v1/latest?from=USD&to=EUR"
                try:
                   req = urllib.request.Request(target, headers={"User-Agent": "SecureCurrencyApp/1.0"})
                   ctx = ssl.create_default_context()
                   with urllib.request.urlopen(req, timeout=5, context=ctx) as resp:
                      data = {"verdict": "PERMITTED", "target": target, "http_status": resp.status}
                      code = 200
                except Exception as e:
                   data = {"verdict": "BLOCKED_OR_FAILED", "target": target, "error": str(e)}
                   code = 502
    
                self.send_response(code)
                self.send_header("Content-Type", "application/json")
                self.end_headers()
                self.wfile.write(json.dumps(data, indent=2).encode("utf-8"))
                return
    
          self.render_page()
    
       def do_POST(self):
          parsed = urllib.parse.urlparse(self.path)
          if parsed.path == "/generate":
                content_length = int(self.headers.get("Content-Length", 0))
                post_body = self.rfile.read(content_length).decode("utf-8")
                form = urllib.parse.parse_qs(post_body)
    
                base_curr = form.get("base_curr", ["USD"])[0]
                target_curr = form.get("target_curr", ["EUR"])[0]
                try:
                   amount = float(form.get("amount", ["2500.00"])[0])
                except ValueError:
                   amount = 2500.00
    
                rate_str = "Unavailable"
                total_str = "Rate lookup pending outbound internet activation"
                try:
                   if base_curr == target_curr:
                      rate = 1.0
                   else:
                      url = f"https://api.frankfurter.dev/v1/latest?from={base_curr}&to={target_curr}"
                      req = urllib.request.Request(url, headers={"User-Agent": "SecureCurrencyApp/1.0"})
                      with urllib.request.urlopen(req, timeout=4) as resp:
                            res_json = json.loads(resp.read().decode("utf-8"))
                            rate = res_json["rates"][target_curr]
                   rate_str = str(rate)
                   total_str = f"{round(amount * rate, 2):,.2f} {target_curr}"
                except Exception as e:
                   total_str = f"Outbound connection unavailable {str(e)}"
    
                self.render_page(base_curr, target_curr, amount, rate_str, total_str)
                return
    
          self.send_response(404)
          self.end_headers()
    
       def render_page(self, base_curr="USD", target_curr="EUR", amount=2500.00, fx_rate="1.00", total_str=""):
          hostname = socket.gethostname()
          curr_options_base = "".join([f'<option value="{c}" {"selected" if c == base_curr else ""}>{c}</option>' for c in SUPPORTED_CURRENCIES])
          curr_options_target = "".join([f'<option value="{c}" {"selected" if c == target_curr else ""}>{c}</option>' for c in SUPPORTED_CURRENCIES])
    
          result_block = ""
          if total_str:
                if fx_rate == "Unavailable":
                   rate_line = "<p style='margin: 6px 0;'>Exchange Rate: <span style='color: #d93025; font-weight: bold;'>⚠️ Offline-Outbound internet blocked</span></p>"
                else:
                   rate_line = f"<p style='margin: 6px 0; font-size: 14px; color: #137333;'>🟢 Exchange Rate: <strong>1 {base_curr} = {fx_rate} {target_curr}</strong> (Secured via Cloud NAT & Cloud NGFW)</p>"
    
                result_block = f"""
                <div style="margin-top: 22px; background: #e6f4ea; border: 1px solid #c6e1c6; border-left: 5px solid #34a853; padding: 18px 20px; border-radius: 8px;">
                   <h4 style="margin: 0 0 6px 0; text-transform: uppercase; font-size: 12px; color: #137333; letter-spacing: 0.5px;">Conversion Result</h4>
                   <div style="font-size: 24px; font-weight: 700; color: #202124; margin-bottom: 6px;">
                      {amount:,.2f} {base_curr} = <span style="color: #1a73e8;">{total_str}</span>
                   </div>
                   {rate_line}
                </div>
                """
    
          html = ("""<!DOCTYPE html>
    <html lang="en">
    <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>gCurrenC calculator</title>
       <style>
          body {
                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
                background: #f8f9fa;
                margin: 30px 15px;
                color: #202124;
                display: flex;
                justify-content: center;
          }
          .container {
                width: 100%;
                max-width: 860px;
          }
          .card {
                background: white;
                padding: 24px 28px;
                border-radius: 12px;
                box-shadow: 0 1px 3px rgba(60,64,67,0.12), 0 4px 8px rgba(60,64,67,0.06);
                border: 1px solid #dadce0;
                margin-bottom: 20px;
          }
          .header {
                display: flex;
                justify-content: space-between;
                align-items: center;
                border-bottom: 1px solid #e8eaed;
                padding-bottom: 14px;
                margin-bottom: 20px;
          }
          .header h2 {
                margin: 0 0 4px 0;
                font-size: 20px;
                font-weight: 600;
          }
          .header p {
                margin: 0;
                font-size: 13px;
                color: #5f6368;
          }
          .badge {
                background: #e8f0fe;
                color: #1a73e8;
                padding: 6px 12px;
                border-radius: 16px;
                font-weight: 600;
                font-size: 12px;
                border: 1px solid #d2e3fc;
                display: flex;
                align-items: center;
                gap: 6px;
          }
          .badge::before {
                content: "";
                width: 8px;
                height: 8px;
                border-radius: 50%;
                background-color: #34a853;
          }
          .form-row {
                display: flex;
                gap: 14px;
                align-items: flex-end;
                flex-wrap: wrap;
          }
          .form-group {
                display: flex;
                flex-direction: column;
                gap: 6px;
          }
          .form-group label {
                font-size: 12px;
                font-weight: 600;
                color: #5f6368;
                text-transform: uppercase;
                letter-spacing: 0.5px;
          }
          input, select {
                padding: 10px 14px;
                border: 1px solid #dadce0;
                border-radius: 6px;
                font-size: 14px;
                color: #202124;
                background-color: #fff;
                box-sizing: border-box;
                transition: border-color 0.15s, box-shadow 0.15s;
          }
          input:focus, select:focus {
                outline: none;
                border-color: #1a73e8;
                box-shadow: 0 0 0 3px rgba(26, 115, 232, 0.15);
          }
          button {
                padding: 11px 20px;
                background: #1a73e8;
                color: white;
                border: none;
                border-radius: 6px;
                font-size: 14px;
                font-weight: 500;
                cursor: pointer;
                transition: background 0.15s, box-shadow 0.15s;
          }
          button:hover {
                background: #1557b0;
                box-shadow: 0 1px 2px rgba(60,64,67,0.3);
          }
          .danger-btn {
                background: #d93025;
          }
          .danger-btn:hover {
                background: #b31412;
          }
          pre {
                background: #202124;
                color: #8ab4f8;
                padding: 14px;
                border-radius: 6px;
                overflow-x: auto;
                font-family: "SF Mono", "Fira Code", Consolas, monospace;
                font-size: 13px;
                line-height: 1.5;
                margin: 0;
          }
          /* Collapsible Security Console */
          details.security-drawer {
                background: white;
                border-radius: 12px;
                box-shadow: 0 1px 3px rgba(60,64,67,0.12);
                border: 1px solid #dadce0;
                overflow: hidden;
                margin-bottom: 24px;
          }
          details.security-drawer summary {
                padding: 16px 20px;
                font-size: 14px;
                font-weight: 600;
                cursor: pointer;
                list-style: none;
                display: flex;
                justify-content: space-between;
                align-items: center;
                user-select: none;
                background: #fafafa;
                transition: background 0.15s;
          }
          details.security-drawer summary::-webkit-details-marker {
                display: none;
          }
          details.security-drawer summary:hover {
                background: #f1f3f4;
          }
          details.security-drawer[open] summary {
                border-bottom: 1px solid #dadce0;
                background: #ffffff;
          }
          .expand-toggle {
                font-size: 13px;
                font-weight: 500;
          }
          details.security-drawer summary .expand-toggle::before {
                content: "▶ Click to Expand";
                color: #1a73e8;
          }
          details.security-drawer[open] summary .expand-toggle::before {
                content: "▼ Click to Collapse";
                color: #5f6368;
          }
          .drawer-body {
                padding: 20px;
                background: #ffffff;
          }
          .drawer-body p {
                margin-top: 0;
                font-size: 13px;
                color: #5f6368;
          }
          .probe-buttons {
                display: flex;
                gap: 10px;
                margin-bottom: 14px;
          }
       </style>
    </head>
    <body>
    <div class="container">
       <div class="card">
          <div class="header">
                <div>
                   <h2>💱 gCurrenC calculator</h2>
    
                </div>
                <div class="badge">Serving host: {hostname}</div>
          </div>
          <form method="POST" action="/generate">
                <div class="form-row">
                   <div class="form-group" style="flex: 1.5; min-width: 140px;">
                      <label>Amount</label>
                      <input type="number" step="0.01" name="amount" value="{amount}" required>
                   </div>
                   <div class="form-group" style="flex: 1; min-width: 100px;">
                      <label>From</label>
                      <select name="base_curr">{curr_options_base}</select>
                   </div>
                   <div class="form-group" style="flex: 1; min-width: 100px;">
                      <label>To (Target)</label>
                      <select name="target_curr">{curr_options_target}</select>
                   </div>
                   <div class="form-group">
                      <button type="submit">Convert currency ➔</button>
                   </div>
                </div>
          </form>
          {result_block}
       </div>
    
       <!-- Collapsible Security Verification Console -->
       <details class="security-drawer">
          <summary>
                <span>🛡️ Security verification console</span>
                <span class="expand-toggle"></span>
          </summary>
          <div class="drawer-body">
                <p>Test outbound HTTPS traffic and threat prevention capabilities in real time:</p>
                <div class="probe-buttons">
                   <button type="button" onclick="runProbe('safe')">Test Outbound API Connection</button>
                   <button type="button" class="danger-btn" onclick="runProbe('threat')">Simulate Encrypted Threat (EICAR)</button>
                </div>
                <pre id="output">Waiting for command...</pre>
          </div>
       </details>
    </div>
    <script>
    function runProbe(mode) {
       const el = document.getElementById('output');
       el.innerText = 'Executing outbound request...';
       fetch('/api/security-test?mode=' + mode)
          .then(res => res.json())
          .then(data => el.innerText = JSON.stringify(data, null, 2))
          .catch(err => el.innerText = 'Connection dropped / reset by Firewall: ' + err);
    }
    </script>
    </body>
    </html>"""
             .replace("{hostname}", str(hostname))
             .replace("{amount}", str(amount))
             .replace("{curr_options_base}", curr_options_base)
             .replace("{curr_options_target}", curr_options_target)
             .replace("{result_block}", result_block)
          )
          self.send_response(200)
          self.send_header("Content-Type", "text/html; charset=utf-8")
          self.end_headers()
          self.wfile.write(html.encode("utf-8"))
    
    def run():
       server_address = ('0.0.0.0', 8080)
       httpd = ThreadingHTTPServer(server_address, CurrencyAppHandler)
       httpd.serve_forever()
    
    if __name__ == '__main__':
       run()
    APPEOF
    
    # Register and start systemd unit
    cat << 'SERVICEEOF' > /etc/systemd/system/gcurrenc-app.service
    [Unit]
    Description=Currency exchange calculator web application
    After=network.target
    
    [Service]
    Type=simple
    User=root
    WorkingDirectory=/opt/gcurrenc-app
    ExecStart=/usr/bin/python3 /opt/gcurrenc-app/app.py
    Restart=always
    
    [Install]
    WantedBy=multi-user.target
    SERVICEEOF
    
    systemctl daemon-reload
    systemctl enable gcurrenc-app
    systemctl start gcurrenc-app
    STARTUP_EOF
    
    echo "==> [4/5] Creating Firewall, Regional Instance Template, and 2-VM MIG..."
    gcloud compute firewall-rules create allow-iap-admin \
       --network="${NETWORK}" \
       --allow=tcp:22,tcp:8080 \
       --source-ranges=35.235.240.0/20 \
       --target-tags=gcurrenc-app-vm \
       --description="Allow IAP SSH and port 8080 access to private VMs" \
       --quiet 2>/dev/null || true
    
    # Explicitly pass both --region and --instance-template-region to avoid prompt
    gcloud compute instance-templates create gcurrenc-app-template \
       --instance-template-region="${REGION}" \
       --region="${REGION}" \
       --network="${NETWORK}" \
       --subnet="${SUBNET}" \
       --machine-type=e2-medium \
       --no-address \
       --tags=gcurrenc-app-vm \
       --metadata-from-file=startup-script=/tmp/private_app_startup.sh \
       --quiet
    
    gcloud compute instance-groups managed create gcurrenc-app-mig \
       --base-instance-name=gcurrenc-vm \
       --template="projects/${PROJECT_ID}/regions/${REGION}/instanceTemplates/gcurrenc-app-template" \
       --size=2 \
       --zone="${ZONE}" \
       --quiet
    
    gcloud compute instance-groups managed set-named-ports gcurrenc-app-mig \
       --named-ports=http-port:8080 \
       --zone="${ZONE}" \
       --quiet
    
    echo "==> [5/5] Verifying private VM deployment and internal status..."
    sleep 30
    
    gcloud compute instances list \
       --filter="name ~ '^gcurrenc-vm-'" \
       --zones="${ZONE}" \
       --format="table(name,zone.basename():label=ZONE,networkInterfaces[0].networkIP:label=INTERNAL_IP,status)"
    
    FIRST_VM=$(gcloud compute instances list \
       --filter="name ~ '^gcurrenc-vm-'" \
       --zones="${ZONE}" \
       --format="value(name)" \
       --limit=1)
    
    echo "Testing healthz on ${FIRST_VM} via IAP tunnel..."
    gcloud compute ssh "${FIRST_VM}" \
       --zone="${ZONE}" \
       --tunnel-through-iap \
       --quiet \
       --command="curl -fsS http://localhost:8080/healthz"
    
    echo ""
    echo "=========================================================================="
    echo "PREREQUISITE COMPLETE: 2 private VMs deployed with no external IPs."
    echo "VPC: ${NETWORK} | Subnet: ${SUBNET} (${SUBNET_RANGE})"
    echo "Instance Group: gcurrenc-app-mig (Zone: ${ZONE}, Port: 8080)"
    echo ""
    echo "The VMs are private and the IAP tunnel is not active. Set up the background IAP tunnel first to access the deployed app."
    echo ""
    echo "=========================================================================="
    ```
    

درستی‌سنجی ایجاد نمونه ماشین مجازی

پس‌از اینکه Antigravity استقرار برنامه را در دو Compute Engine VM خصوصی به‌پایان رساند، نمونه‌ها را در کنسول Google Cloud درستی‌سنجی کنید:

  1. در کنسول Google Cloud، به نمونه‌های VM بروید.
  2. تأیید کنید که دو نمونه VM با نشانی‌های IP داخلی و بدون نشانی‌های IP خارجی درحال اجرا هستند:تأیید کردن دو نمونه ماشین مجازی Compute Engine خصوصی بدون نشانی IP خارجی

۵. آزمایش برنامه

چون ماشین‌های مجازی خصوصی نشانی IP خارجی (--no-address) و دروازه Cloud NAT ندارند، مسیری به اینترنت ندارند و نمی‌توانند به میاناهای برنامه‌سازی کاربردی خارجی تبدیل ارز دسترسی پیدا کنند. قبل‌از پیکربندی دسترسی برون‌مرزی ایمن، برنامه را ازطریق تونل IAP محلی آزمایش کنید تا مطمئن شوید دسترسی به اینترنت وجود ندارد.

  1. در حالت /goal، پیام‌واره زیر را در پنجره گپ Antigravity اجرا کنید:
    Automate the IAP tunnel configuration and health verification for the web app, then output the live test URL.
    
    Run a terminal script that performs the following steps non-interactively:
    
    1. Firewall Check:
       - Identify the active network ('gcurrenc-vpc' if it exists, otherwise 'default').
       - Idempotently ensure an ingress firewall rule exists permitting 'tcp:22,tcp:8080' from the Google IAP range '35.235.240.0/20' targeting 'gcurrenc-app-vm'.
    
    2. VM Health Verification:
       - Find the first running instance matching '^gcurrenc-vm-' in zone 'us-central1-a'.
       - Via 'gcloud compute ssh --tunnel-through-iap', verify that the 'gcurrenc-app' systemd service is active. If not active, restart it.
    
    3. Background IAP Tunnel:
       - Free up local port 8080 if an old tunnel or process is lingering (e.g., using 'lsof -ti:8080 | xargs kill -9' or 'fuser -k 8080/tcp').
       - Launch 'gcloud compute start-iap-tunnel <VM_NAME> 8080 --local-host-port=localhost:8080 --zone=us-central1-a' in the background using nohup, redirecting output to '/tmp/iap_tunnel.log'.
       - Wait up to 10 seconds for the tunnel to establish, checking with 'curl -fsS http://localhost:8080/healthz'.
    
    4. Output Web Preview URL:
       - Detect whether the environment is Google Cloud Shell (check if $CLOUD_SHELL is true) or a local workstation.
       - If Cloud Shell, print instructions and the direct web preview link.
       - If local machine, provide the clickable 'http://localhost:8080' URL.
    
  2. پس‌از شروع تونل، http://localhost:8080/ را در مرورگر وب باز کنید:ماشین‌حساب gCurrenC درحال اجرا در VM خصوصی بدون دسترسی به اینترنت برون‌سو
  3. آزمایش برنامه:
    1. روی تبدیل واحد پول کلیک کنید. نتیجه تبدیل Offline - Outbound internet blocked و Outbound connection unavailable را نمایش می‌دهد. این نتیجه موردانتظار است زیرا ماشین‌های مجازی خصوصی نمی‌توانند برای واکشی جدیدترین نرخ‌های تبدیل ارز به اینترنت متصل شوند.
    2. کنسول درستی‌سنجی امنیتی را ازهم باز کنید و روی آزمایش اتصال میانای برنامه‌سازی کاربردی خروجی کلیک کنید. برونداد verdict: BLOCKED_OR_FAILED () را برای https://api.frankfurter.dev/v1/latest نمایش می‌دهد. این نتیجه موردانتظار است زیرا ماشین‌های مجازی خصوصی نمی‌توانند به اینترنت متصل شوند و نرخ‌های تبدیل را از https://api.frankfurter.dev/v1/latest واکشی کنند.
    3. روی شبیه‌سازی تهدید رمزگذاری‌شده (EICAR) کلیک کنید. خروجی همچنین verdict: BLOCKED_OR_FAILED را برای https://secure.eicar.org/eicar.com.txt نمایش می‌دهد. این نتیجه نیز مورد انتظار است زیرا ماشین‌های مجازی خصوصی اتصال اینترنت ندارند.

توقف تونل IAP محلی

قبل‌از طراحی و استقرار معماری امنیتی، تونل IAP محلی را برای آزاد کردن درگاه 8080 خاتمه دهید:

  1. در حالت /goal، پیام‌واره زیر را اجرا کنید:
    Free up local port 8080 and terminate any running Google Cloud IAP tunnels (e.g., kill processes matching 'start-iap-tunnel' or listening on port 8080).
    
    Antigravity تأیید می‌کند که تونل IAP خاتمه یافته است و درگاه محلی 8080 آزاد است.

‫۶. ایمن‌سازی برنامه

در بخش‌های قبلی، ماشین‌های مجازی Compute Engine خصوصی بدون نشانی‌های IP عمومی ایجاد کردید و دو چالش اصلی شبکه‌سازی و امنیتی را تأیید کردید:

  • دسترسی ورودی (ورود): کاربران اینترنت نمی‌توانند مستقیماً به نمونه‌های VM خصوصی دسترسی پیدا کنند و نمایش برنامه وب مستلزم پراکسی کردن ترافیک ازطریق «ترازکننده بار برنامه» خارجی جهانی و زیرشبکه اختصاصی فقط پراکسی بدون نمایش VM به اینترنت عمومی است.
  • دسترسی خروجی (خروج): ماشین‌های مجازی خصوصی هیچ مسیری به اینترنت برای پُرسمان میاناهای برنامه‌سازی کاربردی تبدیل ارز HTTPS زنده ندارند و فعال کردن دسترسی خروجی مستلزم بازرسی ترافیک رمزگذاری‌شده برای بدافزار و استخراج داده بدون شکستن اعتماد SSL/TLS است.

در این بخش، Antigravity را ازطریق یک گردش کار ساده‌شده براساس اسناد رسمی Google Cloud (@retrieving-developer-knowledge) راهنمایی می‌کنید تا یک معماری امنیتی ورودی و خروجی در سطح پروژه برای برنامه خود طراحی، خودبازرسی، و مستقر کنید.

طراحی معماری امنیتی یکپارچه

  1. در حالت /goal، پیام‌واره زیر را اجرا کنید تا نمودار معماری سرتاسری و توضیحی که هم جریان‌های ترافیک ورودی و هم خروجی را پوشش می‌دهد تولید شود:
    You are a Google Cloud Network and Security Architect. We need to design an end-to-end security architecture for our "gCurrenC calculator" app running on private Compute Engine VMs with no external IP addresses inside 'gcurrenc-vpc'.
    
    We are operating in a standalone Google Cloud project without an Organization resource, so all security resources must be scoped at the project level.
    
    Use the @retrieving-developer-knowledge skill to consult official Google Cloud documentation and suggest an architecture diagram and explanation covering both flows:
    
    1. Ingress Flow:
       - How internet users securely reach the private VMs via a global external Application Load Balancer.
       - Why Envoy-based external Application Load Balancers require a dedicated proxy-only subnet, and how Google Front Ends (GFEs) proxy traffic to private backends without exposing VMs to the public internet.
    
    2. Egress Flow:
       - How private VMs reach the internet via Cloud NAT to query live currency exchange APIs, such as frankfurter.dev.
       - How Cloud NGFW Enterprise provides Layer 7 deep packet inspection and intrusion prevention (IPS) for outbound encrypted HTTPS traffic.
       - How TLS inspection backed by Certificate Authority Service (CAS) decrypts outbound HTTPS sessions on the fly, and what Root CA trust configuration the private VMs require.
    
    Provide a clear diagram and explain how these components connect together.
    
    Antigravity از سرور DK MCP پُرسمان می‌کند و نمودار معماری و توضیحی را برمی‌گرداند که نشان می‌دهد چگونه «توازن بار برنامه» خارجی جهانی، زیرشبکه فقط پروکسی، Cloud NAT،‏ CAS، و Cloud NGFW Enterprise در سطح پروژه به یکدیگر متصل می‌شوند.

تولید کردن رئوس مطالب منابع معماری

  1. پیام‌واره زیر را وارد کنید تا طراحی را قبل‌از تولید کردن دستورگان استقرار، در یک طرح کلی منبع در سطح پروژه دسته‌بندی کنید:
    Act as a Lead Network Security Architect. Using the @retrieving-developer-knowledge skill, provide an architectural outline of all the Google Cloud resources required to secure the "gCurrenC calculator" app.
    
    Our starting state:
    - The custom VPC ('gcurrenc-vpc'), workload subnet ('gcurrenc-app-subnet'), and 2-instance MIG ('gcurrenc-app-mig', port 8080) are already deployed.
    - All newly added security components must be project-level resources (no organization resources).
    
    Structure your resource outline into three distinct categories, indicating which resources are new additions:
    1. Core VPC Infrastructure: proxy-only subnet ('gcurrenc-proxy-subnet', 10.10.2.0/24), Cloud Router, and Cloud NAT gateway.
    2. Inbound security (ingress): global external ALB components (forwarding rule on port 443, target HTTPS proxy, SSL certificate, URL map, backend service attached to 'gcurrenc-app-mig' on port 8080, and HTTP health check on '/healthz') and ingress firewall rules.
    3. Outbound security (egress): CAS DevOps CA pool and root CA, project-level Cloud NGFW Enterprise components (Threat Prevention profile, Security Profile Group, Firewall Endpoint in zone us-central1-a, and Endpoint Association attaching the TLS policy), and global network firewall policy egress rules.
    
    For each resource, briefly state its role in the security boundary and how it connects to adjacent components.
    
    ‫Antigravity طرح کلی ساختاریافته‌ای از منابع تولید می‌کند که در سراسر زیرساخت اصلی VPC، توازن بار ورودی، و جلوگیری از تهدیدهای خروجی در سطح پروژه نگاشت شده است.

تولید و خودبازرسی دستورگان استقرار

  1. در حالت /goal، پیام‌واره زیر را اجرا کنید تا یک متن استقرار bash کامل و غیرتعاملی تولید شود و به‌طور خودکار در همان نوبت با الزامات رعایت مطابقت خودسنجی شود:
    Act as a Principal Infrastructure Engineer. Using the @retrieving-developer-knowledge skill, generate a complete, non-interactive Bash script to deploy this entire security architecture for our "gCurrenC calculator" app, and self-audit the script before outputting it.
    
    Requirements:
    - Discover the project ID, region, and zone dynamically from the existing 'gcurrenc-app-subnet' and 'gcurrenc-app-mig'.
    - Keep all resources scoped strictly to the project level (no Organization resource).
    - Deploy the proxy-only subnet, global external Application Load Balancer, Cloud Router, and Cloud NAT. Don't use Cloud Armor.
    - Deploy project-level Cloud NGFW Enterprise with CAS TLS inspection ('--tls-inspect' on the firewall policy egress rule and 'gcloud beta' for the project-level firewall endpoint association) and an explicit DENY override for malware and antivirus threats.
    - Distribute the root CA to the private VMs over IAP SSH with connection timeouts so the guest OS trust store is updated.
    - Print the final Load Balancer URL ('https://${LB_IP}') at the end.
    
    Wrap the script in 'set -euxo pipefail' and output only the single executable bash script block.
    
    ‫Antigravity متن کامل bash را تولید می‌کند، هر فرمان را دربرابر محدودیت‌های رعایت مقررات خودبازرسی می‌کند، و بلوک متن اجرایی واحد را در set -euxo pipefail قرار می‌دهد و خروجی می‌دهد.

اجرای متن فرمان استقرار امنیتی

  1. در حالت /goal، اسکریپت bash تولیدشده از پیام‌واره قبلی را در پنجره گپ Antigravity با قالب زیر جای‌گذاری کنید تا استقرار اجرا شود و نشانی وب برنامه زنده (https://<LB_IP>) خروجی داده شود:
    Run this script.
    <PASTED-SCRIPT>
    

‫۷. درستی‌سنجی کردن برنامه ایمن‌شده

وقتی اسکریپت استقرار به‌پایان می‌رسد، Antigravity نشانی وب HTTPS خارجی «ترازکننده بار برنامه» خارجی جهانی (https://<LB_IP>) را خروجی می‌دهد.

  1. https://<LB_IP> را در مرورگر وب باز کنید و هشدار گواهینامه خودامضاشده مرورگر را دور بزنید تا میانای ماشین‌حساب gCurrenC بار شود:ماشین‌حساب gCurrenC با ترازکننده بار برنامه خارجی جهانی، Cloud NAT، و Cloud NGFW Enterprise ایمن شده است
  2. برنامه را آزمایش کنید تا هم اتصال‌پذیری خروجی و هم جلوگیری از تهدید را تأیید کنید:
    1. روی تبدیل واحد پول کلیک کنید. برنامه بلافاصله نرخ تبدیل ارز زنده را نمایش می‌دهد. این تأیید می‌کند که توازن بار ورودی به‌راحتی ازطریق Google Front Ends (GFEs) و زیرشبکه فقط پراکسی هدایت می‌شود، درحالی‌که Cloud NAT نرخ‌های تبدیل زنده را از api.frankfurter.dev واکشی می‌کند.
    2. کنسول درستی‌سنجی امنیتی را ازهم باز کنید و روی آزمایش اتصال میانای برنامه‌سازی کاربردی خروجی کلیک کنید. برنامه verdict: PERMITTED (HTTP 200) را نمایش می‌دهد. این تأیید می‌کند که مسیریابی Cloud NAT کار می‌کند و سیستم‌عامل VM به CAS Root CA خصوصی برای جلسه‌های HTTPS رمزگشایی‌شده اعتماد دارد.
    3. روی شبیه‌سازی تهدید رمزگذاری‌شده (EICAR) کلیک کنید. برنامه verdict: PERMITTED را نمایش می‌دهد. این تأیید می‌کند که Cloud NGFW Enterprise درخواست HTTPS خروجی را بااستفاده از بازرسی امنیت لایه انتقال (TLS) با پشتیبانی CAS رمزگشایی می‌کند و امضای آزمایشی EICAR را با «سرویس جلوگیری از نفوذ» (IPS) خود بازرسی می‌کند.

‫۸. مرتب‌سازی

برای جلوگیری از کسر هزینه‌های جاری از حساب Google Cloud شما برای منابع ایجادشده در این codelab، می‌توانید فقط منابع codelab را حذف کنید یا پروژه Google Cloud خود را حذف کنید.

  1. اگر می‌خواهید پروژه Google Cloud خود را نگه دارید و فقط منابع ایجادشده درطول این codelab را بردارید، پیام‌واره زیر را در حالت /goal در پنجره گپ Antigravity اجرا کنید:
    Remove all resources created in this session, including the gcurrenc app and its resources. Don't delete the project.
    
  2. اگر پروژه Google Cloud اختصاصی برای این codelab ایجاد کرده‌اید و می‌خواهید کل پروژه را حذف کنید، پیام‌واره زیر را در حالت /goal در پنجره گپ Antigravity اجرا کنید:
    Clean up the demo environment by deleting the Google Cloud project. Run the following command in the terminal:
    gcloud projects delete "$(gcloud config get-value project 2>/dev/null)" --quiet
    

‫۹. تبریک می‌گوییم

تبریک! برنامه وب ماشین‌حساب gCurrenC را بااستفاده از افزونه Google Cloud Developer (سرور DK MCP) در Google Antigravity در Google Cloud مستقر و ایمن کردید.

قدم بعدی چیست

برای کسب اطلاعات بیشتر درباره سرویس‌های استفاده‌شده در این codelab، اسناد رسمی Google Cloud را کاوش کنید: