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

Development:  dev-mcp-server-langgraph-gke
Preview:      preview-mcp-server-langgraph-gke
Production:   production-mcp-server-langgraph-gke

Namespaces

Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph

Deployments (with Kustomize namePrefix)

Development:  dev-mcp-server-langgraph
Preview:      preview-mcp-server-langgraph
Production:   production-mcp-server-langgraph

Services

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

Development:  dev-mcp-server-langgraph-eks
Preview:      preview-mcp-server-langgraph-eks
Production:   production-mcp-server-langgraph-eks

Namespaces

(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

Development:  dev-mcp-server-langgraph-aks
Preview:      preview-mcp-server-langgraph-aks
Production:   production-mcp-server-langgraph-aks

Namespaces

(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

namespace: mcp-server-langgraph (generic base)

Environment Overlays

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)

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

Pattern: {account-id}.dkr.ecr.{region}.amazonaws.com/mcp-server-langgraph

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

Image Tags

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

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

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

- 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

# 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