Kubernetes Deployment Prerequisites
This page outlines the requirements for deploying AI/Run CodeMie on a managed Kubernetes cluster. A cloud provider can be selected below to view provider-specific requirements.
Account Requirements
- AWS
- Azure
- GCP
Required Access and Permissions
To deploy AI/Run CodeMie on AWS, you need:
- Active AWS Account with preferred region for deployment
- Programmatic Access with credentials that have permissions to create and manage IAM Roles and Policy Documents
IAM Roles and Permissions
For the complete list of IAM roles and permissions, including the requirements for installation into existing infrastructure and an existing EKS cluster, see AWS IAM Roles and Permissions.
- Sufficient Quota for the required resources (EKS, RDS, networking, storage, etc.)
Complete Resource List
For a detailed list of all AWS resources that will be provisioned, refer to the Architecture section or review the Terraform modules in the deployment repository.
Required Access and Permissions
To deploy AI/Run CodeMie on Azure, you need:
- Active Azure Subscription with sufficient quota for the required resources
- Contributor Role for the deployment user with the following permissions:
- Access to Entra ID App Registration to obtain Application ID and Secret
- Ability to create and manage Azure resources (AKS, networking, storage, etc.)
Complete Resource List
For a detailed list of all Azure resources that will be provisioned, refer to the Architecture section or review the Terraform modules in the deployment repository.
- Entra ID Access on the Azure portal to retrieve application details such as Tenant ID
Required Access and Permissions
To deploy AI/Run CodeMie on GCP, you need:
- Active GCP Project with sufficient quota for the required resources
- Project Owner or Editor Role for the deployment user with the following permissions:
- Ability to create and manage IAM Roles and Service Accounts
- Access to create and manage GCP resources (GKE, VPC, Cloud SQL, etc.)
Complete Resource List
For a detailed list of all GCP resources that will be provisioned, refer to the Architecture section or review the Terraform modules in the deployment repository.
- Ability to bind the following IAM roles to service accounts:
roles/aiplatform.user- For Vertex AI accessroles/storage.admin- For Cloud Storage managementroles/cloudkms.cryptoKeyEncrypterDecrypter- For encryption key operations
Required GCP APIs
The following APIs must be enabled in your GCP project before deployment:
| API | Purpose |
|---|---|
| Cloud Identity-Aware Proxy API | Secure identity-based access control |
| Service Networking API | Private service connectivity |
| Secret Manager API | Centralized secrets management |
| Vertex AI API | AI model integration and inference |
Make sure you are familiar with Gemini models, their parameters, available regions, and other crucial details in the Vertex AI documentation.
Network Requirements
DNS and Certificate Requirements
- AWS
- Azure
- GCP
AI/Run CodeMie requires proper DNS and TLS certificate configuration:
- Route 53 Hosted Zone with available wildcard DNS configuration
- Automatic Certificate Management - AI/Run CodeMie Terraform modules will automatically create:
- DNS Records in Route 53
- TLS certificates through AWS Certificate Manager for ALB and NLB
DNS and certificate provisioning is fully automated through Terraform when using AI/Run CodeMie-managed infrastructure. You only need to provide the hosted zone. However, if you're using self-provisioned infrastructure, you will need to handle DNS records and certificates for it.
DNS and TLS certificate requirements depend on your access model:
- Public Access
- Private Access
If you require public internet access to AI/Run CodeMie:
- Azure DNS Zone must be created and domain delegated there
- Valid wildcard TLS certificate must be available for HTTPS connections
If you only require internal access within your organization:
- AI/Run CodeMie Terraform modules will automatically create a private DNS zone
- No external DNS delegation or public certificates are required
- Registered domain name delegated to Cloud DNS with permissions to create DNS records
- Valid wildcard TLS certificate must be available for HTTPS connections (see Ingress NGINX TLS guide)
- AWS
- Azure
- GCP
Outbound Connectivity
Your EKS cluster's Security Groups and Network ACLs must allow outbound access to the following endpoints:
| Destination | Purpose |
|---|---|
europe-west3-docker.pkg.dev | AI/Run CodeMie container registry (Google Container Registry) |
quay.io | Third-party container images |
docker.io | Docker Hub container images |
| Your integration services | GitLab, GitHub, or other services you plan to use with CodeMie |
AI/Run CodeMie container images are hosted on Google Container Registry (GCR). You will need gcloud CLI installed on your deployment machine to authenticate and pull helm charts from GCR.
Inbound Connectivity on Corporate Services
If you plan to integrate AI/Run CodeMie with external corporate services (e.g., GitLab, GitHub, internal APIs):
- Configure the firewall on your external service to allow inbound traffic from the AI/Run CodeMie NAT Gateway public IP address
- This allows AI/Run CodeMie to make outbound API calls to your external services (e.g., GitLab API, GitHub API, internal services)
The AI/Run CodeMie NAT Gateway public IP address will only be available after infrastructure deployment. You will need to configure external service firewalls after the installation is complete.
Access Control Network List
To restrict access to AI/Run CodeMie and prevent unauthorized access from the public internet, prepare a list of allowed networks:
- Corporate network CIDR ranges from which users will access AI/Run CodeMie
- VPN network ranges if remote users connect via VPN
- Office locations and their public IP addresses or CIDR blocks
- Any other trusted networks that require access to the platform
Outbound Connectivity
Your AKS cluster's Network Security Group (NSG) or firewall must allow outbound access to the following endpoints:
| Destination | Purpose |
|---|---|
europe-west3-docker.pkg.dev | AI/Run CodeMie container registry (Google Container Registry) |
quay.io | Third-party container images |
docker.io | Docker Hub container images |
| Your integration services | GitLab, GitHub, or other services you plan to use with CodeMie |
AI/Run CodeMie container images are hosted on Google Container Registry (GCR). You will need gcloud CLI installed on your deployment machine to authenticate and pull helm charts from GCR.
Inbound Connectivity on Corporate Services
If you plan to integrate AI/Run CodeMie with external corporate services (e.g., GitLab, GitHub, internal APIs):
- Configure the firewall on your external service to allow inbound traffic from the AI/Run CodeMie NAT Gateway public IP address
- This allows AI/Run CodeMie to make outbound API calls to your external services (e.g., GitLab API, GitHub API, internal services)
The AI/Run CodeMie NAT Gateway public IP address will only be available after infrastructure deployment. You will need to configure external service firewalls after the installation is complete.
Access Control Network List
To restrict access to AI/Run CodeMie and prevent unauthorized access from the public internet, prepare a list of allowed networks:
- Corporate network CIDR ranges from which users will access AI/Run CodeMie
- VPN network ranges if remote users connect via VPN
- Office locations and their public IP addresses or CIDR blocks
- Any other trusted networks that require access to the platform
Outbound Connectivity
Your GKE cluster's firewall or VPC firewall rules must allow outbound access to the following endpoints:
| Destination | Purpose |
|---|---|
europe-west3-docker.pkg.dev | AI/Run CodeMie container registry (Google Container Registry) |
quay.io | Third-party container images |
docker.io | Docker Hub container images |
| Your integration services | GitLab, GitHub, or other services you plan to use with CodeMie |
AI/Run CodeMie container images are hosted on Google Container Registry (GCR). You will need gcloud CLI installed on your deployment machine to authenticate and pull helm charts from GCR.
Inbound Connectivity on Corporate Services
If you plan to integrate AI/Run CodeMie with external corporate services (e.g., GitLab, GitHub, internal APIs):
- Configure the firewall on your external service to allow inbound traffic from the AI/Run CodeMie Cloud NAT public IP address
- This allows AI/Run CodeMie to make outbound API calls to your external services (e.g., GitLab API, GitHub API, internal services)
The AI/Run CodeMie Cloud NAT public IP address will only be available after infrastructure deployment. You will need to configure external service firewalls after the installation is complete.
Access Control Network List
To restrict access to AI/Run CodeMie and prevent unauthorized access from the public internet, prepare a list of allowed networks:
- Corporate network CIDR ranges from which users will access AI/Run CodeMie
- VPN network ranges if remote users connect via VPN
- Office locations and their public IP addresses or CIDR blocks
- Any other trusted networks that require access to the platform
Kubernetes Cluster Requirements
- AWS
- Azure
- GCP
Requirements for EKS cluster deployment.
Administrative Permissions
The deployment user must have:
- EKS Admin permissions with the ability to create and manage namespaces
- Access to configure cluster-level resources (if deploying to an existing cluster)
Admission Control and Resource Requirements
If deploying to an existing EKS cluster, ensure that admission webhooks allow the creation of the following Kubernetes resources:
- NATS Messaging
- Keycloak Operator
- Security Context
NATS is currently deprecated as part of the NATS retirement direction.
Kubernetes API: Service (LoadBalancer type)
Purpose: NATS is a core component of the CodeMie Plugin Engine, providing messaging infrastructure for communication between the codemie-plugins CLI tool with MCP and the AI/Run CodeMie platform.
The LoadBalancer configuration depends on where the CLI tool will be executed:
| CLI Tool Execution Location | LoadBalancer Type | Description |
|---|---|---|
| Same VPC as EKS cluster | Internal LoadBalancer | Secure, private network communication within the VPC |
| External to EKS VPC | Public LoadBalancer | Cross-network communication when CLI is run outside the VPC |
Kubernetes APIs: ClusterRole, ClusterRoleBinding, Role, RoleBinding, Custom Resource Definitions (CRDs), Custom Resources (CRs)
Purpose: Manages Keycloak configuration including realms, clients, and user federation
Requires cluster-wide permissions for identity and access management operations.
Kubernetes API: Pod with securityContext
Requirement: All AI/Run CodeMie components require readOnlyRootFilesystem: false in their security context for proper operation
Requirements for AKS cluster deployment.
Administrative Permissions
The deployment user must have:
- AKS Admin permissions with the ability to create and manage namespaces
- Access to configure cluster-level resources (if deploying to an existing cluster)
Admission Control and Resource Requirements
If deploying to an existing AKS cluster, ensure that admission webhooks allow the creation of the following Kubernetes resources:
- NATS Messaging
- Keycloak Operator
- Security Context
NATS is currently deprecated as part of the NATS retirement direction.
Kubernetes API: Service (LoadBalancer type)
Purpose: NATS is a core component of the CodeMie Plugin Engine, providing messaging infrastructure for communication between the codemie-plugins CLI tool with MCP and the AI/Run CodeMie platform.
The LoadBalancer configuration depends on where the CLI tool will be executed:
| CLI Tool Execution Location | LoadBalancer Type | Description |
|---|---|---|
| Same VNet as AKS cluster | Internal LoadBalancer | Secure, private network communication within the VNet |
| External to AKS VNet | Public LoadBalancer | Cross-network communication when CLI is run outside the VNet |
Kubernetes APIs: ClusterRole, ClusterRoleBinding, Role, RoleBinding, Custom Resource Definitions (CRDs), Custom Resources (CRs)
Purpose: Manages Keycloak configuration including realms, clients, and user federation
Requires cluster-wide permissions for identity and access management operations.
Kubernetes API: Pod with securityContext
Requirement: All AI/Run CodeMie components require readOnlyRootFilesystem: false in their security context for proper operation
Requirements for GKE cluster deployment.
Administrative Permissions
The deployment user must have:
- GKE Admin permissions with the ability to create and manage namespaces
- Access to configure cluster-level resources (if deploying to an existing cluster)
Admission Control and Resource Requirements
If deploying to an existing GKE cluster, ensure that admission webhooks allow the creation of the following Kubernetes resources:
- NATS Messaging
- Keycloak Operator
- Security Context
NATS is currently deprecated as part of the NATS retirement direction.
Kubernetes API: Service (LoadBalancer type)
Purpose: NATS is a core component of the CodeMie Plugin Engine, providing messaging infrastructure for communication between the codemie-plugins CLI tool with MCP and the AI/Run CodeMie platform.
The LoadBalancer configuration depends on where the CLI tool will be executed:
| CLI Tool Execution Location | LoadBalancer Type | Description |
|---|---|---|
| Same VPC as GKE cluster | Internal LoadBalancer | Secure, private network communication within the VPC |
| External to GKE VPC | Public LoadBalancer | Cross-network communication when CLI is run outside the VPC |
Kubernetes APIs: ClusterRole, ClusterRoleBinding, Role, RoleBinding, Custom Resource Definitions (CRDs), Custom Resources (CRs)
Purpose: Manages Keycloak configuration including realms, clients, and user federation
Requires cluster-wide permissions for identity and access management operations.
Kubernetes API: Pod with securityContext
Requirement: All AI/Run CodeMie components require readOnlyRootFilesystem: false in their security context for proper operation
- AWS
- Azure
- GCP
No AWS-specific cluster configuration is required beyond the general Kubernetes cluster requirements above.
No Azure-specific cluster configuration is required beyond the general Kubernetes cluster requirements above.
GKE Cluster Configuration
This section applies only to GCP deployments.
VPC-Native Networking and Container-Native Load Balancing
AI/Run CodeMie requires GKE clusters configured with VPC-native networking and container-native load balancing (NEGs) for proper Ingress functionality.
Required Configuration:
- Networking Mode:
VPC_NATIVEwith IP allocation policy (secondary ranges for pods and services) - HTTP Load Balancing Addon: Enabled (default)
If your cluster uses GKE Network Policy or Calico, container-native load balancing will NOT be enabled automatically. This causes Ingress errors:
service "namespace/service" is type "ClusterIP", expected "NodePort" or "LoadBalancer"
Solution: Manually enable NEGs by adding this annotation to all Services exposed via Ingress in chart values. For example:
service:
type: ClusterIP
port: 8080
annotations:
cloud.google.com/neg: '{"ingress": true}'
Deployment Machine Requirements
Required Software Tools
The following tools must be pre-installed and properly configured on your deployment machine (laptop, workstation, or VDI instance):
| Tool | Version | Purpose |
|---|---|---|
| Terraform | 1.13.5 | Infrastructure as Code provisioning |
| kubectl | latest | Kubernetes cluster management |
| Helm | 3.16.0+ | Kubernetes package management |
| gcloud CLI | latest | Authentication to AI/Run CodeMie container registry (GCR) |
| Docker | latest | Container operations |
| natscli | latest | NATS messaging CLI |
| nsc | latest | NATS security configuration |
| jq | latest | JSON processing and parsing |
| curl | latest | HTTP requests and file transfers |
htpasswd | linux package | Password hash generation |
- AWS
- Azure
- GCP
Cloud-Specific Tools:
| Tool | Version | Purpose |
|---|---|---|
| AWS CLI | latest | AWS resource management |
Cloud-Specific Tools:
| Tool | Version | Purpose |
|---|---|---|
| Azure CLI | latest | Azure resource management |
| kubelogin | latest | AKS authentication plugin |
For GCP deployments, gcloud CLI serves dual purposes: GCP resource management and authentication to AI/Run CodeMie container registry (GCR).
Cluster Access
Before proceeding to Platform Deployment, confirm you have kubectl access to the cluster provisioned during Infrastructure Deployment.
- AWS
- Azure
- GCP
Obtain kubeconfig credentials for the EKS cluster:
aws eks update-kubeconfig --region <REGION> --name <CLUSTER_NAME>
Verify access:
kubectl get nodes
Connect to the Jumpbox VM via Bastion, then obtain kubeconfig credentials for the AKS cluster:
az login
az account set --subscription <SUBSCRIPTION_ID>
az aks get-credentials \
--resource-group <RESOURCE_GROUP> \
--name <CLUSTER_NAME> \
--overwrite-existing
kubelogin convert-kubeconfig -l azurecli
Verify access:
kubectl get nodes
For private clusters, connect via the Bastion Host first. Then obtain kubeconfig credentials for the GKE cluster:
gcloud container clusters get-credentials <CLUSTER_NAME> --project <PROJECT_ID> --region <REGION>
Verify access:
kubectl get nodes
Container Registry Access
CodeMie container images are hosted on europe-west3-docker.pkg.dev regardless of the cloud provider you deploy to. You need a GCP service account key file (key.json) with read access to the registry before installing components.
Contact your CodeMie administrator or EPAM delivery team to obtain the key.json file for registry access.
Create the namespace and pull secret:
kubectl create namespace codemie
kubectl create secret docker-registry gcp-artifact-registry \
--docker-server=https://europe-west3-docker.pkg.dev \
--docker-email=`<client_email from shared with you key>` \
--docker-username=_json_key \
--docker-password="$(cat key.json)" \
-n codemie
Verify the secret:
kubectl get secret gcp-artifact-registry -n codemie
The gcp-artifact-registry secret must be referenced in all AI/Run CodeMie component deployments: codemie-ui, codemie-api, codemie-nats-auth-callout, codemie-mcp-connect-service, and mermaid-server.
This is configured automatically in the values files:
imagePullSecrets:
- name: gcp-artifact-registry
Required Repository Access
You will need access to the following repositories to complete the deployment:
- AWS
- Azure
- GCP
- Terraform IAM Module: codemie-terraform-aws-iam
- Terraform Platform Module: codemie-terraform-aws-platform
- Terraform Remote Backend: codemie-terraform-aws-remote-backend
- Helm Charts: codemie-helm-charts
- Terraform Modules: codemie-terraform-azure
- Helm Charts: codemie-helm-charts
- Terraform Platform Modules: codemie-terraform-gcp-platform
- Helm Charts: codemie-helm-charts
If your deployment machine operates in an isolated environment without direct internet or repository access, the repositories can be provided as ZIP/TAR archives and transferred through approved channels.