> ## 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.

# Infrastructure Naming Conventions

> Standardized naming conventions for all infrastructure resources across GCP, AWS, and Azure with environment-based patterns and platform-specific guidelines

# Infrastructure Naming Conventions

## Overview

This document defines the standardized naming conventions for all infrastructure resources across the MCP Server LangGraph project. All resources follow the pattern: `{environment}-mcp-server-langgraph-{resource-type}`.

**Last Updated:** 2025-11-04
**Status:** ✅ Standardized across GCP, AWS, and Azure

***

## Core Naming Pattern

### Standard Format

```
{environment}-mcp-server-langgraph-{resource-type}
```

### ⚠️ Dual-Prefix Strategy for GCP

Due to GCP character limits on certain resources, we use a **dual-prefix approach**:

1. **Full Prefix** (`{env}-mcp-server-langgraph`): For resources **without** length limits
   * GKE Clusters, Kubernetes Namespaces, Deployments, Services

2. **Short Prefix** (`{env}-mcp-slg`): For resources **with** GCP character limits
   * VPC (20 char max), Cloud SQL, Memorystore Redis, Service Accounts (30 char max)

**Rationale**: GCP enforces strict character limits (20-30 chars) on network and database resources, requiring abbreviated naming while maintaining consistency for Kubernetes resources.

### Environments

| Environment | Abbreviation | Use Case                                       |
| ----------- | ------------ | ---------------------------------------------- |
| Development | `dev`        | Local development, testing, CI/CD validation   |
| Preview     | `preview`    | Pre-production testing, integration validation |
| Production  | `production` | Live production workloads                      |

### Resource Types

| Resource    | Suffix   | Example                            |
| ----------- | -------- | ---------------------------------- |
| GKE Cluster | `-gke`   | `preview-mcp-server-langgraph-gke` |
| EKS Cluster | `-eks`   | `preview-mcp-server-langgraph-eks` |
| AKS Cluster | `-aks`   | `preview-mcp-server-langgraph-aks` |
| Namespace   | *(none)* | `preview-mcp-server-langgraph`     |
| Deployment  | *(none)* | `preview-mcp-server-langgraph`     |
| Service     | *(none)* | `preview-mcp-server-langgraph`     |

***

## Platform-Specific Naming

### Google Cloud Platform (GKE)

#### Cluster Names

```yaml theme={null}
Development:  dev-mcp-server-langgraph-gke
Preview:      preview-mcp-server-langgraph-gke
Production:   production-mcp-server-langgraph-gke
```

#### Namespaces

```yaml theme={null}
Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph
```

#### Deployments (with Kustomize namePrefix)

```yaml theme={null}
Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph
```

#### Services

```yaml theme={null}
Main:         {env}-mcp-server-langgraph
SSE:          {env}-mcp-server-langgraph-sse
Headless:     {env}-mcp-server-langgraph-headless
```

#### Other GCP Resources (Using Short Prefix)

| Resource          | Pattern                           | Example                             |
| ----------------- | --------------------------------- | ----------------------------------- |
| VPC               | `{short_prefix}-vpc`              | `preview-mcp-slg-vpc`               |
| Subnet            | `{short_prefix}-{purpose}-subnet` | `preview-mcp-slg-nodes-us-central1` |
| Cloud SQL         | `{short_prefix}-postgres`         | `preview-mcp-slg-postgres`          |
| Memorystore       | `{short_prefix}-redis`            | `preview-mcp-slg-redis`             |
| Service Account   | `{short_prefix}-{role}-sa`        | `preview-mcp-slg-app-sa`            |
| Artifact Registry | `mcp-{env}`                       | `mcp-preview`, `mcp-production`     |

**Note**: Short prefix = `{env}-mcp-slg` (e.g., `preview-mcp-slg`, `production-mcp-slg`, `dev-mcp-slg`)

***

### Amazon Web Services (EKS)

#### Cluster Names

```yaml theme={null}
Development:  dev-mcp-server-langgraph-eks
Preview:      preview-mcp-server-langgraph-eks
Production:   production-mcp-server-langgraph-eks
```

#### Namespaces

```yaml theme={null}
(Same as GKE - platform-agnostic)
Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph
```

#### Other AWS Resources

| Resource       | Pattern                     | Example                                           |
| -------------- | --------------------------- | ------------------------------------------------- |
| VPC            | `{name_prefix}-vpc`         | `preview-mcp-server-langgraph-vpc`                |
| Subnet         | `{name_prefix}-{az}-{type}` | `preview-mcp-server-langgraph-us-east-1a-private` |
| RDS Instance   | `{name_prefix}-db`          | `preview-mcp-server-langgraph-db`                 |
| ElastiCache    | `{name_prefix}-redis`       | `preview-mcp-server-langgraph-redis`              |
| IAM Role       | `{cluster_name}-{purpose}`  | `preview-mcp-server-langgraph-eks-cluster-role`   |
| ECR Repository | `mcp-server-langgraph`      | *(environment in tags)*                           |

