Skip to main content

Kubernetes Infrastructure Deployment

This guide covers deploying the cloud infrastructure required to run AI/Run CodeMie on Kubernetes. All three cloud providers are supported: AWS (EKS), GCP (GKE), and Azure (AKS).

The Terraform automation provisions a managed Kubernetes cluster together with networking, storage, databases, and security infrastructure. The resulting deployment_outputs.env file contains all values needed for the subsequent platform deployment phase.

This guide covers two deployment methods:

Recommended Approach

Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically.

Existing Infrastructure

If you already have a provisioned Kubernetes cluster with all required services, skip this page and proceed directly to Platform Deployment.

On AWS, the IAM roles and permissions that must be present in an existing account or cluster are listed in AWS IAM Roles and Permissions.

Prerequisites​

Ensure all requirements from the cloud-specific Prerequisites page are met before starting.

Verification Checklist

  • AWS Access: Programmatic access with IAM permissions
  • Tools Installed: Terraform 1.13.5+, AWS CLI, kubectl, Helm, gcloud CLI, Docker
  • AWS Authentication: Configured AWS credentials and region
  • Repository Access: Access to Terraform and Helm repositories
  • Network Planning: Prepared list of allowed networks
  • Domain Configuration: Route 53 hosted zone ready
Authentication Required

You must have configured AWS credentials before running the deployment. Verify with aws sts get-caller-identity.

Scripted Deployment​

Scripted deployment runs all Terraform phases automatically in the correct order and generates deployment_outputs.env upon completion.

Deployment Phases (AWS)

PhaseDescriptionRequired
Phase 1: IAM Deployer RoleCreates IAM role with required permissions for deploymentCan be skipped if role already exists
Phase 2: State BackendCreates S3 bucket with native locking for Terraform state filesYes
Phase 3: Platform InfrastructureDeploys EKS, networking, storage, databases, security componentsYes

Phase 1: Deploy IAM Deployer Role

The IAM deployer role provides necessary permissions for all subsequent infrastructure operations. Skip this phase if the role already exists. An existing role must have the trust policy and permissions described in AWS IAM Roles and Permissions.

  1. Clone the IAM Terraform repository:
git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git
cd codemie-terraform-aws-iam
  1. Create terraform.tfvars:
region             = "us-east-1"
platform_name      = "codemie"
deployer_role_name = "AIRunDeployerRole"

# Optional: IAM Permissions Boundary
iam_permissions_boundary_policy_arn = ""

# Optional: Custom tags
tags = {
  "SysName"     = "AI/Run"
  "Environment" = "Production"
  "Project"     = "AI/Run"
}
  1. Initialize and apply Terraform:
terraform init
terraform plan
terraform apply

Phase 2 & 3: Deploy Platform Infrastructure

  1. Clone the platform repository:
git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git
cd codemie-terraform-aws-platform
  1. Edit deployment.conf:
# Required: AWS Account Information
AWS_PROFILE="My_Profile"

# Required: Basic Configuration
TF_VAR_region="us-east-1"
TF_VAR_role_arn="arn:aws:iam::123456789012:role/AIRunDeployerRole"
TF_VAR_platform_domain_name="airun.example.com"

# Required: EKS Configuration
TF_VAR_cluster_version="1.35"
TF_VAR_demand_instance_types='[{ instance_type = "r5.xlarge" }]'
TF_VAR_demand_max_nodes_count=3
TF_VAR_demand_desired_nodes_count=3
TF_VAR_demand_min_nodes_count=3

# Required: Platform Configuration
TF_VAR_platform_name="codemie"
TF_VAR_subnet_azs='["us-east-1a", "us-east-1b", "us-east-1c"]'
TF_VAR_s3_states_bucket_name="codemie-terraform-states"

# Optional: IAM Permissions Boundary
TF_VAR_eks_admin_role_arn=""
TF_VAR_role_permissions_boundary_arn=""

# Optional: Network Access Control
TF_VAR_enable_private_connections=true
TF_VAR_lb_prefix_list_ids='[]'
TF_VAR_lb_specific_ips='[]'
TF_VAR_security_group_ids='[]'

# Optional: Dedicated RDS Instances
TF_VAR_keycloak_db_config='{"enabled":true}'
TF_VAR_langfuse_db_config='{"enabled":false}'
TF_VAR_litellm_db_config='{"enabled":false}'
Complete Variable List

For all available configuration options, refer to the variables.tf file in the platform repository.

  1. Run the deployment script:
bash ./aws-terraform.sh

The script automatically executes:

  1. Validate Environment — Check for required tools and AWS authentication
  2. Verify Configuration — Validate deployment.conf parameters
  3. Deploy State Backend — Create S3 bucket with native locking
  4. Deploy Platform Infrastructure — Provision EKS, networking, storage, databases
  5. Generate Outputs — Create deployment_outputs.env
