> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GKE Production Deployment

> Deploy MCP Server LangGraph to Google Kubernetes Engine (GKE) Autopilot with production-grade security, observability, and high availability

### Overview

This guide provides step-by-step instructions for deploying MCP Server LangGraph on **Google Kubernetes Engine (GKE) Autopilot** with enterprise-grade security, monitoring, and cost optimization.

<CardGroup cols={2}>
  <Card title="Deployment Time" icon="clock">
    2-3 hours for complete production setup
  </Card>

  <Card title="Cost Savings" icon="piggy-bank">
    40-60% vs. traditional GKE Standard
  </Card>

  <Card title="Infrastructure Maturity" icon="shield-check">
    94/100 production-readiness score
  </Card>

  <Card title="Best Practices" icon="circle-check">
    100% GCP best practices compliance
  </Card>
</CardGroup>

#### What You'll Deploy

* **GKE Autopilot Cluster**: Fully managed Kubernetes (regional, multi-zone)
* **Cloud SQL PostgreSQL**: High-availability database with automated backups
  * **3 databases**: Keycloak (identity), OpenFGA (authorization), GDPR (compliance per [ADR-0041](/architecture/adr-0041-postgresql-gdpr-storage))
* **Memorystore Redis**: High-availability cache with persistence
* **Workload Identity**: Secure pod-to-GCP service authentication
* **Private Networking**: VPC-native with Cloud NAT
* **Observability**: Cloud Monitoring, Logging, Trace, Profiler
* **Security**: Binary Authorization, Network Policies, Encryption

#### Key Benefits

<AccordionGroup>
  <Accordion title="40-60% Cost Savings">
    GKE Autopilot uses pay-per-pod pricing with no idle node costs. Production environment runs for $880-1,275/month vs. $1,290-1,970 with traditional GKE.
  </Accordion>

  <Accordion title="Zero Node Management">
    Google manages all node infrastructure, upgrades, and scaling automatically. Focus on your application, not Kubernetes operations.
  </Accordion>

  <Accordion title="99.9% Uptime">
    Regional deployment across 3 zones with automated failover for databases and cache provides enterprise-grade reliability.
  </Accordion>

  <Accordion title="Security by Default">
    Built-in Workload Identity, Binary Authorization, Shielded Nodes, Network Policies, and encryption at rest/transit.
  </Accordion>
</AccordionGroup>

***

### Prerequisites