***

### Microsoft Azure (AKS)

#### Cluster Names

```yaml theme={null}
Development:  dev-mcp-server-langgraph-aks
Preview:      preview-mcp-server-langgraph-aks
Production:   production-mcp-server-langgraph-aks
```

#### Namespaces

```yaml theme={null}
(Same as GKE/EKS - platform-agnostic)
Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph
```

#### Other Azure Resources

| Resource        | Pattern               | Example                              |
| --------------- | --------------------- | ------------------------------------ |
| Resource Group  | `{name_prefix}-rg`    | `preview-mcp-server-langgraph-rg`    |
| Virtual Network | `{name_prefix}-vnet`  | `preview-mcp-server-langgraph-vnet`  |
| PostgreSQL      | `{name_prefix}-db`    | `preview-mcp-server-langgraph-db`    |
| Redis Cache     | `{name_prefix}-redis` | `preview-mcp-server-langgraph-redis` |

***

## Kubernetes Resources

### Kustomize Configuration

#### Base Resources

```yaml theme={null}
namespace: mcp-server-langgraph (generic base)
```

#### Environment Overlays

```yaml theme={null}
Development:
  namespace: dev-mcp-server-langgraph
  namePrefix: dev-

Preview (GKE):
  namespace: preview-mcp-server-langgraph
  namePrefix: preview-

Production (GKE):
  namespace: production-mcp-server-langgraph
  namePrefix: production-
```

### Generated Resource Names

With `namePrefix` applied:

| Base Name                                 | Environment | Generated Name                         |
| ----------------------------------------- | ----------- | -------------------------------------- |
| `mcp-server-langgraph` (Deployment)       | preview     | `preview-mcp-server-langgraph`         |
| `mcp-server-langgraph` (Service)          | preview     | `preview-mcp-server-langgraph`         |
| `mcp-server-langgraph-config` (ConfigMap) | preview     | `preview-mcp-server-langgraph-config`  |
| `mcp-server-langgraph-secrets` (Secret)   | preview     | `preview-mcp-server-langgraph-secrets` |

***

## Container Images

### Repository Naming

#### GitHub Container Registry (GHCR)

```
ghcr.io/vishnu2kmohan/mcp-server-langgraph
```

#### Google Artifact Registry (GAR)

```yaml theme={null}
Pattern: {region}-docker.pkg.dev/{project-id}/mcp-{env}/{image-name}

Development:  ghcr.io/vishnu2kmohan/mcp-server-langgraph
Preview:      us-central1-docker.pkg.dev/vishnu-sandbox-20250310/mcp-preview/mcp-server-langgraph
Production:   us-central1-docker.pkg.dev/PROJECT_ID/mcp-production/mcp-server-langgraph
```

#### AWS ECR

```yaml theme={null}
Pattern: {account-id}.dkr.ecr.{region}.amazonaws.com/mcp-server-langgraph

All Environments: mcp-server-langgraph (environment in tags)
```

### Image Tags

```yaml theme={null}
Development:  2.8.0-dev, dev-latest, dev-{sha}
Preview:      2.8.0-preview, preview-latest, preview-{sha}
Production:   2.8.0, latest, {sha}
```

***

## GitHub Actions Variables

### Cluster Variables

| Variable              | Default                               | Description             |
| --------------------- | ------------------------------------- | ----------------------- |
| `GKE_CLUSTER`         | `dev-mcp-server-langgraph-gke`        | Development GKE cluster |
| `GKE_PREVIEW_CLUSTER` | `preview-mcp-server-langgraph-gke`    | Preview GKE cluster     |
| `GKE_PROD_CLUSTER`    | `production-mcp-server-langgraph-gke` | Production GKE cluster  |

### Namespace Variables

| Variable               | Default                           | Description          |
| ---------------------- | --------------------------------- | -------------------- |
| `PREVIEW_NAMESPACE`    | `preview-mcp-server-langgraph`    | Preview namespace    |
| `PRODUCTION_NAMESPACE` | `production-mcp-server-langgraph` | Production namespace |

### Deployment Names

| Variable                       | Value                             | Description           |
| ------------------------------ | --------------------------------- | --------------------- |
| `DEPLOYMENT_NAME` (preview)    | `preview-mcp-server-langgraph`    | Preview deployment    |
| `DEPLOYMENT_NAME` (production) | `production-mcp-server-langgraph` | Production deployment |

***

## Terraform Locals

### Name Prefix Pattern

```hcl theme={null}
locals {
  # GCP Preview
  name_prefix  = "preview-mcp-server-langgraph"
  cluster_name = "${local.name_prefix}-gke"

  # GCP Production
  name_prefix  = "production-mcp-server-langgraph"
  cluster_name = "${local.name_prefix}-gke"

  # GCP Development
  name_prefix  = "dev-mcp-server-langgraph"
  cluster_name = "${local.name_prefix}-gke"

  # AWS Development
  name_prefix  = "dev-mcp-server-langgraph"
  cluster_name = "${local.name_prefix}-eks"

  # AWS Preview
  name_prefix  = "preview-mcp-server-langgraph"
  cluster_name = "${local.name_prefix}-eks"
}
```