Security Groups

Ensure that incoming traffic to the Security Group on LoadBalancers is allowed from:

  • Your VPN or networks you plan to use with AI/Run CodeMie
  • EKS Cluster NAT Gateway EIP (not required if enable_private_connections=true)

Deployment Outputs​

Upon successful deployment, a deployment_outputs.env file is generated containing infrastructure details needed for the platform deployment phase.

# Platform Infrastructure
AWS_DEFAULT_REGION=us-east-1
EKS_AWS_ROLE_ARN=arn:aws:iam::123456789012:role/codemie-eks-role
AWS_KMS_KEY_ID=12345678-90ab-cdef-1234-567890abcdef
AWS_S3_BUCKET_NAME=codemie-platform-bucket
CODEMIE_DOMAIN_NAME=airun.example.com

# PostgreSQL
CODEMIE_POSTGRES_DATABASE_HOST=codemie-rds.123456789012.us-east-1.rds.amazonaws.com
CODEMIE_POSTGRES_DATABASE_PORT=5432
CODEMIE_POSTGRES_DATABASE_NAME=codemie
CODEMIE_POSTGRES_DATABASE_USER=dbadmin
CODEMIE_POSTGRES_DATABASE_PASSWORD="generated-password"
Secure Storage

deployment_outputs.env contains sensitive information. Store it securely, do not commit it to version control, and reference it during the Platform Deployment phase.

Post-Deployment Validation​

# List all resources in the region
aws resourcegroupstaggingapi get-resources --region <region>

# Verify EKS cluster status
aws eks describe-cluster --name <cluster-name> --region <region> --query "cluster.status"

# Verify RDS instance status
aws rds describe-db-instances --db-instance-identifier <rds-instance-name> --region <region>

Review deployment logs:

less logs/codemie_aws_deployment_YYYY-MM-DD-HHMMSS.log

Manual Deployment​

Manual deployment gives full control over each Terraform operation. Use this when you need custom configurations or are integrating with existing infrastructure management workflows.

When to Use Manual Deployment

Use manual deployment when you need fine-grained control over each deployment phase, want to customize Terraform configurations, or are integrating with existing infrastructure management workflows.

Phase 1: IAM Deployer Role

The DeployerRole AWS IAM role will be used for all subsequent infrastructure deployments.

  1. Clone the repository:
git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git
cd codemie-terraform-aws-iam
  1. Create terraform.tfvars:
region             = "us-east-1"
platform_name      = "codemie"
deployer_role_name = "AIRunDeployerRole"
  1. Apply Terraform:
terraform init
terraform plan
terraform apply

Phase 2: Terraform State Backend

  1. Clone the remote backend repository:
git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend.git
cd codemie-terraform-aws-remote-backend
  1. Create terraform.tfvars:
region                = "us-east-1"
role_arn              = "arn:aws:iam::123456789012:role/AIRunDeployerRole"
s3_states_bucket_name = "codemie-terraform-states"
  1. Apply Terraform and note the outputs:
terraform init
terraform plan -out=tfplan
terraform apply tfplan

export BACKEND_BUCKET=$(terraform output -raw terraform_states_s3_bucket_name)
export BACKEND_KMS_KEY_ARN=$(terraform output -raw terraform_state_kms_key_arn)

Phase 3: Platform Infrastructure

  1. Clone the platform repository:
git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git
cd codemie-terraform-aws-platform/platform
  1. Create terraform.tfvars:
region               = "us-east-1"
role_arn             = "arn:aws:iam::123456789012:role/AIRunDeployerRole"
platform_domain_name = "codemie.airun.example.com"
platform_name        = "codemie"
subnet_azs           = ["us-east-1a", "us-east-1b", "us-east-1c"]
cluster_version      = "1.35"
demand_instance_types      = [{ instance_type = "r5.xlarge" }]
demand_max_nodes_count     = 3
demand_desired_nodes_count = 3
demand_min_nodes_count     = 3
keycloak_db_config         = { enabled = true }
langfuse_db_config         = { enabled = false }
litellm_db_config          = { enabled = false }
  1. Initialize Terraform with backend configuration:
export AWS_PROFILE="your-aws-profile"
export REGION="us-east-1"

terraform init \
  -backend-config="bucket=${BACKEND_BUCKET}" \
  -backend-config="key=${REGION}/codemie/platform_terraform.tfstate" \
  -backend-config="region=${REGION}" \
  -backend-config="acl=bucket-owner-full-control" \
  -backend-config="encrypt=true" \
  -backend-config="kms_key_id=${BACKEND_KMS_KEY_ARN}" \
  -backend-config="use_lockfile=true"

terraform plan -out=tfplan
terraform apply tfplan
terraform output

Next Steps​

After successful infrastructure deployment, proceed to Platform Deployment to install AI/Run CodeMie application components.