<Steps>
  <Step title="GCP Account & Project">
    Create a GCP project with billing enabled:

    ```bash theme={null}
    # Create project
    gcloud projects create PROJECT_ID --name="MCP LangGraph Production"

    # Link billing
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    # Set active project
    gcloud config set project PROJECT_ID
    ```
  </Step>

  <Step title="Install Required Tools">
    | Tool       | Version | Installation                                             |
    | ---------- | ------- | -------------------------------------------------------- |
    | gcloud CLI | Latest  | `curl https://sdk.cloud.google.com \| bash`              |
    | Terraform  | ≥ 1.5.0 | [terraform.io/downloads](https://terraform.io/downloads) |
    | kubectl    | ≥ 1.28  | `gcloud components install kubectl`                      |
    | kustomize  | ≥ 5.0   | `brew install kustomize`                                 |

    Verify installations:

    ```bash theme={null}
    gcloud version
    terraform version
    kubectl version --client
    kustomize version
    ```
  </Step>

  <Step title="Enable Required APIs">
    Enable 20+ required GCP APIs:

    ```bash theme={null}
    gcloud services enable \
        container.googleapis.com \
        compute.googleapis.com \
        sqladmin.googleapis.com \
        redis.googleapis.com \
        servicenetworking.googleapis.com \
        cloudresourcemanager.googleapis.com \
        iam.googleapis.com \
        binaryauthorization.googleapis.com \
        monitoring.googleapis.com \
        logging.googleapis.com \
        cloudtrace.googleapis.com \
        cloudprofiler.googleapis.com \
        secretmanager.googleapis.com \
        artifactregistry.googleapis.com \
        --project=PROJECT_ID
    ```
  </Step>

  <Step title="Configure IAM Permissions">
    Required roles (or `roles/owner`):

    * `roles/compute.networkAdmin`
    * `roles/container.admin`
    * `roles/cloudsql.admin`
    * `roles/redis.admin`
    * `roles/iam.securityAdmin`
    * `roles/resourcemanager.projectIamAdmin`
  </Step>
</Steps>

***

### Architecture

The production deployment creates a fully managed, highly available infrastructure:

```mermaid theme={null}
flowchart TB
    Internet[Internet Users/APIs]
    LB[Cloud Load Balancer<br/>with Cloud Armor]
    VPC[VPC Network<br/>us-central1]

    subgraph GKE[GKE Autopilot Cluster - Regional]
        ZoneA[Zone A<br/>Pods]
        ZoneB[Zone B<br/>Pods]
        ZoneC[Zone C<br/>Pods]
    end

    WI[Workload Identity]
    GCPSA[GCP Service Accounts]

    subgraph Data[Data Layer]
        SQL[Cloud SQL PostgreSQL<br/>Regional HA]
        Redis[Memorystore Redis<br/>STANDARD_HA]
    end

    subgraph Observability[Cloud Operations]
        Monitor[Cloud Monitoring]
        Logging[Cloud Logging]
        Trace[Cloud Trace]
        Profiler[Cloud Profiler]
    end

    Internet --> LB
    LB --> VPC
    VPC --> GKE
    GKE --> WI
    WI --> GCPSA
    GKE --> Data
    GKE -.-> Observability
    Data -.-> Observability

    %% ColorBrewer2 Set3 palette - each component type uniquely colored
    classDef externalStyle fill:#8dd3c7,stroke:#2a9d8f,stroke-width:2px,color:#333
    classDef ingressStyle fill:#fdb462,stroke:#e67e22,stroke-width:2px,color:#333
    classDef networkStyle fill:#80b1d3,stroke:#3498db,stroke-width:2px,color:#333
    classDef clusterStyle fill:#b3de69,stroke:#7cb342,stroke-width:2px,color:#333
    classDef authStyle fill:#bebada,stroke:#7e5eb0,stroke-width:2px,color:#333
    classDef dataStyle fill:#ffffb3,stroke:#f1c40f,stroke-width:2px,color:#333
    classDef obsStyle fill:#fccde5,stroke:#ec7ab8,stroke-width:2px,color:#333

    class Internet externalStyle
    class LB ingressStyle
    class VPC networkStyle
    class GKE,ZoneA,ZoneB,ZoneC clusterStyle
    class WI,GCPSA authStyle
    class Data,SQL,Redis dataStyle
    class Observability,Monitor,Logging,Trace,Profiler obsStyle
```

***

### Phase 1: Infrastructure Setup (30 minutes)

#### Step 1: Create Terraform State Backend

<Tabs>
  <Tab title="Quick Setup">
    ```bash theme={null}
    cd terraform/backend-setup-gcp

    # Create terraform.tfvars
    cat > terraform.tfvars <<EOF
    project_id    = "YOUR_PROJECT_ID"
    region        = "us-central1"
    bucket_prefix = "mcp-langgraph"
    EOF

    # Deploy
    terraform init
    terraform apply -auto-approve

    # Save bucket name
    export TF_STATE_BUCKET=$(terraform output -raw terraform_state_bucket)
    ```
  </Tab>

  <Tab title="With Options">
    ```bash theme={null}
    cd terraform/backend-setup-gcp

    cat > terraform.tfvars <<EOF
    project_id    = "YOUR_PROJECT_ID"
    region        = "us-central1"
    bucket_prefix = "mcp-langgraph"

    # Optional: Service account for Terraform
    terraform_service_account = "terraform@PROJECT_ID.iam.gserviceaccount.com"

    # Optional: Customer-managed encryption
    enable_cmek  = true
    kms_key_name = "projects/PROJECT_ID/locations/us-central1/keyRings/terraform/cryptoKeys/state"
    EOF

    terraform init
    terraform apply
    ```
  </Tab>
</Tabs>

<Check>Expected: GCS bucket created with versioning and logging enabled</Check>

#### Step 2: Configure Production Environment

```bash theme={null}
cd terraform/environments/gcp-prod

## Update main.tf with state bucket
sed -i "s/bucket = \"mcp-langgraph-terraform-state-us-central1-XXXXX\"/bucket = \"$TF_STATE_BUCKET\"/g" main.tf

## Create terraform.tfvars
cp terraform.tfvars.example terraform.tfvars
```

Edit `terraform.tfvars` with your configuration:

```hcl theme={null}
project_id  = "YOUR_PROJECT_ID"
region      = "us-central1"
team        = "platform"
cost_center = "engineering"

## Security (enable after Phase 4)
enable_binary_authorization = false
enable_private_endpoint     = false  # Set true for maximum security

## Optional: Restrict control plane access
master_authorized_networks_cidrs = [
  {
    cidr_block   = "YOUR_IP/32"
    display_name = "My IP"
  }
]
```

<Warning>
  **Important**: Replace `YOUR_PROJECT_ID` with your actual GCP project ID throughout the configuration.
</Warning>

***

### Phase 2: Deploy Infrastructure (25 minutes)

#### Step 1: Initialize and Plan

```bash theme={null}
cd terraform/environments/gcp-prod
terraform init
terraform plan -out=tfplan
```

<Check>
  Review the plan. It should create:

  * 1 VPC network with 3 subnets
  * 1 GKE Autopilot cluster (regional)
  * 1 Cloud SQL instance (PostgreSQL 15, HA)
  * 1 Memorystore instance (Redis 7.0, HA)
  * 2 NAT IPs
  * Multiple service accounts
  * IAM bindings
  * Firewall rules
  * Monitoring alerts
</Check>

#### Step 2: Deploy

```bash theme={null}
terraform apply tfplan
```

<Info>
  **Duration**: 20-25 minutes. Cloud SQL takes 10-12 minutes, GKE takes 8-10 minutes.
</Info>

#### Step 3: Configure kubectl

```bash theme={null}
## Get credentials
eval $(terraform output -raw kubectl_config_command)

## Verify access
kubectl cluster-info
kubectl get nodes
kubectl get namespaces
```

<Check>
  Expected output:

  ```text theme={null}
  Kubernetes control plane is running at https://X.X.X.X
  NAME              STATUS   AGE
  default           Active   5m
  kube-system       Active   5m
  ```
</Check>

***

### Phase 3: Application Deployment (20 minutes)

#### Step 1: Create Secrets in Secret Manager

```bash theme={null}
PROJECT_ID="YOUR_PROJECT_ID"

## Create secret
gcloud secrets create mcp-production-secrets \
  --replication-policy="automatic" \
  --project="$PROJECT_ID"

## Prepare secret data
cat > /tmp/secrets.json <<EOF
{
  "anthropic_api_key": "sk-ant-...",
  "google_api_key": "AIza...",
  "jwt_secret": "$(openssl rand -base64 32)",
  "postgres_password": "$(terraform output -raw cloudsql_user_password)",
  "cloudsql_connection_name": "$(terraform output -raw cloudsql_connection_name)",
  "redis_host": "$(terraform output -raw redis_host)",
  "redis_port": "$(terraform output -raw redis_port)",
  "redis_password": "$(terraform output -raw redis_auth_string)"
}
EOF

## Upload secrets
gcloud secrets versions add mcp-production-secrets \
  --data-file=/tmp/secrets.json \
  --project="$PROJECT_ID"

## Cleanup
rm -f /tmp/secrets.json
```

#### Step 2: Install External Secrets Operator

```bash theme={null}
helm repo add external-secrets https://charts.external-secrets.io
helm repo update

helm install external-secrets \
  external-secrets/external-secrets \
  --namespace external-secrets-system \
  --create-namespace \
  --set installCRDs=true

kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/name=external-secrets \
  -n external-secrets-system \
  --timeout=120s
```

#### Step 3: Deploy Application

```bash theme={null}
cd deployments/overlays/production-gke

## Update with your project ID
sed -i "s/PROJECT_ID/$PROJECT_ID/g" *.yaml

## Deploy
kubectl apply -k .

## Watch rollout
kubectl rollout status deployment/production-mcp-server-langgraph \
  -n mcp-production \
  --timeout=10m
```

<Check>
  Verify deployment:

  ```bash theme={null}
  kubectl get pods -n mcp-production
  kubectl logs -n mcp-production -l app=mcp-server-langgraph --tail=50
  ```
</Check>

***

### Phase 4: Security Hardening (30 minutes)

#### Binary Authorization

Enable image signing to ensure only trusted container images run in your cluster:

<Steps>
  <Step title="Run Setup Script">
    ```bash theme={null}
    ./deployments/security/binary-authorization/setup-binary-auth.sh \
      PROJECT_ID \
      production
    ```

    This creates:

    * KMS key for signing
    * Binary Authorization attestor
    * Enforcement policy
  </Step>

  <Step title="Sign Images">
    ```bash theme={null}
    IMAGE="us-central1-docker.pkg.dev/PROJECT_ID/mcp-production/mcp-server-langgraph:2.8.0"

    ./deployments/security/binary-authorization/sign-image.sh \
      PROJECT_ID \
      production \
      "$IMAGE"
    ```
  </Step>

  <Step title="Enable in Cluster">
    Edit `terraform.tfvars`:

    ```hcl theme={null}
    enable_binary_authorization = true
    ```

    Apply:

    ```bash theme={null}
    terraform apply -auto-approve
    ```
  </Step>
</Steps>

<Info>
  Learn more about [Binary Authorization](/deployment/binary-authorization) for complete setup details.
</Info>

***

### Phase 5: Observability (10 minutes)

#### Setup Monitoring

```bash theme={null}
## Create dashboards and alerts
./monitoring/gcp/setup-monitoring.sh PROJECT_ID
```

This configures:

* Custom Cloud Monitoring dashboard
* Alert policies (CPU, memory, errors, latency)
* Uptime checks
* SLO definitions

#### Access Dashboards

<CardGroup cols={2}>
  <Card title="GKE Workloads" icon="chart-line" href="https://console.cloud.google.com/kubernetes/workload/overview">
    View pod status, deployments, services
  </Card>

  <Card title="Cloud Monitoring" icon="chart-area" href="https://console.cloud.google.com/monitoring">
    Custom dashboards, metrics, alerts
  </Card>

  <Card title="Cloud Logging" icon="file-lines" href="https://console.cloud.google.com/logs">
    Centralized log aggregation
  </Card>

  <Card title="Cloud Trace" icon="network-wired" href="https://console.cloud.google.com/traces">
    Distributed tracing
  </Card>
</CardGroup>

***

### Verification & Testing

#### Health Checks

Test all health endpoints:

<CodeGroup>
  ```bash Port Forward theme={null}
  kubectl port-forward -n mcp-production \
    svc/production-mcp-server-langgraph 8000:8000 &

  curl http://localhost:8000/health/live
  curl http://localhost:8000/health/ready
  curl http://localhost:8000/health/startup
  ```

  ```bash Load Balancer theme={null}
  SERVICE_IP=$(kubectl get svc production-mcp-server-langgraph \
    -n mcp-production \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

  curl http://$SERVICE_IP:8000/health/live
  ```
</CodeGroup>

<Check>All health checks should return HTTP 200</Check>

#### Database Connectivity

```bash theme={null}
kubectl exec -it -n mcp-production \
  $(kubectl get pod -n mcp-production -l app=mcp-server-langgraph -o jsonpath='{.items[0].metadata.name}') \
  -c cloud-sql-proxy \
  -- wget -qO- http://localhost:9801/readiness
```

<Check>Should return: `ok`</Check>

#### Workload Identity

Verify service account annotation:

```bash theme={null}
kubectl get sa production-mcp-server-langgraph \
  -n mcp-production \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'
```

<Check>Should show: `mcp-prod-app-sa@PROJECT_ID.iam.gserviceaccount.com`</Check>

***

### Troubleshooting

<AccordionGroup>
  <Accordion title="Pods Stuck in Pending">
    **Diagnosis**:

    ```bash theme={null}
    kubectl describe pod POD_NAME -n mcp-production
    ```

    **Common causes**:

    1. Resource requests too high (Autopilot provisions automatically but has limits)
    2. Image pull errors (check Workload Identity permissions)
    3. Binary Authorization blocking unsigned images

    **Solution**:

    * Reduce CPU/memory requests in deployment
    * Verify image exists in Artifact Registry
    * Sign the image if Binary Auth is enabled
  </Accordion>

  <Accordion title="Can't Access Cloud SQL">
    **Diagnosis**:

    ```bash theme={null}
    kubectl logs -n mcp-production POD_NAME -c cloud-sql-proxy
    ```

    **Solution**:

    1. Verify private service connection exists
    2. Check Cloud SQL instance is running
    3. Verify Cloud SQL Proxy sidecar configuration
    4. Check Workload Identity IAM bindings
  </Accordion>

  <Accordion title="Workload Identity Not Working">
    **Diagnosis**:

    ```bash theme={null}
    kubectl get sa -n mcp-production production-mcp-server-langgraph -o yaml

    gcloud iam service-accounts get-iam-policy \
      mcp-prod-app-sa@PROJECT_ID.iam.gserviceaccount.com
    ```

    **Solution**:

    1. Verify annotation: `iam.gke.io/gcp-service-account`
    2. Check IAM binding exists
    3. Wait 1-2 minutes for propagation
  </Accordion>
</AccordionGroup>

For complete troubleshooting, see [GKE Operational Runbooks](/deployment/operations/gke-runbooks).

***

### Cost Optimization

#### Expected Monthly Costs

<Tabs>
  <Tab title="Production">
    | Component     | Configuration                     | Cost/Month      |
    | ------------- | --------------------------------- | --------------- |
    | GKE Autopilot | \~25 pods (500m CPU, 1GB RAM avg) | \$360           |
    | Cloud SQL     | 4 vCPU, 15GB RAM, HA + replica    | \$280           |
    | Memorystore   | 5GB Redis HA                      | \$220           |
    | Networking    | NAT, egress                       | \$60            |
    | Monitoring    | Standard retention                | \$50            |
    | **Total**     |                                   | **\$970/month** |

    **vs. Traditional GKE**: $1,290/month (Save $320/month = 25%)
  </Tab>

  <Tab title="With Commitments">
    | Commitment | Discount | Monthly Cost | Annual Savings |
    | ---------- | -------- | ------------ | -------------- |
    | On-demand  | 0%       | \$970        | -              |
    | 1-year CUD | 25%      | \$728        | \$2,904        |
    | 3-year CUD | 52%      | \$466        | \$6,048        |
  </Tab>
</Tabs>

<Card title="Cost Optimization Guide" icon="money-bill-trend-up" href="/deployment/cost-optimization">
  Learn how to achieve 40-60% cost savings with rightsizing, committed use discounts, and automation.
</Card>

***

### Next Steps

<CardGroup cols={2}>
  <Card title="Operational Runbooks" icon="book" href="/deployment/operations/gke-runbooks">
    Day-2 operations, incident response, maintenance procedures
  </Card>

  <Card title="Security Hardening" icon="shield-halved" href="/security/gcp-security-hardening">
    Enable VPC Service Controls, configure Cloud Armor, implement policies
  </Card>

  <Card title="CI/CD Pipeline" icon="arrows-spin" href="/deployment/gitops-argocd">
    Setup automated deployments with ArgoCD and GitHub Actions
  </Card>

  <Card title="Monitoring & SLOs" icon="chart-mixed" href="/deployment/monitoring">
    Configure custom dashboards, define SLIs/SLOs, set up alerts
  </Card>
</CardGroup>

***

### Related Documentation

<CardGroup cols={3}>
  <Card title="Infrastructure as Code" icon="code" href="/deployment/infrastructure/terraform-gcp">
    Terraform modules for VPC, GKE, Cloud SQL, Redis
  </Card>

  <Card title="Multi-Environment Setup" icon="layer-group" href="/deployment/infrastructure/multi-environment">
    Dev, staging, production configurations
  </Card>

  <Card title="Disaster Recovery" icon="life-ring" href="/deployment/disaster-recovery">
    Multi-region failover and backup automation
  </Card>

  <Card title="Service Mesh" icon="diagram-project" href="/deployment/service-mesh">
    Anthos Service Mesh for advanced traffic management
  </Card>

  <Card title="Binary Authorization" icon="file-signature" href="/deployment/binary-authorization">
    Image signing and policy enforcement
  </Card>

  <Card title="GKE Preview" icon="flask" href="/deployment/kubernetes/gke-preview">
    Preview environment setup
  </Card>
</CardGroup>

***

### Support Resources

<Card title="Complete Technical Documentation" icon="file-zipper">
  For detailed technical documentation, see:

  * GKE Deployment Guide (800+ lines, root directory)
  * Terraform Module READMEs (5,000+ lines technical docs)
  * GCP Best Practices Summary (root directory)
</Card>

Need help? Check our [operational runbooks](/deployment/operations/gke-runbooks).