***

## Scripts and CLI Tools

### Environment Variables

```bash theme={null}
# GCP Preview
CLUSTER_NAME="preview-mcp-server-langgraph-gke"
NAMESPACE="preview-mcp-server-langgraph"
SERVICE_NAME="preview-mcp-server-langgraph"

# GCP Production
CLUSTER_NAME="production-mcp-server-langgraph-gke"
NAMESPACE="production-mcp-server-langgraph"
SERVICE_NAME="production-mcp-server-langgraph"

# Development
CLUSTER_NAME="dev-mcp-server-langgraph-gke"
NAMESPACE="dev-mcp-server-langgraph"
SERVICE_NAME="dev-mcp-server-langgraph"
```

***

## Legacy Naming (Deprecated)

### Old Patterns (DO NOT USE)

| Old Pattern                    | New Pattern                           | Status                      |
| ------------------------------ | ------------------------------------- | --------------------------- |
| `mcp-staging-cluster`          | `preview-mcp-server-langgraph-gke`    | ❌ Deprecated                |
| `mcp-prod-gke`                 | `production-mcp-server-langgraph-gke` | ❌ Deprecated                |
| `mcp-staging`                  | `preview-mcp-server-langgraph`        | ❌ Deprecated                |
| `mcp-production`               | `production-mcp-server-langgraph`     | ❌ Deprecated                |
| `mcp-server-langgraph-staging` | `preview-mcp-server-langgraph`        | ❌ Deprecated                |
| `mcp-dev-cluster`              | `dev-mcp-server-langgraph-gke`        | ❌ Deprecated                |
| `staging-*`                    | `preview-*`                           | ❌ Deprecated (use preview-) |

### Migration Status

| Component                     | Migration Status | Updated Date |
| ----------------------------- | ---------------- | ------------ |
| GCP Terraform (staging, prod) | ✅ Complete       | 2025-11-04   |
| GCP Terraform (dev)           | ✅ Complete       | 2025-11-04   |
| AWS Terraform (dev, staging)  | ✅ Complete       | 2025-11-04   |
| Kustomization Overlays        | ✅ Complete       | 2025-11-04   |
| GitHub Workflows              | ✅ Complete       | 2025-11-04   |
| GCP Scripts                   | ✅ Complete       | 2025-11-04   |
| Documentation                 | 🟡 In Progress   | 2025-11-04   |
| E2E Tests                     | ⏳ Pending        | -            |

***

## Naming Rules and Guidelines

### Rules

1. **Environment-First**: Always start with the environment name (`dev`, `staging`, `production`)
2. **Consistent Separators**: Use hyphens (`-`) for all multi-word names
3. **Lowercase Only**: All infrastructure names must be lowercase
4. **No Underscores**: Use hyphens instead of underscores (except in variable names)
5. **Platform Suffix**: Add platform suffix (`-gke`, `-eks`, `-aks`) for cluster names
6. **No Platform in Namespaces**: Namespaces are platform-agnostic

### Exceptions

* **Artifact Registry Repos**: Use `mcp-{env}` pattern for simplicity
* **Legacy Service Accounts**: Some SA names may retain `mcp-{env}-*` pattern
* **Generic Platform Overlays**: AWS/Azure Kustomize overlays use generic `mcp-server-langgraph` namespace

***

## Validation

### Automated Checks

Add to `.github/workflows/validate.yaml`:

```yaml theme={null}
- name: Validate Naming Conventions
  run: |
    # Check for deprecated naming patterns
    if grep -r "mcp-staging-cluster\|mcp-prod-gke" terraform/ deployments/ scripts/; then
      echo "❌ Found deprecated naming patterns"
      exit 1
    fi
```

### Manual Verification

```bash theme={null}
# Verify Terraform
grep -r "name_prefix" terraform/environments/

# Verify Kustomization
grep "namespace:" deployments/overlays/*/kustomization.yaml

# Verify Workflows
grep "GKE_CLUSTER\|NAMESPACE" .github/workflows/*.yaml
```

***

## References

* **Terraform**: `terraform/environments/{platform}-{env}/main.tf`
* **Kustomization**: `deployments/overlays/{platform}/kustomization.yaml`
* **Workflows**: `.github/workflows/deploy-{env}-{platform}.yaml`
* **Scripts**: `scripts/{platform}/*.sh`
* **Secrets**: `SECRETS.md`

***

## Support

For questions or clarifications:

1. Review this document first
2. Check implementation in Terraform/Kustomization files
3. Consult team leads for approval before deviating

**Maintained By**: Platform Team
**Review Frequency**: Quarterly or when adding new platforms/environments