diff --git a/docs/admin/deployment/aws/kubernetes/images/architecture-diagram.drawio.png b/docs/admin/architecture/images/architecture-diagram-aws.drawio.png similarity index 100% rename from docs/admin/deployment/aws/kubernetes/images/architecture-diagram.drawio.png rename to docs/admin/architecture/images/architecture-diagram-aws.drawio.png diff --git a/docs/admin/deployment/azure/kubernetes/images/architecture-diagram.drawio.png b/docs/admin/architecture/images/architecture-diagram-azure.drawio.png similarity index 100% rename from docs/admin/deployment/azure/kubernetes/images/architecture-diagram.drawio.png rename to docs/admin/architecture/images/architecture-diagram-azure.drawio.png diff --git a/docs/admin/deployment/gcp/kubernetes/images/architecture-diagram.drawio.png b/docs/admin/architecture/images/architecture-diagram-gcp.drawio.png similarity index 100% rename from docs/admin/deployment/gcp/kubernetes/images/architecture-diagram.drawio.png rename to docs/admin/architecture/images/architecture-diagram-gcp.drawio.png diff --git a/docs/admin/deployment/aws/on-vm/images/domain-mode-diagram.drawio.png b/docs/admin/architecture/images/on-vm-architecture-diagram-aws-domain-mode.drawio.png similarity index 100% rename from docs/admin/deployment/aws/on-vm/images/domain-mode-diagram.drawio.png rename to docs/admin/architecture/images/on-vm-architecture-diagram-aws-domain-mode.drawio.png diff --git a/docs/admin/deployment/aws/on-vm/images/ip-mode-diagram.drawio.png b/docs/admin/architecture/images/on-vm-architecture-diagram-aws-ip-mode.drawio.png similarity index 100% rename from docs/admin/deployment/aws/on-vm/images/ip-mode-diagram.drawio.png rename to docs/admin/architecture/images/on-vm-architecture-diagram-aws-ip-mode.drawio.png diff --git a/docs/admin/deployment/aws/on-vm/images/private-mode-diagram.drawio.png b/docs/admin/architecture/images/on-vm-architecture-diagram-aws-private-mode.drawio.png similarity index 100% rename from docs/admin/deployment/aws/on-vm/images/private-mode-diagram.drawio.png rename to docs/admin/architecture/images/on-vm-architecture-diagram-aws-private-mode.drawio.png diff --git a/docs/admin/deployment/azure/on-vm/images/architecture-diagram.drawio.png b/docs/admin/architecture/images/on-vm-architecture-diagram-azure.drawio.png similarity index 100% rename from docs/admin/deployment/azure/on-vm/images/architecture-diagram.drawio.png rename to docs/admin/architecture/images/on-vm-architecture-diagram-azure.drawio.png diff --git a/docs/admin/deployment/gcp/on-vm/images/architecture-diagram.drawio.png b/docs/admin/architecture/images/on-vm-architecture-diagram-gcp.drawio.png similarity index 100% rename from docs/admin/deployment/gcp/on-vm/images/architecture-diagram.drawio.png rename to docs/admin/architecture/images/on-vm-architecture-diagram-gcp.drawio.png diff --git a/docs/admin/architecture/index.mdx b/docs/admin/architecture/index.mdx new file mode 100644 index 00000000..2b0005e6 --- /dev/null +++ b/docs/admin/architecture/index.mdx @@ -0,0 +1,38 @@ +--- +id: architecture-overview +title: AI/Run CodeMie Deployment Architecture +sidebar_label: Architecture +sidebar_position: 1 +pagination_prev: admin/index +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + +# AI/Run CodeMie Deployment Architecture + +This section describes the AI/Run CodeMie deployment architecture, including infrastructure components, network design, and resource requirements. Two architecture variants are available depending on the target environment. + +## Architecture Variants + + + + +
+ + +## Next Steps + +After reviewing the architecture, proceed to [Prerequisites](../deployment/prerequisites/) to review the requirements before deployment. diff --git a/docs/admin/architecture/kubernetes.mdx b/docs/admin/architecture/kubernetes.mdx new file mode 100644 index 00000000..9e5aac48 --- /dev/null +++ b/docs/admin/architecture/kubernetes.mdx @@ -0,0 +1,154 @@ +--- +id: architecture-kubernetes +title: Kubernetes Deployment Architecture +sidebar_label: Kubernetes +sidebar_position: 2 +pagination_prev: admin/architecture/architecture-overview +pagination_next: admin/architecture/architecture-on-vm +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ContainerResources from '../deployment/common/deployment/architecture/_container-resources.mdx'; + +# Kubernetes Deployment Architecture + +This page describes the full production deployment architecture on a managed Kubernetes cluster. A cloud provider can be selected below for provider-specific details. + +## Application Stack Components + +The AI/Run CodeMie application consists of multiple integrated components organized into functional categories: + +![Application Stack](../deployment/common/deployment/images/application-stack-diagram.drawio.png) + +### Core AI/Run CodeMie Services + +Proprietary services that provide the main AI/Run CodeMie functionality: + +| Component | Container Registry | Description | +| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| **CodeMie API** | `europe-west3-docker.pkg.dev/.../codemie:x.y.z` | Backend service handling business logic, data processing, and API operations | +| **CodeMie UI** | `europe-west3-docker.pkg.dev/.../codemie-ui:x.y.z` | Frontend web application providing the user interface | +| **NATS Auth Callout** | `europe-west3-docker.pkg.dev/.../codemie-nats-auth-callout:x.y.z` | Authentication and authorization service for NATS messaging (Plugin Engine component) | +| **MCP Connect** | `europe-west3-docker.pkg.dev/.../codemie-mcp-connect-service:x.y.z` | Bridge enabling CodeMie to communicate with MCP servers | +| **Mermaid Server** | `europe-west3-docker.pkg.dev/.../mermaid-server:x.y.z` | Diagram generation service for visualization in chats | + +### Data Layer + +Database and search components for data persistence: + +| Component | Container Registry | Description | +| ----------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | +| **Elasticsearch** | `docker.elastic.co/elasticsearch/elasticsearch:x.y.z` | Primary data store for AI/Run CodeMie (datasources, projects, conversations, etc.) | +| **Kibana** | `docker.elastic.co/kibana/kibana:x.y.z` | Analytics and visualization interface for Elasticsearch data | + +### Security & Identity Management + +Authentication and authorization components: + +| Component | Container Registry | Description | +| --------------------- | ----------------------------------------- | --------------------------------------------------------------------------- | +| **Keycloak Operator** | `epamedp/keycloak-operator:x.y.z` | Manages Keycloak deployment and configuration | +| **Keycloak** | `quay.io/keycloak/keycloak:x.y.z` | Identity and access management (IAM) solution providing SSO, authentication | +| **OAuth2 Proxy** | `quay.io/oauth2-proxy/oauth2-proxy:x.y.z` | Authentication middleware integrating with Keycloak for secure access | + +### Infrastructure Services + +Essential Kubernetes infrastructure components: + +| Component | Container Registry | Description | +| ---------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- | +| **Nginx Ingress Controller** | `registry.k8s.io/ingress-nginx/controller:x.y.z` | Routes external traffic to internal services | +| **Storage Class** | Cloud-provider CSI driver (EBS, Azure Disk, or GCP Persistent Disk) | Provides persistent volumes for stateful components | + +### Messaging & Integration + +Message broker for Plugin Engine: + +| Component | Container Registry | Description | +| --------- | ------------------ | ----------------------------------------------------------------- | +| **NATS** | `nats:x.y.z` | High-performance messaging system for Plugin Engine communication | + +### Observability + +Logging and monitoring components: + +| Component | Container Registry | Description | +| -------------- | ----------------------------------------- | ------------------------------------------------------ | +| **Fluent Bit** | `cr.fluentbit.io/fluent/fluent-bit:x.y.z` | Lightweight log collector enabling agent observability | + +### Optional Components + +Components that can be omitted based on configuration: + +| Component | Container Registry | Description | +| ------------- | ------------------ | ----------------------------------------------------------------------------------------------- | +| **LLM Proxy** | – | Optional proxy for load balancing and high availability of AI model requests and usage insights | + +### Deployment Dependencies + +Components must be deployed in the following order due to dependencies: + +1. **Infrastructure** → Ingress Controller, Storage Class +2. **Operators** → Keycloak Operator +3. **Data Layer** → Elasticsearch +4. **Security** → Keycloak (with database credentials), OAuth2 Proxy +5. **Messaging** → NATS +6. **Core Services** → CodeMie API, UI, MCP Connect, NATS Auth +7. **Observability** → Fluent Bit, Kibana +8. **Optional** → LLM Proxy (if needed) + +## Cloud Infrastructure + +A cloud provider can be selected below for provider-specific infrastructure details. + + + + +AI/Run CodeMie is deployed on Amazon Elastic Kubernetes Service (EKS) with supporting AWS services for networking, storage, and identity management. + +**High-Level Architecture Diagram** + +The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on AWS: + +![AWS Architecture Diagram](./images/architecture-diagram-aws.drawio.png) + + + + +AI/Run CodeMie is deployed on Azure Kubernetes Service (AKS) with supporting Azure services for networking, storage, and identity management. + +**High-Level Architecture Diagram** + +The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on Azure: + +![Azure Architecture Diagram](./images/architecture-diagram-azure.drawio.png) + + + + +AI/Run CodeMie is deployed on Google Kubernetes Engine (GKE) with supporting GCP services for networking, storage, and identity management. + +**Deployment Options** + +There are two deployment options available depending on your organization's access requirements: + +- **Public cluster option** - Access to AI/Run CodeMie from predefined networks or IP addresses (VPN, corporate networks, etc.) using public DNS resolution from user workstations +- **Private cluster option** - Access to AI/Run CodeMie via Bastion host using private DNS resolution for enhanced security + +**High-Level Architecture Diagram** + +The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on GCP: + +![GCP Architecture Diagram](./images/architecture-diagram-gcp.drawio.png) + + + + +:::tip Architecture Customization +The architecture can be customized based on your organization's security policies, compliance requirements, and operational preferences. Consult with your deployment team to discuss specific requirements. +::: + +## Kubernetes Resource Requirements + + diff --git a/docs/admin/architecture/on-vm.mdx b/docs/admin/architecture/on-vm.mdx new file mode 100644 index 00000000..f9f489c4 --- /dev/null +++ b/docs/admin/architecture/on-vm.mdx @@ -0,0 +1,193 @@ +--- +id: architecture-on-vm +title: On-VM Deployment Architecture +sidebar_label: On VM +sidebar_position: 3 +pagination_prev: admin/architecture/architecture-kubernetes +pagination_next: admin/deployment/prerequisites/prerequisites-overview +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# On-VM Deployment Architecture + +CodeMie On VM deploys the full AI/Run CodeMie platform on a **single virtual machine** using Docker Compose. It provides the same core functionality as the full Kubernetes deployment but with minimal infrastructure overhead, and is designed for proof-of-concept and demo environments rather than production workloads. + +## Application Architecture + +All CodeMie services run as Docker containers on the VM, orchestrated by Docker Compose. This layer is identical regardless of the underlying cloud provider. + +![Docker Compose Services](../deployment/common/deployment/images/docker-compose-diagram.drawio.png) + +### Services by Profile + +**Shared services** (both profiles): + +| Service | Image | Purpose | +| ------------- | --------------------------- | ------------------------------------------------- | +| postgres | pgvector/pgvector:pg17 | Primary database for application data | +| elasticsearch | elasticsearch:8.x | Document storage and search for Data Sources | +| kibana | kibana:8.x | Log visualization and analytics for Elasticsearch | +| mcp-connect | codemie-mcp-connect-service | Connector for MCP servers | +| nginx | nginx:1.31-alpine | Reverse proxy, TLS termination | + +**OSS profile:** + +| Service | Purpose | +| -------------- | --------------------------------------------- | +| codemie-oss | API server with built-in local authentication | +| codemie-ui-oss | Web frontend | + +**Enterprise profile:** + +| Service | Purpose | +| ----------------- | ---------------------------------------------- | +| codemie | API server | +| codemie-ui | Web frontend | +| keycloak | Identity provider (SSO, OIDC) | +| oauth2-proxy | Authentication proxy in front of nginx | +| litellm | LLM proxy for model routing and key management | +| nats | Messaging for plugin engine | +| nats-auth-callout | NATS authentication service | +| mermaid-server | Diagram rendering | + +## Infrastructure Overview + + + + +CodeMie On VM runs on a single EC2 instance with supporting AWS services. Terraform provisions the following resources depending on the network mode: + + + + Direct access to the EC2 instance via Elastic IP: + + ![IP Mode Diagram](./images/on-vm-architecture-diagram-aws-ip-mode.drawio.png) + + + + When `TF_VAR_platform_domain_name` is configured, an ALB with trusted TLS certificate is created: + + ![Domain Mode Diagram](./images/on-vm-architecture-diagram-aws-domain-mode.drawio.png) + + + + When `TF_VAR_private_ip_only=true`, EC2 is placed in a private subnet with NAT Gateway for outbound traffic. Access is via VPN, AWS Workspaces, or some other available VM: + + ![Private Mode Diagram](./images/on-vm-architecture-diagram-aws-private-mode.drawio.png) + + + + +**AWS Resources** + +| Resource | Purpose | +| ------------------------ | --------------------------------------------------------------------- | +| **VPC** | Isolated network with public subnets (+ private if `private_ip_only`) | +| **EC2 Instance** | Single instance running Docker Compose (Ubuntu, r5.xlarge default) | +| **Elastic IP** | Static public IP for the EC2 instance | +| **S3 Bucket** | Persistent storage for user data (repos, files) | +| **KMS Key** | Encryption key for S3 data at rest | +| **ALB** | Application Load Balancer with TLS (if domain configured) | +| **ACM Certificate** | Trusted TLS certificate for the domain (if domain configured) | +| **Route 53 Record** | DNS A record pointing to ALB (if domain configured) | +| **SSM Parameter** | Stores EC2 SSH private key securely | +| **Security Groups** | Controls inbound traffic to ALB and EC2 | +| **IAM Instance Profile** | Grants EC2 access to Bedrock, S3, KMS, SSM | + +**Network Modes** + +| Mode | Configuration | Access | +| ----------------------- | ------------------------------------------- | --------------------------------- | +| **Public IP** (default) | `TF_VAR_private_ip_only=false` | EC2 gets EIP, direct HTTPS access | +| **Domain + ALB** | `TF_VAR_platform_domain_name="example.com"` | ALB with ACM cert, Route 53 DNS | +| **Private IP** | `TF_VAR_private_ip_only=true` | No public IP, access via VPN only | + + + + +![Azure On VM Infrastructure Architecture](./images/on-vm-architecture-diagram-azure.drawio.png) + +CodeMie On VM runs on a single Azure VM with supporting Azure services. Terraform provisions the following resources: + +**Azure Resources** + +| Resource | Purpose | +| ------------------------------ | -------------------------------------------------------------------- | +| **Azure VM (Standard_E4s_v5)** | Single VM running Docker Compose (4 vCPU, 32 GB RAM) | +| **Virtual Network / Subnet** | Isolated network for the VM | +| **Network Security Group** | Controls inbound/outbound traffic to the VM | +| **Azure Storage Account** | Persistent storage for user data (repos, files) | +| **Azure Key Vault** | Encryption key management for storage data | +| **Private DNS Zone** | Custom domain resolution (when `TF_VAR_platform_domain_name` is set) | +| **Azure Bastion** | Secure SSH access to the VM without exposing a public IP | + +**Network Modes** + +| Mode | Configuration | Access | +| ------------------------ | ----------------------------------------------- | ----------------------------------------- | +| **Private IP** (default) | `TF_VAR_platform_domain_name` empty | VM private IP, access via VPN or Bastion | +| **Domain** | `TF_VAR_platform_domain_name="private.lab.com"` | Creates private DNS zone, access via name | + + + + +![GCP On VM Infrastructure Architecture](./images/on-vm-architecture-diagram-gcp.drawio.png) + +CodeMie On VM runs on a single GCE VM with supporting GCP services. Terraform provisions the following resources: + +**GCP Resources** + +| Resource | Purpose | +| ------------------------------ | -------------------------------------------------------------------- | +| **GCE VM (n2-highmem-4)** | Single VM running Docker Compose (4 vCPU, 32 GB RAM) | +| **VPC / Subnet** | Isolated network for the VM | +| **Firewall Rules** | Controls inbound/outbound traffic to the VM | +| **GCS Bucket** | Persistent storage for user data (repos, files) | +| **Cloud KMS Key** | Encryption key management for storage data | +| **Cloud DNS Private Zone** | Custom domain resolution (when `TF_VAR_platform_domain_name` is set) | +| **IAP (Identity-Aware Proxy)** | Secure SSH access to the VM without exposing a public IP | +| **Secret Manager** | Stores the SSH private key for VM access | + +**Network Modes** + +| Mode | Configuration | Access | +| ------------------------ | ------------------------------------------------ | ----------------------------------------------- | +| **Private IP** (default) | `TF_VAR_platform_domain_name` empty | VM private IP, access via VPN or IAP | +| **Domain** | `TF_VAR_platform_domain_name="codemie.internal"` | Creates Cloud DNS private zone, access via name | + + + + +## On-VM Resource Requirements + + + + +| Resource | Minimum | Recommended | +| -------- | ------- | ------------- | +| vCPU | 4 | 4 (r5.xlarge) | +| RAM | 16 GB | 32 GB | +| Disk | 50 GB | 100 GB (gp3) | + + + + +| Resource | Minimum | Recommended | +| -------- | ------- | ------------------- | +| vCPU | 4 | 4 (Standard_E4s_v5) | +| RAM | 16 GB | 32 GB | +| Disk | 50 GB | 100 GB | + + + + +| Resource | Minimum | Recommended | +| -------- | ------- | ---------------- | +| vCPU | 4 | 4 (n2-highmem-4) | +| RAM | 16 GB | 32 GB | +| Disk | 50 GB | 100 GB | + + + diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index 502df054..b0dedec0 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -1502,9 +1502,5 @@ AUTHORIZED_APPS_ALLOWED_KEY_DOMAINS=["trusted.example","keys.trusted.example"] ## See Also -- [AWS Kubernetes Deployment](../../deployment/aws/kubernetes/overview.md) - Complete AWS Kubernetes deployment walkthrough -- [AWS On VM Deployment](../../deployment/aws/on-vm/overview.md) - AWS EC2 deployment with Docker Compose -- [Azure Kubernetes Deployment](../../deployment/azure/kubernetes/overview.md) - Azure Kubernetes setup instructions -- [Azure On VM Deployment](../../deployment/azure/on-vm/overview.md) - Azure VM deployment with Docker Compose -- [GCP Kubernetes Deployment](../../deployment/gcp/kubernetes/overview.md) - Google Cloud Kubernetes deployment steps -- [GCP On VM Deployment](../../deployment/gcp/on-vm/overview.md) - Google Cloud GCE deployment with Docker Compose +- [Kubernetes Deployment](../../deployment/infrastructure-deployment/kubernetes.mdx) - Complete Kubernetes deployment walkthrough for AWS, Azure, and GCP +- [On-VM Deployment](../../deployment/infrastructure-deployment/on-vm.mdx) - EC2, Azure VM, or Compute Engine deployment with Docker Compose diff --git a/docs/admin/configuration/index.mdx b/docs/admin/configuration/index.mdx index e64139f4..cea8b4aa 100644 --- a/docs/admin/configuration/index.mdx +++ b/docs/admin/configuration/index.mdx @@ -14,36 +14,43 @@ import FeatureGrid from '@site/src/components/FeatureGrid'; Configure AI/Run CodeMie to match your organizational requirements and workflows. -## AI/Run CodeMie Configuration Areas +## CodeMie + + + + + +## Access Control + + + + + + +
+
-## Extensions Configuration +## Extensions Configure optional extensions to enhance AI/Run CodeMie capabilities. +### ✨ Assistants Evaluation + + + +
+
+ + +### ✨ LiteLLM Proxy + -
+ + + + +## Observability + + + +
diff --git a/docs/admin/configuration/observability/index.md b/docs/admin/configuration/observability/index.md index ecbb89f9..5fecc1bc 100644 --- a/docs/admin/configuration/observability/index.md +++ b/docs/admin/configuration/observability/index.md @@ -115,5 +115,5 @@ Langfuse integration is configured via environment variables in the CodeMie API - [API Configuration](../codemie/api-configuration.md) — full reference for all observability environment variables -- [Observability Components Deployment](../../deployment/aws/kubernetes/components-deployment/manual-deployment/observability.md) — +- [Observability Components Deployment](../../deployment/platform-deployment/manual/kubernetes/observability) — install Fluent Bit, Elasticsearch, and Kibana on your cluster diff --git a/docs/admin/configuration/observability/metrics-index-rotation.md b/docs/admin/configuration/observability/metrics-index-rotation.md index 03cac0b3..e0e58e7d 100644 --- a/docs/admin/configuration/observability/metrics-index-rotation.md +++ b/docs/admin/configuration/observability/metrics-index-rotation.md @@ -94,10 +94,7 @@ codemie_metrics_logs_write Do not change the output used for infrastructure logs. User metrics must continue to be collected for Kibana dashboards and usage analytics. -The cloud-specific deployment guides describe the metrics and infrastructure-log -outputs: [AWS](../../../deployment/aws/kubernetes/components-deployment/manual-deployment/observability), -[Azure](../../../deployment/azure/kubernetes/components-deployment/manual-deployment/observability), or -[GCP](../../../deployment/gcp/kubernetes/components-deployment/manual-deployment/observability). +The [Observability Components Deployment](../../../deployment/platform-deployment/manual/kubernetes/observability) guide describes the metrics and infrastructure-log outputs for AWS, Azure, and GCP. ## Enable rotation diff --git a/docs/admin/deployment/accessing-applications.mdx b/docs/admin/deployment/accessing-applications.mdx new file mode 100644 index 00000000..ffc9f3f2 --- /dev/null +++ b/docs/admin/deployment/accessing-applications.mdx @@ -0,0 +1,17 @@ +--- +id: accessing-applications +title: Accessing AI/Run CodeMie Applications +sidebar_label: Accessing Applications +sidebar_position: 5 +pagination_prev: admin/deployment/platform-deployment/platform-deployment-overview +pagination_next: admin/deployment/extensions/extensions-overview +--- + +import AccessingApplicationsContent from './common/deployment/accessing-codemie/_accessing-codemie-applications.mdx'; + + diff --git a/docs/admin/deployment/aws/kubernetes/accessing-applications.md b/docs/admin/deployment/aws/kubernetes/accessing-applications.md deleted file mode 100644 index 3193db71..00000000 --- a/docs/admin/deployment/aws/kubernetes/accessing-applications.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: accessing-applications -sidebar_position: 6 -title: Accessing AI/Run CodeMie Applications -sidebar_label: Accessing Applications -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/configuration/index ---- - -import AccessingApplicationsContent from '../../common/deployment/accessing-codemie/\_accessing-codemie-applications.mdx'; - - diff --git a/docs/admin/deployment/aws/kubernetes/architecture.md b/docs/admin/deployment/aws/kubernetes/architecture.md deleted file mode 100644 index 02c5f554..00000000 --- a/docs/admin/deployment/aws/kubernetes/architecture.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: architecture -title: AI/Run CodeMie Deployment Architecture -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/aws/kubernetes/prerequisites -pagination_next: admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-deployment-overview ---- - -import ContainerResources from '../../common/deployment/architecture/\_container-resources.mdx'; - -# AI/Run CodeMie Deployment Architecture - -This page provides an overview of the AI/Run CodeMie deployment architecture on Amazon Web Services, including infrastructure components, network design, and resource requirements. - -## Architecture Overview - -AI/Run CodeMie is deployed on Amazon Elastic Kubernetes Service (EKS) with supporting AWS services for networking, storage, and identity management. - -### High-Level Architecture Diagram - -The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on AWS: - -![AWS Architecture Diagram](./images/architecture-diagram.drawio.png) - -:::tip Architecture Customization -The architecture can be customized based on your organization's security policies, compliance requirements, and operational preferences. Consult with your deployment team to discuss specific requirements. -::: - -## Resource Requirements - - - -## Next Steps - -After understanding the architecture, proceed to: - -- [Infrastructure Deployment](./infrastructure-deployment/index.md) - Deploy the AWS infrastructure using Terraform -- [Components Deployment](./components-deployment/index.md) - Deploy AI/Run CodeMie application components using Helm diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/index.md b/docs/admin/deployment/aws/kubernetes/components-deployment/index.md deleted file mode 100644 index 36d6509a..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/index.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -id: components-deployment-overview -sidebar_position: 5 -title: AI/Run CodeMie Components Deployment -sidebar_label: CodeMie Components Deployment -pagination_prev: admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/components-scripted-deployment ---- - -# AI/Run CodeMie Components Deployment - -## Overview - -This section guides you through deploying the AI/Run CodeMie application stack on your EKS cluster. After completing infrastructure deployment, this phase installs all necessary Kubernetes components including: - -- **Core AI/Run CodeMie services** (API, UI, MCP Connect, NATS Auth) -- **Data layer** (Elasticsearch) -- **Security & Identity** (Keycloak, OAuth2 Proxy) -- **Infrastructure services** (Ingress controller, storage) -- **Observability** (Kibana, Fluent Bit) -- **Optional LLM Proxy** (for load balancing AI model requests) - -The deployment uses Helm charts to install and configure all components in the correct order, ensuring proper dependencies and integration. - -:::info Prerequisites -This phase assumes you have completed [Infrastructure Deployment](../infrastructure-deployment/) and have a running EKS cluster with network, storage, and security configured. -::: - -### Application Stack Components - -The AI/Run CodeMie application consists of multiple integrated components organized into functional categories: - -![Application Stack](../../../common/deployment/images/application-stack-diagram.drawio.png) - -#### Core AI/Run CodeMie Services - -Proprietary services that provide the main AI/Run CodeMie functionality: - -| Component | Container Registry | Description | -| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| **CodeMie API** | `europe-west3-docker.pkg.dev/.../codemie:x.y.z` | Backend service handling business logic, data processing, and API operations | -| **CodeMie UI** | `europe-west3-docker.pkg.dev/.../codemie-ui:x.y.z` | Frontend web application providing the user interface | -| **NATS Auth Callout** | `europe-west3-docker.pkg.dev/.../codemie-nats-auth-callout:x.y.z` | Authentication and authorization service for NATS messaging (Plugin Engine component) | -| **MCP Connect** | `europe-west3-docker.pkg.dev/.../codemie-mcp-connect-service:x.y.z` | Bridge enabling CodeMie to communicate with MCP servers | -| **Mermaid Server** | `europe-west3-docker.pkg.dev/.../mermaid-server:x.y.z` | Diagram generation service for visualization in chats | - -:::info Version Information -To find the latest release versions for CodeMie components: - -```bash -# Clone the helm charts repository -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts - -# Check latest versions (requires GCR authentication) -bash get-codemie-latest-release-version.sh -c /path/to/key.json -``` - -**Note**: Docker container versions match Helm chart release versions. -::: - -#### Data Layer - -Database and search components for data persistence: - -| Component | Container Registry | Description | -| ----------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | -| **Elasticsearch** | `docker.elastic.co/elasticsearch/elasticsearch:x.y.z` | Primary data store for AI/Run CodeMie (datasources, projects, conversations, etc.) | -| **Kibana** | `docker.elastic.co/kibana/kibana:x.y.z` | Analytics and visualization interface for Elasticsearch data | - -#### Security & Identity Management - -Authentication and authorization components: - -| Component | Container Registry | Description | -| --------------------- | ----------------------------------------- | --------------------------------------------------------------------------- | -| **Keycloak Operator** | `epamedp/keycloak-operator:x.y.z` | Manages Keycloak deployment and configuration | -| **Keycloak** | `quay.io/keycloak/keycloak:x.y.z` | Identity and access management (IAM) solution providing SSO, authentication | -| **OAuth2 Proxy** | `quay.io/oauth2-proxy/oauth2-proxy:x.y.z` | Authentication middleware integrating with Keycloak for secure access | - -#### Infrastructure Services - -Essential Kubernetes infrastructure components: - -| Component | Container Registry | Description | -| ---------------------------- | ------------------------------------------------ | --------------------------------------------------- | -| **Nginx Ingress Controller** | `registry.k8s.io/ingress-nginx/controller:x.y.z` | Routes external traffic to internal services | -| **Storage Class** | AWS EBS CSI Driver | Provides persistent volumes for stateful components | - -#### Messaging & Integration - -Message broker for Plugin Engine: - -| Component | Container Registry | Description | -| --------- | ------------------ | ----------------------------------------------------------------- | -| **NATS** | `nats:x.y.z` | High-performance messaging system for Plugin Engine communication | - -#### Observability - -Logging and monitoring components: - -| Component | Container Registry | Description | -| -------------- | ----------------------------------------- | ------------------------------------------------------ | -| **Fluent Bit** | `cr.fluentbit.io/fluent/fluent-bit:x.y.z` | Lightweight log collector enabling agent observability | - -#### Optional Components - -Components that can be omitted based on configuration: - -| Component | Container Registry | Description | -| ------------- | ------------------ | ----------------------------------------------------------------------------------------------- | -| **LLM Proxy** | – | Optional proxy for load balancing and high availability of AI model requests and usage insights | - -#### Deployment Dependencies - -Components must be deployed in the following order due to dependencies: - -1. **Infrastructure** → Ingress Controller, Storage Class -2. **Operators** → Keycloak Operator -3. **Data Layer** → Elasticsearch -4. **Security** → Keycloak (with database credentials), OAuth2 Proxy -5. **Messaging** → NATS -6. **Core Services** → CodeMie API, UI, MCP Connect, NATS Auth -7. **Observability** → Fluent Bit, Kibana -8. **Optional** → LLM Proxy (if needed) - -## Prerequisites - -### Cluster Readiness - -Ensure your EKS cluster is ready for component deployment: - -- [x] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/) phase -- [x] **Cluster Access**: kubectl configured and authenticated to EKS cluster -- [x] **Kubeconfig Setup**: Obtained kubeconfig using: - -```bash -aws eks update-kubeconfig --region --name -``` - -### Required Components - -The following components will be installed during this phase if not already present: - -- **Nginx Ingress Controller**: Routes external traffic to services -- **AWS gp3 Storage Class**: Provides persistent storage for stateful components - -:::info -These components will be installed automatically if not already present in your cluster. Both scripted and manual deployment procedures include the necessary installation steps. -::: - -### Repository and Access {#repository-and-access} - -#### Helm Charts Repository - -Clone the Helm charts repository on your deployment machine (local workstation or bastion host): - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -#### Container Registry Credentials - -Before deploying AI/Run CodeMie components, you need to set up authentication for the container registry. - -**Request Access**: Ask the AI/Run CodeMie team to provide: - -- `key.json` file (GCP service account credentials) -- Service account email for pulling images from GCR - -**Create Namespace**: - -```bash -kubectl create namespace codemie -``` - -**Configure Registry Secret**: - -Replace `%%PROJECT_NAME%%` with your project name and create the pull secret: - -```bash -kubectl create secret docker-registry gcp-artifact-registry \ - --docker-server=https://europe-west3-docker.pkg.dev \ - --docker-email=`` \ - --docker-username=_json_key \ - --docker-password="$(cat key.json)" \ - -n codemie -``` - -**Verify Secret**: - -```bash -kubectl get secret gcp-artifact-registry -n codemie -``` - -:::info Pull Secret Usage -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: - -```yaml -imagePullSecrets: - - name: gcp-artifact-registry -``` - -::: - -## Deployment Methods - -Two deployment approaches are available depending on your needs: - -### Scripted Deployment (Recommended) - -Automated deployment using the `helm-charts.sh` wrapper script: - -- **Best for**: Standard deployments, quick setup, production environments -- **Advantages**: Automated dependency ordering, validation checks, consistent configuration - -[→ Scripted Deployment Guide](./components-scripted-deployment) - -### Manual Deployment - -Step-by-step manual installation of each component: - -- **Best for**: Custom configurations, learning the stack, troubleshooting -- **Advantages**: Full control over each component, easier to debug issues - -[→ Manual Deployment Guide](./manual-deployment/) - -:::tip Recommendation -Use **Scripted Deployment** for initial installations. Switch to manual deployment only if you need custom configurations or are troubleshooting specific issues. -::: diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/core-components.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/core-components.md deleted file mode 100644 index fe69820a..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/core-components.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: core-components -sidebar_position: 6 -title: Core Components -sidebar_label: Core Components -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/observability ---- - -import CoreComponentsOverview from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-overview.mdx'; -import CoreComponentsMcpConnect from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-mcp-connect.mdx'; -import CoreComponentsMermaid from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-mermaid.mdx'; -import CoreComponentsUi from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-ui.mdx'; -import CoreComponentsApi from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-api.mdx'; -import CoreComponentsAccess from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-access.mdx'; -import CoreComponentsValidation from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-validation.mdx'; - - - - - - - - - - - - - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer.md deleted file mode 100644 index e50a5239..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: data-layer -sidebar_position: 2 -title: Data Layer -sidebar_label: Data Layer -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/security-and-identity ---- - -import DataLayerOverview from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-overview.mdx'; -import DataLayerElasticsearch from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-elasticsearch.mdx'; -import DataLayerPostgresConfig from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-postgresql-config.mdx'; -import DataLayerPostgresIamSetup from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-postgresql-iam-setup.mdx'; -import DataLayerPostgresSecret from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-postgresql-secret-aws.mdx'; -import DataLayerValidation from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-validation.mdx'; - - - - - - - - - - - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/index.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/index.md deleted file mode 100644 index 152ecbaa..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/index.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -id: manual-deployment-overview -sidebar_position: 2 -title: Manual Deployment Overview -description: Overview of manual component installation process -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components ---- - -# Manual CodeMie Components Deployment - -This guide provides step-by-step instructions for manually deploying AI/Run CodeMie application components using Helm charts. Manual deployment gives you granular control over each component installation, allowing for customization and troubleshooting at each stage. - -:::info When to Use Manual Deployment -Use manual deployment when you need: - -- Fine-grained control over individual component configuration -- Custom installation order or selective component deployment -- Troubleshooting capabilities at each deployment stage -- Integration with existing infrastructure components - -If you prefer automated deployment, see [Scripted Deployment](../components-scripted-deployment) instead. -::: - -## Overview - -Manual deployment involves installing components individually in a specific dependency order. Each component is deployed using Helm charts with cloud-specific values files (`values-aws.yaml`). - -### Deployment Scope - -This guide covers all components required for a fully functional AI/Run CodeMie installation: - -- **Infrastructure services** - Storage provisioning and ingress routing -- **Data layer** - Document storage and relational databases -- **Security components** - Identity management and authentication proxies -- **Messaging system** - Inter-service communication infrastructure -- **Core CodeMie services** - Main application components -- **Observability stack** - Logging and monitoring dashboards - -## Prerequisites - -Before starting manual deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/) phase -- [ ] **Cluster Access**: kubectl configured for EKS cluster -- [ ] **Container Registry**: Completed [Container Registry Access Setup](../#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs -- [ ] **Deployment Outputs File**: Have `deployment_outputs.env` from infrastructure deployment - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](../#repository-and-access) before proceeding. Each component requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine: - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `aws` CLI - For AWS operations - -## Component Installation Order - -Components must be installed in the following order to satisfy dependencies: - -### 1. [Kubernetes Components](./k8s-components) - -**Purpose**: Foundation infrastructure for storage provisioning and external access - -**Components**: - -- AWS gp3 Storage Class (for dynamic volume provisioning) -- Nginx Ingress Controller (for HTTP/HTTPS routing) - -**When to Skip**: If your cluster already has these components configured - -### 2. [Data Layer](./data-layer) - -**Purpose**: Persistent storage for application data and user content - -**Components**: - -- Elasticsearch (document storage and search engine) - -**Dependencies**: Requires storage class from Step 1 - -### 3. [Security and Identity](./security-and-identity) - -**Purpose**: User authentication, authorization, and access control - -**Components**: - -- Keycloak Operator (Keycloak lifecycle management) -- Keycloak (identity and access management) -- OAuth2 Proxy (authentication proxy) - -**Dependencies**: Requires RDS from infrastructure deployment - -### 4. [Plugin Engine](./plugin-engine) - -**Purpose**: Inter-service messaging and plugin communication infrastructure - -**Components**: - -- NATS (message broker) -- NATS Auth Callout (authentication service for NATS) - -**Dependencies**: None (standalone messaging layer) - -### 5. [AI/Run CodeMie Core](./core-components) - -**Purpose**: Main application services providing CodeMie functionality - -**Components**: - -- CodeMie API (backend REST API) -- CodeMie UI (frontend web application) -- MCP Connect (Model Context Protocol connector) -- Mermaid Server (diagram rendering service) - -**Dependencies**: Requires all previous components (data layer, security, messaging) - -### 6. [Observability](./observability.md) - -**Purpose**: System monitoring, logging aggregation, and operational insights - -**Components**: - -- Fluent Bit (log collection and forwarding) -- Kibana (log visualization and analysis) -- Kibana Dashboards (pre-configured monitoring views) - -**Dependencies**: Requires Elasticsearch from Step 2 - -## Getting Started - -### Step 1: Clone Repository - -Clone the Helm charts repository on your deployment machine: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure AWS-Specific Values - -Update AWS-specific values in the CodeMie API configuration. Use values from your `deployment_outputs.env` file: - -```bash -# Source the deployment outputs -source deployment_outputs.env - -# Update CodeMie API values with AWS-specific configuration -sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_DEFAULT_REGION%%/${AWS_DEFAULT_REGION}/g" codemie-api/values-aws.yaml -sed -i "s|%%EKS_AWS_ROLE_ARN%%|${EKS_AWS_ROLE_ARN}|g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_KMS_KEY_ID%%/${AWS_KMS_KEY_ID}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_S3_BUCKET_NAME%%/${AWS_S3_BUCKET_NAME}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_S3_REGION%%/${AWS_S3_REGION}/g" codemie-api/values-aws.yaml -``` - -### Step 3: Configure Domain Name - -Update the DNS zone name in values files. Replace `%%DOMAIN%%` with your actual DNS zone name: - -```bash -# Use your DNS zone name from deployment_outputs.env -CODEMIE_DOMAIN_NAME="airun.example.com" - -# Update all values-aws.yaml files -find . -name "values-aws.yaml" -exec sed -i "s/%%DOMAIN%%/$CODEMIE_DOMAIN_NAME/g" {} \; -``` - -:::tip Domain Configuration -Your DNS zone name was configured during infrastructure deployment. Find it in `deployment_outputs.env` as `CODEMIE_DOMAIN_NAME`. -::: - -### Step 4: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to registry -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 5: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version (e.g., 1.2.3) for component installations -``` - -You'll use this version when installing each component's Helm chart. - -## Installation Process - -Follow the component installation guides in the order listed above. Each guide provides: - -- Detailed installation commands -- Configuration options -- Validation steps -- Troubleshooting guidance - -:::warning Respect Installation Order -Installing components out of order will cause deployment failures. Always follow the numbered sequence to ensure dependencies are satisfied. -::: - -## Common Issues - -### Image Pull Failures - -**Symptom**: Pods stuck in `ImagePullBackOff` or `ErrImagePull` - -**Solution**: - -- Verify `gcp-artifact-registry` secret exists: `kubectl get secret -n codemie` -- Re-authenticate to registry (repeat Step 4) -- Check network connectivity to `europe-west3-docker.pkg.dev` - -## Next Steps - -Begin the installation process by following the guides in order, starting with **[Kubernetes Components](./k8s-components)**. - -After completing all component installations, proceed to **[Configuration](../../../../../configuration/)** to configure users, AI models, and data sources. diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components.md deleted file mode 100644 index 42c4f49f..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: k8s-components -sidebar_position: 1 -title: Kubernetes Components -sidebar_label: Kubernetes Components -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer ---- - -import StorageIngressOverview from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-overview.mdx'; -import StorageIngressNginx from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-nginx.mdx'; -import StorageClassInstallation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-class-installation.mdx'; -import StorageIngressValidation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-validation.mdx'; - - - - - -### Step 4: Configure DNS Record - -Create a DNS record pointing to the ingress controller's load balancer: - -```bash -# Retrieve ingress controller hostname/IP -INGRESS_HOST=$(kubectl get service ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') - -echo "Ingress Host: ${INGRESS_HOST}" -``` - -**DNS Configuration Options**: - -If using **Route 53**: - -```bash -# Get your hosted zone ID -HOSTED_ZONE_ID=$(aws route53 list-hosted-zones-by-name \ - --dns-name airun.example.com \ - --query 'HostedZones[0].Id' \ - --output text | cut -d'/' -f3) - -# Create CNAME record -aws route53 change-resource-record-sets \ - --hosted-zone-id ${HOSTED_ZONE_ID} \ - --change-batch '{ - "Changes": [{ - "Action": "UPSERT", - "ResourceRecordSet": { - "Name": "codemie.airun.example.com", - "Type": "CNAME", - "TTL": 300, - "ResourceRecords": [{"Value": "'${INGRESS_HOST}'"}] - } - }] - }' -``` - -**Parameters to Adjust**: - -- `airun.example.com` - Replace with your DNS zone name -- `codemie.airun.example.com` - Replace with your desired hostname - -:::tip DNS Configuration -These values should match what you configured during infrastructure deployment. Check your `deployment_outputs.env` file for the correct domain name. -::: - -### Verification - -Confirm the DNS record was created: - -```bash -# List DNS records in Route 53 -aws route53 list-resource-record-sets \ - --hosted-zone-id ${HOSTED_ZONE_ID} \ - --query "ResourceRecordSets[?Name=='codemie.airun.example.com.']" - -# Test DNS resolution -nslookup codemie.airun.example.com -``` - - - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/observability.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/observability.md deleted file mode 100644 index 4caed1fa..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/observability.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: observability -sidebar_position: 7 -title: Observability -sidebar_label: Observability -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/accessing-applications ---- - -import ObservabilityOverview from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-overview.mdx'; -import ObservabilityFluentBit from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-fluent-bit.mdx'; -import ObservabilityKibana from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-kibana.mdx'; -import ObservabilityDashboards from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-dashboards.mdx'; -import ObservabilityValidation from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx deleted file mode 100644 index 2da0d254..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: plugin-engine -sidebar_position: 5 -title: Plugin Engine -sidebar_label: Plugin Engine -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/core-components ---- - -import PluginEngineContent from '../../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx'; - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/security-and-identity.md b/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/security-and-identity.md deleted file mode 100644 index 1b94500d..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/manual-deployment/security-and-identity.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: security-and-identity -sidebar_position: 4 -title: Security and Identity -sidebar_label: Security and Identity -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/manual-deployment/plugin-engine ---- - -import SecurityOverview from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-overview.mdx'; -import SecurityKeycloakOperator from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-operator.mdx'; -import SecurityKeycloakInstall from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-install.mdx'; -import SecurityOauth2Proxy from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-oauth2-proxy.mdx'; -import SecurityValidation from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/aws/kubernetes/components-deployment/scripted-deployment.md b/docs/admin/deployment/aws/kubernetes/components-deployment/scripted-deployment.md deleted file mode 100644 index 5b672e08..00000000 --- a/docs/admin/deployment/aws/kubernetes/components-deployment/scripted-deployment.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -id: components-scripted-deployment -sidebar_position: 1 -title: CodeMie Scripted Deployment -sidebar_label: CodeMie Scripted Deployment -pagination_prev: admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/accessing-applications ---- - -# Scripted CodeMie Components Deployment - -This guide walks you through deploying AI/Run CodeMie application components using the automated `helm-charts.sh` deployment script. The script handles the installation of all components in the correct dependency order using Helm charts. - -:::tip Recommended Approach -Scripted deployment is recommended for standard installations as it automates component ordering, validates prerequisites, and ensures consistent configuration across all components. -::: - -## Overview - -The deployment script automates the installation of: - -- **Infrastructure services** (Nginx Ingress, Storage Class) -- **Data layer** (Elasticsearch) -- **Security components** (Keycloak, OAuth2 Proxy) -- **Messaging system** (NATS) -- **Core CodeMie services** (API, UI, MCP Connect) -- **Observability stack** (Fluent Bit, Kibana) - -## Prerequisites - -Before starting deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/index.md) phase -- [ ] **Cluster Access**: kubectl configured for EKS cluster -- [ ] **Container Registry**: Completed [Container Registry Access Setup](./index.md#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs -- [ ] **Deployment Outputs File**: Have `deployment_outputs.env` from infrastructure deployment - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](./index.md#repository-and-access) before proceeding. The script requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine: - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `aws` CLI - For AWS operations - -## Quick Start - -### Step 1: Clone Repository - -Clone the Helm charts repository on your deployment machine: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure AWS-Specific Values - -Update AWS-specific values in the CodeMie API configuration. Use values from your `deployment_outputs.env` file: - -```bash -# Source the deployment outputs -source deployment_outputs.env - -# Update CodeMie API values with AWS-specific configuration -sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_DEFAULT_REGION%%/${AWS_DEFAULT_REGION}/g" codemie-api/values-aws.yaml -sed -i "s|%%EKS_AWS_ROLE_ARN%%|${EKS_AWS_ROLE_ARN}|g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_KMS_KEY_ID%%/${AWS_KMS_KEY_ID}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_S3_BUCKET_NAME%%/${AWS_S3_BUCKET_NAME}/g" codemie-api/values-aws.yaml -sed -i "s/%%AWS_S3_REGION%%/${AWS_S3_REGION}/g" codemie-api/values-aws.yaml -``` - -### Step 3: Configure Domain Name - -Update the DNS zone name in the remaining values files: - -```bash -# Use your domain zone name from deployment_outputs.env -CODEMIE_DOMAIN_NAME="airun.example.com" - -# Update all values-aws.yaml files -find . -name "values-aws.yaml" -exec sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" {} \; -``` - -:::tip Domain Configuration -Your DNS zone name was configured during infrastructure deployment. Find it in `deployment_outputs.env` as `CODEMIE_DOMAIN_NAME`. -::: - -### Step 4: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to registry -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 5: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version (e.g., 1.2.3) for next step -``` - -### Step 6: Configure Optional Components (If Required) - -**Optional Components:** - -- `litellm` - LiteLLM Proxy for unified LLM API interface, multi-model routing, and cost tracking -- `pgadmin` - PostgreSQL administration interface for database inspection and monitoring - -:::warning LiteLLM Configuration Required -If deploying with the `--optional litellm` flag, configuration must be completed **before** running the deployment script. Follow the [LiteLLM Proxy Installation and Configuration Guide](../../../extensions/litellm-proxy/index.md) to set up values files and credentials. -::: - -Skip this step if not deploying optional components. - -### Step 7: Run Deployment Script - -Execute the deployment script with your chosen mode: - -```bash -# Standard installation with all core components -bash helm-charts.sh --cloud aws --version --mode all - -# Production deployment with LiteLLM proxy for multi-model routing -bash helm-charts.sh --cloud aws --version --mode all --optional litellm - -# Complete installation with database administration capabilities -bash helm-charts.sh --cloud aws --version --mode all --optional litellm,pgadmin - -# Cluster with existing Nginx Ingress (installs only CodeMie components) -bash helm-charts.sh --cloud aws --version --mode recommended - -# Update existing installation to new version (core components only) -bash helm-charts.sh --cloud aws --version --mode update -``` - -:::tip Idempotent Script -The deployment script is idempotent, meaning you can safely re-run it multiple times. If the script fails or is interrupted, simply run it again with the same parameters to continue or retry the deployment. -::: - -## Configuration Reference - -### Script Parameters - -The deployment script accepts the following parameters: - -| Parameter | Description | Required | Values | -| --------------- | ------------------------------------ | -------- | -------------------------------------------------------------------- | -| `-h, --help` | Show help message and usage examples | No | N/A | -| `-c, --cloud` | Target cloud provider | Yes | `aws`, `azure`, `gcp` | -| `-v, --version` | CodeMie component version | Yes | Semantic version (e.g., `2.2.3`) | -| `-m, --mode` | Installation mode | Yes | `all`, `recommended`, `update` | -| `--optional` | Optional components to deploy | No | Comma-separated list: `litellm`, `pgadmin` (e.g., `litellm,pgadmin`) | - -### Deployment Modes - -| Mode | Components Installed | Use Case | -| --------------- | ------------------------------------------------------------ | --------------------------------------------- | -| **all** | All components including Nginx Ingress Controller | Fresh EKS cluster without existing ingress | -| **recommended** | All components except Nginx Ingress Controller | Cluster with existing ingress controller | -| **update** | Only CodeMie core components (API, UI, MCP Connect, Mermaid) | Updating existing installation to new version | - -:::tip Choosing Deployment Mode - -- **First-time installation**: Use `all` or `recommended` depending on whether you need Nginx Ingress -- **Version updates**: Use `update` to upgrade only CodeMie components -- **Fresh EKS cluster**: Use `all` mode - ::: - -### AWS-Specific Configuration Values - -The following AWS-specific values must be configured in `codemie-api/values-aws.yaml` (automated by Step 2 in Quick Start): - -| Placeholder | Description | Example Value | Source File | -| ------------------------ | ----------------------------- | ------------------------------------------------ | ------------------------ | -| `%%DOMAIN%%` | Your DNS Zone name | `airun.example.com` | `deployment_outputs.env` | -| `%%AWS_DEFAULT_REGION%%` | AWS region | `us-west-2` | `deployment_outputs.env` | -| `%%EKS_AWS_ROLE_ARN%%` | IAM role for EKS IRSA | `arn:aws:iam::0123456789012:role/AWSIRSA_AI_RUN` | `deployment_outputs.env` | -| `%%AWS_KMS_KEY_ID%%` | AWS KMS key ID for encryption | `50f3f093-dc86-48de-8f2d-7a76e480348c` | `deployment_outputs.env` | -| `%%AWS_S3_BUCKET_NAME%%` | S3 bucket for user data | `codemie-user-data-0123456789012` | `deployment_outputs.env` | -| `%%AWS_S3_REGION%%` | S3 bucket region | `us-west-2` | `deployment_outputs.env` | - -### Domain Name Configuration - -The following files require domain name configuration (automated by Step 3 in Quick Start): - -| Component | File | Placeholder | Example Value | -| ---------------- | ------------------------------- | --------------------- | ---------------------------- | -| **Kibana** | `kibana/values-aws.yaml` | `kibana.%%DOMAIN%%` | `kibana.airun.example.com` | -| **Keycloak** | `keycloak-helm/values-aws.yaml` | `keycloak.%%DOMAIN%%` | `keycloak.airun.example.com` | -| **OAuth2 Proxy** | `oauth2-proxy/values-aws.yaml` | `*.%%DOMAIN%%` | `*.airun.example.com` | -| **CodeMie UI** | `codemie-ui/values-aws.yaml` | `codemie.%%DOMAIN%%` | `codemie.airun.example.com` | -| **CodeMie API** | `codemie-api/values-aws.yaml` | `*.%%DOMAIN%%` | `*.airun.example.com` | - -## Next Steps - -After successful deployment and validation, proceed to: - -**[Accessing Applications](../accessing-applications.md)** - Learn how to access the deployed AI/Run CodeMie applications and complete the required configuration steps. diff --git a/docs/admin/deployment/aws/kubernetes/images/2613320799.png b/docs/admin/deployment/aws/kubernetes/images/2613320799.png deleted file mode 100644 index 82076ca6..00000000 Binary files a/docs/admin/deployment/aws/kubernetes/images/2613320799.png and /dev/null differ diff --git a/docs/admin/deployment/aws/kubernetes/images/2613320927.png b/docs/admin/deployment/aws/kubernetes/images/2613320927.png deleted file mode 100644 index 9c63e266..00000000 Binary files a/docs/admin/deployment/aws/kubernetes/images/2613320927.png and /dev/null differ diff --git a/docs/admin/deployment/aws/kubernetes/images/2613321045.png b/docs/admin/deployment/aws/kubernetes/images/2613321045.png deleted file mode 100644 index 50482e7d..00000000 Binary files a/docs/admin/deployment/aws/kubernetes/images/2613321045.png and /dev/null differ diff --git a/docs/admin/deployment/aws/kubernetes/images/2613321923.png b/docs/admin/deployment/aws/kubernetes/images/2613321923.png deleted file mode 100644 index cda316bf..00000000 Binary files a/docs/admin/deployment/aws/kubernetes/images/2613321923.png and /dev/null differ diff --git a/docs/admin/deployment/aws/kubernetes/images/README.md b/docs/admin/deployment/aws/kubernetes/images/README.md deleted file mode 100644 index 15b8301b..00000000 --- a/docs/admin/deployment/aws/kubernetes/images/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Images Directory - -This directory contains all images and diagrams used in the AWS deployment guide documentation. - -## Key Diagrams - -- **architecture-diagram.drawio.png** - Main AWS infrastructure architecture diagram showing EKS, VPC, ALB/NLB, RDS, S3, etc. -- **application-stack-diagram.drawio.png** - Complete application stack showing all AI/Run CodeMie components and their relationships -- **litellm-architecture.png** - LiteLLM Proxy architecture diagram (if available) - -## Usage - -All other images in this directory are screenshots and supporting diagrams used throughout the deployment guide, particularly for: - -- Post-installation configuration steps -- Keycloak setup instructions -- User management workflows -- Extension configurations - -## Image Naming - -- Original numeric filenames (e.g., `2418773898.png`) are preserved from the source -- Key diagrams have been given descriptive aliases for easier reference -- All images are referenced in the corresponding markdown documentation files diff --git a/docs/admin/deployment/aws/kubernetes/images/litellm-architecture.png b/docs/admin/deployment/aws/kubernetes/images/litellm-architecture.png deleted file mode 100644 index 1ca89f9d..00000000 Binary files a/docs/admin/deployment/aws/kubernetes/images/litellm-architecture.png and /dev/null differ diff --git a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/index.md b/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/index.md deleted file mode 100644 index a6f4c594..00000000 --- a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/index.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -id: infrastructure-deployment-overview -title: AWS Infrastructure Deployment -sidebar_label: Infrastructure Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/aws/kubernetes/architecture -pagination_next: admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment ---- - -# AWS Infrastructure Deployment - -This section guides you through deploying the AWS infrastructure foundation required for AI/Run CodeMie using Terraform automation. - -:::info Existing Infrastructure -If you already have a provisioned EKS cluster with all required AWS services (networking, storage, databases, etc.), you can skip this section and proceed directly to [Components Deployment](../components-deployment/index.md). -::: - -## Overview - -The Terraform deployment is organized into three distinct phases, each with its own set of resources and purpose: - -1. **IAM Deployer Role** - Privileged role for executing Terraform operations -2. **Terraform State Backend** - Infrastructure for storing Terraform state files securely -3. **Core Platform Infrastructure** - Main AWS resources for running AI/Run CodeMie - -:::note Important -The deployment uses a registered domain name in AWS Route 53, which allows Terraform to automatically create SSL/TLS certificates via AWS Certificate Manager for the Application Load Balancer (ALB) and Network Load Balancer (NLB). -::: - -## Phase 1: IAM Deployer Role - -The IAM deployer role is created first to provide necessary permissions for all subsequent infrastructure operations. - -| Resource | Purpose | -| ------------------ | -------------------------------------------------------------------- | -| **IAM Role** | Deployer role with permissions to create and manage AWS resources | -| **IAM Policies** | Granular permission policies for EKS, networking, storage, databases | -| **Trust Policies** | Trust relationships allowing specific principals to assume the role | - -:::tip IAM Role Purpose -The IAM deployer role enables: - -- **Least Privilege**: Scoped permissions for infrastructure operations only -- **Separation of Duties**: Dedicated role for infrastructure deployment -- **Auditability**: CloudTrail logging of all actions performed by the role -- **Consistency**: Same permissions across different deployment environments - ::: - -## Phase 2: Terraform State Backend - -The state backend is deployed to provide secure, centralized storage for Terraform state files. - -| Resource | Purpose | -| ------------------- | ----------------------------------------------------------------------- | -| **S3 Bucket** | Storage for Terraform state files with versioning and native S3 locking | -| **Bucket Policies** | Access control policies for state file security | -| **Encryption** | Server-side encryption for state files at rest | - -:::tip State Backend Purpose -The Terraform state backend enables: - -- **Team Collaboration**: Multiple engineers can work on infrastructure simultaneously -- **State Locking**: S3 native locking prevents concurrent modifications that could corrupt state -- **Versioning**: Maintains history of infrastructure changes -- **Security**: State files contain sensitive data and require secure storage - ::: - -## Phase 3: Core Platform Infrastructure - -The core platform infrastructure provisions all AWS resources needed to run AI/Run CodeMie. This is the main deployment phase and following AWS resources will be deployed: - -### Compute & Orchestration - -| Resource | Purpose | -| ----------------------- | --------------------------------------------------------------- | -| **EKS Cluster** | Managed Kubernetes cluster for running AI/Run CodeMie workloads | -| **Managed Node Groups** | Auto-scaling node groups for application workloads | -| **Launch Templates** | EC2 instance configurations for node groups | - -### Networking - -| Resource | Purpose | -| ----------------------------- | ------------------------------------------------------------------- | -| **VPC** | Isolated virtual network for AI/Run CodeMie resources | -| **Public Subnets** | Subnets for load balancers and NAT gateways | -| **Private Subnets** | Subnets for EKS nodes and pods (application workloads) | -| **Database Subnets** | Isolated subnets for RDS PostgreSQL instances | -| **Internet Gateway** | Enables internet connectivity for public subnets | -| **NAT Gateway** | Provides consistent outbound public IP for private subnet resources | -| **Route Tables** | Controls routing between subnets and internet | -| **Application Load Balancer** | Distributes incoming HTTPS traffic to application services | -| **Network Load Balancer** | Handles TCP traffic for NATS messaging system | -| **Route 53 DNS Records** | Automated DNS record creation for CodeMie services | -| **Network Security Groups** | Firewall rules controlling traffic flow | - -### Data & Storage - -| Resource | Purpose | -| ----------------------------- | ------------------------------------------------------------- | -| **RDS PostgreSQL** | Managed database service for CodeMie application data | -| **RDS PostgreSQL (Keycloak)** | Dedicated database instance for Keycloak (optional) | -| **RDS Subnet Group** | Database subnet group for multi-AZ deployment | -| **S3 Bucket** | Persistent storage for CodeMie application data and artifacts | -| **EBS Volumes** | Block storage for Kubernetes persistent volumes | - -### Security & Identity - -| Resource | Purpose | -| --------------------------- | --------------------------------------------------------------- | -| **AWS Certificate Manager** | Automated SSL/TLS certificates for ALB and NLB | -| **KMS Key** | Encryption key for S3 bucket and other encrypted resources | -| **IAM Roles for EKS** | Service roles for EKS cluster and node groups | -| **IAM Roles for Workloads** | IRSA (IAM Roles for Service Accounts) for pod-level permissions | -| **Security Groups** | Network access control lists for EKS, RDS, load balancers | -| **Secrets Manager** | Optional secret storage for database credentials | - -### Optional Features - -| Resource | Purpose | -| --------------------------- | ---------------------------------------------------- | -| **Internal ALB** | Private load balancer for internal-only access | -| **Private DNS Hosted Zone** | Private Route 53 zone for internal service discovery | -| **VPC Endpoints** | Private connectivity to AWS services (S3, ECR, etc.) | - -## Next Steps - -Proceed to the next step to deploy the infrastructure: - -- [**Scripted Deployment** →](./infrastructure-scripted-deployment) - Recommended automated deployment using Terraform wrapper scripts -- [**Manual Deployment** →](./infrastructure-manual-deployment) - Advanced option for custom scenarios with manual Terraform control - -:::note Deployment Method Selection - -- **Scripted Deployment**: Handles prerequisites, validation, and orchestration automatically (recommended for most users) -- **Manual Deployment**: Provides full control over Terraform operations for advanced customization - ::: diff --git a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/manual-deployment.md b/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/manual-deployment.md deleted file mode 100644 index 12594e2d..00000000 --- a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/manual-deployment.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -id: infrastructure-manual-deployment -sidebar_position: 2 -title: Manual Deployment -description: Manual AWS infrastructure deployment with Terraform -pagination_prev: admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Manual Infrastructure Deployment - -This guide provides step-by-step instructions for manually deploying AWS infrastructure using Terraform, offering more control and customization options. - -:::info When to Use Manual Deployment -Manual deployment is suitable when you need fine-grained control over each deployment phase, want to customize Terraform configurations, or are integrating with existing infrastructure management workflows. -::: - -## Prerequisites - -Before starting the deployment, ensure you have completed all requirements from the [Prerequisites](../prerequisites.md) page: - -### 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**: Have access to Terraform and Helm repositories -- [ ] **Network Planning**: Prepared list of allowed networks -- [ ] **Domain Configuration**: Route 53 hosted zone ready - -:::warning Authentication Required -You must have configured AWS credentials before starting deployment. Verify with `aws sts get-caller-identity`. -::: - -## Deployment Phases - -Manual deployment involves three sequential phases: - -| Phase | Description | Repository | -| ------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Phase 1: IAM Deployer Role** | Creates IAM role with required permissions for deployment | [codemie-terraform-aws-iam](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam) | -| **Phase 2: State Backend** | Creates S3 bucket with native locking for Terraform state files | [codemie-terraform-aws-remote-backend](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend) | -| **Phase 3: Platform Infrastructure** | Deploys EKS, networking, storage, databases, security components | [codemie-terraform-aws-platform](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform) | - -## Phase 1: IAM Deployer Role Creation - -The `DeployerRole` AWS IAM role will be used for all subsequent infrastructure deployments and updates. - -:::info -The created IAM role contains all required permissions to manage AWS resources for AI/Run CodeMie deployment. -::: - -1. Clone the repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git -cd codemie-terraform-aws-iam -``` - -2. Review input variables in `codemie-terraform-aws-iam/variables.tf` and create a `terraform.tfvars` file: - -```hcl -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" -} -``` - -:::tip Review All Variables -Most variables have sensible defaults. Review `variables.tf` for the complete list of available configuration options. -::: - -3. Initialize and apply Terraform: - -```bash -terraform init -terraform plan -terraform apply -``` - -## Phase 2: Terraform Backend Resources Deployment - -This phase creates: - -- S3 bucket with policy to store terraform states and native S3 locking enabled - -1. Clone the repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend.git -cd codemie-terraform-aws-remote-backend -``` - -2. Configure and deploy. There are two ways to provide Terraform variables: - - - - -This method uses environment variables with the `TF_VAR_` prefix, which Terraform automatically recognizes. - -Set AWS profile and load variables from deployment.conf: - -```bash -export AWS_PROFILE="your-aws-profile" -``` - -```bash -set -a && source ../deployment.conf && set +a -``` - -Initialize Terraform: - -```bash -terraform init -``` - -Plan the changes: - -```bash -terraform plan -out=tfplan -``` - -Apply the changes: - -```bash -terraform apply tfplan -``` - -Note the outputs for the S3 bucket and its KMS key (you'll need these for Phase 3): - -```bash -export BACKEND_BUCKET=$(terraform output -raw terraform_states_s3_bucket_name) -export BACKEND_KMS_KEY_ARN=$(terraform output -raw terraform_state_kms_key_arn) -echo "Backend bucket: $BACKEND_BUCKET" -echo "Backend KMS key: $BACKEND_KMS_KEY_ARN" -``` - - - - -Create a `terraform.tfvars` file in the `remote-backend` directory: - -```hcl -region = "us-east-1" -role_arn = "arn:aws:iam::123456789012:role/AIRunDeployerRole" # IAM role created in Phase 1 -s3_states_bucket_name = "codemie-terraform-states" - -# Optional: Custom tags -tags = { - "SysName" = "CodeMie" - "Environment" = "Production" - "Project" = "CodeMie" -} -``` - -:::tip Review All Variables -Most variables have sensible defaults. Review `variables.tf` for the complete list of available configuration options. -::: - -Set AWS profile: - -```bash -export AWS_PROFILE="your-aws-profile" -``` - -Initialize and apply Terraform: - -```bash -terraform init -terraform plan -out=tfplan -terraform apply tfplan -``` - -Note the outputs for the S3 bucket and its KMS key (you'll need these for Phase 3): - -```bash -export BACKEND_BUCKET=$(terraform output -raw terraform_states_s3_bucket_name) -export BACKEND_KMS_KEY_ARN=$(terraform output -raw terraform_state_kms_key_arn) -echo "Backend bucket: $BACKEND_BUCKET" -echo "Backend KMS key: $BACKEND_KMS_KEY_ARN" -``` - - - - -The created S3 bucket will be used for all subsequent infrastructure deployments. - -:::warning KMS Key Access -The backend's KMS key policy restricts `Decrypt`/`GenerateDataKey*` to the `role_arn` deployer role. If you run `terraform init`/`plan`/`apply` for Phase 3 as a different AWS identity (e.g. an SSO admin profile), backend state reads/writes will fail with `AccessDenied`. Either run as the deployer role directly, or add an `assume_role` block to your backend config, e.g. in a `backend.hcl` file passed as `-backend-config=backend.hcl`: - -```hcl -assume_role = { - role_arn = "arn:aws:iam::123456789012:role/AIRunDeployerRole" -} -``` - -::: - -## Phase 3: Main AWS Resources Deployment - -This phase creates the following resources (see [Architecture](../architecture.md)): - -- EKS Cluster -- AWS ASGs for the EKS Cluster -- AWS ALB & AWS NLB -- AWS KMS key to encrypt and decrypt sensitive data -- AWS IAM Role to access AWS KMS and Bedrock services -- AWS IAM role ExternalSecretOperator to use AWS Systems Manager -- AWS RDS Postgres -- Optionally: internal AWS ALB and private DNS hosted zone for private network connections - -1. Clone the repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git -cd codemie-terraform-aws-platform/platform -``` - -2. Configure and deploy. There are two ways to provide Terraform variables: - - - - -This is the same method used by the `aws-terraform.sh` script. Variables are loaded as environment variables with the `TF_VAR_` prefix, which Terraform automatically recognizes. - -Set AWS profile: - -```bash -export AWS_PROFILE="your-aws-profile" -``` - -Load variables from deployment.conf (`set -a` enables auto-export of all variables): - -```bash -set -a && source ../deployment.conf && set +a -``` - -Initialize Terraform with backend configuration: - -```bash -terraform init \ - -backend-config="bucket=${BACKEND_BUCKET}" \ - -backend-config="key=${TF_VAR_region}/codemie/platform_terraform.tfstate" \ - -backend-config="region=${TF_VAR_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" -``` - -Run terraform plan: - -```bash -terraform plan -out=tfplan -``` - -Apply the changes: - -```bash -terraform apply tfplan -``` - -Check the outputs: - -```bash -terraform output -``` - - - - -Create a `terraform.tfvars` file with your configuration: - -```hcl -# Required: AWS Configuration -region = "us-east-1" -role_arn = "arn:aws:iam::123456789012:role/AIRunDeployerRole" # IAM role created in Phase 1 -platform_domain_name = "codemie.airun.example.com" - -# Required: Platform Configuration -platform_name = "codemie" -subnet_azs = ["us-east-1a", "us-east-1b", "us-east-1c"] - -# Required: EKS Configuration -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 - -# Optional: Network Configuration -platform_cidr = "10.0.0.0/16" -private_cidrs = ["10.0.0.0/22", "10.0.4.0/22", "10.0.8.0/22"] -public_cidrs = ["10.0.12.0/24", "10.0.13.0/24", "10.0.14.0/24"] - -# Optional: IAM Permissions Boundary -eks_admin_role_arn = "" -role_permissions_boundary_arn = "" - -# Optional: Network Access Control -enable_private_connections = true -lb_prefix_list_ids = [] -lb_specific_ips = [] -security_group_ids = [] - -# Optional: Dedicated RDS Instances Configuration -# Set enabled = true to provision a dedicated RDS instance for the service. -# All other fields are optional and fall back to defaults. -keycloak_db_config = { enabled = true } -langfuse_db_config = { enabled = false } -litellm_db_config = { enabled = false } -``` - -:::tip Review All Variables -The configuration file contains many variables. Most have sensible defaults. Review `variables.tf` for the complete list of available configuration options. -::: - -Set AWS profile: - -```bash -export AWS_PROFILE="your-aws-profile" -``` - -Set region for backend configuration (Terraform doesn't read tfvars during init phase): - -```bash -export REGION="us-east-1" -``` - -Initialize Terraform with backend configuration: - -```bash -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" -``` - -Run terraform plan: - -```bash -terraform plan -out=tfplan -``` - -Apply the changes: - -```bash -terraform apply tfplan -``` - -Check the outputs: - -```bash -terraform output -``` - - - - -:::warning Security Groups -Ensure that you allowed incoming traffic to the Security Group attached to LoadBalancers from: - -- Your VPN or from networks you're planning to work with AI/Run CodeMie -- EKS Cluster NAT Gateway EIP (not required if `enable_private_connections` variable is set to `true`) - ::: - -This concludes AWS infrastructure deployment. - -## Next Steps - -After successful deployment, proceed to [Components Deployment](../components-deployment/index.md) to install AI/Run CodeMie application components. diff --git a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/scripted-deployment.md b/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/scripted-deployment.md deleted file mode 100644 index b1ed094a..00000000 --- a/docs/admin/deployment/aws/kubernetes/infrastructure-deployment/scripted-deployment.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -id: infrastructure-scripted-deployment -title: Infrastructure Scripted Deployment -sidebar_label: Infrastructure Scripted Deployment -sidebar_position: 1 -pagination_prev: admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview ---- - -# Scripted Infrastructure Deployment - -This guide walks you through deploying AWS infrastructure for AI/Run CodeMie using the automated `aws-terraform.sh` deployment script. The script handles all deployment phases automatically: IAM deployer role, Terraform state backend, and core platform infrastructure. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Prerequisites - -Before starting the deployment, ensure you have completed all requirements from the [Prerequisites](../prerequisites.md) page: - -### 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**: Have access to Terraform and Helm repositories -- [ ] **Network Planning**: Prepared list of allowed networks -- [ ] **Domain Configuration**: Route 53 hosted zone ready - -:::warning Authentication Required -You must have configured AWS credentials before running the deployment script. Verify with `aws sts get-caller-identity`. -::: - -## Deployment Phases - -The script automatically deploys infrastructure in sequential phases: - -| Phase | Description | Required | -| ------------------------------------ | ---------------------------------------------------------------- | ------------------------------------- | -| **Phase 1: IAM Deployer Role** | Creates IAM role with required permissions for deployment | Can be skipped if role already exists | -| **Phase 2: State Backend** | Creates S3 bucket with native locking for Terraform state files | Yes | -| **Phase 3: Platform Infrastructure** | Deploys EKS, networking, storage, databases, security components | Yes | - -## Phase 1: Deploy IAM Deployer Role - -The IAM deployer role is created first to provide necessary permissions for all subsequent infrastructure operations. This phase can be skipped if the role already exists. - -### Step 1: Clone IAM Repository - -Clone the IAM Terraform repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git -cd codemie-terraform-aws-iam -``` - -### Step 2: Configure IAM Deployment - -Review input variables in `variables.tf` and create a `terraform.tfvars` file with your AWS-specific configuration: - -```hcl -# Required: AWS Configuration -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" -} -``` - -### Step 3: Deploy IAM Role - -Initialize and apply Terraform to create the IAM deployer role: - -```bash -terraform init -terraform plan -terraform apply -``` - -:::info -The created IAM role contains all required permissions to manage AWS resources for AI/Run CodeMie deployment. This role will be used for all subsequent platform infrastructure deployments and updates. -::: - -## Phase 2 & 3: Deploy Platform Infrastructure - -This phase deploys both the Terraform state backend (Phase 2) and core platform infrastructure (Phase 3) using the automated deployment script. - -### Step 1: Clone Platform Repository - -Clone the platform Terraform repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git -cd codemie-terraform-aws-platform -``` - -### Step 2: Configure Platform Deployment - -Edit the `deployment.conf` file to provide your AWS-specific configuration: - -```bash -# Required: AWS Account Information -AWS_PROFILE="My_Profile" - -# Required: Basic Configuration -TF_VAR_region="us-east-1" # AWS region for deployment -TF_VAR_role_arn="arn:aws:iam::123456789012:role/AIRunDeployerRole" # IAM role created in Phase 1 -TF_VAR_platform_domain_name="airun.example.com" # DNS zone name for the platform - -# 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 Configuration -# Set enabled=true to provision a dedicated RDS instance for the service. -# Omitted fields fall back to defaults (instance_class, db_name, username, etc.). -TF_VAR_keycloak_db_config='{"enabled":true}' -TF_VAR_langfuse_db_config='{"enabled":false}' -TF_VAR_litellm_db_config='{"enabled":false}' -... -``` - -:::info Complete Variable List -For all available configuration options, refer to the `variables.tf` file in the platform repository. -::: - -### Step 3: Run Deployment Script - -Execute the automated deployment script: - -```bash -bash ./aws-terraform.sh -``` - -The script will automatically execute the following operations: - -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 for Terraform state files -4. **Deploy Platform Infrastructure**: Provision core platform infrastructure (EKS, networking, storage, databases) -5. **Generate Outputs**: Create `deployment_outputs.env` with infrastructure details required during next phases - -## Deployment Outputs - -Upon successful deployment, the script generates a `deployment_outputs.env` file containing essential infrastructure details needed for the next deployment phase: - -```bash -# Platform Infrastructure Outputs -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 - -# RDS Database Outputs -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" - -# Keycloak Database Outputs (present when keycloak_db_config.enabled=true) -KEYCLOAK_POSTGRES_DATABASE_HOST=codemie-keycloak-rds.123456789012.us-east-1.rds.amazonaws.com -KEYCLOAK_POSTGRES_DATABASE_PORT=5432 -KEYCLOAK_POSTGRES_DATABASE_NAME=keycloak -KEYCLOAK_POSTGRES_DATABASE_USER=keycloak_admin -KEYCLOAK_POSTGRES_DATABASE_PASSWORD="generated-password" - -# LiteLLM Database Outputs (present when litellm_db_config.enabled=true) -LITELLM_POSTGRES_DATABASE_HOST=codemie-litellm-rds.123456789012.us-east-1.rds.amazonaws.com -LITELLM_POSTGRES_DATABASE_PORT=5432 -LITELLM_POSTGRES_DATABASE_NAME=litellm -LITELLM_POSTGRES_DATABASE_USER=litellm_admin -LITELLM_POSTGRES_DATABASE_PASSWORD="generated-password" - -# Langfuse Database Outputs (present when langfuse_db_config.enabled=true) -LANGFUSE_POSTGRES_DATABASE_HOST=codemie-langfuse-rds.123456789012.us-east-1.rds.amazonaws.com -LANGFUSE_POSTGRES_DATABASE_PORT=5432 -LANGFUSE_POSTGRES_DATABASE_NAME=langfuse -LANGFUSE_POSTGRES_DATABASE_USER=langfuse_admin -LANGFUSE_POSTGRES_DATABASE_PASSWORD="generated-password" -``` - -:::tip Save These Outputs -The `deployment_outputs.env` file contains sensitive information. Store it securely, do not commit to version control system and reference it during the Components Deployment phase. -::: - -:::warning Security Groups -Ensure that you allowed incoming traffic to the Security Group attached to LoadBalancers from: - -- Your VPN or from networks you're planning to work with AI/Run CodeMie -- EKS Cluster NAT Gateway EIP (not required if `enable_private_connections` variable is set to `true`) - ::: - -This concludes AWS infrastructure deployment. - -## Post-Deployment Validation - -After deployment completes, verify that all infrastructure was created successfully: - -### Step 1: Verify AWS Resources - -Check that all expected resources were created in the AWS Console or via CLI: - -```bash -# List all resources in the region -aws resourcegroupstaggingapi get-resources --region - -# Verify EKS cluster status -aws eks describe-cluster --name --region --query "cluster.status" - -# Verify RDS instance status -aws rds describe-db-instances --db-instance-identifier --region -``` - -### Step 2: Check Deployment Logs - -Review the deployment logs in the `logs/` directory for any warnings or errors: - -```bash -less logs/codemie_aws_deployment_YYYY-MM-DD-HHMMSS.log -``` - -## Next Steps - -After successful infrastructure deployment and validation, proceed to: - -**[Components Deployment](../components-deployment/index.md)** - Deploy AI/Run CodeMie application components to your EKS cluster diff --git a/docs/admin/deployment/aws/kubernetes/overview.md b/docs/admin/deployment/aws/kubernetes/overview.md deleted file mode 100644 index a1b796df..00000000 --- a/docs/admin/deployment/aws/kubernetes/overview.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: overview -title: AI/Run Deployment Guide on AWS -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/aws/kubernetes/prerequisites ---- - -import OverviewContent from '../../common/deployment/overview/\_overview-content.mdx'; - - diff --git a/docs/admin/deployment/aws/kubernetes/prerequisites.md b/docs/admin/deployment/aws/kubernetes/prerequisites.md deleted file mode 100644 index a6eb20f7..00000000 --- a/docs/admin/deployment/aws/kubernetes/prerequisites.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/aws/kubernetes/overview -pagination_next: admin/deployment/aws/kubernetes/architecture ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import NetworkRequirements from '../../common/deployment/prerequisites/\_network-requirements.mdx'; -import ClusterRequirements from '../../common/deployment/prerequisites/\_cluster-requirements.mdx'; -import DeploymentMachineTools from '../../common/deployment/prerequisites/\_deployment-machine-tools.mdx'; -import NextSteps from '../../common/deployment/prerequisites/\_next-steps.mdx'; - -# Prerequisites - -This page outlines the requirements and prerequisites necessary for deploying AI/Run CodeMie on Amazon Web Services. Please ensure all requirements are met before proceeding with the installation. - -## AWS Account Requirements - -### 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 -- **Sufficient Quota** for the required resources (EKS, RDS, networking, storage, etc.) - :::info Complete Resource List - For a detailed list of all AWS resources that will be provisioned, refer to the [Infrastructure Deployment](./infrastructure-deployment/index.md) section or review the Terraform modules in the deployment repository. - ::: - -## Network Requirements - -### DNS and Certificate Requirements - -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 - -:::tip Automatic Setup -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. -::: - - - - - - - -**Cloud-Specific Tools:** - -| Tool | Version | Purpose | -| ---------------------------------------------------------------------------------------- | ------- | ----------------------- | -| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) | latest | AWS resource management | - -### Required Repository Access - -You will need access to the following repositories to complete the deployment: - -- **Terraform IAM Module:** [codemie-terraform-aws-iam](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam) -- **Terraform Platform Module:** [codemie-terraform-aws-platform](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform) -- **Terraform Remote Backend:** [codemie-terraform-aws-remote-backend](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend) -- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) - -:::info Air-Gapped Environments -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. -::: - - diff --git a/docs/admin/deployment/aws/on-vm/architecture.mdx b/docs/admin/deployment/aws/on-vm/architecture.mdx deleted file mode 100644 index c3ff9d39..00000000 --- a/docs/admin/deployment/aws/on-vm/architecture.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -id: architecture -title: On VM Deployment Architecture -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/aws/on-vm/prerequisites -pagination_next: admin/deployment/aws/on-vm/deployment/deployment ---- - -# On VM Deployment Architecture - -This page describes the infrastructure and application architecture of CodeMie On VM. - -## Infrastructure Overview - -CodeMie On VM runs on a single EC2 instance with supporting AWS services. Terraform provisions the following resources depending on the network mode: - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - Direct access to the EC2 instance via Elastic IP: - - ![IP Mode Diagram](./images/ip-mode-diagram.drawio.png) - - - - When `TF_VAR_platform_domain_name` is configured, an ALB with trusted TLS certificate is created: - - ![Domain Mode Diagram](./images/domain-mode-diagram.drawio.png) - - - - When `TF_VAR_private_ip_only=true`, EC2 is placed in a private subnet with NAT Gateway for outbound traffic. Access is via VPN, AWS Workspaces, or some other available VM: - - ![Private Mode Diagram](./images/private-mode-diagram.drawio.png) - - - - -### AWS Resources - -| Resource | Purpose | -| ------------------------ | --------------------------------------------------------------------- | -| **VPC** | Isolated network with public subnets (+ private if `private_ip_only`) | -| **EC2 Instance** | Single instance running Docker Compose (Ubuntu, r5.xlarge default) | -| **Elastic IP** | Static public IP for the EC2 instance | -| **S3 Bucket** | Persistent storage for user data (repos, files) | -| **KMS Key** | Encryption key for S3 data at rest | -| **ALB** | Application Load Balancer with TLS (if domain configured) | -| **ACM Certificate** | Trusted TLS certificate for the domain (if domain configured) | -| **Route 53 Record** | DNS A record pointing to ALB (if domain configured) | -| **SSM Parameter** | Stores EC2 SSH private key securely | -| **Security Groups** | Controls inbound traffic to ALB and EC2 | -| **IAM Instance Profile** | Grants EC2 access to Bedrock, S3, KMS, SSM | - -### Network Modes - -| Mode | Configuration | Access | -| ----------------------- | ------------------------------------------- | --------------------------------- | -| **Public IP** (default) | `TF_VAR_private_ip_only=false` | EC2 gets EIP, direct HTTPS access | -| **Domain + ALB** | `TF_VAR_platform_domain_name="example.com"` | ALB with ACM cert, Route 53 DNS | -| **Private IP** | `TF_VAR_private_ip_only=true` | No public IP, access via VPN only | - -## Application Architecture - -All CodeMie services run as Docker containers on the EC2 instance, orchestrated by Docker Compose. - -![Docker Compose Services](../../common/deployment/images/docker-compose-diagram.drawio.png) - -### Services by Profile - -**Shared services** (both profiles): - -| Service | Image | Purpose | -| ------------- | --------------------------- | ------------------------------------------------- | -| postgres | pgvector/pgvector:pg17 | Primary database for application data | -| elasticsearch | elasticsearch:8.x | Document storage and search for Data Sources | -| kibana | kibana:8.x | Log visualization and analytics for Elasticsearch | -| mcp-connect | codemie-mcp-connect-service | Connector for MCP servers | -| nginx | nginx:1.31-alpine | Reverse proxy, TLS termination | - -**OSS profile:** - -| Service | Purpose | -| -------------- | --------------------------------------------- | -| codemie-oss | API server with built-in local authentication | -| codemie-ui-oss | Web frontend | - -**Enterprise profile:** - -| Service | Purpose | -| ----------------- | ---------------------------------------------- | -| codemie | API server | -| codemie-ui | Web frontend | -| keycloak | Identity provider (SSO, OIDC) | -| oauth2-proxy | Authentication proxy in front of nginx | -| litellm | LLM proxy for model routing and key management | -| nats | Messaging for plugin engine | -| nats-auth-callout | NATS authentication service | -| mermaid-server | Diagram rendering | - -## Resource Requirements - -### Minimum EC2 Instance - -| Resource | Minimum | Recommended | -| -------- | ------- | ------------- | -| vCPU | 4 | 4 (r5.xlarge) | -| RAM | 16 GB | 32 GB | -| Disk | 50 GB | 100 GB (gp3) | - -## Next Steps - -- [Deployment](../deployment/) — Deploy CodeMie On VM with Terraform diff --git a/docs/admin/deployment/aws/on-vm/deployment/byo.md b/docs/admin/deployment/aws/on-vm/deployment/byo.md deleted file mode 100644 index 95d32d2b..00000000 --- a/docs/admin/deployment/aws/on-vm/deployment/byo.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -id: byo -title: BYO EC2 Deployment -sidebar_label: BYO EC2 -sidebar_position: 7 -pagination_prev: admin/deployment/aws/on-vm/deployment/manual-deployment -pagination_next: null ---- - -# BYO EC2 Deployment - -Deploy CodeMie on an **existing EC2 instance** that is not managed by this project's Terraform. This mode skips all infrastructure provisioning and directly provisions the application stack. - -## When to Use - -- You already have an EC2 instance (provisioned manually, via CloudFormation, or another Terraform stack) -- You want to avoid creating additional VPC/ALB/S3 resources via Terraform -- Your organization manages infrastructure separately from application deployment - -## EC2 Requirements - -Your existing EC2 instance must meet these requirements: - -| Requirement | Details | -| --------------------- | -------------------------------------------------------------- | -| **OS** | Ubuntu 24.04 | -| **Instance type** | Minimum t3.xlarge (4 vCPU, 16 GB RAM); recommended r5.xlarge | -| **Disk** | Minimum 50 GB; recommended 100 GB | -| **Internet access** | Outbound HTTPS for pulling Docker images and accessing Bedrock | -| **IAM Instance Role** | Permissions for S3, KMS (optional), and Bedrock | - -### Required IAM Permissions on EC2 - -The instance role must include: - -```json -{ - "Effect": "Allow", - "Action": [ - "bedrock:InvokeModel", - "bedrock:InvokeModelWithResponseStream", - "s3:GetObject", - "s3:PutObject", - "s3:DeleteObject", - "s3:ListBucket" - ], - "Resource": "*" -} -``` - -If using KMS encryption, add: - -```json -{ - "Effect": "Allow", - "Action": ["kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey"], - "Resource": "arn:aws:kms:::key/" -} -``` - -## Configuration - -Edit `deployment.conf` with BYO-specific variables: - -```bash -# ── Shared (required for both modes) ──────────────────────────────── -TF_VAR_region="eu-north-1" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# ── BYO EC2 ────────────────────────────────────────────────────────── -BYO_EC2_HOST="1.2.3.4" # Public IP, private IP, or hostname -BYO_EC2_USER="ubuntu" # SSH user -BYO_EC2_SSH_KEY="/path/to/key.pem" # Absolute path to SSH private key -BYO_EC2_SSH_MODE="direct" # direct | ssm -BYO_EC2_INSTANCE_ID="" # Required only for ssm mode -BYO_AWS_S3_BUCKET_NAME="my-bucket" # S3 bucket (must already exist) -BYO_AWS_KMS_KEY_ID="" # KMS key ID (empty = plain encryption) -BYO_PLATFORM_DOMAIN_NAME="" # Optional: overrides CODEMIE_HOST URL -``` - -### BYO_EC2_HOST - -This variable serves two purposes depending on the SSH mode: - -| SSH Mode | Purpose of `BYO_EC2_HOST` | -| ---------- | ------------------------------------------------------------- | -| **direct** | SSH target address AND application URL (`CODEMIE_HOST`) | -| **ssm** | Application URL only (SSH connects via `BYO_EC2_INSTANCE_ID`) | - -Set it based on how users will access the application: - -| Scenario | `BYO_EC2_HOST` value | Result | -| --------------------------- | ------------------------------- | -------------------------------------- | -| EC2 has a public IP | Public IP (e.g. `1.2.3.4`) | `CODEMIE_HOST=https://1.2.3.4` | -| EC2 in private subnet (VPN) | Private IP (e.g. `10.0.10.104`) | `CODEMIE_HOST=https://10.0.10.104` | -| ALB with domain in front | Any IP (overridden) | Set `BYO_PLATFORM_DOMAIN_NAME` instead | - -### SSH Modes - -| Mode | When to Use | Requirements | -| ---------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- | -| **direct** | EC2 has a reachable IP/hostname and port 22 is open | SSH private key, network access to port 22 | -| **ssm** | EC2 is in a private subnet, or you prefer not to open port 22 | SSM Agent installed on EC2, valid AWS credentials locally, instance ID | - -### Encryption - -| `BYO_AWS_KMS_KEY_ID` | Behavior | -| --------------------------- | ------------------------------------------------------- | -| Empty | `ENCRYPTION_TYPE=plain` — data stored unencrypted in S3 | -| Set (e.g. `12345-abcde...`) | `ENCRYPTION_TYPE=aws` — S3 data encrypted with KMS | - -### CODEMIE_HOST Resolution - -| Configuration | Result | -| ------------------------------------------------ | ------------------------------------------ | -| `BYO_PLATFORM_DOMAIN_NAME` empty | `CODEMIE_HOST=https://` | -| `BYO_PLATFORM_DOMAIN_NAME="codemie.example.com"` | `CODEMIE_HOST=https://codemie.example.com` | - -:::tip Using with ALB -If you have your own ALB with ACM certificate in front of the EC2: - -1. Set `BYO_PLATFORM_DOMAIN_NAME` to your domain -2. Point the ALB target group to EC2 port 443 -3. The self-signed certificate on nginx works fine as an ALB backend (ALB does not validate backend certs) - ::: - -## Deployment - -### Step 1: Place the GCP registry key - -This is a GCP service account credentials file used to pull CodeMie container images from Google Artifact Registry. - -:::info -For open-source deployments with self-built images, this key is optional. -::: - -```bash -cp /path/to/key.json ./key.json -``` - -### Step 2: Run BYO deployment - -```bash -./deploy.sh --byo -``` - -The script executes: - -| Phase | Description | -| ------------------------- | ---------------------------------------------------- | -| Loading config | Validates BYO-specific variables | -| Checking prerequisites | Verifies tools (no Terraform needed for direct mode) | -| Verifying AWS credentials | Only if SSM mode | -| Setting up BYO variables | Maps config to internal variables | -| Generating .env | Creates secrets, renders environment file | -| Setting up SSH | Configures SSH transport (direct or SSM) | -| Provisioning EC2 | Installs Docker, syncs files, starts services | -| Writing outputs | Saves deployment info to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -### Step 3: Verify - -```bash -curl -k https:///v1/healthcheck -``` - -## Re-deploying - -Run `./deploy.sh --byo` again. Secrets from `deployment_outputs.env` are preserved automatically. - -## Troubleshooting - -### SSH connection refused - -- **Direct mode**: Verify port 22 is open in the EC2 security group and the SSH key is correct -- **SSM mode**: Verify SSM Agent is running (`systemctl status amazon-ssm-agent`) and your AWS credentials are valid - -### Docker login fails - -The `key.json` must be a valid GCP service account with access to `europe-west3-docker.pkg.dev`. Verify locally: - -```bash -cat key.json | docker login -u _json_key --password-stdin https://europe-west3-docker.pkg.dev -``` - -### Containers unhealthy - -SSH into the instance and check logs: - -```bash -cd /opt/codemie/compose -docker compose --profile enterprise logs --tail=50 -docker compose --profile enterprise ps -``` diff --git a/docs/admin/deployment/aws/on-vm/deployment/index.md b/docs/admin/deployment/aws/on-vm/deployment/index.md deleted file mode 100644 index b7bbfacc..00000000 --- a/docs/admin/deployment/aws/on-vm/deployment/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: deployment -title: Deployment -sidebar_label: Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/aws/on-vm/architecture -pagination_next: admin/deployment/aws/on-vm/deployment/scripted-deployment ---- - -# Deployment - -This section covers deploying CodeMie On VM infrastructure and application stack. - -## Deployment Methods - -| Method | Description | When to Use | -| ------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| [**Scripted Deployment**](./scripted-deployment) | Fully automated — single `./deploy.sh` handles IAM, Terraform, and provisioning | Recommended for most users | -| [**Manual Deployment**](./manual-deployment) | Step-by-step Terraform commands, then BYO mode for application provisioning | When you need full control or are integrating with existing workflows | - -:::tip Recommendation -Use **Scripted Deployment** unless you have specific requirements for manual Terraform control. The script handles prerequisite checks, configuration validation, and proper phase sequencing automatically. -::: - -## Deployment Phases - -Both methods execute the same logical phases: - -| Phase | Description | -| ---------------------------- | ------------------------------------------------------------------------ | -| **IAM Deployer Role** | Creates IAM role with permissions for EC2, VPC, S3, KMS, ALB (one-time) | -| **Terraform State Backend** | Creates S3 bucket for Terraform state (one-time) | -| **Platform Infrastructure** | Provisions VPC, EC2, S3, KMS, ALB, Security Groups | -| **Application Provisioning** | Installs Docker, syncs compose files, generates secrets, starts services | - -## Next Steps - -- [Scripted Deployment](./scripted-deployment) — Automated deployment with `./deploy.sh` -- [Manual Deployment](./manual-deployment) — Manual Terraform + BYO application provisioning diff --git a/docs/admin/deployment/aws/on-vm/deployment/manual-deployment.md b/docs/admin/deployment/aws/on-vm/deployment/manual-deployment.md deleted file mode 100644 index 6e31ccb6..00000000 --- a/docs/admin/deployment/aws/on-vm/deployment/manual-deployment.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -id: manual-deployment -title: Manual Deployment -sidebar_label: Manual Deployment -sidebar_position: 6 -pagination_prev: admin/deployment/aws/on-vm/deployment/scripted-deployment -pagination_next: admin/deployment/aws/on-vm/deployment/byo ---- - -# Manual Deployment - -This guide provides step-by-step instructions for manually deploying CodeMie On VM infrastructure using Terraform, followed by application provisioning via the BYO mode (`./deploy.sh --byo`). - -:::info When to Use Manual Deployment -Manual deployment is suitable when you need fine-grained control over each Terraform phase, want to customize infrastructure configurations, or are integrating with existing infrastructure management workflows. -::: - -## Prerequisites - -Ensure you have completed all requirements from the [Prerequisites](../../prerequisites) page: - -- [ ] **AWS Access**: Programmatic access with IAM permissions -- [ ] **Tools Installed**: Terraform 1.15.x, AWS CLI, jq, openssl, envsubst, session-manager-plugin -- [ ] **AWS Authentication**: Configured AWS credentials -- [ ] **Repository Access**: Cloned [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) -- [ ] **GCP Registry**: `key.json` file available - -## Deployment Phases - -| Phase | Description | Directory | -| ------------------------------------ | ------------------------------------------ | -------------------------------------- | -| **Phase 1: IAM Deployer Role** | Creates IAM role with required permissions | `terraform/aws/codemie-on-vm-aws-iam/` | -| **Phase 2: State Backend** | Creates S3 bucket for Terraform state | `terraform/aws/remote-backend/` | -| **Phase 3: Platform Infrastructure** | Provisions VPC, EC2, S3, KMS, ALB | `terraform/aws/platform/` | -| **Phase 4: Application** | Deploys Docker Compose stack via BYO mode | `./` (repo root) | - ---- - -## Phase 1: IAM Deployer Role - -:::info One-Time Setup -This phase only needs to run once per AWS account. -::: - -1. Navigate to the IAM module: - -```bash -cd terraform/aws/codemie-on-vm-aws-iam/ -``` - -2. Create a `terraform.tfvars` file: - -```hcl -region = "eu-north-1" -platform_name = "codemie" -deployer_role_name = "CodemieOnVmDeployerRole" - -# Optional: IAM Permissions Boundary -iam_permissions_boundary_policy_arn = "" - -# Optional: Custom tags -tags = { - "SysName" = "CodeMie" - "Environment" = "Development" - "Project" = "codemie-on-vm" -} -``` - -3. Initialize and apply: - -```bash -terraform init -terraform plan -out=tfplan -terraform apply tfplan -``` - -4. Note the deployer role ARN: - -```bash -terraform output deployer_iam_role_arn -# Example: arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole -``` - ---- - -## Phase 2: Terraform State Backend - -1. Navigate to the remote backend directory: - -```bash -cd terraform/aws/remote-backend/ -``` - -2. Initialize Terraform: - -```bash -terraform init -``` - -3. Plan and apply with variables: - -```bash -terraform plan -out=tfplan \ - -var="region=eu-north-1" \ - -var="role_arn=arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" \ - -var="bucket_name=codemie-terraform-states" - -terraform apply tfplan -``` - -The S3 bucket is now ready for storing platform state. - ---- - -## Phase 3: Platform Infrastructure - -1. Navigate to the platform directory: - -```bash -cd terraform/aws/platform/ -``` - -2. Create `backend.tfvars`: - -```hcl -bucket = "codemie-terraform-states" -key = "codemie/terraform.tfstate" -region = "eu-north-1" -use_lockfile = true -``` - -3. Initialize Terraform with backend configuration: - -```bash -terraform init -backend-config=backend.tfvars -``` - -4. Create `terraform.tfvars` with platform configuration: - -```hcl -region = "eu-north-1" -role_arn = "arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" -platform_name = "codemie" -instance_type = "r5.xlarge" -volume_size = 100 - -# Network: set to true for private-only deployment (requires VPN) -private_ip_only = false - -# Domain (optional): enables ALB + ACM certificate + Route 53 record -# Leave empty for IP-only access with self-signed certificate -platform_domain_name = "" - -# Access control: prefix list IDs allowed to reach ALB/EC2 -access_prefix_list_ids = [] -``` - -5. Plan and apply: - -```bash -terraform plan -out=tfplan -terraform apply tfplan -``` - -6. Note the outputs — you will need them for Phase 4: - -```bash -terraform output ec2_instance_id -terraform output ec2_public_ip # Empty if private_ip_only=true -terraform output ec2_private_ip -terraform output s3_bucket_name -terraform output kms_key_id -terraform output ssm_ec2_private_key -``` - -7. Fetch the SSH key from SSM: - -```bash -aws ssm get-parameter \ - --name "$(terraform output -raw ssm_ec2_private_key)" \ - --region eu-north-1 \ - --with-decryption \ - --query "Parameter.Value" \ - --output text > codemie-key.pem - -chmod 600 codemie-key.pem -``` - ---- - -## Phase 4: Application Provisioning (BYO Mode) - -Now that infrastructure is provisioned manually, use the BYO mode to deploy the application stack. The BYO mode skips Terraform and connects directly to the EC2 instance. - -1. Navigate to the project root: - -2. Place the GCP registry key: - -```bash -cp /path/to/key.json ./key.json -``` - -3. Configure `deployment.conf` with BYO settings. - -**`BYO_EC2_HOST`** determines the application URL (`CODEMIE_HOST`). Set it based on your network mode: - -| Network Mode | `BYO_EC2_HOST` value | Access | -| ------------ | ------------------------------------------------- | ------------------- | -| Public IP | `ec2_public_ip` from outputs | Direct HTTPS to EIP | -| Private IP | `ec2_private_ip` from outputs | HTTPS via VPN only | -| Domain + ALB | Any IP (overridden by `BYO_PLATFORM_DOMAIN_NAME`) | HTTPS via ALB | - -**`BYO_EC2_SSH_MODE`** determines how the script connects to the instance: - -| SSH Mode | When to use | `BYO_EC2_HOST` used for SSH? | -| -------- | -------------------------------------------------- | ----------------------------- | -| `ssm` | Instance created by this Terraform (has SSM agent) | No — connects via instance ID | -| `direct` | Instance with port 22 reachable from your machine | Yes — SSH target | - -**Example: Public IP mode** - -```bash -# ── Shared ─────────────────────────────────────────────────────────── -TF_VAR_region="eu-north-1" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" - -# ── BYO EC2 ────────────────────────────────────────────────────────── -BYO_EC2_HOST="*.*.*.*" # ec2_public_ip -BYO_EC2_USER="ubuntu" -BYO_EC2_SSH_KEY="./terraform/platform/codemie-key.pem" -BYO_EC2_SSH_MODE="ssm" -BYO_EC2_INSTANCE_ID="i-xxxxxxxxxxxxxxxxx" -BYO_AWS_S3_BUCKET_NAME="codemie-user-data" -BYO_AWS_KMS_KEY_ID="" -BYO_PLATFORM_DOMAIN_NAME="" -``` - -**Example: Private IP mode** (`private_ip_only=true`) - -```bash -BYO_EC2_HOST="10.0.10.104" # ec2_private_ip (accessible via VPN) -BYO_EC2_USER="ubuntu" -BYO_EC2_SSH_KEY="./terraform/platform/codemie-key.pem" -BYO_EC2_SSH_MODE="ssm" -BYO_EC2_INSTANCE_ID="i-xxxxxxxxxxxxxxxxx" -BYO_AWS_S3_BUCKET_NAME="codemie-user-data" -BYO_AWS_KMS_KEY_ID="" -BYO_PLATFORM_DOMAIN_NAME="" -``` - -**Example: Domain mode** (ALB + ACM configured in Phase 3) - -```bash -BYO_EC2_HOST="10.0.10.104" # Any reachable IP (not used for URL) -BYO_EC2_USER="ubuntu" -BYO_EC2_SSH_KEY="./terraform/platform/codemie-key.pem" -BYO_EC2_SSH_MODE="ssm" -BYO_EC2_INSTANCE_ID="i-xxxxxxxxxxxxxxxxx" -BYO_AWS_S3_BUCKET_NAME="codemie-user-data" -BYO_AWS_KMS_KEY_ID="" -BYO_PLATFORM_DOMAIN_NAME="example.com" -``` - -4. Run the BYO deployment: - -```bash -./deploy.sh --byo -``` - -5. Verify the deployment: - -```bash -curl -k https:///v1/healthcheck -``` - -## Post-Deployment - -### SSH Access - -```bash -ssh -i codemie-key.pem \ - -o "ProxyCommand=aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p" \ - ubuntu@ -``` - -### Re-deploying - -To update the application (e.g., new version): - -1. Edit `deployment.conf` (change `CODEMIE_VERSION`) -2. Run `./deploy.sh --byo` again - -Secrets from `deployment_outputs.env` are preserved automatically. - -### Modifying Infrastructure - -To change infrastructure (e.g., instance type, add domain): - -1. Update `terraform.tfvars` in `terraform/platform/` -2. Run `terraform plan -out=tfplan && terraform apply tfplan` -3. Update `deployment.conf` with new outputs if needed -4. Run `./deploy.sh --byo` to re-provision the application - -## Next Steps - -- [BYO EC2](../byo) — Deploy on a completely external EC2 instance (not managed by this Terraform) diff --git a/docs/admin/deployment/aws/on-vm/deployment/scripted-deployment.md b/docs/admin/deployment/aws/on-vm/deployment/scripted-deployment.md deleted file mode 100644 index 444c2e6d..00000000 --- a/docs/admin/deployment/aws/on-vm/deployment/scripted-deployment.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -id: scripted-deployment -title: Scripted Deployment -sidebar_label: Scripted Deployment -sidebar_position: 5 -pagination_prev: admin/deployment/aws/on-vm/deployment/deployment -pagination_next: admin/deployment/aws/on-vm/deployment/manual-deployment ---- - -# Scripted Deployment - -This guide walks through deploying CodeMie On VM using the automated `deploy.sh` script. The script handles all phases automatically: IAM role creation, Terraform state backend, infrastructure provisioning, and application deployment. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Phase 1: IAM Deployer Role - -The IAM deployer role provides scoped permissions for Terraform to create and manage AWS resources. - -:::info One-Time Setup -Phase 1 only needs to run once per AWS account. If the role already exists, skip to Phase 2. -::: - -### Step 1: Navigate to the IAM module - -```bash -cd terraform/aws/codemie-on-vm-aws-iam/ -``` - -### Step 2: Configure variables - -Create a `terraform.tfvars` file: - -```hcl -region = "eu-north-1" -platform_name = "codemie" -deployer_role_name = "CodemieOnVmDeployerRole" - -# Optional: IAM permissions boundary (leave empty if not required) -iam_permissions_boundary_policy_arn = "" - -# Optional: custom tags -tags = { - "SysName" = "CodeMie" - "Environment" = "Development" - "Project" = "codemie-on-vm" -} -``` - -### Step 3: Deploy the role - -```bash -terraform init -terraform plan -terraform apply -``` - -### Step 4: Note the output - -```bash -terraform output deployer_iam_role_arn -# Example: arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole -``` - -Save this ARN — you will use it as `TF_VAR_role_arn` in the next phase. - ---- - -## Phase 2: Platform Deployment - -### Step 1: Navigate to the repo root - -### Step 2: Place the GCP registry key - -Copy your `key.json` file to the repository root: - -```bash -cp /path/to/key.json ./key.json -``` - -### Step 3: Create deployment configuration - -```bash -cp deployment.conf.example deployment.conf -``` - -Edit `deployment.conf`: - -```bash -# ── AWS ────────────────────────────────────────────────────────────── -AWS_PROFILE="" # AWS CLI profile (optional) -TF_VAR_region="eu-north-1" -TF_VAR_role_arn="arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" - -# ── Terraform State ────────────────────────────────────────────────── -TF_VAR_s3_states_bucket_name="codemie-terraform-states" - -# ── Platform ───────────────────────────────────────────────────────── -TF_VAR_platform_name="codemie" - -# ── EC2 ────────────────────────────────────────────────────────────── -TF_VAR_instance_type="r5.xlarge" # 4 vCPU, 32GB RAM -TF_VAR_volume_size=100 # Root EBS size in GB -TF_VAR_access_prefix_list_ids='[]' # Prefix lists for ALB/EC2 SG access - -# ── Network mode ───────────────────────────────────────────────────── -TF_VAR_private_ip_only=false # true = private subnet, no public IP - -# ── Domain & TLS (optional) ────────────────────────────────────────── -TF_VAR_platform_domain_name="" # e.g. codemie.example.com - -# ── CodeMie ────────────────────────────────────────────────────────── -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise -``` - -### Step 4: Authenticate with AWS - -```bash -# If using AWS SSO: -aws sso login --profile your-profile -export AWS_PROFILE=your-profile - -# Verify credentials: -aws sts get-caller-identity -``` - -### Step 5: Run the deployment - -```bash -./deploy.sh -``` - -The script executes the following phases: - -| Phase | Description | -| ------------------------------ | ------------------------------------------------------- | -| Loading config | Validates `deployment.conf` variables | -| Checking prerequisites | Verifies required tools are installed | -| Verifying AWS credentials | Confirms valid AWS session | -| Initializing S3 remote backend | Creates S3 bucket for Terraform state | -| Running terraform | Plans and applies infrastructure (with approval prompt) | -| Reading terraform outputs | Fetches EC2 ID, IPs, S3 bucket, KMS key | -| Generating .env | Creates secrets and renders Docker Compose environment | -| Provisioning EC2 | Installs Docker, syncs files, starts services | -| Writing outputs | Saves credentials to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -:::warning Interactive Prompts -The script will pause twice for approval: - -1. Remote backend Terraform plan -2. Platform Terraform plan - -Review the plans carefully before typing `y`. -::: - -### Step 6: Verify deployment - -After the script completes, verify the application is running: - -```bash -# Check the health endpoint (use the URL from the summary) -curl -k https:///v1/healthcheck -``` - -Expected response: `{"status":"ok"}` - -## Deployment Outputs - -The script creates `deployment_outputs.env` with: - -- **CODEMIE_URL** — Application URL -- **EC2_INSTANCE_ID** — Instance ID for management -- **SSH_COMMAND** — Full SSH command for access -- **Credentials** — Keycloak admin or superadmin password (depending on profile) -- **Internal secrets** — Preserved across re-runs to avoid breaking running databases - -:::danger Sensitive File -`deployment_outputs.env` contains passwords and secrets. Do not commit it to version control. -::: - -## SSH Access - -Connect to the EC2 instance: - -```bash -# The SSH command is provided in the deployment summary and outputs file -ssh -i codemie-key.pem \ - -o "ProxyCommand=aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p" \ - ubuntu@ -``` - -:::tip SSH via SSM -SSH access uses AWS Systems Manager Session Manager as a proxy. This means: - -- No need to open SSH port (22) in security groups -- All sessions are logged in CloudTrail -- Works even for private-IP-only instances - ::: - -## Re-deploying / Updating - -To update CodeMie version or configuration: - -1. Edit `deployment.conf` (e.g., change `CODEMIE_VERSION`) -2. Run `./deploy.sh` again - -The script detects the existing `deployment_outputs.env` and preserves all secrets. Only the Docker Compose services are updated. - -## Next Steps - -- [Manual Deployment](../manual-deployment) — Alternative method with full Terraform control diff --git a/docs/admin/deployment/aws/on-vm/overview.md b/docs/admin/deployment/aws/on-vm/overview.md deleted file mode 100644 index c0161429..00000000 --- a/docs/admin/deployment/aws/on-vm/overview.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -id: overview -title: AI/Run CodeMie On VM Deployment Guide -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/aws/on-vm/prerequisites ---- - -# AI/Run CodeMie On VM Deployment - -CodeMie On VM deploys the full AI/Run CodeMie platform on a **single EC2 instance** using Docker Compose. It provides the same core functionality as the full AWS (EKS) deployment but with minimal infrastructure overhead. - -## When to Use - -CodeMie On VM is designed for: - -- **Proof of Concept (PoC)** — quickly validate CodeMie capabilities in your environment -- **Demo environments** — showcase CodeMie to stakeholders without complex infrastructure - -:::warning Not for Production -For production workloads with high availability, scaling, and multi-AZ redundancy, use the full [AWS EKS Deployment Guide](/admin/deployment/aws/kubernetes/overview). -::: - -## Deployment Profiles - -CodeMie On VM supports two profiles: - -| Profile | Authentication | LLM Proxy | Plugin Tool | -| -------------- | ----------------------- | --------- | ----------- | -| **OSS** | Local (built-in) | Internal | No | -| **Enterprise** | Keycloak + OAuth2 Proxy | LiteLLM | Yes | - -## Deployment Modes - -| Mode | Command | Infrastructure | -| ------------ | ------------------- | ---------------------------------------- | -| **Standard** | `./deploy.sh` | Terraform creates EC2, VPC, ALB, S3, KMS | -| **BYO EC2** | `./deploy.sh --byo` | Use your existing EC2 instance | - -## Repository - -All deployment code is hosted at: [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) - -``` -codemie-on-vm/ -├── compose/ # Docker Compose files and config -├── deploy.sh # Deployment script -├── destroy.sh # Destroy script -├── deployment.conf.aws.example # Configuration template -└── terraform/ - └── aws/ - ├── codemie-on-vm-aws-iam/ # IAM deployer role Terraform module - ├── platform/ # EC2, VPC, ALB, S3, KMS infrastructure - └── remote-backend/ # S3 Terraform state bucket -``` - -## Next Steps - -Proceed to [Prerequisites](/admin/deployment/aws/on-vm/prerequisites) to verify your environment is ready for deployment. diff --git a/docs/admin/deployment/aws/on-vm/prerequisites.md b/docs/admin/deployment/aws/on-vm/prerequisites.md deleted file mode 100644 index d752c61e..00000000 --- a/docs/admin/deployment/aws/on-vm/prerequisites.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/aws/on-vm/overview -pagination_next: admin/deployment/aws/on-vm/architecture ---- - -# Prerequisites - -This page outlines the requirements for deploying AI/Run CodeMie On VM. Ensure all prerequisites are met before proceeding. - -## AWS Account Requirements - -### Required Access and Permissions - -- **Active AWS Account** with a region that supports [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) -- **IAM permissions** to create an IAM deployer role (one-time setup) -- **Sufficient quota** for: 1 EC2 instance, 1 VPC, 1 S3 bucket, 1 KMS key, 1 EIP - -:::tip IAM Deployer Role -The deployment uses a dedicated IAM role with scoped permissions. You only need broad IAM access to create this role once — subsequent deployments use the role. -::: - -### Network Requirements - -- Outbound internet access from EC2 (to pull Docker images, access Bedrock API) -- Optional: Route 53 hosted zone (if using a custom domain with ALB + ACM) - -## Deployment Machine Tools - -The following tools must be installed on the machine where you run `./deploy.sh`: - -| Tool | Version | Purpose | -| --------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------- | -| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | -| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) | latest | AWS resource management | -| [Session Manager Plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) | latest | SSH access via AWS SSM | -| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | -| openssl | latest | Secret generation | -| envsubst | latest | Template rendering | - -**Enterprise profile only:** - -| Tool | Version | Purpose | -| ------------------------------------- | ------- | ------------------- | -| [nsc](https://github.com/nats-io/nsc) | latest | NATS key generation | - -### Verify Installation - -```bash -terraform version # Should show 1.15.x -aws --version # AWS CLI v2 -session-manager-plugin # Should print version info -jq --version -openssl version -envsubst --version -``` - -## GCP Container Registry Access - -CodeMie container images are hosted on `europe-west3-docker.pkg.dev`. You need a **GCP service account key file** (`key.json`) with read access to the registry. - -:::info Obtaining key.json -Contact your CodeMie administrator or EPAM delivery team to obtain the `key.json` file for registry access. -::: - -## Repository Access - -Clone the deployment repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git -cd codemie-on-vm -``` - -The repository structure: - -| Directory | Purpose | -| -------------------------------------- | ---------------------------------------------- | -| `compose/` | Docker Compose files and service configuration | -| `deploy.sh` | Deployment script | -| `terraform/aws/codemie-on-vm-aws-iam/` | IAM deployer role Terraform module | -| `terraform/aws/remote-backend/` | S3 Terraform state bucket | -| `terraform/aws/platform/` | EC2, VPC, ALB, S3, KMS infrastructure | - -## Next Steps - -After verifying all prerequisites, review the [Architecture](/admin/deployment/aws/on-vm/architecture) to understand what will be deployed. diff --git a/docs/admin/deployment/azure/kubernetes/accessing-applications.md b/docs/admin/deployment/azure/kubernetes/accessing-applications.md deleted file mode 100644 index fb829cbd..00000000 --- a/docs/admin/deployment/azure/kubernetes/accessing-applications.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: accessing-applications -sidebar_position: 6 -title: Accessing AI/Run CodeMie Applications -sidebar_label: Accessing Applications -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/configuration/index ---- - -import AccessingApplicationsContent from '../../common/deployment/accessing-codemie/\_accessing-codemie-applications.mdx'; - - diff --git a/docs/admin/deployment/azure/kubernetes/architecture.md b/docs/admin/deployment/azure/kubernetes/architecture.md deleted file mode 100644 index b8ca9886..00000000 --- a/docs/admin/deployment/azure/kubernetes/architecture.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: architecture -title: AI/Run CodeMie Deployment Architecture -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/azure/kubernetes/prerequisites -pagination_next: admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-deployment-overview ---- - -import ContainerResources from '../../common/deployment/architecture/\_container-resources.mdx'; - -# AI/Run CodeMie Deployment Architecture - -This page provides an overview of the AI/Run CodeMie deployment architecture on Microsoft Azure, including infrastructure components, network design, and resource requirements. - -## Architecture Overview - -AI/Run CodeMie is deployed on Azure Kubernetes Service (AKS) with supporting Azure services for networking, storage, and identity management. - -### High-Level Architecture Diagram - -The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on Azure: - -![Azure Architecture Diagram](./images/architecture-diagram.drawio.png) - -:::tip Architecture Customization -The architecture can be customized based on your organization's security policies, compliance requirements, and operational preferences. Consult with your deployment team to discuss specific requirements. -::: - -## Resource Requirements - - - -## Next Steps - -After understanding the architecture, proceed to: - -- [Infrastructure Deployment](./infrastructure-deployment/index.md) - Deploy the Azure infrastructure using Terraform -- [Components Deployment](./components-deployment/index.md) - Deploy AI/Run CodeMie application components using Helm diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/index.md b/docs/admin/deployment/azure/kubernetes/components-deployment/index.md deleted file mode 100644 index 1d31b245..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/index.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -id: components-deployment-overview -sidebar_position: 5 -title: AI/Run CodeMie Components Deployment -sidebar_label: CodeMie Components Deployment -pagination_prev: admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/components-scripted-deployment ---- - -# AI/Run CodeMie Components Deployment - -## Overview - -This section guides you through deploying the AI/Run CodeMie application stack on your AKS cluster. After completing infrastructure deployment, this phase installs all necessary Kubernetes components including: - -- **Core AI/Run CodeMie services** (API, UI, MCP Connect, NATS Auth) -- **Data layer** (Elasticsearch) -- **Security & Identity** (Keycloak, OAuth2 Proxy) -- **Infrastructure services** (Ingress controller, storage) -- **Observability** (Kibana, Fluent Bit) -- **Optional LLM Proxy** (for load balancing AI model requests) - -The deployment uses Helm charts to install and configure all components in the correct order, ensuring proper dependencies and integration. - -:::info Prerequisites -This phase assumes you have completed [Infrastructure Deployment](../infrastructure-deployment/index.md) and have a running AKS cluster with network, storage, and security configured. -::: - -### Application Stack Components - -The AI/Run CodeMie application consists of multiple integrated components organized into functional categories: - -![Application Stack](../../../common/deployment/images/application-stack-diagram.drawio.png) - -#### Core AI/Run CodeMie Services - -Proprietary services that provide the main AI/Run CodeMie functionality: - -| Component | Container Registry | Description | -| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| **CodeMie API** | `europe-west3-docker.pkg.dev/.../codemie:x.y.z` | Backend service handling business logic, data processing, and API operations | -| **CodeMie UI** | `europe-west3-docker.pkg.dev/.../codemie-ui:x.y.z` | Frontend web application providing the user interface | -| **NATS Auth Callout** | `europe-west3-docker.pkg.dev/.../codemie-nats-auth-callout:x.y.z` | Authentication and authorization service for NATS messaging (Plugin Engine component) | -| **MCP Connect** | `europe-west3-docker.pkg.dev/.../codemie-mcp-connect-service:x.y.z` | Bridge enabling CodeMie to communicate with MCP servers | -| **Mermaid Server** | `europe-west3-docker.pkg.dev/.../mermaid-server:x.y.z` | Diagram generation service for visualization in chats | - -:::info Version Information -To find the latest release versions for CodeMie components: - -```bash -# Clone the helm charts repository -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts - -# Check latest versions (requires GCR authentication) -bash get-codemie-latest-release-version.sh -c /path/to/key.json -``` - -**Note**: Docker container versions match Helm chart release versions. -::: - -#### Data Layer - -Database and search components for data persistence: - -| Component | Container Registry | Description | -| ----------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | -| **Elasticsearch** | `docker.elastic.co/elasticsearch/elasticsearch:x.y.z` | Primary data store for AI/Run CodeMie (datasources, projects, conversations, etc.) | -| **Kibana** | `docker.elastic.co/kibana/kibana:x.y.z` | Analytics and visualization interface for Elasticsearch data | - -#### Security & Identity Management - -Authentication and authorization components: - -| Component | Container Registry | Description | -| --------------------- | ----------------------------------------- | --------------------------------------------------------------------------- | -| **Keycloak Operator** | `epamedp/keycloak-operator:x.y.z` | Manages Keycloak deployment and configuration | -| **Keycloak** | `quay.io/keycloak/keycloak:x.y.z` | Identity and access management (IAM) solution providing SSO, authentication | -| **OAuth2 Proxy** | `quay.io/oauth2-proxy/oauth2-proxy:x.y.z` | Authentication middleware integrating with Keycloak for secure access | - -#### Infrastructure Services - -Essential Kubernetes infrastructure components: - -| Component | Container Registry | Description | -| ---------------------------- | ------------------------------------------------ | --------------------------------------------------- | -| **Nginx Ingress Controller** | `registry.k8s.io/ingress-nginx/controller:x.y.z` | Routes external traffic to internal services | -| **Storage Class** | Azure CSI Driver | Provides persistent volumes for stateful components | - -#### Messaging & Integration - -Message broker for Plugin Engine: - -| Component | Container Registry | Description | -| --------- | ------------------ | ----------------------------------------------------------------- | -| **NATS** | `nats:x.y.z` | High-performance messaging system for Plugin Engine communication | - -#### Observability - -Logging and monitoring components: - -| Component | Container Registry | Description | -| -------------- | ----------------------------------------- | ------------------------------------------------------ | -| **Fluent Bit** | `cr.fluentbit.io/fluent/fluent-bit:x.y.z` | Lightweight log collector enabling agent observability | - -#### Optional Components - -Components that can be omitted based on configuration: - -| Component | Container Registry | Description | -| ------------- | ------------------ | ----------------------------------------------------------------------------------------------- | -| **LLM Proxy** | – | Optional proxy for load balancing and high availability of AI model requests and usage insights | - -#### Deployment Dependencies - -Components must be deployed in the following order due to dependencies: - -1. **Infrastructure** → Ingress Controller, Storage Class -2. **Operators** → Keycloak Operator -3. **Data Layer** → Elasticsearch -4. **Security** → Keycloak (with database credentials), OAuth2 Proxy -5. **Messaging** → NATS -6. **Core Services** → CodeMie API, UI, MCP Connect, NATS Auth -7. **Observability** → Fluent Bit, Kibana -8. **Optional** → LLM Proxy (if needed) - -## Prerequisites - -### Cluster Readiness - -Ensure your AKS cluster is ready for component deployment: - -- [x] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/index.md) phase -- [x] **Cluster Access**: kubectl configured and authenticated to AKS cluster -- [x] **Jumpbox Access**: Connected to Jumpbox VM via Azure Bastion (for deployment) - -### Required Components - -The following components will be installed during this phase if not already present: - -- **Nginx Ingress Controller**: Routes external traffic to services -- **Azure Storage Class**: Provides persistent storage for stateful components - -:::info -These components will be installed automatically if not already present in your cluster. Both scripted and manual deployment procedures include the necessary installation steps. -::: - -### Repository and Access {#repository-and-access} - -#### Helm Charts Repository - -Clone the Helm charts repository on your deployment machine (Jumpbox or local workstation): - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -#### Container Registry Credentials - -Before deploying AI/Run CodeMie components, you need to set up authentication for the container registry. - -**Request Access**: Ask the AI/Run CodeMie team to provide: - -- `key.json` file (GCP service account credentials) -- Service account email for pulling images from GCR - -**Create Namespace**: - -```bash -kubectl create namespace codemie -``` - -**Configure Registry Secret**: - -Replace `%%PROJECT_NAME%%` with your project name and create the pull secret: - -```bash -kubectl create secret docker-registry gcp-artifact-registry \ - --docker-server=https://europe-west3-docker.pkg.dev \ - --docker-email=`` \ - --docker-username=_json_key \ - --docker-password="$(cat key.json)" \ - -n codemie -``` - -**Verify Secret**: - -```bash -kubectl get secret gcp-artifact-registry -n codemie -``` - -:::info Pull Secret Usage -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: - -```yaml -imagePullSecrets: - - name: gcp-artifact-registry -``` - -::: - -## Deployment Methods - -Two deployment approaches are available depending on your needs: - -### Scripted Deployment (Recommended) - -Automated deployment using the `helm-charts.sh` wrapper script: - -- **Best for**: Standard deployments, quick setup, production environments -- **Advantages**: Automated dependency ordering, validation checks, consistent configuration - -[→ Scripted Deployment Guide](./scripted-deployment.md) - -### Manual Deployment - -Step-by-step manual installation of each component: - -- **Best for**: Custom configurations, learning the stack, troubleshooting -- **Advantages**: Full control over each component, easier to debug issues - -[→ Manual Deployment Guide](./manual-deployment/index.md) - -:::tip Recommendation -Use **Scripted Deployment** for initial installations. Switch to manual deployment only if you need custom configurations or are troubleshooting specific issues. -::: diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/core-components.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/core-components.md deleted file mode 100644 index 80d5f60d..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/core-components.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: core-components -sidebar_position: 5 -title: Core Components -sidebar_label: Core Components -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/observability ---- - -import CoreComponentsOverview from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-overview.mdx'; -import CoreComponentsMcpConnect from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-mcp-connect.mdx'; -import CoreComponentsMermaid from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-mermaid.mdx'; -import CoreComponentsUi from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-ui.mdx'; -import CoreComponentsApi from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-api.mdx'; -import CoreComponentsAccess from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-access.mdx'; -import CoreComponentsValidation from '../../../../common/deployment/components-deployment/manual-deployment/core/\_core-components-validation.mdx'; - - - - - - - - - - - - - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/data-layer.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/data-layer.md deleted file mode 100644 index 934ee4a2..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/data-layer.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -id: data-layer -sidebar_position: 2 -title: Data Layer -sidebar_label: Data Layer -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/security-and-identity ---- - -import DataLayerOverview from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-overview.mdx'; -import DataLayerElasticsearch from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-elasticsearch.mdx'; -import DataLayerPostgresConfig from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-postgresql-config.mdx'; -import DataLayerPostgresSecret from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-postgresql-secret-common.mdx'; -import DataLayerValidation from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/\_data-layer-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/index.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/index.md deleted file mode 100644 index 5be7b354..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/index.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -id: manual-deployment-overview -sidebar_position: 2 -title: Manual Deployment Overview -description: Overview of manual component installation process -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components ---- - -# Manual CodeMie Components Deployment - -This guide provides step-by-step instructions for manually deploying AI/Run CodeMie application components using Helm charts. Manual deployment gives you granular control over each component installation, allowing for customization and troubleshooting at each stage. - -:::info When to Use Manual Deployment -Use manual deployment when you need: - -- Fine-grained control over individual component configuration -- Custom installation order or selective component deployment -- Troubleshooting capabilities at each deployment stage -- Integration with existing infrastructure components - -If you prefer automated deployment, see [Scripted Deployment](../components-scripted-deployment) instead. -::: - -## Overview - -Manual deployment involves installing components individually in a specific dependency order. Each component is deployed using Helm charts with cloud-specific values files (`values-azure.yaml`). - -### Deployment Scope - -This guide covers all components required for a fully functional AI/Run CodeMie installation: - -- **Infrastructure services** - Storage provisioning and ingress routing -- **Data layer** - Document storage and relational databases -- **Security components** - Identity management and authentication proxies -- **Messaging system** - Inter-service communication infrastructure -- **Core CodeMie services** - Main application components -- **Observability stack** - Logging and monitoring dashboards - -## Prerequisites - -Before starting manual deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/) phase -- [ ] **Cluster Access**: Connected to Jumpbox VM and kubectl configured for AKS -- [ ] **Container Registry**: Completed [Container Registry Access Setup](../#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs -- [ ] **Deployment Outputs File**: Have `deployment_outputs.env` from infrastructure deployment - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](../#repository-and-access) before proceeding. Each component requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine (Jumpbox): - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `az` CLI - For Azure operations - -## Component Installation Order - -Components must be installed in the following order to satisfy dependencies: - -### 1. [Kubernetes Components](./k8s-components) - -**Purpose**: Foundation infrastructure for storage provisioning and external access - -**Components**: - -- Azure Storage Class (for dynamic volume provisioning) -- Nginx Ingress Controller (for HTTP/HTTPS routing) - -**When to Skip**: If your cluster already has these components configured - -### 2. [Data Layer](./data-layer) - -**Purpose**: Persistent storage for application data and user content - -**Components**: - -- Elasticsearch (document storage and search engine) - -**Dependencies**: Requires storage class from Step 1 - -### 3. [Security and Identity](./security-and-identity) - -**Purpose**: User authentication, authorization, and access control - -**Components**: - -- Keycloak Operator (Keycloak lifecycle management) -- Keycloak (identity and access management) -- OAuth2 Proxy (authentication proxy) - -**Dependencies**: Requires PostgreSQL from infrastructure deployment - -### 4. [Plugin Engine](./plugin-engine) - -**Purpose**: Inter-service messaging and plugin communication infrastructure - -**Components**: - -- NATS (message broker) -- NATS Auth Callout (authentication service for NATS) - -**Dependencies**: None (standalone messaging layer) - -### 5. [AI/Run CodeMie Core](./core-components) - -**Purpose**: Main application services providing CodeMie functionality - -**Components**: - -- CodeMie API (backend REST API) -- CodeMie UI (frontend web application) -- MCP Connect (Model Context Protocol connector) -- Mermaid Server (diagram rendering service) - -**Dependencies**: Requires all previous components (data layer, security, messaging) - -### 6. [Observability](./observability.md) - -**Purpose**: System monitoring, logging aggregation, and operational insights - -**Components**: - -- Fluent Bit (log collection and forwarding) -- Kibana (log visualization and analysis) -- Kibana Dashboards (pre-configured monitoring views) - -**Dependencies**: Requires Elasticsearch from Step 2 - -## Getting Started - -### Step 1: Clone Repository - -Clone the Helm charts repository on your Jumpbox VM: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure Domain Name - -Update the DNS zone name in values files. Replace `private.lab.com` with your actual DNS zone name, or leave it if using the default one: - -```bash -# Use your DNS zone name from deployment_outputs.env -CODEMIE_DOMAIN_NAME="airun.example.com" - -# Update all values-azure.yaml files -find . -name "values-azure.yaml" -exec sed -i "s/private.lab.com/$CODEMIE_DOMAIN_NAME/g" {} \; - -# Update domain placeholder in CodeMie API values -sed -i "s/%%DOMAIN%%/$CODEMIE_DOMAIN_NAME/g" codemie-api/values-azure.yaml -``` - -:::tip Domain Configuration -Your DNS zone name was configured during infrastructure deployment. Find it in `deployment_outputs.env` as `CODEMIE_DOMAIN_NAME`. -::: - -### Step 3: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to registry -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 4: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version (e.g., 1.2.3) for component installations -``` - -You'll use this version when installing each component's Helm chart. - -## Installation Process - -Follow the component installation guides in the order listed above. Each guide provides: - -- Detailed installation commands -- Configuration options -- Validation steps -- Troubleshooting guidance - -:::warning Respect Installation Order -Installing components out of order will cause deployment failures. Always follow the numbered sequence to ensure dependencies are satisfied. -::: - -## Common Issues - -### Image Pull Failures - -**Symptom**: Pods stuck in `ImagePullBackOff` or `ErrImagePull` - -**Solution**: - -- Verify `gcp-artifact-registry` secret exists: `kubectl get secret -n codemie` -- Re-authenticate to registry (repeat Step 3) -- Check network connectivity to `europe-west3-docker.pkg.dev` - -## Next Steps - -Begin the installation process by following the guides in order, starting with **[Kubernetes Components](./k8s-components.md)**. - -After completing all component installations, proceed to **[Configuration](../../../../../configuration/index.mdx)** to configure users, AI models, and data sources. diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components.md deleted file mode 100644 index 111a762c..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: k8s-components -sidebar_position: 1 -title: Kubernetes Components -sidebar_label: Kubernetes Components -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/data-layer ---- - -import StorageIngressOverview from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-overview.mdx'; -import StorageIngressNginx from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-nginx.mdx'; -import StorageClassInstallation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-class-installation.mdx'; -import StorageIngressValidation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-validation.mdx'; - - - - - -### Step 4: Configure DNS Record - -Create an A record in your Azure Private DNS zone pointing to the ingress controller's load balancer IP: - -```bash -# Retrieve ingress controller IP -ingressip=$(kubectl get service ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].ip}') - -echo "Ingress IP: ${ingressip}" - -# Create A record (adjust parameters to match your environment) -az network private-dns record-set a add-record \ - -g CodeMieRG \ - -z airun.example.com \ - -n codemie \ - -a ${ingressip} -``` - -**Parameters to Adjust**: - -- `-g CodeMieRG` - Replace with your resource group name -- `-z airun.example.com` - Replace with your Private DNS zone name -- `-n codemie` - Replace with your desired hostname (subdomain) - -:::tip DNS Configuration -These values should match what you configured during infrastructure deployment. Check your `deployment_outputs.env` file for the correct DNS zone and resource group names. -::: - -### Verification - -Confirm the DNS record was created: - -```bash -# List DNS records -az network private-dns record-set a list \ - -g CodeMieRG \ - -z airun.example.com \ - -o table - -# Test DNS resolution (from within VNet or via VPN) -nslookup codemie.airun.example.com -``` - - - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/observability.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/observability.md deleted file mode 100644 index dfdf1181..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/observability.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: observability -sidebar_position: 6 -title: Observability -sidebar_label: Observability -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/accessing-applications ---- - -import ObservabilityOverview from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-overview.mdx'; -import ObservabilityFluentBit from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-fluent-bit.mdx'; -import ObservabilityKibana from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-kibana.mdx'; -import ObservabilityDashboards from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-dashboards.mdx'; -import ObservabilityValidation from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx deleted file mode 100644 index 3178e535..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: plugin-engine -sidebar_position: 4 -title: Plugin Engine -sidebar_label: Plugin Engine -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/core-components ---- - -import PluginEngineContent from '../../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx'; - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/security-and-identity.md b/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/security-and-identity.md deleted file mode 100644 index 541120b7..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/manual-deployment/security-and-identity.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: security-and-identity -sidebar_position: 3 -title: Security and Identity -sidebar_label: Security and Identity -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/manual-deployment/plugin-engine ---- - -import SecurityOverview from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-overview.mdx'; -import SecurityKeycloakOperator from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-operator.mdx'; -import SecurityKeycloakInstall from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-install.mdx'; -import SecurityOauth2Proxy from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-oauth2-proxy.mdx'; -import SecurityValidation from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/azure/kubernetes/components-deployment/scripted-deployment.md b/docs/admin/deployment/azure/kubernetes/components-deployment/scripted-deployment.md deleted file mode 100644 index a38978a4..00000000 --- a/docs/admin/deployment/azure/kubernetes/components-deployment/scripted-deployment.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -id: components-scripted-deployment -sidebar_position: 1 -title: CodeMie Scripted Deployment -sidebar_label: CodeMie Scripted Deployment -pagination_prev: admin/deployment/azure/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/accessing-applications ---- - -# Scripted CodeMie Components Deployment - -This guide walks you through deploying AI/Run CodeMie application components using the automated `helm-charts.sh` deployment script. The script handles the installation of all components in the correct dependency order using Helm charts. - -:::tip Recommended Approach -Scripted deployment is recommended for standard installations as it automates component ordering, validates prerequisites, and ensures consistent configuration across all components. -::: - -## Overview - -The deployment script automates the installation of: - -- **Infrastructure services** (Nginx Ingress, Storage Class) -- **Data layer** (Elasticsearch) -- **Security components** (Keycloak, OAuth2 Proxy) -- **Messaging system** (NATS) -- **Core CodeMie services** (API, UI, MCP Connect) -- **Observability stack** (Fluent Bit, Kibana) - -## Prerequisites - -Before starting deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/index.md) phase -- [ ] **Cluster Access**: Connected to Jumpbox VM and kubectl configured for AKS -- [ ] **Container Registry**: Completed [Container Registry Access Setup](./index.md#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs -- [ ] **Deployment Outputs File**: Have `deployment_outputs.env` from infrastructure deployment - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](./index.md#repository-and-access) before proceeding. The script requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine (Jumpbox): - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `az` CLI - For Azure operations - -## Quick Start - -### Step 1: Clone Repository - -Clone the Helm charts repository on your Jumpbox VM: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure Domain Name - -Update the DNS zone name in values files. Replace `private.lab.com` with your actual DNS zone name, or leave it if using the default one: - -```bash -# Use your DNS zone name from deployment_outputs.env -CODEMIE_DOMAIN_NAME="airun.example.com" - -# Update all values-azure.yaml files -find . -name "values-azure.yaml" -exec sed -i "s/private.lab.com/$CODEMIE_DOMAIN_NAME/g" {} \; - -# Update domain placeholder in CodeMie API values -sed -i "s/private.lab.com/$CODEMIE_DOMAIN_NAME/g" codemie-api/values-azure.yaml -``` - -:::tip Domain Configuration -Your DNS zone name was configured during infrastructure deployment. Find it in `deployment_outputs.env` as `CODEMIE_DOMAIN_NAME`. -::: - -### Step 3: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to registry -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 4: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version (e.g., 1.2.3) for next step -``` - -### Step 5: Configure Optional Components (If Required) - -**Optional Components:** - -- `litellm` - LiteLLM Proxy for unified LLM API interface, multi-model routing, and cost tracking -- `pgadmin` - PostgreSQL administration interface for database inspection and monitoring - -:::warning LiteLLM Configuration Required -If deploying with the `--optional litellm` flag, configuration must be completed **before** running the deployment script. Follow the [LiteLLM Proxy Installation and Configuration Guide](../../../extensions/litellm-proxy/index.md) to set up values files and credentials. -::: - -Skip this step if not deploying optional components. - -### Step 6: Run Deployment Script - -Execute the deployment script with your chosen mode: - -```bash -# Initial installation with all core components -bash helm-charts.sh --cloud azure --version --mode all - -# Upgrade existing deployment to new version (preserves configuration) -bash helm-charts.sh --cloud azure --version --mode update - -# Add LiteLLM to existing installation for AI model management -bash helm-charts.sh --cloud azure --version --mode recommended --optional litellm - -# Maintenance deployment with database administration tools -bash helm-charts.sh --cloud azure --version --mode update --optional pgadmin - -# Enterprise installation with all optional components -bash helm-charts.sh --cloud azure --version --mode all --optional litellm,pgadmin -``` - -Replace `` with the version from Step 4 (e.g., `2.2.3`). - -:::tip Idempotent Script -The deployment script is idempotent, meaning you can safely re-run it multiple times. If the script fails or is interrupted, simply run it again with the same parameters to continue or retry the deployment. -::: - -## Configuration Reference - -### Script Parameters - -The deployment script accepts the following parameters: - -| Parameter | Description | Required | Values | -| --------------- | ------------------------------------ | -------- | -------------------------------------------------------------------- | -| `-h, --help` | Show help message and usage examples | No | N/A | -| `-c, --cloud` | Target cloud provider | Yes | `azure`, `aws`, `gcp` | -| `-v, --version` | CodeMie component version | Yes | Semantic version (e.g., `2.2.3`) | -| `-m, --mode` | Installation mode | Yes | `all`, `recommended`, `update` | -| `--optional` | Optional components to deploy | No | Comma-separated list: `litellm`, `pgadmin` (e.g., `litellm,pgadmin`) | - -### Deployment Modes - -| Mode | Components Installed | Use Case | -| --------------- | ------------------------------------------------------------ | --------------------------------------------- | -| **all** | All components including Nginx Ingress Controller | Fresh AKS cluster without existing ingress | -| **recommended** | All components except Nginx Ingress Controller | Cluster with existing ingress controller | -| **update** | Only CodeMie core components (API, UI, MCP Connect, Mermaid) | Updating existing installation to new version | - -:::tip Choosing Deployment Mode - -- **First-time installation**: Use `all` or `recommended` depending on whether you need Nginx Ingress -- **Version updates**: Use `update` to upgrade only CodeMie components -- **Fresh AKS cluster**: Use `all` mode - ::: - -### Domain Name Configuration - -The following files require domain name configuration (automated by Step 2 in Quick Start): - -| Component | File | Placeholder | Example Value | -| ---------------- | --------------------------------- | ------------------------- | --------------------------- | -| **Kibana** | `kibana/values-azure.yaml` | `*.private.lab.com` | `*.airun.example.com` | -| **Keycloak** | `keycloak-helm/values-azure.yaml` | `*.private.lab.com` | `*.airun.example.com` | -| **OAuth2 Proxy** | `oauth2-proxy/values-azure.yaml` | `*.private.lab.com` | `*.airun.example.com` | -| **CodeMie UI** | `codemie-ui/values-azure.yaml` | `codemie.private.lab.com` | `codemie.airun.example.com` | -| **CodeMie API** | `codemie-api/values-azure.yaml` | `*.private.lab.com` | `*.airun.example.com` | - -## Next Steps - -After successful deployment and validation, proceed to: - -**[Accessing Applications](../accessing-applications.md)** - Learn how to access the deployed AI/Run CodeMie applications and complete the required configuration steps. diff --git a/docs/admin/deployment/azure/kubernetes/images/azure-client-tenant.drawio.png b/docs/admin/deployment/azure/kubernetes/images/azure-client-tenant.drawio.png deleted file mode 100644 index b00fffb7..00000000 Binary files a/docs/admin/deployment/azure/kubernetes/images/azure-client-tenant.drawio.png and /dev/null differ diff --git a/docs/admin/deployment/azure/kubernetes/images/azure-cross-tenants.drawio.png b/docs/admin/deployment/azure/kubernetes/images/azure-cross-tenants.drawio.png deleted file mode 100644 index 2932a6c2..00000000 Binary files a/docs/admin/deployment/azure/kubernetes/images/azure-cross-tenants.drawio.png and /dev/null differ diff --git a/docs/admin/deployment/azure/kubernetes/images/azure-epam-tenant.drawio.png b/docs/admin/deployment/azure/kubernetes/images/azure-epam-tenant.drawio.png deleted file mode 100644 index 7143d722..00000000 Binary files a/docs/admin/deployment/azure/kubernetes/images/azure-epam-tenant.drawio.png and /dev/null differ diff --git a/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/index.md b/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/index.md deleted file mode 100644 index ca7942bd..00000000 --- a/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/index.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -id: infrastructure-deployment-overview -title: Azure Infrastructure Deployment -sidebar_label: Infrastructure Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/azure/kubernetes/architecture -pagination_next: admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment ---- - -# Azure Infrastructure Deployment - -This section guides you through deploying the Azure infrastructure foundation required for AI/Run CodeMie using Terraform automation. - -:::info Existing Infrastructure -If you already have a provisioned AKS cluster with all required Azure services (networking, storage, databases, etc.), you can skip this section and proceed directly to [Components Deployment](../components-deployment/index.md). -::: - -## Overview - -The Terraform deployment is organized into three distinct phases, each with its own set of resources and purpose: - -1. **Terraform State Backend** - Infrastructure for storing Terraform state files securely -2. **Core Platform Infrastructure** - Main Azure resources for running AI/Run CodeMie -3. **AI Model Deployments** - Optional Azure OpenAI services for AI capabilities - -This modular approach allows you to deploy only what you need and maintain clear separation between infrastructure layers. - -## Phase 1: Terraform State Backend - -The state backend is deployed first to provide secure, centralized storage for Terraform state files. - -| Resource | Purpose | -| ---------------------- | ------------------------------------------------------------------------------ | -| **Resource Group** | Dedicated resource group for Terraform state management resources | -| **Storage Account** | Azure Storage Account for storing Terraform state files with versioning | -| **Storage Containers** | Blob containers for state files (`tfstate`) and deployment scripts (`scripts`) | - -:::tip State Backend Purpose -The Terraform state backend enables: - -- **Team Collaboration**: Multiple engineers can work on infrastructure simultaneously -- **State Locking**: Prevents concurrent modifications that could corrupt state -- **Versioning**: Maintains history of infrastructure changes -- **Security**: State files contain sensitive data and require secure storage - ::: - -## Phase 2: Core Platform Infrastructure - -The core platform infrastructure provisions all Azure resources needed to run AI/Run CodeMie. This is the main deployment phase and following Azure resources will be deployed: - -### Compute & Orchestration - -| Resource | Purpose | -| ----------------------------- | ----------------------------------------------------------------------- | -| **AKS Cluster** | Private Kubernetes cluster for running AI/Run CodeMie workloads | -| **Default Node Pool** | Primary node pool with system workloads | -| **Additional Node Pool** | Secondary node pool for application workloads with custom labels/taints | -| **Virtual Machine (Jumpbox)** | Management VM for secure cluster access and administrative tasks | - -### Networking - -| Resource | Purpose | -| --------------------------- | -------------------------------------------------------------------- | -| **Hub Virtual Network** | Central network hub for shared services (Bastion, private endpoints) | -| **AKS Virtual Network** | Isolated network for AKS cluster with multiple dedicated subnets | -| **VNet Peering** | Secure connectivity between Hub and AKS virtual networks | -| **NAT Gateway** | Provides consistent outbound public IP for internet connectivity | -| **Public IP Address** | Static public IP associated with NAT Gateway | -| **DNS Zones** | Name resolution for CodeMie components | -| **Azure Bastion** | Secure RDP/SSH access to VMs without exposing public IP addresses | -| **Network Security Groups** | Firewall rules controlling traffic flow between subnets | - -### Data & Storage - -| Resource | Purpose | -| ----------------------------------------- | ------------------------------------------------------------------------------- | -| **PostgreSQL Flexible Server** | Managed database service for CodeMie application data with private connectivity | -| **PostgreSQL Flexible Server (Keycloak)** | Dedicated database instance for Keycloak (optional) | -| **Storage Account** | Persistent storage for CodeMie application data and artifacts | -| **Container Registry (ACR)** | Private Docker image repository for CodeMie container images | - -:::info Optional: Azure Container Registry -ACR deployment is optional. If you plan to use an external container registry (e.g., Google Container Registry, Docker Hub, or a corporate registry), ACR can be omitted from the deployment. -::: - -### Security & Identity - -| Resource | Purpose | -| ---------------------- | ------------------------------------------------------------------------------------------- | -| **Azure Key Vault** | Centralized secrets management and encryption key storage | -| **Managed Identities** | System-assigned identities for AKS cluster and workload identity federation | -| **Private Endpoints** | Secure, private network access to Azure PaaS services (Storage, ACR, PostgreSQL, Key Vault) | -| **SSH Key Pair** | Generated SSH key pair for secure VM access (stored in Key Vault) | -| **Role Assignments** | RBAC permissions for AKS to pull from ACR and access Key Vault | -| **Workload Identity** | OIDC federation enabling Kubernetes service accounts to authenticate with Azure AD | - -### Observability - -| Resource | Purpose | -| --------------------------- | ------------------------------------------------------------- | -| **Log Analytics Workspace** | Centralized repository for logs, metrics, and monitoring data | - -## Phase 3: AI Model Deployments (Optional) - -The AI model deployment phase provisions Azure OpenAI services. This phase is **optional** and only needed if you want to use Azure-hosted AI models. - -| Resource | Purpose | -| ------------------------- | -------------------------------------------------------------------------------------------- | -| **Azure OpenAI Services** | Azure Cognitive Services for OpenAI model deployments (GPT-5, GPT-4, embeddings models, etc) | -| **Azure AI Application** | Application registration and managed identity for AI service access control | -| **Private DNS Zone** | Private DNS zone for Azure OpenAI (`privatelink.openai.azure.com`) | -| **Private Endpoint** | Private network connectivity to Azure OpenAI services | -| **VNet Link** | Links OpenAI private DNS zone to AKS virtual network | - -:::info Alternative AI Providers -Azure OpenAI Services are optional. AI/Run CodeMie supports other external AI providers: - -- **AWS Bedrock**: Direct integration with api.openai.com -- **GCP VertexAI**: Integration with Anthropic's Claude models -- **Any Other Providers**: Any LLM API endpoint that can be integrated with LLM Proxy - -If using external AI providers or other models, skip Phase 3 entirely. -::: - -## Next Steps - -Proceed to the next step to deploy the infrastructure: - -- [**Scripted Deployment** →](./infrastructure-scripted-deployment) - Recommended automated deployment using Terraform wrapper scripts - -:::note Manual Deployment -For advanced users or custom scenarios, manual Terraform deployment is possible but not documented. The scripted approach handles all prerequisites, variable management, and deployment orchestration automatically. -::: diff --git a/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/scripted-deployment.md b/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/scripted-deployment.md deleted file mode 100644 index 86f01971..00000000 --- a/docs/admin/deployment/azure/kubernetes/infrastructure-deployment/scripted-deployment.md +++ /dev/null @@ -1,546 +0,0 @@ ---- -id: infrastructure-scripted-deployment -title: Infrastructure Scripted Deployment -sidebar_label: Infrastructure Scripted Deployment -sidebar_position: 1 -pagination_prev: admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/azure/kubernetes/components-deployment/components-deployment-overview ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Scripted Infrastructure Deployment - -This guide walks you through deploying Azure infrastructure for AI/Run CodeMie using the automated `azure-terraform.sh` deployment script. The script handles all three deployment phases automatically: Terraform state backend, core platform infrastructure, and optional AI model deployments. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Prerequisites - -Before starting the deployment, ensure you have completed all requirements from the [Prerequisites](../prerequisites.md) page: - -### Verification Checklist - -- [ ] **Azure Access**: Contributor role with Entra ID App Registration access -- [ ] **Tools Installed**: Terraform 1.13.5, Azure CLI, kubectl, Helm, gcloud CLI, Docker -- [ ] **Azure Authentication**: Logged in via `az login` and subscription set -- [ ] **Repository Access**: Have access to `codemie-terraform-azure` repository -- [ ] **Network Planning**: Prepared list of allowed networks -- [ ] **Domain & Certificate**: DNS zone and TLS certificate ready (for public access) or will use private DNS - -:::warning Authentication Required -You must be authenticated to Azure CLI before running the deployment script. Run `az login` and verify with `az account show`. -::: - -## Deployment Phases - -The script automatically deploys infrastructure in three sequential phases: - -| Phase | Description | Required | -| ------------------------------------ | ---------------------------------------------------------------- | -------- | -| **Phase 1: State Backend** | Creates Azure Storage Account for Terraform state files | Yes | -| **Phase 2: Platform Infrastructure** | Deploys AKS, networking, storage, databases, security components | Yes | -| **Phase 3: AI Models** | Provisions Azure OpenAI services (if enabled) | Optional | - -:::info Skipping AI Models -Set `DEPLOY_AI_MODELS="false"` in configuration to skip Phase 3 if using external AI providers. -::: - -## Phase 1, 2 & 3: Deploy Infrastructure - -This phase deploys all infrastructure components using the automated deployment script: Terraform state backend (Phase 1), core platform infrastructure (Phase 2), and optionally AI model deployments (Phase 3). - -### Step 1: Clone Repository - -Clone the Terraform deployment repository: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-terraform-azure.git -cd codemie-terraform-azure -``` - -### Step 2: Configure Deployment - -Edit the `deployment.conf` file to provide your Azure-specific configuration: - -```bash -# Required: Azure Account Information -AZURE_TENANT_ID="00000000-0000-0000-0000-000000000000" -AZURE_SUBSCRIPTION_ID="11111111-1111-1111-1111-111111111111" - -# Required: Basic Configuration -TF_VAR_customer="airun" # Customer identifier (lowercase letters only) -TF_VAR_location="West Europe" # Azure region for deployment -TF_VAR_resource_group_name="" # Leave empty to auto-generate - -# Required: AKS Admin Access -TF_VAR_admin_group_object_ids='["3a459347-0000-1111-2222-e73413cfa80a"]' - -# Optional: Resource Tagging -TF_VAR_tags='{"createdWith":"Terraform","environment":"production"}' - -# Optional: AI Models Deployment -DEPLOY_AI_MODELS="true" # Set to "false" to skip Azure OpenAI deployment - -# Optional: Dedicated PostgreSQL Flexible Server Instances Configuration -# Set enabled=true to provision a dedicated instance for the service. -# Omitted fields fall back to defaults (sku_name, db_name, username, etc.). -TF_VAR_keycloak_db_config='{"enabled":true}' -TF_VAR_langfuse_db_config='{"enabled":false}' -TF_VAR_litellm_db_config='{"enabled":false}' -``` - -:::tip Required vs Optional Variables -The configuration file contains many variables. Most have sensible defaults. Focus on the **Required** variables first. See the [Configuration Reference](#configuration-reference) below for advanced options. -::: - -:::info Complete Variable List -For all available configuration options, refer to the `variables.tf` files: - -- **Platform variables**: [platform/variables.tf](https://gitbud.epam.com/epm-cdme/codemie-terraform-azure/-/blob/main/platform/variables.tf) -- **AI models variables**: [ai-models/variables.tf](https://gitbud.epam.com/epm-cdme/codemie-terraform-azure/-/blob/main/ai-models/variables.tf) - ::: - -### Step 3: Run Deployment Script - -Execute the automated deployment script: - -```bash -bash ./azure-terraform.sh -``` - -The script will automatically execute the following operations: - -1. **Validate Environment**: Check for required tools and Azure authentication -2. **Verify Configuration**: Validate `deployment.conf` parameters -3. **Deploy State Backend**: Create Azure Storage Account for Terraform state files -4. **Deploy Platform Infrastructure**: Provision core platform infrastructure (AKS, networking, storage, databases) -5. **Deploy AI Models**: Provision Azure OpenAI services (if `DEPLOY_AI_MODELS="true"`) -6. **Generate Outputs**: Create `deployment_outputs.env` with infrastructure details that will be required during next phases - -:::warning Deployment in Progress -Do not interrupt the script during execution. Monitor the output for any errors. -::: - -## Configuration Reference - -### AI Models Deployment Control - -Control whether Azure OpenAI services are deployed using the `DEPLOY_AI_MODELS` parameter: - -| Setting | Behavior | Use Case | -| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `"true"` (default) | Deploys Azure OpenAI services, private endpoints, and AI application | Using Azure-hosted AI models | -| `"false"` | Skips AI models deployment entirely | Using external AI providers (OpenAI API, Anthropic, AWS Bedrock, GCP Vertex AI) | - -:::tip When to Skip AI Models -Skip Azure OpenAI deployment (`DEPLOY_AI_MODELS="false"`) if you: - -- Already have Azure OpenAI services deployed -- Plan to use other non GPT family models (Claude, Gemini, etc) -- Want to deploy AI models separately later -- Are deploying infrastructure in stages - ::: - -### AI Models Network Access - -Configure network access controls for Azure OpenAI services. All deployments include private endpoint connectivity; public access is optional and can be restricted. - - - - **Most Secure Configuration** - Access only through Azure Private Endpoints - - ```bash - TF_VAR_ai_models_public_network_access_enabled="false" - ``` - - **Result**: - - ✅ Access via Azure Private Links from your VNet - - ❌ Public internet access completely disabled - - ✅ Recommended for production environments - - - - - **Hybrid Configuration** - Private access + specific public IPs allowed - - ```bash - TF_VAR_ai_models_public_network_access_enabled="true" - TF_VAR_ai_models_network_acls='{ - "default_action": "Deny", - "ip_rules": ["x.x.x.x/24", "x.x.x.x"] - }' - ``` - - **Result**: - - ✅ Access via Azure Private Links from your VNet - - ✅ Access from specified IP addresses/ranges only - - ❌ All other public access denied - - 💡 Useful for accessing from corporate networks or specific locations - - - - - **Least Secure Configuration** - Open public access - - ```bash - TF_VAR_ai_models_public_network_access_enabled="true" - TF_VAR_ai_models_network_acls='{ - "default_action": "Allow", - "ip_rules": [] - }' - ``` - - **Result**: - - ✅ Access via Azure Private Links from your VNet - - ⚠️ Access from any public IP address - - ❌ Not recommended for production - - - - -#### Private Endpoint Configuration - -Private endpoints are automatically deployed for secure VNet connectivity. Customize the network location if needed: - -```bash -# Default values (can be customized) -TF_VAR_ai_network_name="AksVNet" # VNet for private endpoint -TF_VAR_ai_endpoint_subnet_name="UserSubnet" # Subnet for private endpoint -``` - -:::info Private Endpoints -Private endpoints are created regardless of public access settings, ensuring secure connectivity from your Azure infrastructure. -::: - -### Azure OpenAI Model Configuration - -When `DEPLOY_AI_MODELS="true"`, configure which AI models to deploy and their regional distribution using `TF_VAR_cognitive_regions`. - -#### Configuration Parameters - -**Region-Level Settings**: - -- `region_name`: Azure region (e.g., "eastus", "westeurope", "japaneast") -- `count`: Number of Azure OpenAI instances to create in this region -- `custom_domain_name`: Enable custom domain names (true/false) - -**Model-Level Settings**: - -- `format`: Always `"OpenAI"` -- `name`: Deployment name used in API calls -- `model_name`: Azure OpenAI model identifier (e.g., "gpt-4o", "gpt-4", "text-embedding-ada-002") -- `version`: Model version (e.g., "2024-11-20") -- `capacity`: Total capacity units (automatically distributed across instances) -- `type`: `"Standard"` (regional) or `"GlobalStandard"` (global with higher availability) - -:::tip Capacity Distribution -The `capacity` value is the **total** capacity for that model. It's automatically divided by `count`: - -- `capacity: 348` with `count: 3` → Each instance gets 116 capacity units -- `capacity: 200` with `count: 2` → Each instance gets 100 capacity units - ::: - -#### Configuration Examples - -
-Single Region Configuration Example - -```bash -TF_VAR_cognitive_regions='{ - "eastus": { - "count": 2, - "custom_domain_name": true, - "available_models": [ - { - "format": "OpenAI", - "name": "gpt-4.1-2025-04-14", - "model_name": "gpt-4.1", - "version": "2025-04-14", - "capacity": 200, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "gpt-5-2025-08-07", - "model_name": "gpt-5", - "version": "2025-08-07", - "capacity": 500, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "text-embedding-ada-002", - "model_name": "text-embedding-ada-002", - "version": "2", - "capacity": 200, - "type": "GlobalStandard" - } - ] - } -}' -``` - -
- -
-Multiple Regions Configuration Example - -```bash -TF_VAR_cognitive_regions='{ - "eastus": { - "count": 2, - "custom_domain_name": true, - "available_models": [ - { - "format": "OpenAI", - "name": "gpt-4.1-2025-04-14", - "model_name": "gpt-4.1", - "version": "2025-04-14", - "capacity": 200, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "gpt-5-2025-08-07", - "model_name": "gpt-5", - "version": "2025-08-07", - "capacity": 500, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "text-embedding-ada-002", - "model_name": "text-embedding-ada-002", - "version": "2", - "capacity": 200, - "type": "GlobalStandard" - } - ] - }, - "eastus2": { - "count": 2, - "custom_domain_name": true, - "available_models": [ - { - "format": "OpenAI", - "name": "gpt-4.1-2025-04-14", - "model_name": "gpt-4.1", - "version": "2025-04-14", - "capacity": 200, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "gpt-5-2025-08-07", - "model_name": "gpt-5", - "version": "2025-08-07", - "capacity": 500, - "type": "GlobalStandard" - }, - { - "format": "OpenAI", - "name": "text-embedding-ada-002", - "model_name": "text-embedding-ada-002", - "version": "2", - "capacity": 200, - "type": "GlobalStandard" - } - ] - } -}' -``` - -
- -## Deployment Outputs - -Upon successful deployment, the script generates a `deployment_outputs.env` file containing essential infrastructure details needed for the next deployment phase: - -```bash -# Platform Infrastructure Outputs -AZURE_CLIENT_ID="00000000-0000-0000-0000-000000000000" -AZURE_KEY_VAULT_URL="https://codemie-kv-abc123.vault.azure.net" -AZURE_KEY_NAME="codemie-key" -AZURE_STORAGE_ACCOUNT_NAME="codemiestorage123" -AZURE_RESOURCE_GROUP="airun-codemie" -BASTION_ADMIN_USERNAME="azadmin" -CODEMIE_DOMAIN_NAME="airun.example.com" - -# AI Model Outputs (if DEPLOY_AI_MODELS="true") -AZURE_AI_TENANT_ID="00000000-0000-0000-0000-000000000000" -AZURE_AI_CLIENT_ID="00000000-0000-0000-0000-000000000000" -AZURE_AI_CLIENT_SECRET="some-secret" - -# CodeMie PostgreSQL -CODEMIE_POSTGRES_DATABASE_HOST="codemie-psql-abc123.postgres.database.azure.com" -CODEMIE_POSTGRES_DATABASE_PORT="5432" -CODEMIE_POSTGRES_DATABASE_NAME="codemie" -CODEMIE_POSTGRES_DATABASE_USER="pgadmin" -CODEMIE_POSTGRES_DATABASE_PASSWORD="password" - -# Keycloak PostgreSQL (present when keycloak_db_config.enabled=true) -KEYCLOAK_POSTGRES_DATABASE_HOST="keycloak-psql-abc123.postgres.database.azure.com" -KEYCLOAK_POSTGRES_DATABASE_PORT=5432 -KEYCLOAK_POSTGRES_DATABASE_NAME="keycloak" -KEYCLOAK_POSTGRES_DATABASE_USER="keycloak_admin" -KEYCLOAK_POSTGRES_DATABASE_PASSWORD="password" - -# LiteLLM PostgreSQL (present when litellm_db_config.enabled=true) -LITELLM_POSTGRES_DATABASE_HOST="litellm-psql-abc123.postgres.database.azure.com" -LITELLM_POSTGRES_DATABASE_PORT=5432 -LITELLM_POSTGRES_DATABASE_NAME="litellm" -LITELLM_POSTGRES_DATABASE_USER="litellm_admin" -LITELLM_POSTGRES_DATABASE_PASSWORD="password" - -# Langfuse PostgreSQL (present when langfuse_db_config.enabled=true) -LANGFUSE_POSTGRES_DATABASE_HOST="langfuse-psql-abc123.postgres.database.azure.com" -LANGFUSE_POSTGRES_DATABASE_PORT=5432 -LANGFUSE_POSTGRES_DATABASE_NAME="langfuse" -LANGFUSE_POSTGRES_DATABASE_USER="langfuse_admin" -LANGFUSE_POSTGRES_DATABASE_PASSWORD="password" -``` - -:::tip Save These Outputs -The `deployment_outputs.env` file contains sensitive information. Store it securely and reference it during the Components Deployment phase. -::: - -## Post-Deployment Validation - -After deployment completes, verify that all infrastructure was created successfully: - -### Step 1: Verify Azure Resources - -Check that all expected resources were created in the Azure Portal: - -```bash -# List all resources in the resource group -az resource list --resource-group --output table - -# Verify AKS cluster status -az aks show --resource-group --name CodeMieAks --query "provisioningState" - -# Verify PostgreSQL server status -az postgres flexible-server show --resource-group --name -``` - -### Step 2: Check Deployment Logs - -Review the deployment logs in the `logs/` directory for any warnings or errors: - -```bash -ls -la logs/ -# Review logs -cat logs/codemie_azure_deployment_YYYY-MM-DD-HHMMSS.log -``` - -### Step 3: Verify Key Resources - -Ensure critical resources are accessible: - -| Resource | Verification | -| ------------------- | ------------------------------------------------------ | -| **AKS Cluster** | Status should be "Succeeded", private endpoint created | -| **Key Vault** | Accessible, contains SSH keys and secrets | -| **Storage Account** | Created with private endpoint | -| **PostgreSQL** | Running, accessible via private endpoint | -| **Azure Bastion** | Deployed and associated with Hub VNet | -| **NAT Gateway** | Public IP assigned and associated with AKS subnets | - -## Access Jumpbox VM via Bastion - -The Jumpbox VM provides secure management access to your AKS cluster. Access it through Azure Bastion: - -### Step 1: Connect via SSH (Initial Setup) - -1. Navigate to your resource group in the Azure Portal (default: `CodeMieRG`) -2. Select the Jumpbox VM (`CodeMieVM`) -3. Click **Connect** → **Connect via Bastion** -4. Configure connection settings: - - **Authentication type**: `SSH Private Key from Azure Key Vault` - - **Username**: `azadmin` - - **Subscription**: Your Azure subscription - - **Azure Key Vault**: `CodeMieAskVault` (or your Key Vault name) - - **Azure Key Vault Secret**: `codemie-vm-private-key` -5. Click **Connect** - -:::tip Browser Shortcuts -Use `Ctrl+Shift+C` and `Ctrl+Shift+V` to copy/paste in the browser-based Bastion session. -::: - -### Step 2: Set User Password - -After initial SSH connection, set a password for the `azadmin` user (required for RDP access): - -```bash -sudo passwd azadmin -``` - -### Step 3: Connect via RDP (Management Access) - -1. Disconnect from SSH session -2. Return to VM → **Connect** → **Connect via Bastion** -3. Configure connection settings: - - **Protocol**: `RDP` - - **Username**: `azadmin` - - **Authentication type**: `Password` - - **Password**: Password set in Step 2 -4. Click **Connect** - -## Configure Jumpbox for AKS Access - -Once connected to the Jumpbox via RDP, configure access to the AKS cluster: - -### Step 1: Authenticate to Azure - -```bash -az login -``` - -### Step 2: Set Active Subscription - -```bash -az account set --subscription -``` - -### Step 3: Configure kubectl Access - -Retrieve AKS credentials and configure kubectl: - -```bash -# Replace with your resource group -# Default: CodeMieRG (unless overridden in deployment.conf) -az aks get-credentials \ - --resource-group \ - --name CodeMieAks \ - --overwrite-existing - -# Convert kubeconfig for Azure CLI authentication -kubelogin convert-kubeconfig -l azurecli -``` - -### Step 4: Set Default Resource Group - -```bash -# Set default resource group for Azure CLI commands -az configure --defaults group= -``` - -### Step 5: Verify Cluster Access - -```bash -# Test cluster connectivity -kubectl get nodes - -# View cluster information -kubectl cluster-info -``` - -## Next Steps - -After successful infrastructure deployment and validation, proceed to: - -**[Components Deployment](../components-deployment/index.md)** - Deploy AI/Run CodeMie application components to your AKS cluster diff --git a/docs/admin/deployment/azure/kubernetes/overview.md b/docs/admin/deployment/azure/kubernetes/overview.md deleted file mode 100644 index f4e216b0..00000000 --- a/docs/admin/deployment/azure/kubernetes/overview.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: overview -title: AI/Run Deployment Guide on Azure -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/azure/kubernetes/prerequisites ---- - -import OverviewContent from '../../common/deployment/overview/\_overview-content.mdx'; - - diff --git a/docs/admin/deployment/azure/kubernetes/prerequisites.md b/docs/admin/deployment/azure/kubernetes/prerequisites.md deleted file mode 100644 index be97e6b7..00000000 --- a/docs/admin/deployment/azure/kubernetes/prerequisites.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/azure/kubernetes/overview -pagination_next: admin/deployment/azure/kubernetes/architecture ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import ClusterRequirements from '../../common/deployment/prerequisites/\_cluster-requirements.mdx'; -import NetworkRequirements from '../../common/deployment/prerequisites/\_network-requirements.mdx'; -import DeploymentMachineTools from '../../common/deployment/prerequisites/\_deployment-machine-tools.mdx'; -import NextSteps from '../../common/deployment/prerequisites/\_next-steps.mdx'; - -# Prerequisites - -This page outlines the requirements and prerequisites necessary for deploying AI/Run CodeMie on Microsoft Azure. Please ensure all requirements are met before proceeding with the installation. - -## Azure Account Requirements - -### 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.) - :::info Complete Resource List - For a detailed list of all Azure resources that will be provisioned, refer to the [Infrastructure Deployment](./infrastructure-deployment/index.md) 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 - -### DNS and Certificate Requirements - -DNS and TLS certificate requirements depend on your access model: - - - - 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 - - - - -## Network Requirements - - - - - - - -**Cloud-Specific Tools:** - -| Tool | Version | Purpose | -| -------------------------------------------------------------------------- | ------- | ------------------------- | -| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | latest | Azure resource management | -| [kubelogin](https://azure.github.io/kubelogin/install.html) | latest | AKS authentication plugin | - -### Required Repository Access - -You will need access to the following repositories to complete the deployment: - -- **Terraform Modules:** [codemie-terraform-azure](https://gitbud.epam.com/epm-cdme/codemie-terraform-azure) -- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) - -:::info Air-Gapped Environments -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. -::: - - diff --git a/docs/admin/deployment/azure/on-vm/architecture.mdx b/docs/admin/deployment/azure/on-vm/architecture.mdx deleted file mode 100644 index d3ebc48c..00000000 --- a/docs/admin/deployment/azure/on-vm/architecture.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -id: architecture -title: On VM Deployment Architecture (Azure) -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/azure/on-vm/prerequisites -pagination_next: admin/deployment/azure/on-vm/deployment/deployment ---- - -# On VM Deployment Architecture (Azure) - -This page describes the infrastructure and application architecture of CodeMie On VM on Azure. - -## Infrastructure Overview - -![Azure On VM Infrastructure Architecture](./images/architecture-diagram.drawio.png) - -CodeMie On VM runs on a single Azure VM with supporting Azure services. Terraform provisions the following resources: - -| Resource | Purpose | -| ------------------------------ | -------------------------------------------------------------------- | -| **Azure VM (Standard_E4s_v5)** | Single VM running Docker Compose (4 vCPU, 32 GB RAM) | -| **Virtual Network / Subnet** | Isolated network for the VM | -| **Network Security Group** | Controls inbound/outbound traffic to the VM | -| **Azure Storage Account** | Persistent storage for user data (repos, files) | -| **Azure Key Vault** | Encryption key management for storage data | -| **Private DNS Zone** | Custom domain resolution (when `TF_VAR_platform_domain_name` is set) | -| **Azure Bastion** | Secure SSH access to the VM without exposing a public IP | - -### Network Modes - -| Mode | Configuration | Access | -| ------------------------ | ----------------------------------------------- | ----------------------------------------- | -| **Private IP** (default) | `TF_VAR_platform_domain_name` empty | VM private IP, access via VPN or Bastion | -| **Domain** | `TF_VAR_platform_domain_name="private.lab.com"` | Creates private DNS zone, access via name | - -## Application Architecture - -All CodeMie services run as Docker containers on the Azure VM, orchestrated by Docker Compose. - -![Docker Compose Services](../../common/deployment/images/docker-compose-diagram.drawio.png) - -### Services by Profile - -**Shared services** (both profiles): - -| Service | Image | Purpose | -| ------------- | --------------------------- | ------------------------------------------------- | -| postgres | pgvector/pgvector:pg17 | Primary database for application data | -| elasticsearch | elasticsearch:8.x | Document storage and search for Data Sources | -| kibana | kibana:8.x | Log visualization and analytics for Elasticsearch | -| mcp-connect | codemie-mcp-connect-service | Connector for MCP servers | -| nginx | nginx:1.31-alpine | Reverse proxy, TLS termination | - -**OSS profile:** - -| Service | Purpose | -| -------------- | --------------------------------------------- | -| codemie-oss | API server with built-in local authentication | -| codemie-ui-oss | Web frontend | - -**Enterprise profile:** - -| Service | Purpose | -| ----------------- | ---------------------------------------------- | -| codemie | API server | -| codemie-ui | Web frontend | -| keycloak | Identity provider (SSO, OIDC) | -| oauth2-proxy | Authentication proxy in front of nginx | -| litellm | LLM proxy for model routing and key management | -| nats | Messaging for plugin engine | -| nats-auth-callout | NATS authentication service | -| mermaid-server | Diagram rendering | - -## Resource Requirements - -### Minimum Azure VM - -| Resource | Minimum | Recommended | -| -------- | ------- | ------------------- | -| vCPU | 4 | 4 (Standard_E4s_v5) | -| RAM | 16 GB | 32 GB | -| Disk | 50 GB | 100 GB | - -## Next Steps - -- [Deployment](../deployment/) — Deploy CodeMie On VM with Terraform diff --git a/docs/admin/deployment/azure/on-vm/deployment/byo.md b/docs/admin/deployment/azure/on-vm/deployment/byo.md deleted file mode 100644 index 629694d1..00000000 --- a/docs/admin/deployment/azure/on-vm/deployment/byo.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -id: byo -title: BYO Azure VM Deployment -sidebar_label: BYO Azure VM -sidebar_position: 7 -pagination_prev: admin/deployment/azure/on-vm/deployment/manual-deployment -pagination_next: null ---- - -# BYO Azure VM Deployment - -Deploy CodeMie on an **existing Azure VM** that is not managed by this project's Terraform. This mode skips all infrastructure provisioning and directly provisions the application stack. - -## When to Use - -- You already have an Azure VM (provisioned manually or via another Terraform stack) -- You want to avoid creating additional Azure resources via Terraform -- Your organization manages infrastructure separately from application deployment - -## VM Requirements - -Your existing Azure VM must meet these requirements: - -| Requirement | Details | -| -------------------- | ------------------------------------------------------------------------ | -| **OS** | Ubuntu 24.04 | -| **VM size** | Minimum Standard_D4s_v5 (4 vCPU, 16 GB RAM); recommended Standard_E4s_v5 | -| **Disk** | Minimum 50 GB; recommended 100 GB | -| **Internet access** | Outbound HTTPS for pulling Docker images | -| **Managed Identity** | Permissions for Storage Account and Key Vault access (if used) | - -## Configuration - -Edit `deployment.conf` with BYO-specific variables: - -```bash -CLOUD_PROVIDER="azure" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# ── BYO Azure VM ───────────────────────────────────────────────────── -BYO_VM_HOST="" # Private IP of the VM -BYO_VM_USER="azadmin" # SSH user -BYO_VM_SSH_KEY="" # Absolute path to SSH private key -BYO_VM_SSH_MODE="bastion" # bastion | direct -BYO_AZURE_BASTION_NAME="" # Azure Bastion host name -BYO_AZURE_RESOURCE_GROUP="" # Resource group containing Bastion and VM -BYO_AZURE_VM_RESOURCE_ID="" # Full VM resource ID (/subscriptions/...) -BYO_AZURE_STORAGE_ACCOUNT_NAME="" # Storage Account for user data -BYO_AZURE_KEY_VAULT_URL="" # https://.vault.azure.net/ -BYO_AZURE_KEY_NAME="codemie-key" # Key name in Key Vault -BYO_PLATFORM_DOMAIN_NAME="" # Optional: overrides CODEMIE_HOST -``` - -### SSH Modes - -| Mode | When to Use | Requirements | -| --------- | ------------------------------------------------------------ | ------------------------------------------ | -| `bastion` | VM in private subnet, access via Azure Bastion (recommended) | Azure Bastion deployed, VM resource ID | -| `direct` | VM has a reachable IP and port 22 is open | SSH private key, network access to port 22 | - -### BYO_VM_HOST - -`BYO_VM_HOST` sets the application URL (`CODEMIE_HOST`): - -| Scenario | `BYO_VM_HOST` value | Result | -| ------------------------------ | ------------------- | -------------------------------------- | -| VM private IP (access via VPN) | `10.0.1.5` | `CODEMIE_HOST=https://10.0.1.5` | -| Custom domain | Any IP (overridden) | Set `BYO_PLATFORM_DOMAIN_NAME` instead | - -### Encryption - -| Setting | Behavior | -| ------------------------------- | -------------------------------------------------------------- | -| `BYO_AZURE_KEY_VAULT_URL` empty | `ENCRYPTION_TYPE=plain` — data stored without envelope key | -| `BYO_AZURE_KEY_VAULT_URL` set | `ENCRYPTION_TYPE=azure` — storage data protected via Key Vault | - -## Deployment - -### Step 1: Place the GCP Registry Key - -This is a GCP service account credentials file used to pull CodeMie container images from Google Artifact Registry. - -:::info -For open-source deployments with self-built images, this key is optional. -::: - -```bash -cp /path/to/key.json ./key.json -``` - -### Step 2: Run BYO Deployment - -```bash -./deploy.sh --byo -``` - -The script executes: - -| Phase | Description | -| ------------------------ | ------------------------------------------------- | -| Loading config | Validates BYO-specific variables | -| Checking prerequisites | Verifies tools (Terraform not required) | -| Verifying Azure session | Only for bastion mode | -| Setting up BYO variables | Maps config to internal variables | -| Generating .env | Creates secrets, renders environment file | -| Setting up SSH | Configures SSH transport (bastion or direct) | -| Provisioning VM | Installs Docker, syncs files, starts services | -| Writing outputs | Saves deployment info to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -### Step 3: Verify - -```bash -curl -k https:///v1/healthcheck -``` - -## Re-deploying - -Run `./deploy.sh --byo` again. Secrets from `deployment_outputs.env` are preserved automatically. - -## Troubleshooting - -### Bastion connection refused - -- Verify Azure Bastion is deployed and associated with the VM's virtual network -- Confirm `BYO_AZURE_VM_RESOURCE_ID` is the full resource ID (`/subscriptions/...`) -- Check the `BYO_AZURE_RESOURCE_GROUP` contains both the Bastion and the VM - -### Docker login fails - -The `key.json` must be a valid GCP service account with access to `europe-west3-docker.pkg.dev`. Verify locally: - -```bash -cat key.json | docker login -u _json_key --password-stdin https://europe-west3-docker.pkg.dev -``` - -### Containers unhealthy - -SSH into the VM and check logs: - -```bash -cd /opt/codemie/compose -docker compose --profile enterprise logs --tail=50 -docker compose --profile enterprise ps -``` diff --git a/docs/admin/deployment/azure/on-vm/deployment/index.md b/docs/admin/deployment/azure/on-vm/deployment/index.md deleted file mode 100644 index 8968f351..00000000 --- a/docs/admin/deployment/azure/on-vm/deployment/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: deployment -title: Deployment -sidebar_label: Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/azure/on-vm/architecture -pagination_next: admin/deployment/azure/on-vm/deployment/scripted-deployment ---- - -# Deployment - -This section covers deploying CodeMie On VM infrastructure and application stack on Azure. - -## Deployment Methods - -| Method | Description | When to Use | -| ------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| [**Scripted Deployment**](./scripted-deployment) | Fully automated — single `./deploy.sh` handles Terraform and provisioning | Recommended for most users | -| [**Manual Deployment**](./manual-deployment) | Step-by-step Terraform commands, then BYO mode for application provisioning | When you need full control or are integrating with existing workflows | - -:::tip Recommendation -Use **Scripted Deployment** unless you have specific requirements for manual Terraform control. The script handles prerequisite checks, configuration validation, and proper phase sequencing automatically. -::: - -## Deployment Phases - -Both methods execute the same logical phases: - -| Phase | Description | -| ---------------------------- | ------------------------------------------------------------------------- | -| **Terraform State Backend** | Creates Azure Storage container for Terraform state (one-time) | -| **Platform Infrastructure** | Provisions VM, Storage Account, Key Vault, Private DNS Zone, NSG | -| **AI Models** (optional) | Provisions Azure OpenAI cognitive accounts when `DEPLOY_AI_MODELS="true"` | -| **Application Provisioning** | Installs Docker, syncs compose files, generates secrets, starts services | - -## Next Steps - -- [Scripted Deployment](./scripted-deployment) — Automated deployment with `./deploy.sh` -- [Manual Deployment](./manual-deployment) — Manual Terraform + BYO application provisioning diff --git a/docs/admin/deployment/azure/on-vm/deployment/manual-deployment.md b/docs/admin/deployment/azure/on-vm/deployment/manual-deployment.md deleted file mode 100644 index ce1c9512..00000000 --- a/docs/admin/deployment/azure/on-vm/deployment/manual-deployment.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -id: manual-deployment -title: Manual Deployment -sidebar_label: Manual Deployment -sidebar_position: 6 -pagination_prev: admin/deployment/azure/on-vm/deployment/scripted-deployment -pagination_next: admin/deployment/azure/on-vm/deployment/byo ---- - -# Manual Deployment - -This guide provides step-by-step instructions for manually deploying CodeMie On VM infrastructure using Terraform on Azure, followed by application provisioning via BYO mode (`./deploy.sh --byo`). - -:::info When to Use Manual Deployment -Manual deployment is suitable when you need fine-grained control over each Terraform phase, want to customize infrastructure configurations, or are integrating with existing infrastructure management workflows. -::: - -## Prerequisites - -Ensure you have completed all requirements from the [Prerequisites](../../prerequisites) page: - -- [ ] **Azure Access**: Active subscription with Contributor role -- [ ] **Tools Installed**: Terraform 1.15.x, Azure CLI, jq, openssl, envsubst -- [ ] **Azure Authentication**: `az login` completed, subscription set -- [ ] **Repository Access**: Cloned [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) -- [ ] **GCP Registry**: `key.json` file available - -## Deployment Phases - -| Phase | Description | Directory | -| ------------------------------------ | --------------------------------------------------- | --------------------------------- | -| **Phase 1: State Backend** | Creates Azure Storage container for Terraform state | `terraform/azure/remote-backend/` | -| **Phase 2: Platform Infrastructure** | Provisions VM, Storage Account, Key Vault, DNS, NSG | `terraform/azure/platform/` | -| **Phase 3: AI Models** (optional) | Provisions Azure OpenAI cognitive accounts | `terraform/azure/ai-models/` | -| **Phase 4: Application** | Deploys Docker Compose stack via BYO mode | `./` (repo root) | - ---- - -## Phase 1: Terraform State Backend - -:::info One-Time Setup -This phase only needs to run once per Azure subscription. -::: - -1. Navigate to the remote backend directory: - -```bash -cd terraform/azure/remote-backend/ -``` - -2. Initialize Terraform: - -```bash -terraform init -``` - -3. Create `terraform.tfvars`: - -```hcl -location = "westeurope" -platform_name = "codemie" -``` - -4. Plan and apply: - -```bash -terraform plan -out=tfplan -terraform apply tfplan -``` - -5. Note the outputs: - -```bash -terraform output storage_account_name -terraform output container_name -# Example: codemiestate / tfstate -``` - ---- - -## Phase 2: Platform Infrastructure - -1. Navigate to the platform directory: - -```bash -cd terraform/azure/platform/ -``` - -2. Create `backend.tfvars`: - -```hcl -resource_group_name = "codemie-terraform-state" -storage_account_name = "codemiestate" -container_name = "tfstate" -key = "codemie/terraform.tfstate" -``` - -3. Initialize Terraform with backend configuration: - -```bash -terraform init -backend-config=backend.tfvars -``` - -4. Create `terraform.tfvars`: - -```hcl -location = "westeurope" -platform_name = "codemie" -vm_size = "Standard_E4s_v5" -vm_os_disk_size = 100 -platform_domain_name = "" # Leave empty for private IP access -``` - -5. Plan and apply: - -```bash -terraform plan -out=tfplan -terraform apply tfplan -``` - -6. Note the outputs: - -```bash -terraform output vm_private_ip -terraform output storage_account_name -terraform output key_vault_url -terraform output bastion_name -terraform output resource_group_name -terraform output vm_resource_id -``` - ---- - -## Phase 3: AI Models (Optional) - -Skip this phase if `DEPLOY_AI_MODELS="false"` or you have an existing Azure OpenAI endpoint. - -1. Navigate to the AI models directory: - -```bash -cd terraform/azure/ai-models/ -``` - -2. Create `backend.tfvars` (reuse same state backend): - -```hcl -resource_group_name = "codemie-terraform-state" -storage_account_name = "codemiestate" -container_name = "tfstate" -key = "codemie/ai-models.tfstate" -``` - -3. Initialize and apply: - -```bash -terraform init -backend-config=backend.tfvars -terraform plan -out=tfplan -terraform apply tfplan -``` - -4. Note the AI outputs: - -```bash -terraform output azure_openai_endpoint -terraform output azure_client_id -terraform output azure_client_secret -``` - ---- - -## Phase 4: Application Provisioning (BYO Mode) - -Now that infrastructure is provisioned, use BYO mode to deploy the application stack. - -1. Navigate to the project root. - -2. Place the GCP registry key: - -```bash -cp /path/to/key.json ./key.json -``` - -3. Configure `deployment.conf` with BYO settings from Phase 2 outputs: - -```bash -CLOUD_PROVIDER="azure" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# BYO Azure VM settings -BYO_VM_HOST="" # From terraform output -BYO_VM_USER="azadmin" -BYO_VM_SSH_KEY="/path/to/codemie-key.pem" -BYO_VM_SSH_MODE="bastion" # bastion | direct -BYO_AZURE_BASTION_NAME="" # From terraform output -BYO_AZURE_RESOURCE_GROUP="" # From terraform output -BYO_AZURE_VM_RESOURCE_ID="" # From terraform output -BYO_AZURE_STORAGE_ACCOUNT_NAME="" # From terraform output -BYO_AZURE_KEY_VAULT_URL="" # From terraform output -BYO_AZURE_KEY_NAME="codemie-key" -BYO_PLATFORM_DOMAIN_NAME="" # Optional: overrides CODEMIE_HOST - -# If DEPLOY_AI_MODELS=false, supply existing endpoint: -# AZURE_OPENAI_ENDPOINT="" -# AZURE_CLIENT_ID="" -# AZURE_CLIENT_SECRET="" -``` - -4. Run BYO deployment: - -```bash -./deploy.sh --byo -``` - -5. Verify: - -```bash -curl -k https:///v1/healthcheck -``` - -## Re-deploying - -To update CodeMie: - -1. Edit `deployment.conf` (change `CODEMIE_VERSION`) -2. Run `./deploy.sh --byo` again — secrets are preserved automatically - -## Next Steps - -- [BYO VM](../byo) — Deploy on a completely external Azure VM not managed by this Terraform diff --git a/docs/admin/deployment/azure/on-vm/deployment/scripted-deployment.md b/docs/admin/deployment/azure/on-vm/deployment/scripted-deployment.md deleted file mode 100644 index a2b45f9c..00000000 --- a/docs/admin/deployment/azure/on-vm/deployment/scripted-deployment.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -id: scripted-deployment -title: Scripted Deployment -sidebar_label: Scripted Deployment -sidebar_position: 5 -pagination_prev: admin/deployment/azure/on-vm/deployment/deployment -pagination_next: admin/deployment/azure/on-vm/deployment/manual-deployment ---- - -# Scripted Deployment - -This guide walks through deploying CodeMie On VM on Azure using the automated `deploy.sh` script. The script handles all phases: Terraform state backend, infrastructure provisioning, optional Azure OpenAI setup, and application deployment. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Step 1: Clone the Repository - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git -cd codemie-on-vm -``` - -## Step 2: Place the GCP Registry Key - -Copy your `key.json` file to the repository root: - -```bash -cp /path/to/key.json ./key.json -``` - -## Step 3: Create Deployment Configuration - -```bash -cp deployment.conf.azure.example deployment.conf -``` - -Edit `deployment.conf`: - -```bash -CLOUD_PROVIDER="azure" - -# ── Azure ──────────────────────────────────────────────────────────── -AZURE_SUBSCRIPTION_ID="" # Your Azure subscription ID -AZURE_TENANT_ID="" # Your Azure tenant ID - -# ── Terraform ──────────────────────────────────────────────────────── -TF_VAR_location="westeurope" -TF_VAR_platform_name="codemie" -TF_VAR_vm_size="Standard_E4s_v5" # 4 vCPU, 32 GB RAM -TF_VAR_vm_os_disk_size=100 # OS disk size in GB -TF_VAR_platform_domain_name="" # Private DNS zone (e.g. private.lab.com) - -# ── CodeMie ────────────────────────────────────────────────────────── -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# ── Azure OpenAI / AI models ───────────────────────────────────────── -DEPLOY_AI_MODELS="true" # true = provision Azure OpenAI via Terraform - # false = supply existing endpoint below - -# Required only when DEPLOY_AI_MODELS=false: -# AZURE_OPENAI_ENDPOINT="" -# AZURE_CLIENT_ID="" -# AZURE_CLIENT_SECRET="" -``` - -## Step 4: Authenticate with Azure - -```bash -az login -az account set --subscription "" - -# Verify: -az account show -``` - -## Step 5: Run the Deployment - -```bash -./deploy.sh -``` - -The script executes the following phases: - -| Phase | Description | -| ------------------------------ | ---------------------------------------------------------------------- | -| Loading config | Validates `deployment.conf` variables | -| Checking prerequisites | Verifies required tools are installed | -| Verifying Azure credentials | Confirms valid `az` session and subscription | -| Initializing Terraform backend | Creates Azure Storage container for Terraform state | -| Running platform Terraform | Plans and applies VM, Storage Account, Key Vault, DNS, NSG | -| Running AI models Terraform | Plans and applies Azure OpenAI accounts (if `DEPLOY_AI_MODELS="true"`) | -| Reading Terraform outputs | Fetches VM private IP, Storage Account name, Key Vault URL | -| Generating .env | Creates secrets and renders Docker Compose environment | -| Provisioning VM | Installs Docker, syncs files, starts services via Azure Bastion | -| Writing outputs | Saves credentials to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -:::warning Interactive Prompts -The script will pause for approval at each Terraform plan stage. Review the plans carefully before typing `y`. -::: - -## Step 6: Verify Deployment - -After the script completes: - -```bash -curl -k https:///v1/healthcheck -``` - -Expected response: `{"status":"ok"}` - -## Deployment Outputs - -The script creates `deployment_outputs.env` with: - -- **CODEMIE_URL** — Application URL -- **VM_PRIVATE_IP** — VM private IP address -- **SSH_COMMAND** — Full SSH command for access via Bastion -- **Credentials** — Keycloak admin or superadmin password -- **Internal secrets** — Preserved across re-runs - -:::danger Sensitive File -`deployment_outputs.env` contains passwords and secrets. Do not commit it to version control. -::: - -## SSH Access - -Connect to the VM via Azure Bastion: - -```bash -# The SSH command is provided in the deployment summary and outputs file -az network bastion ssh \ - --name "" \ - --resource-group "" \ - --target-resource-id "" \ - --auth-type "ssh-key" \ - --username "azadmin" \ - --ssh-key "~/.ssh/codemie-key.pem" -``` - -## Re-deploying / Updating - -To update CodeMie version or configuration: - -1. Edit `deployment.conf` (e.g., change `CODEMIE_VERSION`) -2. Run `./deploy.sh` again - -The script detects the existing `deployment_outputs.env` and preserves all secrets. - -## Next Steps - -- [Manual Deployment](../manual-deployment) — Alternative method with full Terraform control diff --git a/docs/admin/deployment/azure/on-vm/overview.md b/docs/admin/deployment/azure/on-vm/overview.md deleted file mode 100644 index 69eaaacf..00000000 --- a/docs/admin/deployment/azure/on-vm/overview.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -id: overview -title: AI/Run CodeMie On VM Deployment Guide (Azure) -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/azure/on-vm/prerequisites ---- - -# AI/Run CodeMie On VM Deployment (Azure) - -CodeMie On VM deploys the full AI/Run CodeMie platform on a **single Azure VM** using Docker Compose. It provides the same core functionality as the full Azure (AKS) deployment but with minimal infrastructure overhead. - -## When to Use - -CodeMie On VM is designed for: - -- **Proof of Concept (PoC)** — quickly validate CodeMie capabilities in your environment -- **Demo environments** — showcase CodeMie to stakeholders without complex infrastructure - -:::warning Not for Production -For production workloads with high availability, scaling, and redundancy, use the full [Azure AKS Deployment Guide](../../kubernetes/overview). -::: - -## Deployment Profiles - -CodeMie On VM supports two profiles: - -| Profile | Authentication | LLM Proxy | Plugin Tool | -| -------------- | ----------------------- | --------- | ----------- | -| **OSS** | Local (built-in) | Internal | No | -| **Enterprise** | Keycloak + OAuth2 Proxy | LiteLLM | Yes | - -## Deployment Modes - -| Mode | Command | Infrastructure | -| ------------ | ------------------- | ----------------------------------------------------- | -| **Standard** | `./deploy.sh` | Terraform creates VM, Storage Account, Key Vault, DNS | -| **BYO VM** | `./deploy.sh --byo` | Use your existing Azure VM | - -## Repository - -All deployment code is hosted at: [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) - -``` -codemie-on-vm/ -├── compose/ # Docker Compose files and config -├── deploy.sh # Deployment script -├── destroy.sh # Destroy script -├── deployment.conf.azure.example # Azure configuration template -└── terraform/ - └── azure/ - ├── remote-backend/ # Azure Storage Terraform state backend - ├── platform/ # VM, Storage Account, Key Vault, DNS infrastructure - └── ai-models/ # Azure OpenAI cognitive accounts (optional) -``` - -## Next Steps - -Proceed to [Prerequisites](../prerequisites) to verify your environment is ready for deployment. diff --git a/docs/admin/deployment/azure/on-vm/prerequisites.md b/docs/admin/deployment/azure/on-vm/prerequisites.md deleted file mode 100644 index 089dfc42..00000000 --- a/docs/admin/deployment/azure/on-vm/prerequisites.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/azure/on-vm/overview -pagination_next: admin/deployment/azure/on-vm/architecture ---- - -# Prerequisites - -This page outlines the requirements for deploying AI/Run CodeMie On VM on Azure. Ensure all prerequisites are met before proceeding. - -## Azure Account Requirements - -### Required Access and Permissions - -- **Active Azure Subscription** with sufficient quota for the required resources -- **Contributor role** (or equivalent) on the subscription to create VMs, Storage Accounts, Key Vaults, and DNS zones -- **AZURE_SUBSCRIPTION_ID** and **AZURE_TENANT_ID** — available in the Azure Portal under **Azure Active Directory → Overview** - -### Quota Requirements - -Verify sufficient quota for: - -| Resource | Count | -| ---------------- | ----- | -| Standard_E4s_v5 | 1 | -| Azure Key Vault | 1 | -| Storage Account | 1 | -| Private DNS Zone | 1 | - -## Deployment Machine Tools - -The following tools must be installed on the machine where you run `./deploy.sh`: - -| Tool | Version | Purpose | -| -------------------------------------------------------------------------- | ------- | ----------------------------------- | -| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | -| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | latest | Azure authentication and management | -| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | -| openssl | latest | Secret generation | -| envsubst | latest | Template rendering | - -**Enterprise profile only:** - -| Tool | Version | Purpose | -| ------------------------------------- | ------- | ------------------- | -| [nsc](https://github.com/nats-io/nsc) | latest | NATS key generation | - -### Verify Installation - -```bash -terraform version # Should show 1.15.x -az version # Azure CLI -jq --version -openssl version -envsubst --version -``` - -## GCP Container Registry Access - -CodeMie container images are hosted on `europe-west3-docker.pkg.dev`. You need a **GCP service account key file** (`key.json`) with read access to the registry. - -:::info Obtaining key.json -Contact your CodeMie administrator or EPAM delivery team to obtain the `key.json` file for registry access. -::: - -## Azure Authentication - -Authenticate before running the deployment: - -```bash -az login -az account set --subscription "" - -# Verify active subscription -az account show -``` - -## Repository Access - -Clone the deployment repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git -cd codemie-on-vm -``` - -The repository structure: - -| Directory | Purpose | -| --------------------------------- | ---------------------------------------------- | -| `compose/` | Docker Compose files and service configuration | -| `deploy.sh` | Deployment script | -| `destroy.sh` | Destroy script | -| `terraform/azure/remote-backend/` | Azure Storage Terraform state backend | -| `terraform/azure/platform/` | VM, Storage Account, Key Vault, DNS, NSG | -| `terraform/azure/ai-models/` | Azure OpenAI cognitive accounts (optional) | - -## Next Steps - -After verifying all prerequisites, review the [Architecture](../architecture) to understand what will be deployed. diff --git a/docs/admin/deployment/common/deployment/accessing-codemie/_accessing-codemie-applications.mdx b/docs/admin/deployment/common/deployment/accessing-codemie/_accessing-codemie-applications.mdx index e5d37904..fc0d0f16 100644 --- a/docs/admin/deployment/common/deployment/accessing-codemie/_accessing-codemie-applications.mdx +++ b/docs/admin/deployment/common/deployment/accessing-codemie/_accessing-codemie-applications.mdx @@ -26,21 +26,21 @@ After accessing the applications, complete the configuration to make AI/Run Code #### User Configuration -Configure initial users and authentication in Keycloak. See [Access Control](../../../../configuration/access-control/index.md) for details. +Configure initial users and authentication in Keycloak. See Access Control for details. #### AI LLM Models Integration -Set up AI model providers to enable AI capabilities. See [AI Models Integration](../../../../configuration/codemie/ai-models-integration/index.md) for details. +Set up AI model providers to enable AI capabilities. See AI Models Integration for details. ### Install Extensions Enhance AI/Run CodeMie with optional extensions: -- **[LiteLLM Proxy](../../../extensions/litellm-proxy/index.md)** - Load balancing and high availability for LLM requests -- **[Assistants Evaluation](../../../extensions/assistants-evaluation/index.md)** - LLM observability, tracing, and performance analytics -- **[AI Code Explorer](../../../extensions/ai-code-explorer/index.md)** - Intelligent code analysis and exploration platform +- **LiteLLM Proxy** - Load balancing and high availability for LLM requests +- **Assistants Evaluation** - LLM observability, tracing, and performance analytics +- **AI Code Explorer** - Intelligent code analysis and exploration platform -See [Extensions Overview](../../../extensions/index.mdx) for detailed setup guides. +See Extensions Overview for detailed setup guides. ### Optional Configuration @@ -53,4 +53,4 @@ Additional configuration options include: - Third-party integrations - Backup and recovery setup -See the complete [Configuration Guide](../../../../configuration/index.mdx) for all available options. +See the complete Configuration Guide for all available options. diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx index 757904c6..e63f90c5 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx @@ -7,5 +7,5 @@ https://codemie.airun.example.com ``` :::warning User Creation Required -You'll be redirected to Keycloak for authentication, but no users exist yet. You must complete the [Configuration](../../../../../../configuration/index.mdx) guide to create users before you can log in to the application. +You'll be redirected to Keycloak for authentication, but no users exist yet. You must complete the Configuration guide to create users before you can log in to the application. ::: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-api.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-api.mdx index 3a28d147..e0d8afbc 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-api.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-api.mdx @@ -1,10 +1,8 @@ import CodeBlock from '@theme/CodeBlock'; -## CodeMie API Installation - CodeMie API is the backend service that handles all business logic, AI orchestration, and data processing. -### Step 1: Configure API Values +**Step 1: Configure API Values** The domain configuration should already be set from the Getting Started section. Verify the values in codemie-api/{props.valuesFileName} are correct: @@ -15,7 +13,7 @@ The domain configuration should already be set from the Getting Started section. If you followed the Getting Started steps, these replacements should already be done. ::: -### Step 2: Copy Elasticsearch Credentials +**Step 2: Copy Elasticsearch Credentials** CodeMie API needs access to Elasticsearch. Copy the credentials to the codemie namespace: @@ -25,7 +23,7 @@ kubectl get secret elasticsearch-master-credentials -n elastic -o yaml | \ kubectl apply -n codemie -f - ``` -### Step 3: Install CodeMie API Helm Chart +**Step 3: Install CodeMie API Helm Chart** Deploy CodeMie API: @@ -39,7 +37,7 @@ Deploy CodeMie API: --timeout 600s`} -### Step 4: Verify CodeMie API Deployment +**Step 4: Verify CodeMie API Deployment** Check that CodeMie API is running: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx index a1bb55a7..84dd7820 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx @@ -1,14 +1,12 @@ import CodeBlock from '@theme/CodeBlock'; -## CodeMie UI Installation - CodeMie UI provides the web-based user interface for interacting with AI assistants and managing workflows. -### Step 1: Configure UI Values +**Step 1: Configure UI Values** The domain configuration should already be set from the Getting Started section. Verify the values in codemie-ui/{props.valuesFileName} are correct. -### Step 2: Install CodeMie UI Helm Chart +**Step 2: Install CodeMie UI Helm Chart** Deploy CodeMie UI: @@ -22,7 +20,7 @@ Deploy CodeMie UI: --timeout 180s`} -### Step 3: Verify CodeMie UI Deployment +**Step 3: Verify CodeMie UI Deployment** Check that CodeMie UI is running: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx index a5225e43..0f2c5f17 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx @@ -1,8 +1,6 @@ import CodeBlock from '@theme/CodeBlock'; import Admonition from '@theme/Admonition'; -## PostgreSQL Configuration - CodeMie uses {props.postgresServiceName} (created during infrastructure deployment) rather than running PostgreSQL in the cluster. This section configures the connection credentials. {props.cloudProvider === 'AWS' && ( @@ -16,7 +14,7 @@ On AWS, codemie-api authenticates to RDS using IAM database authenticati )} -### Retrieve Database Credentials +**Retrieve Database Credentials** Get your {props.postgresServiceName} connection details from the infrastructure deployment outputs: @@ -29,5 +27,5 @@ Get your {props.postgresServiceName} connection details from the infrastructure :::tip Finding Credentials -Your `deployment_outputs.env` file was created during [Infrastructure Deployment](../../../infrastructure-deployment). It should be located in your Terraform working directory. +Your `deployment_outputs.env` file was created during Infrastructure Deployment. It should be located in your Terraform working directory. ::: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-iam-setup.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-iam-setup.mdx index d4e7d47e..3ce5b83a 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-iam-setup.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-iam-setup.mdx @@ -1,7 +1,7 @@ import CodeBlock from '@theme/CodeBlock'; import Admonition from '@theme/Admonition'; -### Create the IAM Authentication Database User +**Create the IAM Authentication Database User** Before creating the connection secret, bootstrap the dedicated `codemie_admin` role that codemie-api will use for IAM authentication. This connects as the master user `dbadmin` (password auth) to create the new role, grant it `rds_iam`, and grant it full access to the `codemie` database: @@ -26,7 +26,7 @@ Replace every CODEMIE_* placeholder with the actual value from codemie_admin was already created (e.g. by a prior deployment run), CREATE USER fails with role "codemie_admin" already exists. This is safe to ignore — re-run the command without the CREATE USER ...; clause to (re-)apply the grants only. -### Upgrading an Existing Deployment to IAM Authentication +#### Upgrading an Existing Deployment to IAM Authentication
Migration steps for existing deployments diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-aws.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-aws.mdx index 0de7f343..29264e07 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-aws.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-aws.mdx @@ -6,7 +6,7 @@ export const createSecretCmd = `kubectl create secret generic codemie-postgresql export const verifySecretCmd = `# Check secret exists\nkubectl get secret codemie-postgresql -n codemie\n\n# Verify secret contents (decode to check values)\nkubectl get secret codemie-postgresql -n codemie -o jsonpath='{.data.PG_HOST}' | base64 -d\nkubectl get secret codemie-postgresql -n codemie -o jsonpath='{.data.PG_USER}' | base64 -d`; -### Create PostgreSQL Connection Secret +**Create PostgreSQL Connection Secret** Create a secret with the cloud-managed PostgreSQL credentials: @@ -32,7 +32,7 @@ Replace all `` placeholders with actual values from {secretYaml} -### Verify PostgreSQL Secret +**Verify PostgreSQL Secret** Confirm the secret was created correctly: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx index a5271db8..d5b4f15a 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx @@ -6,7 +6,7 @@ export const createSecretCmd = `kubectl create secret generic codemie-postgresql export const verifySecretCmd = `# Check secret exists\nkubectl get secret codemie-postgresql -n codemie\n\n# Verify secret contents (decode to check values)\nkubectl get secret codemie-postgresql -n codemie -o jsonpath='{.data.PG_HOST}' | base64 -d\nkubectl get secret codemie-postgresql -n codemie -o jsonpath='{.data.PG_USER}' | base64 -d`; -### Create PostgreSQL Connection Secret +**Create PostgreSQL Connection Secret** Create a secret with the cloud-managed PostgreSQL credentials: @@ -31,7 +31,7 @@ Replace all `` placeholders with actual values from {secretYaml} -### Verify PostgreSQL Secret +**Verify PostgreSQL Secret** Confirm the secret was created correctly: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-class-installation.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-class-installation.mdx index 9db54388..e86ee873 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-class-installation.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-class-installation.mdx @@ -2,7 +2,7 @@ import CodeBlock from '@theme/CodeBlock'; ## Storage Class Installation -The {props.storageClassName} enables Kubernetes to dynamically provision {props.storageType} for stateful workloads like databases. +The Storage Class enables Kubernetes to dynamically provision block storage (Amazon EBS, Azure Disk, or GCP Persistent Disk, depending on your cloud provider) for stateful workloads like databases. ### Step 1: Check Existing Storage Classes @@ -13,15 +13,15 @@ kubectl get storageclass ``` :::info Skip if Already Exists -If your cluster already has appropriate storage classes (typically {props.existingStorageExamples}), you can skip this installation. +If your cluster already has appropriate storage classes, you can skip this installation. Clusters commonly ship with a default storage class such as `gp2`/`gp3` (AWS), `managed-premium` (Azure), or `standard-rwo` (GCP). ::: ### Step 2: Install Custom Storage Class -If no suitable storage class exists, install the {props.cloudProvider} storage class: +If no suitable storage class exists, install the storage class manifest for your cloud provider (`aws`, `azure`, or `gcp`): -{`kubectl apply -f storage-class/${props.storageClassFileName}`} +{`kubectl apply -f storage-class/storageclass-.yaml`} ### Step 3: Verify Storage Class diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-nginx.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-nginx.mdx index 0b926632..36add60f 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-nginx.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-nginx.mdx @@ -18,12 +18,12 @@ Check if the namespace already exists before creating: `kubectl get namespace in ### Step 2: Install Nginx Ingress Helm Chart -Deploy the Nginx Ingress Controller using Helm: +Deploy the Nginx Ingress Controller using Helm, selecting the values file for your cloud provider (`aws`, `azure`, or `gcp`): {`helm upgrade --install ingress-nginx ingress-nginx/. \\ -n ingress-nginx \\ - --values ingress-nginx/${props.valuesFileName} \\ + --values ingress-nginx/values-.yaml \\ --wait \\ --timeout 900s \\ --dependency-update`} diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-overview.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-overview.mdx index b6a62f8e..56eeff04 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-overview.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-overview.mdx @@ -5,8 +5,8 @@ This guide covers the installation of foundational infrastructure components tha This step installs two critical infrastructure components: - **Nginx Ingress Controller** - Routes external HTTP/HTTPS traffic to services within the cluster -- **{props.storageClassName}** - Enables dynamic provisioning of persistent volumes for stateful workloads +- **Storage Class** - Enables dynamic provisioning of persistent volumes for stateful workloads :::info When to Skip -If your {props.clusterName} cluster already has an ingress controller and storage class configured, you can skip the relevant sections and proceed to [Data Layer](../data-layer). +If your Kubernetes cluster already has an ingress controller and storage class configured, you can skip the relevant sections and proceed to [Data Layer](../data-layer). ::: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-fluent-bit.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-fluent-bit.mdx index 37e2a6a5..32c4772b 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-fluent-bit.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-fluent-bit.mdx @@ -14,7 +14,7 @@ Collects structured usage metrics from CodeMie application pods, including: These metrics are required for Kibana dashboards and usage analytics. By default, they are stored in the `codemie_metrics_logs` index. When quarterly metrics index rotation is enabled, configure the metrics output to use the `codemie_metrics_logs_write` alias -instead. See the [Metrics Index Rotation](../../../../../../configuration/observability/metrics-index-rotation) +instead. See the Metrics Index Rotation guide for the migration and configuration steps. **2. Infrastructure Logs (Optional)** diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-kibana.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-kibana.mdx index 1cb260f0..c3ec7115 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-kibana.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-kibana.mdx @@ -75,7 +75,7 @@ kubectl logs -n elastic deployment/kibana --tail=50 Kibana can be accessed at: -{props.kibanaUrl} +{props.kibanaUrl} **Login Credentials**: diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-validation.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-validation.mdx index 3189cf9d..5cfb3441 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-validation.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/observability/_observability-validation.mdx @@ -26,4 +26,4 @@ All checks should return successful results. Congratulations! You have successfully completed the manual deployment of all AI/Run CodeMie components. -Proceed to **[Accessing Applications](../../../accessing-applications)** - Learn how to access the deployed AI/Run CodeMie applications and complete the required configuration steps. +Proceed to **Accessing Applications** - Learn how to access the deployed AI/Run CodeMie applications and complete the required configuration steps. diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx deleted file mode 100644 index 71e2fbdd..00000000 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx +++ /dev/null @@ -1,389 +0,0 @@ -import CodeBlock from '@theme/CodeBlock'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Overview - -This guide covers the installation of the messaging infrastructure that enables connecting MCP servers and plugins running externally to AI/Run CodeMie infrastructure. - -The plugin engine consists of two components: - -- **NATS** - High-performance message broker enabling pub/sub and request/reply messaging patterns -- **NATS Auth Callout** - Authentication service that validates NATS connections and enforces authorization policies - -## NATS Installation - -:::warning Deprecated - -NATS is currently deprecated as part of the NATS retirement direction. - -::: - -NATS provides the messaging backbone for CodeMie's plugin system, enabling real-time communication between the core application and distributed plugins. - -### Step 1: Create NATS Secrets - -Create the `codemie-nats-secrets` secret containing authentication credentials and encryption keys. Follow these steps to generate and encode the necessary values: - -#### 1. NATS_URL - -Internal service URL for NATS communication: - - -{`NATS_URL="${props.natsUrl}"`} - - -#### 2. Callout User Credentials - -Credentials for the NATS Auth Callout service: - -```bash -# Username -CALLOUT_USERNAME="callout" - -# Generate secure password -CALLOUT_PASSWORD=$(pwgen -s -1 25) - -# Generate bcrypt hash (requires nats CLI installed) -CALLOUT_BCRYPTED_PASSWORD=$(nats server passwd -p "$CALLOUT_PASSWORD") -``` - -#### 3. CodeMie User Credentials - -Credentials for CodeMie application to connect to NATS: - -```bash -# Username -CODEMIE_USERNAME="codemie" - -# Generate secure password -CODEMIE_PASSWORD=$(pwgen -s -1 25) - -# Generate bcrypt hash (requires nats CLI installed) -CODEMIE_BCRYPTED_PASSWORD=$(nats server passwd -p "$CODEMIE_PASSWORD") -``` - -#### 4. NATS Keys - -Generate NATS keys for JWT authentication and encrypted connections: - -```bash -nsc generate nkey --account -# Output: -# ISSUER_NSEED: SAXXXXX... (private seed, keep secure) -# ISSUER_NKEY: AXXXXX... (public key) - -nsc generate nkey --curve -# Output: -# ISSUER_XSEED: XSXXXXX... (private seed, keep secure) -# ISSUER_XKEY: XXXXXX... (public key) -``` - -Reference: [NATS Auth Callout Example](https://natsbyexample.com/examples/auth/callout/cli) - -#### 5. Create the Secret - -Create the secret using `kubectl` with all generated values: - -```bash -kubectl -n codemie create secret generic codemie-nats-secrets \ - --from-literal=NATS_URL="$NATS_URL" \ - --from-literal=CALLOUT_USERNAME="$CALLOUT_USERNAME" \ - --from-literal=CALLOUT_PASSWORD="$CALLOUT_PASSWORD" \ - --from-literal=CALLOUT_BCRYPTED_PASSWORD="$CALLOUT_BCRYPTED_PASSWORD" \ - --from-literal=CODEMIE_USERNAME="$CODEMIE_USERNAME" \ - --from-literal=CODEMIE_PASSWORD="$CODEMIE_PASSWORD" \ - --from-literal=CODEMIE_BCRYPTED_PASSWORD="$CODEMIE_BCRYPTED_PASSWORD" \ - --from-literal=ISSUER_NKEY="" \ - --from-literal=ISSUER_NSEED="" \ - --from-literal=ISSUER_XKEY="" \ - --from-literal=ISSUER_XSEED="" \ - --type=Opaque -``` - -:::warning Save Credentials -Save all generated passwords and keys securely. You'll need them for troubleshooting and future operations. -::: - -**Alternative: YAML Secret Template** - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: codemie-nats-secrets - namespace: codemie -type: Opaque -data: - NATS_URL: - CALLOUT_USERNAME: - CALLOUT_PASSWORD: - CALLOUT_BCRYPTED_PASSWORD: - CODEMIE_USERNAME: - CODEMIE_PASSWORD: - CODEMIE_BCRYPTED_PASSWORD: - ISSUER_NKEY: - ISSUER_NSEED: - ISSUER_XKEY: - ISSUER_XSEED: -``` - -To encode values: `echo -n 'your-value-here' | base64` - -### Step 2: Add NATS Helm Repository - -Add the official NATS Helm repository: - -```bash -# Add repository -helm repo add nats https://nats-io.github.io/k8s/helm/charts/ - -# Update repository index -helm repo update nats -``` - -### Step 3: Install NATS Helm Chart - -Deploy NATS using the official Helm chart: - - -{`helm upgrade --install codemie-nats nats/nats \\ - --version 1.2.6 \\ - --namespace codemie \\ - --values ./codemie-nats/${props.valuesFileName} \\ - --wait \\ - --timeout 900s`} - - -### Step 4: Verify NATS Deployment - -Check that NATS is running: - -```bash -# Check pod status -kubectl get pods -n codemie | grep nats - -# Check NATS service -kubectl get service -n codemie codemie-nats - -# Check NATS logs -kubectl logs -n codemie statefulset/codemie-nats --tail=50 -``` - -Expected output: - -- NATS pods should be in `Running` state -- Service should show cluster IP assigned -- Logs should indicate successful server startup - -## NATS Auth Callout Installation - -NATS Auth Callout validates authentication and authorization for NATS connections to CodeMie. - -### Step 1: Authenticate to Container Registry - -Before deploying NATS Auth Callout, authenticate to the AI/Run CodeMie container registry: - -```bash -export GOOGLE_APPLICATION_CREDENTIALS=key.json -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -:::tip Registry Authentication -This step is required for all AI/Run CodeMie proprietary components: `codemie-ui`, `codemie-api`, `codemie-nats-auth-callout`, `codemie-mcp-connect-service`, and `mermaid-server`. - -If you already authenticated during the Getting Started steps, you can skip this. -::: - -### Step 2: Install NATS Auth Callout Helm Chart - -Deploy the NATS Auth Callout service: - - -{`helm upgrade --install codemie-nats-auth-callout \\ - oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie-nats-auth-callout \\ - --version "x.y.z" \\ - --namespace codemie \\ - -f ./codemie-nats-auth-callout/${props.valuesFileName} \\ - --wait \\ - --timeout 600s`} - - -### Step 3: Verify NATS Auth Callout Deployment - -Check that the auth callout service is running: - -```bash -# Check pod status -kubectl get pods -n codemie | grep nats-auth-callout - -# Check deployment -kubectl get deployment -n codemie codemie-nats-auth-callout - -# Check logs -kubectl logs -n codemie deployment/codemie-nats-auth-callout --tail=50 -``` - -Expected output: - -- Pod should be in `Running` state -- Deployment should show ready replicas -- Logs should indicate successful connection to NATS - -## TLS Configuration - -Choose the appropriate scenario based on your deployment architecture: - - - - -### Load Balancer TLS Termination - -TLS is handled by Network Load Balancer with TLS certificate on the load balancer itself. - -**NATS Helm Values** (codemie-nats/{props.valuesFileName}): - -```yaml -params: - conf: | - tls: {} - allow_non_tls: true -``` - -**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): - -```yaml -extraEnv: - - name: NATS_SKIP_TLS_VERIFY - value: "false" -``` - -**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): - -```yaml -env: - - name: SKIPTLSVERIFY - value: "0" -``` - -**Plugin URL Format**: - -``` -tls://: -``` - -:::info -The `tls://` prefix forces plugins to perform TLS handshake first, which is essential because the load balancer expects TLS negotiation before any NATS protocol communication. -::: - - - - -### No TLS (Local envs only) - -Plain text communication without encryption. - -**NATS Helm Values** (codemie-nats/{props.valuesFileName}): - -```yaml -params: - conf: | - tls: {} - allow_non_tls: true -``` - -**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): - -```yaml -extraEnv: - - name: NATS_SKIP_TLS_VERIFY - value: "false" -``` - -**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): - -```yaml -env: - - name: SKIPTLSVERIFY - value: "0" -``` - -**Plugin URL Format**: - -``` -nats://: -``` - - - - -### NATS-Managed TLS - -NATS server handles TLS with its own certificate. - -**NATS Helm Values** (codemie-nats/{props.valuesFileName}): - -```yaml -nats: - tls: - enabled: true - secretName: codemie-nats-tls - merge: - timeout: 10 -``` - -**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): - -```yaml -extraEnv: - - name: NATS_SKIP_TLS_VERIFY - value: "true" -``` - -**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): - -```yaml -env: - - name: SKIPTLSVERIFY - value: "1" -``` - -**Plugin URL Format**: - -``` -nats://: -``` - - - - -## Post-Installation Validation - -After completing plugin engine installation, verify the following: - -```bash -# NATS is running -kubectl get pods -n codemie | grep codemie-nats - -# NATS Auth Callout is running -kubectl get pods -n codemie | grep nats-auth-callout - -# NATS service is available -kubectl get service -n codemie codemie-nats - -# NATS secrets exist -kubectl get secret codemie-nats-secrets -n codemie - -# Test NATS connectivity (optional) -``` - - -{`kubectl run -it --rm nats-test --image=natsio/nats-box:latest --restart=Never -n codemie -- nats context create test --server=${props.natsUrl}`} - - -All checks should return successful results before proceeding. - -## Next Steps - -Once the plugin engine is configured, proceed to **[Core Components](../core-components)** installation to deploy the main CodeMie application services. diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-auth-callout.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-auth-callout.mdx new file mode 100644 index 00000000..301fd766 --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-auth-callout.mdx @@ -0,0 +1,54 @@ +import CodeBlock from '@theme/CodeBlock'; + +NATS Auth Callout validates authentication and authorization for NATS connections to CodeMie. + +**Step 1: Authenticate to Container Registry** + +Before deploying NATS Auth Callout, authenticate to the AI/Run CodeMie container registry: + +```bash +export GOOGLE_APPLICATION_CREDENTIALS=key.json +gcloud auth application-default print-access-token | \ + helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev +``` + +:::tip Registry Authentication +This step is required for all AI/Run CodeMie proprietary components: `codemie-ui`, `codemie-api`, `codemie-nats-auth-callout`, `codemie-mcp-connect-service`, and `mermaid-server`. + +If you already authenticated during the Getting Started steps, you can skip this. +::: + +**Step 2: Install NATS Auth Callout Helm Chart** + +Deploy the NATS Auth Callout service: + + +{`helm upgrade --install codemie-nats-auth-callout \\ + oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie-nats-auth-callout \\ + --version "x.y.z" \\ + --namespace codemie \\ + -f ./codemie-nats-auth-callout/${props.valuesFileName} \\ + --wait \\ + --timeout 600s`} + + +**Step 3: Verify NATS Auth Callout Deployment** + +Check that the auth callout service is running: + +```bash +# Check pod status +kubectl get pods -n codemie | grep nats-auth-callout + +# Check deployment +kubectl get deployment -n codemie codemie-nats-auth-callout + +# Check logs +kubectl logs -n codemie deployment/codemie-nats-auth-callout --tail=50 +``` + +Expected output: + +- Pod should be in `Running` state +- Deployment should show ready replicas +- Logs should indicate successful connection to NATS diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-installation.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-installation.mdx new file mode 100644 index 00000000..c5e5304d --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-installation.mdx @@ -0,0 +1,158 @@ +import CodeBlock from '@theme/CodeBlock'; + +NATS provides the messaging backbone for CodeMie's plugin system, enabling real-time communication between the core application and distributed plugins. + +**Step 1: Create NATS Secrets** + +Create the `codemie-nats-secrets` secret containing authentication credentials and encryption keys. Follow these steps to generate and encode the necessary values: + +**1. NATS_URL** + +Internal service URL for NATS communication: + + +{`NATS_URL="${props.natsUrl}"`} + + +**2. Callout User Credentials** + +Credentials for the NATS Auth Callout service: + +```bash +# Username +CALLOUT_USERNAME="callout" + +# Generate secure password +CALLOUT_PASSWORD=$(pwgen -s -1 25) + +# Generate bcrypt hash (requires nats CLI installed) +CALLOUT_BCRYPTED_PASSWORD=$(nats server passwd -p "$CALLOUT_PASSWORD") +``` + +**3. CodeMie User Credentials** + +Credentials for CodeMie application to connect to NATS: + +```bash +# Username +CODEMIE_USERNAME="codemie" + +# Generate secure password +CODEMIE_PASSWORD=$(pwgen -s -1 25) + +# Generate bcrypt hash (requires nats CLI installed) +CODEMIE_BCRYPTED_PASSWORD=$(nats server passwd -p "$CODEMIE_PASSWORD") +``` + +**4. NATS Keys** + +Generate NATS keys for JWT authentication and encrypted connections: + +```bash +nsc generate nkey --account +# Output: +# ISSUER_NSEED: SAXXXXX... (private seed, keep secure) +# ISSUER_NKEY: AXXXXX... (public key) + +nsc generate nkey --curve +# Output: +# ISSUER_XSEED: XSXXXXX... (private seed, keep secure) +# ISSUER_XKEY: XXXXXX... (public key) +``` + +Reference: [NATS Auth Callout Example](https://natsbyexample.com/examples/auth/callout/cli) + +**5. Create the Secret** + +Create the secret using `kubectl` with all generated values: + +```bash +kubectl -n codemie create secret generic codemie-nats-secrets \ + --from-literal=NATS_URL="$NATS_URL" \ + --from-literal=CALLOUT_USERNAME="$CALLOUT_USERNAME" \ + --from-literal=CALLOUT_PASSWORD="$CALLOUT_PASSWORD" \ + --from-literal=CALLOUT_BCRYPTED_PASSWORD="$CALLOUT_BCRYPTED_PASSWORD" \ + --from-literal=CODEMIE_USERNAME="$CODEMIE_USERNAME" \ + --from-literal=CODEMIE_PASSWORD="$CODEMIE_PASSWORD" \ + --from-literal=CODEMIE_BCRYPTED_PASSWORD="$CODEMIE_BCRYPTED_PASSWORD" \ + --from-literal=ISSUER_NKEY="" \ + --from-literal=ISSUER_NSEED="" \ + --from-literal=ISSUER_XKEY="" \ + --from-literal=ISSUER_XSEED="" \ + --type=Opaque +``` + +:::warning Save Credentials +Save all generated passwords and keys securely. You'll need them for troubleshooting and future operations. +::: + +**Alternative: YAML Secret Template** + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: codemie-nats-secrets + namespace: codemie +type: Opaque +data: + NATS_URL: + CALLOUT_USERNAME: + CALLOUT_PASSWORD: + CALLOUT_BCRYPTED_PASSWORD: + CODEMIE_USERNAME: + CODEMIE_PASSWORD: + CODEMIE_BCRYPTED_PASSWORD: + ISSUER_NKEY: + ISSUER_NSEED: + ISSUER_XKEY: + ISSUER_XSEED: +``` + +To encode values: `echo -n 'your-value-here' | base64` + +**Step 2: Add NATS Helm Repository** + +Add the official NATS Helm repository: + +```bash +# Add repository +helm repo add nats https://nats-io.github.io/k8s/helm/charts/ + +# Update repository index +helm repo update nats +``` + +**Step 3: Install NATS Helm Chart** + +Deploy NATS using the official Helm chart: + + +{`helm upgrade --install codemie-nats nats/nats \\ + --version 1.2.6 \\ + --namespace codemie \\ + --values ./codemie-nats/${props.valuesFileName} \\ + --wait \\ + --timeout 900s`} + + +**Step 4: Verify NATS Deployment** + +Check that NATS is running: + +```bash +# Check pod status +kubectl get pods -n codemie | grep nats + +# Check NATS service +kubectl get service -n codemie codemie-nats + +# Check NATS logs +kubectl logs -n codemie statefulset/codemie-nats --tail=50 +``` + +Expected output: + +- NATS pods should be in `Running` state +- Service should show cluster IP assigned +- Logs should indicate successful server startup diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-next-steps.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-next-steps.mdx new file mode 100644 index 00000000..c8c89829 --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-next-steps.mdx @@ -0,0 +1 @@ +Once the plugin engine is configured, proceed to **[Core Components](../core-components)** installation to deploy the main CodeMie application services. diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-overview.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-overview.mdx new file mode 100644 index 00000000..036324ca --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-overview.mdx @@ -0,0 +1,6 @@ +This guide covers the installation of the messaging infrastructure that enables connecting MCP servers and plugins running externally to AI/Run CodeMie infrastructure. + +The plugin engine consists of two components: + +- **NATS** - High-performance message broker enabling pub/sub and request/reply messaging patterns +- **NATS Auth Callout** - Authentication service that validates NATS connections and enforces authorization policies diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-post-validation.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-post-validation.mdx new file mode 100644 index 00000000..0c40cc58 --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-post-validation.mdx @@ -0,0 +1,23 @@ +import CodeBlock from '@theme/CodeBlock'; + +```bash +# NATS is running +kubectl get pods -n codemie | grep codemie-nats + +# NATS Auth Callout is running +kubectl get pods -n codemie | grep nats-auth-callout + +# NATS service is available +kubectl get service -n codemie codemie-nats + +# NATS secrets exist +kubectl get secret codemie-nats-secrets -n codemie + +# Test NATS connectivity (optional) +``` + + +{`kubectl run -it --rm nats-test --image=natsio/nats-box:latest --restart=Never -n codemie -- nats context create test --server=${props.natsUrl}`} + + +All checks should return successful results before proceeding. diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-tls-configuration.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-tls-configuration.mdx new file mode 100644 index 00000000..110ce6f5 --- /dev/null +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-tls-configuration.mdx @@ -0,0 +1,127 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Choose the appropriate scenario based on your deployment architecture: + + + + +**Load Balancer TLS Termination** + +TLS is handled by Network Load Balancer with TLS certificate on the load balancer itself. + +**NATS Helm Values** (codemie-nats/{props.valuesFileName}): + +```yaml +params: + conf: | + tls: {} + allow_non_tls: true +``` + +**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): + +```yaml +extraEnv: + - name: NATS_SKIP_TLS_VERIFY + value: "false" +``` + +**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): + +```yaml +env: + - name: SKIPTLSVERIFY + value: "0" +``` + +**Plugin URL Format**: + +``` +tls://: +``` + +:::info +The `tls://` prefix forces plugins to perform TLS handshake first, which is essential because the load balancer expects TLS negotiation before any NATS protocol communication. +::: + + + + +**No TLS (Local envs only)** + +Plain text communication without encryption. + +**NATS Helm Values** (codemie-nats/{props.valuesFileName}): + +```yaml +params: + conf: | + tls: {} + allow_non_tls: true +``` + +**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): + +```yaml +extraEnv: + - name: NATS_SKIP_TLS_VERIFY + value: "false" +``` + +**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): + +```yaml +env: + - name: SKIPTLSVERIFY + value: "0" +``` + +**Plugin URL Format**: + +``` +nats://: +``` + + + + +**NATS-Managed TLS** + +NATS server handles TLS with its own certificate. + +**NATS Helm Values** (codemie-nats/{props.valuesFileName}): + +```yaml +nats: + tls: + enabled: true + secretName: codemie-nats-tls + merge: + timeout: 10 +``` + +**CodeMie API Configuration** (codemie-api/{props.valuesFileName}): + +```yaml +extraEnv: + - name: NATS_SKIP_TLS_VERIFY + value: "true" +``` + +**NATS Auth Callout Configuration** (codemie-nats-auth-callout/{props.valuesFileName}): + +```yaml +env: + - name: SKIPTLSVERIFY + value: "1" +``` + +**Plugin URL Format**: + +``` +nats://: +``` + + + diff --git a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/security/_security-keycloak-install.mdx b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/security/_security-keycloak-install.mdx index e8a54941..9d206b85 100644 --- a/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/security/_security-keycloak-install.mdx +++ b/docs/admin/deployment/common/deployment/components-deployment/manual-deployment/security/_security-keycloak-install.mdx @@ -109,7 +109,7 @@ Expected output: Keycloak Admin UI can be accessed at: -{props.keycloakUrl} +{props.keycloakUrl} **Login Credentials**: diff --git a/docs/admin/deployment/common/deployment/prerequisites/_cluster-requirements.mdx b/docs/admin/deployment/common/deployment/prerequisites/_cluster-requirements.mdx index bffb93e0..a80de5b6 100644 --- a/docs/admin/deployment/common/deployment/prerequisites/_cluster-requirements.mdx +++ b/docs/admin/deployment/common/deployment/prerequisites/_cluster-requirements.mdx @@ -1,18 +1,16 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -## Kubernetes Cluster Requirements - Requirements for **{props.clusterName}** cluster deployment. -### Administrative Permissions +**Administrative Permissions** The deployment user must have: - **{props.clusterName} 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 +**Admission Control and Resource Requirements** If deploying to an **existing {props.clusterName} cluster**, ensure that admission webhooks allow the creation of the following Kubernetes resources: diff --git a/docs/admin/deployment/common/deployment/prerequisites/_network-requirements.mdx b/docs/admin/deployment/common/deployment/prerequisites/_network-requirements.mdx index 4dbf21be..ef3cc706 100644 --- a/docs/admin/deployment/common/deployment/prerequisites/_network-requirements.mdx +++ b/docs/admin/deployment/common/deployment/prerequisites/_network-requirements.mdx @@ -1,4 +1,4 @@ -### Outbound Connectivity +**Outbound Connectivity** Your {props.clusterName} cluster's {props.networkSecurityName} must allow **outbound access** to the following endpoints: @@ -13,7 +13,7 @@ Your {props.clusterName} cluster's {props.networkSecurityName} must allow **outb 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 +**Inbound Connectivity on Corporate Services** If you plan to integrate AI/Run CodeMie with external corporate services (e.g., GitLab, GitHub, internal APIs): @@ -24,7 +24,7 @@ If you plan to integrate AI/Run CodeMie with external corporate services (e.g., The AI/Run CodeMie {props.natGatewayName} 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 +**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: diff --git a/docs/admin/deployment/common/deployment/prerequisites/_next-steps.mdx b/docs/admin/deployment/common/deployment/prerequisites/_next-steps.mdx index c581c9d3..6e52c884 100644 --- a/docs/admin/deployment/common/deployment/prerequisites/_next-steps.mdx +++ b/docs/admin/deployment/common/deployment/prerequisites/_next-steps.mdx @@ -1,3 +1,3 @@ ## Next Steps -Once all prerequisites are met, proceed to the [Architecture Overview](../architecture) to understand the deployment architecture, or continue directly to [Infrastructure Deployment](../infrastructure-deployment) to begin the installation process. +Once all prerequisites are met, proceed to the [Architecture Overview](../../architecture) to understand the deployment architecture, or continue directly to [Infrastructure Deployment](../infrastructure-deployment) to begin the installation process. diff --git a/docs/admin/deployment/extensions/index.mdx b/docs/admin/deployment/extensions/index.mdx index f6a3ef29..427e3e35 100644 --- a/docs/admin/deployment/extensions/index.mdx +++ b/docs/admin/deployment/extensions/index.mdx @@ -3,7 +3,7 @@ id: extensions-overview sidebar_position: 1 title: Extensions description: Optional extensions and additional features for AI/Run CodeMie -pagination_prev: admin/deployment/index +pagination_prev: admin/deployment/accessing-applications pagination_next: null --- diff --git a/docs/admin/deployment/gcp/kubernetes/accessing-applications.md b/docs/admin/deployment/gcp/kubernetes/accessing-applications.md deleted file mode 100644 index 2623ddf2..00000000 --- a/docs/admin/deployment/gcp/kubernetes/accessing-applications.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: accessing-applications -sidebar_position: 6 -title: Accessing AI/Run CodeMie Applications -sidebar_label: Accessing Applications -pagination_prev: admin/deployment/gcp/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/configuration/index ---- - -import AccessingApplicationsContent from '../../common/deployment/accessing-codemie/\_accessing-codemie-applications.mdx'; - - diff --git a/docs/admin/deployment/gcp/kubernetes/architecture.md b/docs/admin/deployment/gcp/kubernetes/architecture.md deleted file mode 100644 index b6fa7bf3..00000000 --- a/docs/admin/deployment/gcp/kubernetes/architecture.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: architecture -title: AI/Run CodeMie Deployment Architecture -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/gcp/kubernetes/prerequisites -pagination_next: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-deployment-overview ---- - -import ContainerResources from '../../common/deployment/architecture/\_container-resources.mdx'; - -# AI/Run CodeMie Deployment Architecture - -This page provides an overview of the AI/Run CodeMie deployment architecture on Google Cloud Platform (GCP), including infrastructure components, network design, and resource requirements. - -## Architecture Overview - -AI/Run CodeMie is deployed on Google Kubernetes Engine (GKE) with supporting GCP services for networking, storage, and identity management. - -### Deployment Options - -There are two deployment options available depending on your organization's access requirements: - -- **Public cluster option** - Access to AI/Run CodeMie from predefined networks or IP addresses (VPN, corporate networks, etc.) using public DNS resolution from user workstations -- **Private cluster option** - Access to AI/Run CodeMie via Bastion host using private DNS resolution for enhanced security - -### High-Level Architecture Diagram - -The diagram below illustrates the complete AI/Run CodeMie infrastructure deployment on GCP: - -![GCP Architecture Diagram](./images/architecture-diagram.drawio.png) - -:::tip Architecture Customization -The architecture can be customized based on your organization's security policies, compliance requirements, and operational preferences. Consult with your deployment team to discuss specific requirements. -::: - -## Resource Requirements - - - -## Next Steps - -After understanding the architecture, proceed to: - -- [Infrastructure Deployment](./infrastructure-deployment/index.md) - Deploy the GCP infrastructure using Terraform -- [Components Deployment](./components-deployment/index.md) - Deploy AI/Run CodeMie application components using Helm diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/index.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/index.md deleted file mode 100644 index 0113b0e9..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/index.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -id: components-deployment-overview -title: AI/Run CodeMie Components Deployment Overview -sidebar_label: CodeMie Components Deployment -sidebar_position: 5 -pagination_prev: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/components-deployment/components-scripted-deployment ---- - -# AI/Run CodeMie Components Deployment - -## Overview - -This section guides you through deploying the AI/Run CodeMie application stack on your GKE cluster. After completing infrastructure deployment, this phase installs all necessary Kubernetes components including: - -- **Core AI/Run CodeMie services** (API, UI, MCP Connect, NATS Auth) -- **Data layer** (Elasticsearch) -- **Security & Identity** (Keycloak, OAuth2 Proxy) -- **Infrastructure services** (Ingress controller, storage) -- **Observability** (Kibana, Fluent Bit) -- **Optional LLM Proxy** (for load balancing AI model requests) - -The deployment uses Helm charts to install and configure all components in the correct order, ensuring proper dependencies and integration. - -:::info Prerequisites -This phase assumes you have completed [Infrastructure Deployment](../infrastructure-deployment/index.md) and have a running GKE cluster with network, storage, and security configured. -::: - -### Application Stack Components - -The AI/Run CodeMie application consists of multiple integrated components organized into functional categories. Understanding this architecture helps you plan the deployment sequence and troubleshoot issues effectively. - -![Application Stack](../../../common/deployment/images/application-stack-diagram.drawio.png) - -#### Core AI/Run CodeMie Services - -Proprietary services that provide the main AI/Run CodeMie functionality: - -| Component | Container Image | Description | -| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| **CodeMie API** | `europe-west3-docker.pkg.dev/.../codemie:x.y.z` | Backend service handling business logic, data processing, and API operations | -| **CodeMie UI** | `europe-west3-docker.pkg.dev/.../codemie-ui:x.y.z` | Frontend web application providing the user interface | -| **NATS Auth Callout** | `europe-west3-docker.pkg.dev/.../codemie-nats-auth-callout:x.y.z` | Authentication and authorization service for NATS messaging (Plugin Engine component) | -| **MCP Connect** | `europe-west3-docker.pkg.dev/.../codemie-mcp-connect-service:x.y.z` | Bridge enabling CodeMie to communicate with MCP servers | -| **Mermaid Server** | `europe-west3-docker.pkg.dev/.../mermaid-server:x.y.z` | Diagram generation service for visualization in chats | - -:::info Version Information -To find the latest release versions for CodeMie components: - -```bash -bash get-codemie-latest-release-version.sh - -# Use the version detection script with GCP credentials -bash get-codemie-latest-release-version.sh -c key.json -``` - -Make sure you logged in with `key.json` shared with you. - -**Note**: Docker container versions match Helm chart release versions. -::: - -#### Data Layer Components - -Database and storage services for application data: - -| Component | Container Image | Description | -| ----------------- | ----------------------------------------------------- | ------------------------------------------------------------------ | -| **Elasticsearch** | `docker.elastic.co/elasticsearch/elasticsearch:x.y.z` | Document storage, full-text search engine, and analytics platform | -| **Kibana** | `docker.elastic.co/kibana/kibana:x.y.z` | Visualization and exploration tool for Elasticsearch data and logs | - -##### Security & Identity Components - -Authentication, authorization, and access control services: - -| Component | Container Image | Description | -| --------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- | -| **Keycloak Operator** | `epamedp/keycloak-operator:x.y.z` | Kubernetes operator for managing Keycloak lifecycle and configuration | -| **Keycloak** | `quay.io/keycloak/keycloak:x.y.z` | Identity and access management (IAM) server for user authentication | -| **OAuth2 Proxy** | `quay.io/oauth2-proxy/oauth2-proxy:x.y.z` | Reverse proxy providing authentication for web applications using OAuth2/OIDC | - -#### Infrastructure Components - -Foundational services for networking and storage: - -| Component | Container Image | Description | -| ---------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------- | -| **Nginx Ingress Controller** | `registry.k8s.io/ingress-nginx/controller:x.y.z` | HTTP/HTTPS load balancer and reverse proxy for cluster traffic routing | -| **GCP Storage Class** | – | StorageClass for dynamic provisioning of GCP Persistent Disks | - -#### Messaging Infrastructure (Plugin Engine) - -Message broker for inter-service communication and plugin system: - -| Component | Container Image | Description | -| --------- | --------------- | ------------------------------------------------------------------------------ | -| **NATS** | `nats:x.y.z` | Lightweight, high-performance messaging system for microservices communication | - -#### Observability Components - -Logging, monitoring, and troubleshooting tools: - -| Component | Container Image | Description | -| --------------------- | ----------------------------------------- | ------------------------------------------------------------------ | -| **Fluent Bit** | `cr.fluentbit.io/fluent/fluent-bit:x.y.z` | Lightweight log processor and forwarder for centralized logging | -| **Kibana Dashboards** | – | Pre-configured dashboards for monitoring CodeMie metrics and usage | - -#### Optional Components - -Additional services for enhanced functionality: - -| Component | Container Image | Description | -| ------------- | --------------- | ----------------------------------------------------------------------------------- | -| **LLM Proxy** | – | Load balancer and router for AI model requests (supports multiple providers/models) | - -#### Deployment Order - -Components must be installed in the following sequence to satisfy dependencies: - -1. **Infrastructure** → Ingress Controller, Storage Class -2. **Operators** → Keycloak Operator -3. **Data Layer** → Elasticsearch -4. **Security** → Keycloak (with database credentials), OAuth2 Proxy -5. **Messaging** → NATS -6. **Core Services** → CodeMie API, UI, MCP Connect, NATS Auth -7. **Observability** → Fluent Bit, Kibana -8. **Optional** → LLM Proxy (if needed) - -## Prerequisites - -### Cluster Readiness - -Ensure your GKE cluster is ready for component deployment: - -- [x] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/index.md) phase -- [x] **Cluster Access**: kubectl configured and authenticated to GKE cluster -- [x] **Bastion/Jumpbox Access**: Connected to Bastion Host (for private clusters) or have authorized network access - -#### Configure Kubectl Access - -Obtain kubectl credentials using the appropriate Terraform output command based on your cluster access type: - -```bash -# For public clusters or clusters with authorized networks -# Use the command from Terraform outputs -# Parameter: get_kubectl_credentials_for_public_cluster - -# For completely private clusters (access via Bastion Host) -# Use the command from Terraform outputs -# Parameter: get_kubectl_credentials_for_private_cluster -``` - -Verify cluster connectivity: - -```bash -# Test cluster access -kubectl get nodes - -# Check cluster information -kubectl cluster-info -``` - -### Required Components - -The following components will be installed during this phase if not already present: - -- **Nginx Ingress Controller**: Routes external traffic to services -- **GCP Storage Class**: Provides persistent storage for stateful components - -:::info -These components will be installed automatically if not already present in your cluster. Both scripted and manual deployment procedures include the necessary installation steps. -::: - -### Repository and Access {#repository-and-access} - -#### Helm Charts Repository - -Clone the Helm charts repository on your deployment machine (Bastion Host or local workstation): - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -#### Container Registry Credentials - -Before deploying AI/Run CodeMie components, you need to set up authentication for the container registry. - -**Request Access**: Ask the AI/Run CodeMie team to provide: - -- `key.json` file (GCP service account credentials) -- Service account email for pulling images from GCR - -**Create Namespace**: - -```bash -kubectl create namespace codemie -``` - -**Configure Registry Secret**: - -Replace `%%PROJECT_NAME%%` with your project name and create the pull secret: - -```bash -kubectl create secret docker-registry gcp-artifact-registry \ - --docker-server=https://europe-west3-docker.pkg.dev \ - --docker-email=`` \ - --docker-username=_json_key \ - --docker-password="$(cat key.json)" \ - -n codemie -``` - -**Verify Secret**: - -```bash -kubectl get secret gcp-artifact-registry -n codemie -``` - -:::info Pull Secret Usage -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: - -```yaml -imagePullSecrets: - - name: gcp-artifact-registry -``` - -::: - -## Deployment Methods - -Two deployment approaches are available depending on your needs: - -### Scripted Deployment (Recommended) - -Automated deployment using the `helm-charts.sh` wrapper script: - -- **Best for**: Standard deployments, quick setup, production environments -- **Advantages**: Automated dependency ordering, validation checks, consistent configuration - -[→ Scripted Deployment Guide](./scripted-deployment.md) - -### Manual Deployment - -Step-by-step manual installation of each component: - -- **Best for**: Custom configurations, learning the stack, troubleshooting -- **Advantages**: Full control over each component, easier to debug issues - -[→ Manual Deployment Guide](./manual-deployment/index.md) - -:::tip Recommendation -Use **Scripted Deployment** for initial installations. Switch to manual deployment only if you need custom configurations or are troubleshooting specific issues. -::: - -## Next Steps - -After successful component deployment, proceed to [Configuration](../../../../configuration/index.mdx) to set up users, AI models, and complete the platform configuration. diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/core-components.mdx b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/core-components.mdx deleted file mode 100644 index a8e6d707..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/core-components.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -id: core-components -sidebar_position: 5 -title: AI/Run CodeMie Core Components -sidebar_label: Core Components ---- - -import CoreComponentsOverview from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-overview.mdx'; -import CoreComponentsMcpConnect from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-mcp-connect.mdx'; -import CoreComponentsMermaid from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-mermaid.mdx'; -import CoreComponentsUi from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx'; -import CoreComponentsAccess from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx'; -import CoreComponentsValidation from '../../../../common/deployment/components-deployment/manual-deployment/core/_core-components-validation.mdx'; - - - - - - - - - -## CodeMie API Installation - -CodeMie API is the backend service that handles all business logic, AI orchestration, and data processing. - -### Step 1: Configure API Values - -The DNS zone name configuration should already be set from the Getting Started section. Verify the values in `codemie-api/values-gcp.yaml` are correct: - -- `%%DOMAIN%%` should be replaced with your DNS zone name (e.g., `airun.example.com`) -- `%%GOOGLE_PROJECT_ID%%` should be replaced with your GCP project ID where Vertex AI is available -- `%%GOOGLE_KMS_PROJECT_ID%%` should be replaced with your GCP project ID where KMS key is available -- `%%GOOGLE_REGION%%` should be replaced with your GCP region (e.g., `europe-west3`) -- `%%GOOGLE_KMS_REGION%%` should be replaced with your GCP KMS region (e.g., `europe-west3`) - -:::tip Domain Configuration -If you followed the Getting Started steps, these replacements should already be done. -::: - -### Step 2: Copy Elasticsearch Credentials - -CodeMie API needs access to Elasticsearch. Copy the credentials to the codemie namespace: - -```bash -kubectl get secret elasticsearch-master-credentials -n elastic -o yaml | \ - sed '/namespace:/d' | \ - kubectl apply -n codemie -f - -``` - -### Step 3: Create Google Service Account Secret - -Create the secret with the GCP service account key for Vertex AI and KMS access: - -```bash -kubectl create secret generic google-service-account \ - --namespace codemie \ - --from-file=gcp-service-account.json=codemie-gsa-key.json -``` - -:::warning Service Account Key -Ensure the `codemie-gsa-key.json` file exists in your current directory. This key was created during the Getting Started steps and grants access to Vertex AI and Cloud KMS. -::: - -### Step 4: Install CodeMie API Helm Chart - -Deploy CodeMie API: - -```bash -helm upgrade --install codemie-api \ - oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie \ - --version x.y.z \ - --namespace codemie \ - -f ./codemie-api/values-gcp.yaml \ - --wait \ - --timeout 600s -``` - -### Step 5: Verify CodeMie API Deployment - -Check that CodeMie API is running: - -```bash -# Check pod status -kubectl get pods -n codemie | grep codemie-api - -# Check deployment -kubectl get deployment -n codemie codemie-api - -# Check logs -kubectl logs -n codemie deployment/codemie-api --tail=100 - -# Check API health endpoint -kubectl exec -n codemie deployment/codemie-api -- curl -s http://localhost:8080/health -``` - -Expected output: - -- Pod should be in `Running` state -- Deployment should show ready replicas -- Logs should show successful connections to all dependencies -- Health endpoint should return healthy status - - - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/data-layer.mdx b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/data-layer.mdx deleted file mode 100644 index e02cd81d..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/data-layer.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: data-layer -sidebar_position: 2 -title: Data Layer Components -sidebar_label: Data Layer ---- - -import DataLayerOverview from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-overview.mdx'; -import DataLayerElasticsearch from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-elasticsearch.mdx'; -import DataLayerPostgresConfig from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx'; -import DataLayerPostgresSecret from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx'; -import DataLayerValidation from '../../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/index.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/index.md deleted file mode 100644 index 1dc2d3ad..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/index.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -id: manual-deployment-overview -sidebar_position: 2 -title: Manual Deployment Overview -description: Overview of manual component installation process ---- - -# Manual CodeMie Components Deployment - -This guide provides step-by-step instructions for manually deploying AI/Run CodeMie application components using Helm charts. Manual deployment gives you granular control over each component installation, allowing for customization and troubleshooting at each stage. - -:::info When to Use Manual Deployment -Use manual deployment when you need: - -- Fine-grained control over individual component configuration -- Custom installation order or selective component deployment -- Troubleshooting capabilities at each deployment stage -- Integration with existing infrastructure components - -If you prefer automated deployment, see [Scripted Deployment](../scripted-deployment.md) instead. -::: - -## Overview - -Manual deployment involves installing components individually in a specific dependency order. Each component is deployed using Helm charts with cloud-specific values files (`values-gcp.yaml`). - -### Deployment Scope - -This guide covers all components required for a fully functional AI/Run CodeMie installation: - -- **Infrastructure services** - Storage provisioning and ingress routing -- **Data layer** - Document storage and relational databases -- **Security components** - Identity management and authentication proxies -- **Messaging system** - Inter-service communication infrastructure -- **Core CodeMie services** - Main application components -- **Observability stack** - Logging and monitoring dashboards - -## Prerequisites - -Before starting manual deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/index.md) phase -- [ ] **Cluster Access**: Connected to Bastion Host (for private clusters) or have authorized network access and kubectl configured for GKE -- [ ] **Container Registry**: Completed [Container Registry Access Setup](../index.md#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](../index.md#repository-and-access) before proceeding. Each component requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine (Bastion Host or local workstation): - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `bash` - Script execution environment - -## Component Installation Order - -Components must be installed in the following order to satisfy dependencies: - -### 1. [Kubernetes Components](./k8s-components.md) - -**Purpose**: Foundation infrastructure for storage provisioning and external access - -**Components**: - -- GCP Storage Class (for dynamic volume provisioning) -- Nginx Ingress Controller (for HTTP/HTTPS routing) - -**When to Skip**: If your cluster already has these components configured - -### 2. [Data Layer](./data-layer.mdx) - -**Purpose**: Persistent storage for application data and user content - -**Components**: - -- Elasticsearch (document storage and search engine) -- Kibana (visualization and exploration tool) - -**Dependencies**: Requires storage class from Step 1 - -### 3. [Security and Identity](./security-and-identity.md) - -**Purpose**: User authentication, authorization, and access control - -**Components**: - -- Keycloak Operator (Keycloak lifecycle management) -- Keycloak (identity and access management) -- OAuth2 Proxy (authentication proxy) - -**Dependencies**: Requires PostgreSQL from infrastructure deployment - -### 4. [Plugin Engine](./plugin-engine.mdx) - -**Purpose**: Inter-service messaging and plugin communication infrastructure - -**Components**: - -- NATS (message broker) -- NATS Auth Callout (authentication service for NATS) - -**Dependencies**: None (standalone messaging layer) - -### 5. [AI/Run CodeMie Core](./core-components.mdx) - -**Purpose**: Main application services providing CodeMie functionality - -**Components**: - -- PostgreSQL Secret (database credentials) -- MCP Connect (Model Context Protocol connector) -- CodeMie UI (frontend web application) -- Mermaid Server (diagram rendering service) -- CodeMie API (backend REST API) - -**Dependencies**: Requires all previous components (data layer, security, messaging) - -### 6. [Observability](./observability.md) - -**Purpose**: System monitoring, logging aggregation, and operational insights - -**Components**: - -- Fluent Bit (log collection and forwarding) -- Kibana Dashboards (pre-configured monitoring views) - -**Dependencies**: Requires Elasticsearch from Step 2 - -## Getting Started - -### Step 1: Clone Repository - -Clone the Helm charts repository on your deployment machine: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure Domain and GCP Parameters - -Update the required placeholders in the values files. Replace these values with your GCP-specific configuration: - -```bash -# Set your values -CODEMIE_DOMAIN_NAME="airun.example.com" -PROJECT_ID="my-gcp-project" -REGION="europe-west3" - -# Replace DNS zone name in all files -find . -name "values-gcp.yaml" -exec sed -i "s/%%DOMAIN%%/$CODEMIE_DOMAIN_NAME/g" {} \; - -# Replace GCP parameters in CodeMie API -sed -i "s/%%GOOGLE_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_REGION%%/$REGION/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_KMS_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_KMS_REGION%%/$REGION/g" codemie-api/values-gcp.yaml -``` - -:::tip Find Your Values -Your DNS zone name and GCP configuration were set during infrastructure deployment. Check Terraform outputs for `dns_name`, `project_id`, and `region`. -::: - -### Step 3: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials path -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to GCR -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 4: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version (e.g., 1.2.3) for component installations -``` - -You'll use this version when installing each component's Helm chart. - -## Installation Process - -Follow the component installation guides in the order listed above. Each guide provides: - -- Detailed installation commands -- Configuration options -- Validation steps -- Troubleshooting guidance - -:::warning Respect Installation Order -Installing components out of order will cause deployment failures. Always follow the numbered sequence to ensure dependencies are satisfied. -::: - -## Common Issues - -### Image Pull Failures - -**Symptom**: Pods stuck in `ImagePullBackOff` or `ErrImagePull` - -**Solution**: - -- Verify `gcp-artifact-registry` secret exists: `kubectl get secret -n codemie` -- Re-authenticate to registry (repeat Step 3) -- Check network connectivity to `europe-west3-docker.pkg.dev` - -## Next Steps - -Begin the installation process by following the guides in order, starting with **[Kubernetes Components](./k8s-components.md)**. - -After completing all component installations, proceed to **[Configuration](../../../../../configuration/index.mdx)** to configure users, AI models, and data sources. diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/k8s-components.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/k8s-components.md deleted file mode 100644 index 04b03561..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/k8s-components.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: k8s-components -sidebar_position: 1 -title: Kubernetes Components -sidebar_label: Kubernetes Components ---- - -import StorageIngressOverview from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-overview.mdx'; -import StorageIngressNginx from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-nginx.mdx'; -import StorageClassInstallation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-class-installation.mdx'; -import StorageIngressValidation from '../../../../common/deployment/components-deployment/manual-deployment/k8s/\_storage-ingress-validation.mdx'; - - - - - - - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/observability.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/observability.md deleted file mode 100644 index 2851cbb2..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/observability.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: observability -sidebar_position: 6 -title: Observability Components -sidebar_label: Observability -pagination_prev: admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/accessing-applications ---- - -import ObservabilityOverview from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-overview.mdx'; -import ObservabilityFluentBit from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-fluent-bit.mdx'; -import ObservabilityKibana from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-kibana.mdx'; -import ObservabilityDashboards from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-dashboards.mdx'; -import ObservabilityValidation from '../../../../common/deployment/components-deployment/manual-deployment/observability/\_observability-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx deleted file mode 100644 index a9973178..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/plugin-engine.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: plugin-engine -sidebar_position: 4 -title: Plugin Engine -sidebar_label: Plugin Engine -pagination_prev: admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/manual-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/core-components ---- - -import PluginEngineContent from '../../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-content.mdx'; - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/security-and-identity.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/security-and-identity.md deleted file mode 100644 index 0f82f201..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/security-and-identity.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -id: security-and-identity -sidebar_position: 3 -title: Security and Identity Components -sidebar_label: Security and Identity ---- - -import SecurityOverview from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-overview.mdx'; -import SecurityKeycloakOperator from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-operator.mdx'; -import SecurityKeycloakInstall from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-keycloak-install.mdx'; -import SecurityOauth2Proxy from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-oauth2-proxy.mdx'; -import SecurityValidation from '../../../../common/deployment/components-deployment/manual-deployment/security/\_security-validation.mdx'; - - - - - - - - - - diff --git a/docs/admin/deployment/gcp/kubernetes/components-deployment/scripted-deployment.md b/docs/admin/deployment/gcp/kubernetes/components-deployment/scripted-deployment.md deleted file mode 100644 index 2e70f241..00000000 --- a/docs/admin/deployment/gcp/kubernetes/components-deployment/scripted-deployment.md +++ /dev/null @@ -1,390 +0,0 @@ ---- -id: components-scripted-deployment -title: Scripted Components Deployment -sidebar_label: CodeMie Scripted Deployment -sidebar_position: 1 -pagination_prev: admin/deployment/gcp/kubernetes/components-deployment/components-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/accessing-applications ---- - -# Scripted CodeMie Components Deployment - -This guide walks you through deploying AI/Run CodeMie application components using the automated `helm-charts.sh` deployment script. The script handles the installation of all components in the correct dependency order using Helm charts. - -:::tip Recommended Approach -Scripted deployment is recommended for standard installations as it automates component ordering, validates prerequisites, and ensures consistent configuration across all components. -::: - -## Overview - -The `helm-charts.sh` script from the [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) repository automates the installation of: - -- **Infrastructure services** (Nginx Ingress, GCP Storage Class) -- **Data layer** (Elasticsearch) -- **Security components** (Keycloak Operator, Keycloak, OAuth2 Proxy) -- **Messaging system** (NATS, NATS Auth Callout) -- **Core CodeMie services** (API, UI, MCP Connect, Mermaid Server) -- **Observability stack** (Fluent Bit, Kibana, Kibana Dashboards) - -The script supports flexible deployment modes, allowing you to install all components at once or deploy specific component groups based on your needs. - -## Prerequisites - -Before starting deployment, ensure you have completed all requirements: - -### Verification Checklist - -- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../infrastructure-deployment/index.md) phase -- [ ] **Cluster Access**: Connected to Bastion Host (for private clusters) or have authorized network access and kubectl configured for GKE -- [ ] **Container Registry**: Completed [Container Registry Access Setup](./index.md#repository-and-access) from overview page -- [ ] **Helm Installed**: Helm 3.16.0+ installed on deployment machine -- [ ] **Repository Cloned**: `codemie-helm-charts` repository available locally -- [ ] **Domain Configured**: Know your CodeMie domain name from infrastructure outputs - -:::warning Container Registry Access Required -You must complete the Container Registry Access setup from the [Components Deployment Overview](./index.md#repository-and-access) before proceeding. The script requires the `gcp-artifact-registry` pull secret to exist. -::: - -### Required Tools - -Ensure these tools are available on your deployment machine (Bastion Host or local workstation): - -- `kubectl` - Kubernetes cluster management -- `helm` 3.16.0+ - Kubernetes package manager -- `gcloud` CLI - For GCR authentication -- `bash` - Script execution environment - -## Quick Start - -Follow these steps for a standard private cluster deployment: - -### Step 1: Clone Repository - -Clone the Helm charts repository on your deployment machine: - -```bash -git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git -cd codemie-helm-charts -``` - -### Step 2: Configure Domain and GCP Parameters - -Update the required placeholders in the values files. Replace these values with your GCP-specific configuration: - -| Placeholder | Description | Example Value | Files to Edit | -| --------------------------- | ----------------------- | ------------------- | ---------------------------------------- | -| `%%DOMAIN%%` | Your DNS zone name | `airun.example.com` | All `values-gcp.yaml` files listed below | -| `%%GOOGLE_PROJECT_ID%%` | GCP project ID | `my-project-123` | `codemie-api/values-gcp.yaml` | -| `%%GOOGLE_REGION%%` | GCP region | `europe-west3` | `codemie-api/values-gcp.yaml` | -| `%%GOOGLE_KMS_PROJECT_ID%%` | GCP project ID with KMS | `my-project-123` | `codemie-api/values-gcp.yaml` | -| `%%GOOGLE_KMS_REGION%%` | GCP region with KMS | `europe-west3` | `codemie-api/values-gcp.yaml` | - -**Files requiring domain configuration:** - -- `kibana/values-gcp.yaml` -- `keycloak-helm/values-gcp.yaml` -- `oauth2-proxy/values-gcp.yaml` -- `codemie-ui/values-gcp.yaml` -- `codemie-api/values-gcp.yaml` - -:::tip Find Your Values -Your domain name and GCP configuration were set during infrastructure deployment. Check Terraform outputs for `dns_name`, `project_id`, and `region`. -::: - -**Example sed commands to replace placeholders:** - -```bash -# Set your values -DOMAIN="airun.example.com" -PROJECT_ID="my-gcp-project" -REGION="europe-west3" - -# Replace DNS zone name in all files -find . -name "values-gcp.yaml" -exec sed -i "s/%%DOMAIN%%/$DOMAIN/g" {} \; - -# Replace GCP parameters in CodeMie API -sed -i "s/%%GOOGLE_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_REGION%%/$REGION/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_KMS_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml -sed -i "s/%%GOOGLE_KMS_REGION%%/$REGION/g" codemie-api/values-gcp.yaml -``` - -### Step 3: Create Service Account Key - -Create a service account key for Kubernetes to access GCP services: - -1. Access "IAM & Admin" in Google Cloud Console -2. Locate the "codemie-gsa" service account (created by Terraform) -3. Create a new JSON key for this service account -4. Download and save the key file to `codemie-helm-charts/codemie-gsa-key.json` - -```bash -# Verify the key file exists -ls -la codemie-gsa-key.json -``` - -:::warning Key Security -Keep this service account key secure. It grants access to GCP resources including Vertex AI and Cloud KMS. -::: - -### Step 4: Configure LoadBalancer Type (Private vs Public) - -Choose your access model before running the deployment script. The default configuration is for **private access** (recommended). - -#### Option A: Private Access (Default - No Changes Needed) - -For private cluster deployment with access via Bastion Host, **no changes are required**. The default Helm values are pre-configured for Internal LoadBalancer: - -```yaml -# Default configuration (already set) -ingress-nginx: - controller: - service: - annotations: - networking.gke.io/load-balancer-type: Internal -``` - -Skip to [Step 5](#step-5-authenticate-to-container-registry). - -#### Option B: Public Access (Requires Configuration) - -:::warning Prerequisites for Public Access - -- Infrastructure deployed with **public DNS zone** -- Valid **TLS certificate** for your domain -- **Authorized IP ranges** defined (never leave open to 0.0.0.0/0) - ::: - -If you need public access from external networks, modify these files **before running the deployment script**: - -**1. Modify Nginx Ingress Controller** - -Edit `codemie-helm-charts/ingress-nginx/values-gcp.yaml`: - -```yaml -ingress-nginx: - controller: - service: - # Remove the Internal annotation for public LoadBalancer - annotations: {} - type: LoadBalancer - # Define allowed IP ranges (REQUIRED for security) - loadBalancerSourceRanges: - - x.x.x.x/24 # Your office network - - x.x.x.x/24 # Your VPN network - enableHttp: false # Force HTTPS only -``` - -:::danger Security Critical -Never deploy a public LoadBalancer without `loadBalancerSourceRanges` configured. This would expose your application to the entire internet. -::: - -**2. Modify NATS Service** - -Edit `codemie-helm-charts/codemie-nats/values-gcp.yaml`: - -```yaml -service: - merge: - metadata: - # Remove the Internal annotation - annotations: {} - spec: - type: LoadBalancer - # Define allowed IP ranges for NATS access - loadBalancerSourceRanges: - - x.x.x.x/24 # Your office network -``` - -**3. Configure TLS Certificates** - -For public access, create and configure TLS certificates: - -```bash -# Create namespace -kubectl create ns codemie - -# Create TLS secret from your certificate files -kubectl -n codemie create secret tls custom-tls \ - --key ${KEY_FILE} \ - --cert ${CERT_FILE} - -# Copy secret to other namespaces -kubectl get secret custom-tls -n codemie -o yaml | sed '/namespace:/d' | kubectl apply -n security -f - -kubectl get secret custom-tls -n codemie -o yaml | sed '/namespace:/d' | kubectl apply -n elastic -f - -kubectl get secret custom-tls -n codemie -o yaml | sed '/namespace:/d' | kubectl apply -n oauth2-proxy -f - -``` - -**4. Enable TLS in Ingress Configuration** - -Uncomment and configure the `ingress.tls` section in these files: - -- `codemie-api/values-gcp.yaml` -- `codemie-ui/values-gcp.yaml` -- `kibana/values-gcp.yaml` -- `keycloak-helm/values-gcp.yaml` -- `codemie-nats/values-gcp.yaml` - -Example configuration: - -```yaml -tls: - - secretName: custom-tls - hosts: - - codemie.airun.example.com # Replace with your domain -``` - -:::info Certificate Management -You can use [cert-manager](https://cert-manager.io/) for automatic certificate management, but this is not covered in this guide. -::: - -### Step 5: Authenticate to Container Registry - -Authenticate Helm to the Google Container Registry: - -```bash -# Set credentials path -export GOOGLE_APPLICATION_CREDENTIALS=key.json - -# Login to GCR -gcloud auth application-default print-access-token | \ - helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev -``` - -### Step 6: Get Latest CodeMie Version - -Retrieve the latest AI/Run CodeMie release version: - -```bash -# Check latest version -bash get-codemie-latest-release-version.sh -c key.json - -# Note the version output (e.g., 1.2.3) for the next step -``` - -### Step 7: Configure Optional Components (If Required) - -**Optional Components:** - -- `litellm` - LiteLLM Proxy for unified LLM API interface, multi-model routing, and cost tracking -- `pgadmin` - PostgreSQL administration interface for database inspection and monitoring - -:::warning LiteLLM Configuration Required -If deploying with the `--optional litellm` flag, configuration must be completed **before** running the deployment script. Follow the [LiteLLM Proxy Installation and Configuration Guide](../../../extensions/litellm-proxy/index.md) to set up values files and credentials. -::: - -Skip this step if not deploying optional components. - -### Step 8: Run Deployment Script - -Execute the deployment script with your chosen mode: - -```bash -# Development environment with all core components -bash helm-charts.sh --cloud gcp --version --mode all - -# Staging environment with database management tools -bash helm-charts.sh --cloud gcp --version --mode all --optional pgadmin - -# Test environment with LiteLLM for multi-model AI testing -bash helm-charts.sh --cloud gcp --version --mode recommended --optional litellm - -# Full-featured environment with all optional components -bash helm-charts.sh --cloud gcp --version --mode all --optional litellm,pgadmin -``` - -Replace `` with the version from Step 6 (e.g., `2.2.3`). - -:::tip Idempotent Script -The deployment script is idempotent, meaning you can safely re-run it multiple times. If the script fails or is interrupted, simply run it again with the same parameters to continue or retry the deployment. -::: - -## Configuration Reference - -### Script Parameters - -The deployment script accepts the following parameters: - -| Parameter | Description | Required | Values | -| --------------- | ------------------------------------ | -------- | -------------------------------------------------------------------- | -| `-h, --help` | Show help message and usage examples | No | N/A | -| `-c, --cloud` | Target cloud provider | Yes | `gcp`, `aws`, `azure` | -| `-v, --version` | CodeMie component version | Yes | Semantic version (e.g., `2.2.3`) | -| `-m, --mode` | Installation mode | Yes | `all`, `recommended`, `update` | -| `--optional` | Optional components to deploy | No | Comma-separated list: `litellm`, `pgadmin` (e.g., `litellm,pgadmin`) | - -### Deployment Modes - -| Mode | Components Installed | Use Case | -| --------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| **all** | All components including Nginx Ingress Controller | Fresh GKE cluster without existing ingress | -| **recommended** | All components except Nginx Ingress Controller | Cluster with existing ingress controller | -| **update** | Only CodeMie core components (API, UI, MCP Connect, Mermaid) | Updating existing installation to a new version | - -:::tip Choosing Deployment Mode - -- **First-time installation**: Use `all` or `recommended` depending on whether you need Nginx Ingress -- **Version updates**: Use `update` to upgrade only CodeMie components -- **Fresh GKE cluster**: Use `all` mode - ::: - -## Advanced Configuration - -### Setting up DNS Records - -After deployment completes and LoadBalancers are provisioned, configure DNS records to make applications accessible. - -:::info When DNS is Required - -- **Private clusters with private DNS**: DNS is automatically configured by Terraform -- **Public clusters**: You must manually add DNS A records to your DNS provider - ::: - -#### Required DNS Records - -**1. Wildcard Record for Nginx Ingress Controller** - -This allows access to all subdomains managed by Nginx (CodeMie UI, API, Keycloak, Kibana): - -| Field | Value | -| --------- | ------------------------------------------- | -| **Type** | A | -| **Name** | `*` (wildcard) | -| **Value** | LoadBalancer IP of Nginx Ingress Controller | - -Get the Nginx Ingress IP: - -```bash -kubectl get service ingress-nginx-controller -n ingress-nginx \ - -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` - -**2. NATS Record for Plugin Engine** - -This allows direct access to NATS for the CodeMie Plugin Engine: - -| Field | Value | -| --------- | ----------------------- | -| **Type** | A | -| **Name** | `nats-codemie` | -| **Value** | LoadBalancer IP of NATS | - -Get the NATS service IP: - -```bash -kubectl get service codemie-nats -n codemie \ - -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` - -**Example DNS Configuration:** - -``` -*.airun.example.com A x.x.x.x -nats-codemie.airun.example.com A x.x.x.x -``` - -## Next Steps - -After successful deployment and validation, proceed to: - -**[Accessing Applications](../accessing-applications.md)** - Learn how to access the deployed AI/Run CodeMie applications and complete the required configuration steps. diff --git a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/bastion-host-access.md b/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/bastion-host-access.md deleted file mode 100644 index cec7cc60..00000000 --- a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/bastion-host-access.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -id: infrastructure-bastion-host-access -title: Bastion Host Access Configuration -sidebar_label: Bastion Host Access (Optional) -sidebar_position: 3 -pagination_prev: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-manual-deployment -pagination_next: admin/deployment/gcp/kubernetes/components-deployment/components-deployment-overview ---- - -# Bastion Host Access Configuration - -:::warning Private Cluster Only -This section is only required if you deployed a **completely private GKE cluster** with private DNS. For public clusters or clusters with authorized networks configured, you can access the GKE API and CodeMie application directly from your workstation. -::: - -The Bastion Host is a secure jump server that provides access to your private GKE cluster and applications running inside the VPC. This VM enables both command-line management (SSH) and browser-based access (RDP) to internal resources. - -### Connection Methods Overview - -| Connection Type | Use Case | Access Method | -| --------------- | ------------------------------------------------------------- | --------------------- | -| **SSH** | Deploy and manage Kubernetes workloads using kubectl and Helm | Terminal/SSH client | -| **RDP** | Access web UIs exposed via private DNS (Kibana, Keycloak) | Remote Desktop client | - -### Option 1: SSH Connection for Cluster Management - -Use SSH to connect to the Bastion Host for deploying and managing Kubernetes resources. - -1. Retrieve the SSH command from Terraform outputs and connect: - -```bash -# Get the SSH connection command -terraform output bastion_ssh_command - -# Example output: -# gcloud compute ssh bastion-vm --project=your-project --zone=europe-west3-a - -# Use this command to connect -gcloud compute ssh bastion-vm --project=your-project --zone=europe-west3-a -``` - -:::tip IAM Permissions -Ensure your user account is listed in `bastion_members` variable from Phase 2 configuration. Only authorized users can SSH into the Bastion Host. -::: - -#### Step 2: Set user password (Required for RDP) - -After connecting via SSH, set a password for the `ubuntu` user for later RDP access: - -```bash -# Set password for the ubuntu user (you'll be prompted to enter it twice) -sudo passwd ubuntu -``` - -:::info Save Your Password -The `ubuntu` user password you set here will be used to login via RDP. Make sure to remember it or store it securely. -::: - -3. Fetch GKE cluster credentials to enable kubectl commands: - -```bash -# Get the kubectl configuration command -terraform output get_kubectl_credentials_for_private_cluster - -# Example output: -# gcloud container clusters get-credentials your-cluster-name --region=europe-west3 --project=your-project - -# Run the command to configure kubectl -gcloud container clusters get-credentials your-cluster-name --region=europe-west3 --project=your-project -``` - -4. Transfer the Helm charts repository to the Bastion Host. - -:::warning VPN Required for gitbud.epam.com -`gitbud.epam.com` is only accessible through VPN and is not reachable from the Bastion Host directly. Clone the repository on your local machine first, then transfer it using `gcloud scp`. -::: - -On your **local machine** (with VPN active): - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-helm-charts.git -``` - -Then transfer the cloned directory to the Bastion Host: - -```bash -gcloud compute scp --recurse ./codemie-helm-charts bastion-vm:~/ \ - --project=your-project --zone=europe-west3-a -``` - -On the **Bastion Host**, navigate to the transferred directory: - -```bash -cd ~/codemie-helm-charts -``` - -You're now ready to proceed with [Components Deployment](../components-deployment/index.md). - -### Option 2: RDP Connection for Web UI Access - -Use RDP to access application web interfaces that are only available via private DNS (such as Kibana, Keycloak Admin Console). - -:::tip When to Use RDP -RDP is useful when you need to access web-based administrative interfaces that aren't exposed publicly. For kubectl/Helm operations, SSH access is sufficient. -::: - -1. Retrieve the RDP forwarding command from Terraform outputs and start the IAP tunnel: - -```bash -# Get the RDP forwarding command -terraform output bastion_rdp_command - -# Example output: -# gcloud compute start-iap-tunnel bastion-vm 3389 --local-host-port=localhost:3389 --zone=europe-west3-a --project=your-project -``` - -Run the command to create an IAP tunnel that forwards RDP traffic (keep this terminal open): - -```bash -gcloud compute start-iap-tunnel bastion-vm 3389 \ - --local-host-port=localhost:3389 \ - --zone=europe-west3-a \ - --project=your-project -``` - -2. Open your Remote Desktop client and connect: - -| Setting | Value | -| ------------ | -------------------------- | -| **Computer** | `localhost:3389` | -| **Username** | `ubuntu` | -| **Password** | Password set in SSH Step 2 | - -### Tips for Using the Bastion Host - -#### Pasting Commands into Terminal - -Use the correct keyboard shortcut for pasting in Linux terminal: - -``` -Shift + Ctrl + V -``` - -(Regular `Ctrl + V` won't work in most Linux terminal applications) - -#### File Transfer to/from Bastion - -Transfer files between your local machine and Bastion using `gcloud scp`: - -```bash -# Upload file to Bastion -gcloud compute scp local-file.txt bastion-vm:~/remote-file.txt \ - --project=your-project --zone=europe-west3-a - -# Download file from Bastion -gcloud compute scp bastion-vm:~/remote-file.txt ./local-file.txt \ - --project=your-project --zone=europe-west3-a -``` diff --git a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/index.md b/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/index.md deleted file mode 100644 index 28c6fa9e..00000000 --- a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -id: infrastructure-deployment-overview -title: GCP Infrastructure Deployment -sidebar_label: Infrastructure Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/gcp/kubernetes/architecture -pagination_next: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment ---- - -# GCP Infrastructure Deployment - -This section guides you through deploying the GCP infrastructure foundation required for AI/Run CodeMie using Terraform automation. - -:::info Existing Infrastructure -If you already have a provisioned GKE cluster with all required GCP services (networking, storage, databases, etc.), you can skip this section and proceed directly to [Components Deployment](../components-deployment/index.md). -::: - -## Overview - -The Terraform deployment is organized into two distinct phases, each with its own set of resources and purpose: - -1. **Terraform State Backend** - Infrastructure for storing Terraform state files securely -2. **Core Platform Infrastructure** - Main GCP resources for running AI/Run CodeMie - -## Phase 1: Terraform State Backend - -The state backend is deployed first to provide secure, centralized storage for Terraform state files. - -| Resource | Purpose | -| ------------------ | ----------------------------------------------------------------------------- | -| **Storage Bucket** | Google Cloud Storage bucket for storing Terraform state files with versioning | - -:::tip State Backend Purpose -The Terraform state backend enables: - -- **Team Collaboration**: Multiple engineers can work on infrastructure simultaneously -- **State Locking**: Prevents concurrent modifications that could corrupt state -- **Versioning**: Maintains history of infrastructure changes -- **Security**: State files contain sensitive data and require secure storage - ::: - -## Phase 2: Core Platform Infrastructure - -The core platform infrastructure provisions all GCP resources needed to run AI/Run CodeMie. This is the main deployment phase and following GCP resources will be deployed: - -### Compute & Orchestration - -| Resource | Purpose | -| ---------------- | ------------------------------------------------------------------------- | -| **GKE Cluster** | Private or public Kubernetes cluster for running AI/Run CodeMie workloads | -| **Node Pools** | Managed node groups for application workloads | -| **Bastion Host** | Management VM for secure cluster access (optional, for private clusters) | - -### Networking - -| Resource | Purpose | -| ------------------ | ---------------------------------------------------------------- | -| **VPC Network** | Virtual Private Cloud for isolated network environment | -| **Subnets** | Network segmentation for GKE nodes and pods | -| **Cloud NAT** | Provides consistent outbound public IP for internet connectivity | -| **Cloud Router** | Enables dynamic routing for VPC | -| **DNS Zones** | Name resolution for CodeMie components | -| **Firewall Rules** | Network access control and traffic filtering | - -### Data & Storage - -| Resource | Purpose | -| ----------------------------------- | ------------------------------------------------------------------------------------------ | -| **Cloud SQL (PostgreSQL)** | Managed PostgreSQL database service for CodeMie application data with private connectivity | -| **Cloud SQL PostgreSQL (Keycloak)** | Dedicated Cloud SQL instance for Keycloak (optional) | -| **Cloud Storage Buckets** | Optional persistent storage for CodeMie application data and artifacts | - -:::info Optional Components -Some components like Cloud Storage buckets or public DNS zones may be optional depending on your deployment configuration and requirements. -::: - -### Security & Identity - -| Resource | Purpose | -| -------------------------- | ----------------------------------------------------------------------------- | -| **Cloud KMS Key** | Encryption key for encrypting and decrypting sensitive data in AI/Run CodeMie | -| **Service Accounts** | Identity for accessing GCP services (Vertex AI, Cloud Storage, etc.) | -| **IAM Role Bindings** | Role-based access control for service accounts | -| **Private Service Access** | Secure, private network access to Cloud SQL | - -## Terraform Modules - -The core platform infrastructure leverages proven Terraform modules from the community to ensure reliability, security, and best practices: - -- [terraform-google-modules/service-accounts](https://registry.terraform.io/modules/terraform-google-modules/service-accounts/google/latest) -- [terraform-google-modules/kms](https://registry.terraform.io/modules/terraform-google-modules/kms/google/latest) -- [terraform-google-modules/network](https://registry.terraform.io/modules/terraform-google-modules/network/google/latest) -- [terraform-google-modules/cloud-nat](https://registry.terraform.io/modules/terraform-google-modules/cloud-nat/google/latest) -- [terraform-google-modules/kubernetes-engine](https://registry.terraform.io/modules/terraform-google-modules/kubernetes-engine/google/latest) -- [terraform-google-modules/bastion-host](https://registry.terraform.io/modules/terraform-google-modules/bastion-host/google/latest) -- [terraform-google-modules/cloud-dns](https://registry.terraform.io/modules/terraform-google-modules/cloud-dns/google/latest) -- [TerraformFoundation/sql-db/google/private_service_access](https://registry.terraform.io/modules/TerraformFoundation/sql-db/google/latest/submodules/private_service_access) -- [TerraformFoundation/sql-db/google/postgresql](https://registry.terraform.io/modules/TerraformFoundation/sql-db/google/latest/submodules/postgresql) - -## Next Steps - -With the infrastructure resources defined, you are now ready to proceed with the deployment of the GCP infrastructure. - -Proceed to the next step to deploy the infrastructure: - -- [**Scripted Deployment** →](./infrastructure-scripted-deployment) - Recommended automated deployment using the `gcp-terraform.sh` script -- [**Manual Deployment** →](./infrastructure-manual-deployment) - Advanced option for custom scenarios with manual Terraform control - -:::note Deployment Method Selection - -- **Scripted Deployment**: Handles prerequisites, validation, and orchestration automatically (recommended for most users) -- **Manual Deployment**: Provides full control over Terraform operations for advanced customization - ::: diff --git a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/manual-deployment.md b/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/manual-deployment.md deleted file mode 100644 index 574f97fc..00000000 --- a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/manual-deployment.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -id: infrastructure-manual-deployment -title: Manual Infrastructure Deployment -sidebar_label: Manual Deployment -sidebar_position: 2 -pagination_prev: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-bastion-host-access ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Manual Infrastructure Deployment - -This guide walks you through deploying GCP infrastructure for AI/Run CodeMie using Terraform with manual step-by-step instructions. This approach provides full control over each deployment phase and allows for customization at every step. - -:::tip When to Use Manual Deployment -Use manual deployment when you need: - -- Full control over each Terraform operation -- Understanding of each infrastructure component -- Custom configurations or modifications during deployment -- Troubleshooting capabilities at each step - ::: - -## Prerequisites - -Before starting the deployment, ensure you have completed all requirements from the [Prerequisites](../prerequisites.md) page: - -### Verification Checklist - -- [ ] **GCP Access**: Project Owner or Editor role with IAM permissions -- [ ] **Required APIs Enabled**: Cloud IAP, Service Networking, Secret Manager, Vertex AI APIs -- [ ] **Tools Installed**: Terraform 1.13.5, gcloud CLI, kubectl, Helm, Docker -- [ ] **GCP Authentication**: Logged in with gcloud CLI and application default credentials configured -- [ ] **Repository Access**: Have access to Terraform and Helm repositories -- [ ] **Network Planning**: Prepared list of authorized networks (if accessing GKE API from workstation) -- [ ] **Domain & Certificate**: DNS zone and TLS certificate ready (for public access) or will use private DNS - -:::warning Authentication Required -You must be authenticated to GCP CLI before running Terraform. Run `gcloud auth login` and `gcloud auth application-default login`. Verify the active project with `gcloud config get-value project`. -::: - -## Deployment Phases - -Manual deployment involves two sequential phases, both within the same repository: - -| Phase | Description | Directory | -| ------------------------------------ | ---------------------------------------------------------------------------------- | ----------------- | -| **Phase 1: State Backend** | Creates GCS bucket for Terraform state files | `remote-backend/` | -| **Phase 2: Platform Infrastructure** | Deploys GKE, networking, storage, databases, security components, and Bastion Host | `platform/` | - -:::info Bastion Host -Bastion Host is optional and only required for completely private GKE clusters with private DNS. For public clusters or clusters with authorized networks, you can access GKE API directly. -::: - -## Phase 1: Deploy Terraform State Backend - -The first step is to create a Google Cloud Storage bucket for storing Terraform state files. This bucket will be used by all subsequent infrastructure deployments to maintain state consistency and enable team collaboration. - -:::tip Why This Matters -The state backend ensures that your infrastructure state is stored securely and can be shared across your team. Without this, Terraform state would only exist locally on your machine. -::: - -1. Clone the platform repository to your local machine: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform.git -cd codemie-terraform-gcp-platform -``` - -2. Navigate to the `remote-backend/` directory and configure variables. There are two ways to provide Terraform variables: - -```bash -cd remote-backend -``` - - - - -Load variables from `deployment.conf` (`set -a` enables auto-export of all variables): - -```bash -set -a && source ../deployment.conf && set +a -``` - -Initialize Terraform and deploy the storage bucket: - -```bash -terraform init -terraform plan -out=tfplan -terraform apply tfplan -``` - - - - -Create a `terraform.tfvars` file in the `remote-backend/` directory: - -```hcl -project_id = "your-gcp-project-id" -region = "europe-west3" -storage_bucket_name = "codemie-terraform-states" - -# Optional: Custom labels -labels = { - "sys_name" = "ai_run" - "environment" = "development" - "project" = "ai_run" -} -``` - -Initialize Terraform and deploy the storage bucket: - -```bash -terraform init -terraform plan -out=tfplan -terraform apply tfplan -``` - - - - -3. After successful deployment, note the bucket name from Terraform outputs: - -```bash -export BACKEND_BUCKET=$(terraform output -raw terraform_states_storage_bucket_name) -echo "Backend bucket: $BACKEND_BUCKET" -``` - -:::tip Next Phase -The storage bucket is now ready. Proceed to Phase 2 to deploy the main platform infrastructure. -::: - -## Phase 2: Deploy Platform Infrastructure - -This phase deploys all core GCP resources required to run AI/Run CodeMie. This includes the GKE cluster, networking components, databases, and security infrastructure. - -1. Navigate to the `platform/` directory: - -```bash -cd ../platform -``` - -2. Configure and deploy. There are two ways to provide Terraform variables: - - - - -Load variables from `deployment.conf`: - -```bash -set -a && source ../deployment.conf && set +a -``` - -Initialize Terraform with backend configuration and deploy: - -```bash -terraform init \ - -backend-config="bucket=${BACKEND_BUCKET}" \ - -backend-config="prefix=${TF_VAR_region}/codemie/platform_terraform.tfstate" - -terraform plan -out=tfplan -terraform apply tfplan -``` - - - - -Create a `terraform.tfvars` file with your configuration: - -```hcl -# GCP Project Configuration -project_id = "your-gcp-project-id" -platform_name = "codemie" - -# Network Access Control (only used when private_cluster = true) -bastion_members = [ - "group:devops@airun.example.com", - "user:admin@airun.example.com" -] - -# DNS Configuration (only used when create_private_dns_zone = true) -dns_name = "codemie-example-com" -dns_domain = "codemie.airun.example.com." - -# GKE API Access (optional) -extra_authorized_networks = [ - { - cidr_block = "x.x.x.x/24" - display_name = "Office Network" - } -] - -# Cluster Configuration -private_cluster = false # Set to true for completely private GKE cluster -create_private_dns_zone = false # Set to true if using private DNS - -# Optional: Dedicated Cloud SQL Instances Configuration -# Set enabled = true to provision a dedicated Cloud SQL instance for the service. -# All other fields are optional and fall back to defaults. -keycloak_db_config = { enabled = true } -langfuse_db_config = { enabled = false } -litellm_db_config = { enabled = false } - -# Optional: Dedicated Cloud Memorystore Redis Instance -# Set enabled = true to provision a Memorystore Redis instance for caching. -# Supported fields: enabled, tier (BASIC|STANDARD_HA), memory_size_gb, redis_version. -codemie_cache_config = { enabled = false } -``` - -:::info Configuration References -For all available variables and their descriptions, see `variables.tf` in the `platform/` directory. -::: - -Set the backend bucket and region: - -```bash -export BACKEND_BUCKET="your-bucket-name-from-phase1" -export REGION="europe-west3" -``` - -Initialize Terraform with backend configuration and deploy: - -```bash -terraform init \ - -backend-config="bucket=${BACKEND_BUCKET}" \ - -backend-config="prefix=${REGION}/codemie/platform_terraform.tfstate" - -terraform plan -out=tfplan -terraform apply tfplan -``` - - - - -3. After successful deployment, verify all resources were created correctly: - -```bash -# View Terraform outputs -terraform output - -# Verify GKE cluster exists -gcloud container clusters list --project= - -# Check Cloud SQL instance -gcloud sql instances list --project= -``` - -**Save the Terraform outputs** — they contain critical information needed for subsequent steps, including: - -- GKE cluster connection commands -- Bastion Host SSH/RDP commands -- Cloud SQL connection details (`pg_host`, `pg_port`, `pg_database`, `pg_user`, `pg_secret_name`) -- Keycloak Cloud SQL details (`keycloak_pg_host`, `keycloak_pg_database`, `keycloak_pg_user`, `keycloak_pg_secret_name`) — present when `keycloak_db_config.enabled = true` -- LiteLLM Cloud SQL details (`litellm_pg_host`, `litellm_pg_database`, `litellm_pg_user`, `litellm_pg_secret_name`) — present when `litellm_db_config.enabled = true` -- Langfuse Cloud SQL details (`langfuse_pg_host`, `langfuse_pg_database`, `langfuse_pg_user`, `langfuse_pg_secret_name`) — present when `langfuse_db_config.enabled = true` -- Cache details (`codemie_cache_address`, `codemie_cache_secret`) — present when `codemie_cache_config.enabled = true` -- Service account information - -:::tip Infrastructure Ready -The GCP infrastructure deployment is now complete. You can proceed to configure cluster access or continue with components deployment. -::: - -## Next Steps - -After successful infrastructure deployment: - -- **Private GKE cluster with private DNS** — proceed to [Bastion Host Access Configuration](./bastion-host-access.md) to set up secure access before deploying components. -- **Public cluster or authorized networks** — proceed directly to [Components Deployment](../components-deployment/index.md). diff --git a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/scripted-deployment.md b/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/scripted-deployment.md deleted file mode 100644 index 6ab55d17..00000000 --- a/docs/admin/deployment/gcp/kubernetes/infrastructure-deployment/scripted-deployment.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -id: infrastructure-scripted-deployment -title: Infrastructure Scripted Deployment -sidebar_label: Scripted Deployment -sidebar_position: 1 -pagination_prev: admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-deployment-overview -pagination_next: admin/deployment/gcp/kubernetes/components-deployment/components-deployment-overview ---- - -# Scripted Infrastructure Deployment - -This guide walks you through deploying GCP infrastructure for AI/Run CodeMie using the automated `gcp-terraform.sh` deployment script. The script handles all deployment phases automatically: Terraform state backend and core platform infrastructure. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Prerequisites - -Before starting the deployment, ensure you have completed all requirements from the [Prerequisites](../prerequisites.md) page: - -### Verification Checklist - -- [ ] **GCP Access**: Project Owner or Editor role with IAM permissions -- [ ] **Required APIs Enabled**: Cloud IAP, Service Networking, Secret Manager, Vertex AI APIs -- [ ] **Tools Installed**: tfenv, Terraform 1.13.5, gcloud CLI, kubectl, Helm, Docker -- [ ] **GCP Authentication**: Logged in with gcloud CLI and application default credentials configured -- [ ] **Repository Access**: Have access to Terraform and Helm repositories -- [ ] **Network Planning**: Prepared list of authorized networks (if accessing GKE API from workstation) - -:::warning Authentication Required -You must be authenticated to GCP CLI before running Terraform. Run `gcloud auth login` and `gcloud auth application-default login`. Verify the active project with `gcloud config get-value project`. -::: - -## Deployment Phases - -The script automatically deploys infrastructure in sequential phases: - -| Phase | Description | Required | -| ------------------------------------ | ---------------------------------------------------------------------------------- | -------- | -| **Phase 1: State Backend** | Creates GCS bucket for Terraform state files | Yes | -| **Phase 2: Platform Infrastructure** | Deploys GKE, networking, storage, databases, security components, and Bastion Host | Yes | - -## Step 1: Clone Platform Repository - -Clone the platform Terraform repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform.git -cd codemie-terraform-gcp-platform -``` - -## Step 2: Configure Platform Deployment - -Edit `deployment.conf` file to provide your GCP-specific configuration: - -```bash -# GCP project ID where the platform will be deployed -TF_VAR_project_id="my-gcp-project-id" - -# GCP region where the platform will be deployed -TF_VAR_region="europe-west3" - -# GCS bucket name prefix for Terraform remote state storage -TF_VAR_storage_bucket_name="codemie-terraform-states" - -TF_VAR_labels='{"sys_name":"ai_run","environment":"development","project":"ai_run"}' - -# Unique platform identifier used in resource naming -TF_VAR_platform_name="codemie" - -# Whether to create a private GKE cluster -# Setting to true will also deploy a bastion host for cluster access -TF_VAR_private_cluster=false - -# Users/groups who can access the bastion host via IAP (only used when private_cluster = true) -# Format: ["user:email@domain.com", "group:group@domain.com"] -TF_VAR_bastion_members='["user:user@example.com"]' - -# Machine type for worker nodes -TF_VAR_node_pool_machine_type="e2-standard-8" -TF_VAR_node_pool_min_count=2 -TF_VAR_node_pool_max_count=3 - -# Additional networks authorized to access the GKE cluster API server -TF_VAR_extra_authorized_networks='[]' - -# Optional: Dedicated Cloud SQL Instances Configuration -# Set enabled=true to provision a dedicated Cloud SQL instance for the service. -# Omitted fields fall back to defaults (tier, db_name, username, etc.). -TF_VAR_keycloak_db_config='{"enabled":true}' -TF_VAR_langfuse_db_config='{"enabled":false}' -TF_VAR_litellm_db_config='{"enabled":false}' - -# Optional: Dedicated Cloud Memorystore Redis Instance Configuration -# Set enabled=true to provision a Memorystore Redis instance for caching. -# Supported fields: enabled, tier (BASIC|STANDARD_HA), memory_size_gb, redis_version. -TF_VAR_codemie_cache_config='{"enabled":false}' -``` - -:::info Complete Variable List -For all available configuration options, refer to the `platform/terraform.tfvars.example` file in the repository. -::: - -## Step 3: Run Deployment Script - -Execute the automated deployment script: - -```bash -bash ./gcp-terraform.sh -``` - -The script will automatically execute the following operations: - -1. **Validate Configuration**: Check `deployment.conf` for required variables -2. **Verify Prerequisites**: Check for required tools (tfenv, terraform, gcloud CLI) -3. **Check Terraform Version**: Ensure correct Terraform version via tfenv -4. **Verify GCP Authentication**: Validate active gcloud session and application default credentials -5. **Deploy State Backend**: Create GCS bucket for Terraform state storage (`remote-backend/`) -6. **Deploy Platform Infrastructure**: Provision core GCP infrastructure (`platform/`) -7. **Generate Outputs**: Create `deployment_outputs.env` with infrastructure details required for the next phases - -## Deployment Outputs - -Upon successful deployment, the script generates a `deployment_outputs.env` file containing essential infrastructure details needed for the next deployment phase: - -```bash -# GKE Cluster -GKE_CLUSTER_NAME=codemie-gke -GKE_LOCATION=europe-west3 -GKE_NETWORK=codemie-cluster-network -GKE_SUBNET=codemie-cluster-subnet -KUBECTL_COMMAND=gcloud container clusters get-credentials --project my-gcp-project --zone europe-west3 codemie-gke - -# PostgreSQL -CODEMIE_POSTGRES_DATABASE_HOST= -CODEMIE_POSTGRES_DATABASE_PORT=5432 -CODEMIE_POSTGRES_DATABASE_NAME=codemie -CODEMIE_POSTGRES_DATABASE_USER=admin -CODEMIE_POSTGRES_DATABASE_INSTANCE=codemie-postgresql -CODEMIE_POSTGRES_DATABASE_SECRET=codeemiePGDB -CODEMIE_POSTGRES_DATABASE_PASSWORD=generated-password - -# GCP -VERTEX_PROJECT=my-gcp-project - -# Keycloak PostgreSQL (present when keycloak_db_config.enabled=true) -KEYCLOAK_POSTGRES_DATABASE_HOST= -KEYCLOAK_POSTGRES_DATABASE_PORT=5432 -KEYCLOAK_POSTGRES_DATABASE_NAME=keycloak -KEYCLOAK_POSTGRES_DATABASE_USER=keycloak_admin -KEYCLOAK_POSTGRES_DATABASE_INSTANCE=codemie-keycloak-postgresql -KEYCLOAK_POSTGRES_DATABASE_SECRET=codemieKeycloakPGDB -KEYCLOAK_POSTGRES_DATABASE_PASSWORD=generated-password - -# LiteLLM PostgreSQL (present when litellm_db_config.enabled=true) -LITELLM_POSTGRES_DATABASE_HOST= -LITELLM_POSTGRES_DATABASE_PORT=5432 -LITELLM_POSTGRES_DATABASE_NAME=litellm -LITELLM_POSTGRES_DATABASE_USER=litellm_admin -LITELLM_POSTGRES_DATABASE_INSTANCE=codemie-litellm-postgresql -LITELLM_POSTGRES_DATABASE_SECRET=codemieLitellmPGDB -LITELLM_POSTGRES_DATABASE_PASSWORD=generated-password - -# Langfuse PostgreSQL (present when langfuse_db_config.enabled=true) -LANGFUSE_POSTGRES_DATABASE_HOST= -LANGFUSE_POSTGRES_DATABASE_PORT=5432 -LANGFUSE_POSTGRES_DATABASE_NAME=langfuse -LANGFUSE_POSTGRES_DATABASE_USER=langfuse_admin -LANGFUSE_POSTGRES_DATABASE_INSTANCE=codemie-langfuse-postgresql -LANGFUSE_POSTGRES_DATABASE_SECRET=codemieLangfusePGDB -LANGFUSE_POSTGRES_DATABASE_PASSWORD=generated-password - -# Cache (present when codemie_cache_config.enabled=true) -CODEMIE_CACHE_ADDRESS= -CODEMIE_CACHE_SECRET=generated-auth-string -``` - -:::tip Save These Outputs -The `deployment_outputs.env` file contains sensitive information. Store it securely, do not commit to version control and reference it during the Components Deployment phase. -::: - -## Post-Deployment Validation - -After deployment completes, verify that all infrastructure was created successfully: - -### Step 1: Verify GCP Resources - -```bash -# Verify GKE cluster status -gcloud container clusters list --project= - -# Check Cloud SQL instance -gcloud sql instances list --project= - -# Check Memorystore Redis instance (if enabled) -gcloud redis instances list --project= --region= - -# Verify GCS state bucket -gcloud storage buckets list | grep terraform -``` - -### Step 2: Check Deployment Logs - -Review the deployment logs in the `logs/` directory for any warnings or errors: - -```bash -less logs/codemie_gcp_deployment_YYYY-MM-DD-HHMMSS.log -``` - -## Next Steps - -After successful infrastructure deployment and validation: - -- **Private GKE cluster with private DNS** — proceed to [Bastion Host Access Configuration](./bastion-host-access.md) to set up secure access before deploying components. -- **Public cluster or authorized networks** — proceed directly to [Components Deployment](../components-deployment/index.md). diff --git a/docs/admin/deployment/gcp/kubernetes/overview.md b/docs/admin/deployment/gcp/kubernetes/overview.md deleted file mode 100644 index cd2836b4..00000000 --- a/docs/admin/deployment/gcp/kubernetes/overview.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: overview -title: AI/Run Deployment Guide on GCP -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/gcp/kubernetes/prerequisites ---- - -import OverviewContent from '../../common/deployment/overview/\_overview-content.mdx'; - - diff --git a/docs/admin/deployment/gcp/kubernetes/prerequisites.md b/docs/admin/deployment/gcp/kubernetes/prerequisites.md deleted file mode 100644 index d104ab45..00000000 --- a/docs/admin/deployment/gcp/kubernetes/prerequisites.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/gcp/kubernetes/overview -pagination_next: admin/deployment/gcp/kubernetes/architecture ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import ClusterRequirements from '../../common/deployment/prerequisites/\_cluster-requirements.mdx'; -import NetworkRequirements from '../../common/deployment/prerequisites/\_network-requirements.mdx'; -import DeploymentMachineTools from '../../common/deployment/prerequisites/\_deployment-machine-tools.mdx'; -import NextSteps from '../../common/deployment/prerequisites/\_next-steps.mdx'; - -# Prerequisites - -This page outlines the requirements and prerequisites necessary for deploying AI/Run CodeMie on Google Cloud Platform (GCP). -Please ensure all requirements are met before proceeding with the installation. - -## GCP Account Requirements - -### 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.) - :::info Complete Resource List - For a detailed list of all GCP resources that will be provisioned, refer to the [Infrastructure Deployment](./infrastructure-deployment/index.md) 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 access - - `roles/storage.admin` - For Cloud Storage management - - `roles/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](https://console.cloud.google.com/marketplace/product/google/iap.googleapis.com) | Secure identity-based access control | -| [Service Networking API](https://console.cloud.google.com/marketplace/product/google/servicenetworking.googleapis.com) | Private service connectivity | -| [Secret Manager API](https://console.cloud.google.com/marketplace/product/google/secretmanager.googleapis.com) | Centralized secrets management | -| [Vertex AI API](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com) | AI model integration and inference | - -:::info Vertex AI Models -Make sure you are familiar with Gemini models, their parameters, available regions, and other crucial details in the [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models). -::: - -## Network Requirements - -### Domain Name and DNS - -- 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](https://kubernetes.github.io/ingress-nginx/user-guide/tls/)) - - - - - -## GKE Cluster Configuration - -### 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_NATIVE` with IP allocation policy (secondary ranges for pods and services) -- **HTTP Load Balancing Addon:** Enabled (default) - -:::warning Network Policy Disables Automatic NEGs -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: - -```yaml -service: - type: ClusterIP - port: 8080 - annotations: - cloud.google.com/neg: '{"ingress": true}' -``` - -::: - - - -:::note gcloud CLI Multi-Purpose -For GCP deployments, gcloud CLI serves dual purposes: GCP resource management and authentication to AI/Run CodeMie container registry (GCR). -::: - -### Required Repository Access - -You will need access to the following repositories to complete the deployment: - -- **Terraform Platform Modules:** [codemie-terraform-gcp-platform](https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform) -- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) - -:::info Air-Gapped Environments -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. -::: - - diff --git a/docs/admin/deployment/gcp/on-vm/architecture.mdx b/docs/admin/deployment/gcp/on-vm/architecture.mdx deleted file mode 100644 index a90abc66..00000000 --- a/docs/admin/deployment/gcp/on-vm/architecture.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: architecture -title: On VM Deployment Architecture (GCP) -sidebar_label: Architecture -sidebar_position: 3 -pagination_prev: admin/deployment/gcp/on-vm/prerequisites -pagination_next: admin/deployment/gcp/on-vm/deployment/deployment ---- - -# On VM Deployment Architecture (GCP) - -This page describes the infrastructure and application architecture of CodeMie On VM on GCP. - -## Infrastructure Overview - -![GCP On VM Infrastructure Architecture](./images/architecture-diagram.drawio.png) - -CodeMie On VM runs on a single GCE VM with supporting GCP services. Terraform provisions the following resources: - -| Resource | Purpose | -| ------------------------------ | -------------------------------------------------------------------- | -| **GCE VM (n2-highmem-4)** | Single VM running Docker Compose (4 vCPU, 32 GB RAM) | -| **VPC / Subnet** | Isolated network for the VM | -| **Firewall Rules** | Controls inbound/outbound traffic to the VM | -| **GCS Bucket** | Persistent storage for user data (repos, files) | -| **Cloud KMS Key** | Encryption key management for storage data | -| **Cloud DNS Private Zone** | Custom domain resolution (when `TF_VAR_platform_domain_name` is set) | -| **IAP (Identity-Aware Proxy)** | Secure SSH access to the VM without exposing a public IP | -| **Secret Manager** | Stores the SSH private key for VM access | - -### Network Modes - -| Mode | Configuration | Access | -| ------------------------ | ------------------------------------------------ | ----------------------------------------------- | -| **Private IP** (default) | `TF_VAR_platform_domain_name` empty | VM private IP, access via VPN or IAP | -| **Domain** | `TF_VAR_platform_domain_name="codemie.internal"` | Creates Cloud DNS private zone, access via name | - -## Application Architecture - -All CodeMie services run as Docker containers on the GCE VM, orchestrated by Docker Compose. - -![Docker Compose Services](../../common/deployment/images/docker-compose-diagram.drawio.png) - -### Services by Profile - -**Shared services** (both profiles): - -| Service | Image | Purpose | -| ------------- | --------------------------- | ------------------------------------------------- | -| postgres | pgvector/pgvector:pg17 | Primary database for application data | -| elasticsearch | elasticsearch:8.x | Document storage and search for Data Sources | -| kibana | kibana:8.x | Log visualization and analytics for Elasticsearch | -| mcp-connect | codemie-mcp-connect-service | Connector for MCP servers | -| nginx | nginx:1.31-alpine | Reverse proxy, TLS termination | - -**OSS profile:** - -| Service | Purpose | -| -------------- | --------------------------------------------- | -| codemie-oss | API server with built-in local authentication | -| codemie-ui-oss | Web frontend | - -**Enterprise profile:** - -| Service | Purpose | -| ----------------- | ---------------------------------------------- | -| codemie | API server | -| codemie-ui | Web frontend | -| keycloak | Identity provider (SSO, OIDC) | -| oauth2-proxy | Authentication proxy in front of nginx | -| litellm | LLM proxy for model routing and key management | -| nats | Messaging for plugin engine | -| nats-auth-callout | NATS authentication service | -| mermaid-server | Diagram rendering | - -## Resource Requirements - -### Minimum GCE VM - -| Resource | Minimum | Recommended | -| -------- | ------- | ---------------- | -| vCPU | 4 | 4 (n2-highmem-4) | -| RAM | 16 GB | 32 GB | -| Disk | 50 GB | 100 GB | - -## Next Steps - -- [Deployment](../deployment/) — Deploy CodeMie On VM with Terraform diff --git a/docs/admin/deployment/gcp/on-vm/deployment/byo.md b/docs/admin/deployment/gcp/on-vm/deployment/byo.md deleted file mode 100644 index 8755ca04..00000000 --- a/docs/admin/deployment/gcp/on-vm/deployment/byo.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -id: byo -title: BYO GCE VM Deployment -sidebar_label: BYO GCE VM -sidebar_position: 7 -pagination_prev: admin/deployment/gcp/on-vm/deployment/manual-deployment -pagination_next: null ---- - -# BYO GCE VM Deployment - -Deploy CodeMie on an **existing GCE VM** that is not managed by this project's Terraform. This mode skips all infrastructure provisioning and directly provisions the application stack. - -## When to Use - -- You already have a GCE VM (provisioned manually or via another Terraform stack) -- You want to avoid creating additional GCP resources via Terraform -- Your organization manages infrastructure separately from application deployment - -## VM Requirements - -Your existing GCE VM must meet these requirements: - -| Requirement | Details | -| ------------------- | ------------------------------------------------------------------- | -| **OS** | Ubuntu 24.04 | -| **Machine type** | Minimum n2-standard-4 (4 vCPU, 16 GB RAM); recommended n2-highmem-4 | -| **Disk** | Minimum 50 GB; recommended 100 GB | -| **Internet access** | Outbound HTTPS for pulling Docker images | -| **IAP access** | VM must be in a VPC with IAP firewall rule (if using `iap` mode) | - -## Configuration - -Edit `deployment.conf` with BYO-specific variables: - -```bash -CLOUD_PROVIDER="gcp" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# ── BYO GCE ────────────────────────────────────────────────────────── -BYO_VM_HOST="" # Private IP of the VM -BYO_VM_USER="ubuntu" # SSH user on the target VM -BYO_VM_SSH_KEY="" # Absolute path to SSH private key -BYO_VM_SSH_MODE="iap" # iap | direct -BYO_GCP_PROJECT_ID="" # GCP project (required for iap mode) -BYO_GCP_ZONE="" # e.g. europe-west3-a (required for iap mode) -BYO_GCP_INSTANCE_NAME="" # GCE instance name (required for iap mode) -BYO_GCS_BUCKET_NAME="" # Existing GCS bucket for file storage -BYO_GCP_KMS_KEY_ID="" # Cloud KMS crypto key ID (empty = plain encryption) -BYO_PLATFORM_DOMAIN_NAME="" # Optional: overrides CODEMIE_HOST -``` - -### SSH Modes - -| Mode | When to Use | Requirements | -| -------- | ----------------------------------------------- | -------------------------------------------------------------------------------- | -| `iap` | VM in private VPC, access via IAP (recommended) | IAP firewall rule, `BYO_GCP_PROJECT_ID`, `BYO_GCP_ZONE`, `BYO_GCP_INSTANCE_NAME` | -| `direct` | VM has a reachable IP and port 22 is open | SSH private key, network access to port 22 | - -### BYO_VM_HOST - -`BYO_VM_HOST` sets the application URL (`CODEMIE_HOST`): - -| Scenario | `BYO_VM_HOST` value | Result | -| ------------------------------ | ------------------- | -------------------------------------- | -| VM private IP (access via VPN) | `10.0.1.5` | `CODEMIE_HOST=https://10.0.1.5` | -| Custom domain | Any IP (overridden) | Set `BYO_PLATFORM_DOMAIN_NAME` instead | - -### Encryption - -| Setting | Behavior | -| -------------------------- | ------------------------------------------------------------ | -| `BYO_GCP_KMS_KEY_ID` empty | `ENCRYPTION_TYPE=plain` — data stored without envelope key | -| `BYO_GCP_KMS_KEY_ID` set | `ENCRYPTION_TYPE=gcp` — storage data protected via Cloud KMS | - -## Deployment - -### Step 1: Place the GCP Registry Key - -This is a GCP service account credentials file used to pull CodeMie container images from Google Artifact Registry. - -:::info -For open-source deployments with self-built images, this key is optional. -::: - -```bash -cp /path/to/key.json ./key.json -``` - -### Step 2: Run BYO Deployment - -```bash -./deploy.sh --byo -``` - -The script executes: - -| Phase | Description | -| ------------------------ | ------------------------------------------------- | -| Loading config | Validates BYO-specific variables | -| Checking prerequisites | Verifies tools (Terraform not required) | -| Verifying GCP session | Only for iap mode — confirms `gcloud` is active | -| Setting up BYO variables | Maps config to internal variables | -| Generating .env | Creates secrets, renders environment file | -| Setting up SSH | Configures SSH transport (IAP tunnel or direct) | -| Provisioning VM | Installs Docker, syncs files, starts services | -| Writing outputs | Saves deployment info to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -### Step 3: Verify - -```bash -curl -k https:///v1/healthcheck -``` - -## Re-deploying - -Run `./deploy.sh --byo` again. Secrets from `deployment_outputs.env` are preserved automatically. - -## Troubleshooting - -### IAP tunnel connection refused - -- Verify the IAP firewall rule exists: `gcloud compute firewall-rules list --filter="name~iap"` -- Confirm `BYO_GCP_INSTANCE_NAME` matches the exact GCE instance name -- Check `BYO_GCP_ZONE` is in the format `region-zone` (e.g., `europe-west3-a`) -- Ensure `gcloud auth application-default login` has been run and the account has `roles/iap.tunnelResourceAccessor` - -### Docker login fails - -The `key.json` must be a valid GCP service account with access to `europe-west3-docker.pkg.dev`. Verify locally: - -```bash -cat key.json | docker login -u _json_key --password-stdin https://europe-west3-docker.pkg.dev -``` - -### Containers unhealthy - -SSH into the VM and check logs: - -```bash -cd /opt/codemie/compose -docker compose --profile enterprise logs --tail=50 -docker compose --profile enterprise ps -``` diff --git a/docs/admin/deployment/gcp/on-vm/deployment/index.md b/docs/admin/deployment/gcp/on-vm/deployment/index.md deleted file mode 100644 index f741ae02..00000000 --- a/docs/admin/deployment/gcp/on-vm/deployment/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -id: deployment -title: Deployment -sidebar_label: Deployment -sidebar_position: 4 -pagination_prev: admin/deployment/gcp/on-vm/architecture -pagination_next: admin/deployment/gcp/on-vm/deployment/scripted-deployment ---- - -# Deployment - -This section covers deploying CodeMie On VM infrastructure and application stack on GCP. - -## Deployment Methods - -| Method | Description | When to Use | -| ------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| [**Scripted Deployment**](./scripted-deployment) | Fully automated — single `./deploy.sh` handles Terraform and provisioning | Recommended for most users | -| [**Manual Deployment**](./manual-deployment) | Step-by-step Terraform commands, then BYO mode for application provisioning | When you need full control or are integrating with existing workflows | - -:::tip Recommendation -Use **Scripted Deployment** unless you have specific requirements for manual Terraform control. The script handles prerequisite checks, configuration validation, and proper phase sequencing automatically. -::: - -## Deployment Phases - -Both methods execute the same logical phases: - -| Phase | Description | -| ---------------------------- | ------------------------------------------------------------------------ | -| **Terraform State Backend** | Creates GCS bucket for Terraform state (one-time) | -| **Platform Infrastructure** | Provisions VM, GCS bucket, Cloud KMS key, Private DNS zone, firewall | -| **Application Provisioning** | Installs Docker, syncs compose files, generates secrets, starts services | - -## Next Steps - -- [Scripted Deployment](./scripted-deployment) — Automated deployment with `./deploy.sh` -- [Manual Deployment](./manual-deployment) — Manual Terraform + BYO application provisioning diff --git a/docs/admin/deployment/gcp/on-vm/deployment/manual-deployment.md b/docs/admin/deployment/gcp/on-vm/deployment/manual-deployment.md deleted file mode 100644 index 57df0bfe..00000000 --- a/docs/admin/deployment/gcp/on-vm/deployment/manual-deployment.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -id: manual-deployment -title: Manual Deployment -sidebar_label: Manual Deployment -sidebar_position: 6 -pagination_prev: admin/deployment/gcp/on-vm/deployment/scripted-deployment -pagination_next: admin/deployment/gcp/on-vm/deployment/byo ---- - -# Manual Deployment - -This guide provides step-by-step instructions for manually deploying CodeMie On VM infrastructure using Terraform on GCP, followed by application provisioning via BYO mode (`./deploy.sh --byo`). - -:::info When to Use Manual Deployment -Manual deployment is suitable when you need fine-grained control over each Terraform phase, want to customize infrastructure configurations, or are integrating with existing infrastructure management workflows. -::: - -## Prerequisites - -Ensure you have completed all requirements from the [Prerequisites](../../prerequisites) page: - -- [ ] **GCP Access**: Active project with required IAM roles -- [ ] **Tools Installed**: Terraform 1.15.x, gcloud CLI, jq, openssl, envsubst -- [ ] **GCP Authentication**: `gcloud auth application-default login` completed -- [ ] **Repository Access**: Cloned [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) -- [ ] **GCP Registry**: `key.json` file available - -## Deployment Phases - -| Phase | Description | Directory | -| ------------------------------------ | ------------------------------------------------------- | ------------------------------- | -| **Phase 1: State Backend** | Creates GCS bucket for Terraform state | `terraform/gcp/remote-backend/` | -| **Phase 2: Platform Infrastructure** | Provisions VM, GCS bucket, Cloud KMS key, DNS, firewall | `terraform/gcp/platform/` | -| **Phase 3: Application** | Deploys Docker Compose stack via BYO mode | `./` (repo root) | - ---- - -## Phase 1: Terraform State Backend - -:::info One-Time Setup -This phase only needs to run once per GCP project. It creates the GCS bucket used to store Terraform state for subsequent phases. -::: - -1. Navigate to the remote backend directory: - -```bash -cd terraform/gcp/remote-backend/ -``` - -2. Initialize Terraform: - -```bash -terraform init -``` - -3. Create `terraform.tfvars`: - -```hcl -project_id = "my-codemie-project" -region = "europe-west3" -states_bucket_name = "codemie-tfstate" -``` - -4. Plan and apply: - -```bash -terraform plan -out=tfplan -terraform apply tfplan -``` - -5. Note the GCS bucket name from the outputs — you will use it as `TF_VAR_states_bucket_name` in the next phase. - ---- - -## Phase 2: Platform Infrastructure - -1. Navigate to the platform directory: - -```bash -cd terraform/gcp/platform/ -``` - -2. Create `backend.tfvars`: - -```hcl -bucket = "codemie-tfstate" -prefix = "codemie/platform" -``` - -3. Initialize Terraform with backend configuration: - -```bash -terraform init -backend-config=backend.tfvars -``` - -4. Create `terraform.tfvars`: - -```hcl -project_id = "my-codemie-project" -region = "europe-west3" -zone_suffix = "a" -platform_name = "codemie" -machine_type = "n2-highmem-4" -disk_size = 100 -platform_domain_name = "" # Leave empty for private IP access -``` - -5. Plan and apply: - -```bash -terraform plan -out=tfplan -terraform apply tfplan -``` - -6. Note the outputs: - -```bash -terraform output vm_private_ip -terraform output gcs_bucket_name -terraform output kms_key_id -terraform output instance_name -terraform output zone -``` - ---- - -## Phase 3: Application Provisioning (BYO Mode) - -Now that infrastructure is provisioned, use BYO mode to deploy the application stack. - -1. Navigate to the project root. - -2. Place the GCP registry key: - -```bash -cp /path/to/key.json ./key.json -``` - -3. Configure `deployment.conf` with BYO settings from Phase 2 outputs: - -```bash -CLOUD_PROVIDER="gcp" -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise - -# BYO GCE VM settings -BYO_VM_HOST="" # From terraform output -BYO_VM_USER="ubuntu" -BYO_VM_SSH_KEY="/path/to/codemie-key" -BYO_VM_SSH_MODE="iap" # iap | direct -BYO_GCP_PROJECT_ID="" # Your GCP project -BYO_GCP_ZONE="" # e.g. europe-west3-a -BYO_GCP_INSTANCE_NAME="" # From terraform output -BYO_GCS_BUCKET_NAME="" # From terraform output -BYO_GCP_KMS_KEY_ID="" # From terraform output (empty = plain encryption) -BYO_PLATFORM_DOMAIN_NAME="" # Optional: overrides CODEMIE_HOST -``` - -4. Run BYO deployment: - -```bash -./deploy.sh --byo -``` - -5. Verify: - -```bash -curl -k https:///v1/healthcheck -``` - -## Re-deploying - -To update CodeMie: - -1. Edit `deployment.conf` (change `CODEMIE_VERSION`) -2. Run `./deploy.sh --byo` again — secrets are preserved automatically - -## Next Steps - -- [BYO VM](../byo) — Deploy on a completely external GCE VM not managed by this Terraform diff --git a/docs/admin/deployment/gcp/on-vm/deployment/scripted-deployment.md b/docs/admin/deployment/gcp/on-vm/deployment/scripted-deployment.md deleted file mode 100644 index ef61e609..00000000 --- a/docs/admin/deployment/gcp/on-vm/deployment/scripted-deployment.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -id: scripted-deployment -title: Scripted Deployment -sidebar_label: Scripted Deployment -sidebar_position: 5 -pagination_prev: admin/deployment/gcp/on-vm/deployment/deployment -pagination_next: admin/deployment/gcp/on-vm/deployment/manual-deployment ---- - -# Scripted Deployment - -This guide walks through deploying CodeMie On VM on GCP using the automated `deploy.sh` script. The script handles all phases: Terraform state backend, infrastructure provisioning, and application deployment. - -:::tip Recommended Approach -Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. -::: - -## Step 1: Clone the Repository - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git -cd codemie-on-vm -``` - -## Step 2: Place the GCP Registry Key - -Copy your `key.json` file to the repository root: - -```bash -cp /path/to/key.json ./key.json -``` - -## Step 3: Create Deployment Configuration - -```bash -cp deployment.conf.gcp.example deployment.conf -``` - -Edit `deployment.conf`: - -```bash -CLOUD_PROVIDER="gcp" - -# ── GCP ────────────────────────────────────────────────────────────── -TF_VAR_project_id="" # GCP project ID e.g. my-codemie-project -TF_VAR_region="europe-west3" -TF_VAR_zone_suffix="a" # Zone = ${region}-${zone_suffix} - -# ── Terraform State ────────────────────────────────────────────────── -TF_VAR_states_bucket_name="" # GCS bucket name (created by bootstrap phase) - -# ── Platform ───────────────────────────────────────────────────────── -TF_VAR_platform_name="codemie" - -# ── VM ─────────────────────────────────────────────────────────────── -TF_VAR_machine_type="n2-highmem-4" # 4 vCPU, 32 GB RAM -TF_VAR_disk_size=100 # Boot disk size in GB - -# ── Domain & Private DNS (optional) ────────────────────────────────── -TF_VAR_platform_domain_name="" # e.g. codemie.internal - -# ── CodeMie ────────────────────────────────────────────────────────── -CODEMIE_VERSION="2.26.0" -COMPOSE_PROFILE="enterprise" # oss | enterprise -``` - -## Step 4: Authenticate with GCP - -```bash -gcloud auth application-default login - -# Verify active project: -gcloud config get-value project -``` - -## Step 5: Run the Deployment - -```bash -./deploy.sh -``` - -The script executes the following phases: - -| Phase | Description | -| ------------------------------ | ---------------------------------------------------------------- | -| Loading config | Validates `deployment.conf` variables | -| Checking prerequisites | Verifies required tools are installed | -| Verifying GCP credentials | Confirms valid `gcloud` session and project | -| Initializing Terraform backend | Creates GCS bucket for Terraform state | -| Running platform Terraform | Plans and applies VM, GCS bucket, Cloud KMS key, DNS, firewall | -| Reading Terraform outputs | Fetches VM private IP, GCS bucket name, KMS key ID | -| Generating .env | Creates secrets and renders Docker Compose environment | -| Provisioning VM | Installs Docker, syncs files, starts services via IAP SSH tunnel | -| Writing outputs | Saves credentials to `deployment_outputs.env` | -| Deployment summary | Prints URL, SSH command, credentials | - -:::warning Interactive Prompts -The script will pause for approval at each Terraform plan stage. Review the plans carefully before typing `y`. -::: - -## Step 6: Verify Deployment - -After the script completes: - -```bash -curl -k https:///v1/healthcheck -``` - -Expected response: `{"status":"ok"}` - -## Deployment Outputs - -The script creates `deployment_outputs.env` with: - -- **CODEMIE_URL** — Application URL -- **VM_PRIVATE_IP** — VM private IP address -- **SSH_COMMAND** — Full SSH command for access via IAP -- **Credentials** — Keycloak admin or superadmin password -- **Internal secrets** — Preserved across re-runs - -:::danger Sensitive File -`deployment_outputs.env` contains passwords and secrets. Do not commit it to version control. -::: - -## SSH Access - -Connect to the VM via IAP: - -```bash -gcloud compute ssh \ - --project \ - --zone \ - --tunnel-through-iap -``` - -The instance name, project, and zone are printed in the deployment summary and available in `deployment_outputs.env`. - -## Re-deploying / Updating - -To update CodeMie version or configuration: - -1. Edit `deployment.conf` (e.g., change `CODEMIE_VERSION`) -2. Run `./deploy.sh` again - -The script detects the existing `deployment_outputs.env` and preserves all secrets. - -## Next Steps - -- [Manual Deployment](../manual-deployment) — Alternative method with full Terraform control diff --git a/docs/admin/deployment/gcp/on-vm/overview.md b/docs/admin/deployment/gcp/on-vm/overview.md deleted file mode 100644 index 8dce047d..00000000 --- a/docs/admin/deployment/gcp/on-vm/overview.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -id: overview -title: AI/Run CodeMie On VM Deployment Guide (GCP) -sidebar_label: Overview -sidebar_position: 1 -pagination_prev: admin/deployment/index -pagination_next: admin/deployment/gcp/on-vm/prerequisites ---- - -# AI/Run CodeMie On VM Deployment (GCP) - -CodeMie On VM deploys the full AI/Run CodeMie platform on a **single GCE VM** using Docker Compose. It provides the same core functionality as the full GCP (GKE) deployment but with minimal infrastructure overhead. - -## When to Use - -CodeMie On VM is designed for: - -- **Proof of Concept (PoC)** — quickly validate CodeMie capabilities in your environment -- **Demo environments** — showcase CodeMie to stakeholders without complex infrastructure - -:::warning Not for Production -For production workloads with high availability, scaling, and redundancy, use the full [GCP GKE Deployment Guide](../../kubernetes/overview). -::: - -## Deployment Profiles - -CodeMie On VM supports two profiles: - -| Profile | Authentication | LLM Proxy | Plugin Tool | -| -------------- | ----------------------- | --------- | ----------- | -| **OSS** | Local (built-in) | Internal | No | -| **Enterprise** | Keycloak + OAuth2 Proxy | LiteLLM | Yes | - -## Deployment Modes - -| Mode | Command | Infrastructure | -| ------------ | ------------------- | ---------------------------------------------------- | -| **Standard** | `./deploy.sh` | Terraform creates VM, GCS bucket, Cloud KMS key, DNS | -| **BYO VM** | `./deploy.sh --byo` | Use your existing GCE VM | - -## Repository - -All deployment code is hosted at: [codemie-on-vm](https://gitbud.epam.com/epm-cdme/codemie-on-vm) - -``` -codemie-on-vm/ -├── compose/ # Docker Compose files and config -├── deploy.sh # Deployment script -├── destroy.sh # Destroy script -├── deployment.conf.gcp.example # GCP configuration template -└── terraform/ - └── gcp/ - ├── remote-backend/ # GCS bucket for Terraform state - └── platform/ # VM, GCS bucket, KMS key, DNS infrastructure -``` - -## Next Steps - -Proceed to [Prerequisites](../prerequisites) to verify your environment is ready for deployment. diff --git a/docs/admin/deployment/gcp/on-vm/prerequisites.md b/docs/admin/deployment/gcp/on-vm/prerequisites.md deleted file mode 100644 index 4744bd1e..00000000 --- a/docs/admin/deployment/gcp/on-vm/prerequisites.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -id: prerequisites -title: Prerequisites -sidebar_label: Prerequisites -sidebar_position: 2 -pagination_prev: admin/deployment/gcp/on-vm/overview -pagination_next: admin/deployment/gcp/on-vm/architecture ---- - -# Prerequisites - -This page outlines the requirements for deploying AI/Run CodeMie On VM on GCP. Ensure all prerequisites are met before proceeding. - -## GCP Account Requirements - -### Required Access and Permissions - -- **Active GCP Project** with sufficient quota for the required resources -- The operator account must have the following roles or equivalent permissions: - - `roles/iap.tunnelResourceAccessor` — SSH access to the VM via IAP - - `roles/secretmanager.secretAccessor` — fetch SSH key from Secret Manager - - Permissions to create: GCE VM, GCS bucket, Cloud KMS key, Cloud DNS private zone, VPC firewall rules - -### Quota Requirements - -Verify sufficient quota for: - -| Resource | Count | -| ---------------------- | ------------ | -| n2-highmem-4 VM | 1 | -| GCS Bucket | 1 | -| Cloud KMS Key | 1 | -| Cloud DNS Private Zone | 1 (optional) | - -## Deployment Machine Tools - -The following tools must be installed on the machine where you run `./deploy.sh`: - -| Tool | Version | Purpose | -| -------------------------------------------------------------- | ------- | --------------------------------- | -| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | -| [gcloud CLI](https://cloud.google.com/sdk/docs/install) | latest | GCP authentication and management | -| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | -| openssl | latest | Secret generation | -| envsubst | latest | Template rendering | - -**Enterprise profile only:** - -| Tool | Version | Purpose | -| ------------------------------------- | ------- | ------------------- | -| [nsc](https://github.com/nats-io/nsc) | latest | NATS key generation | - -### Verify Installation - -```bash -terraform version # Should show 1.15.x -gcloud version -jq --version -openssl version -envsubst --version -``` - -## GCP Container Registry Access - -CodeMie container images are hosted on `europe-west3-docker.pkg.dev`. You need a **GCP service account key file** (`key.json`) with read access to the registry. - -:::info Obtaining key.json -Contact your CodeMie administrator or EPAM delivery team to obtain the `key.json` file for registry access. -::: - -## GCP Authentication - -Authenticate before running the deployment: - -```bash -gcloud auth application-default login - -# Verify active project -gcloud config get-value project -``` - -## Repository Access - -Clone the deployment repository: - -```bash -git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git -cd codemie-on-vm -``` - -The repository structure: - -| Directory | Purpose | -| ------------------------------- | ---------------------------------------------- | -| `compose/` | Docker Compose files and service configuration | -| `deploy.sh` | Deployment script | -| `destroy.sh` | Destroy script | -| `terraform/gcp/remote-backend/` | GCS bucket for Terraform state | -| `terraform/gcp/platform/` | VM, GCS bucket, KMS key, DNS, firewall | - -## Next Steps - -After verifying all prerequisites, review the [Architecture](../architecture) to understand what will be deployed. diff --git a/docs/admin/deployment/index.mdx b/docs/admin/deployment/index.mdx index 9ec0ee72..23d2dc63 100644 --- a/docs/admin/deployment/index.mdx +++ b/docs/admin/deployment/index.mdx @@ -14,64 +14,47 @@ import FeatureGrid from '@site/src/components/FeatureGrid'; # Deployment Guides -Welcome to the AI/Run CodeMie deployment guides. Choose your cloud provider to get started with deploying CodeMie in your environment. +Welcome to the AI/Run CodeMie deployment guides. A complete deployment follows three phases: review the prerequisites, provision infrastructure, then deploy the platform. See the [Architecture](/admin/architecture/) section first to understand the deployment architecture, infrastructure components, and resource requirements. -## Kubernetes Deployments +## Installation - - -## VM Deployments - - - +
## Marketplace @@ -82,35 +65,9 @@ Welcome to the AI/Run CodeMie deployment guides. Choose your cloud provider to g iconType="image" invertInDarkTheme={false} title="AWS Marketplace" - description="Deploy AI/Run CodeMie directly from AWS Marketplace." + description="Deploy AI/Run CodeMie directly from AWS Marketplace with one-click installation and managed services." link="https://aws.amazon.com/marketplace/pp/prodview-5kkxwllsrb4h2?applicationId=AWSMPContessa&ref_=beagle&sr=0-1" />
- -## Additional Resources - - - - - - diff --git a/docs/admin/deployment/infrastructure-deployment/index.mdx b/docs/admin/deployment/infrastructure-deployment/index.mdx new file mode 100644 index 00000000..15ce690c --- /dev/null +++ b/docs/admin/deployment/infrastructure-deployment/index.mdx @@ -0,0 +1,53 @@ +--- +id: infrastructure-deployment-overview +title: Infrastructure Deployment +sidebar_label: Infrastructure Deployment +sidebar_position: 1 +pagination_prev: admin/deployment/prerequisites/prerequisites-overview +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + +# Infrastructure Deployment + +This section covers deploying the cloud infrastructure required to run AI/Run CodeMie — managed Kubernetes clusters, virtual machines, networking, storage, and databases. All guides support AWS, GCP, and Azure in a unified format using cloud tabs. + +:::info Existing Infrastructure +If you already have a provisioned cluster or VM with all required services, skip this section and proceed directly to [Platform Deployment](../platform-deployment/). +::: + +## Deployment Tracks + +Choose the deployment track that matches your target environment: + + + + +
+ + +## Deployment Methods + +Both tracks support two deployment methods: + +| Method | Description | Recommendation | +| ------------ | ---------------------------------------------------------------- | --------------------------------------- | +| **Scripted** | Automated shell script handles all Terraform phases in sequence | Recommended for most users | +| **Manual** | Step-by-step Terraform commands for full control over each phase | Advanced use cases, custom integrations | + +## Next Steps + +After completing infrastructure deployment, proceed to [Platform Deployment](../platform-deployment/) to install AI/Run CodeMie application components. diff --git a/docs/admin/deployment/infrastructure-deployment/kubernetes.mdx b/docs/admin/deployment/infrastructure-deployment/kubernetes.mdx new file mode 100644 index 00000000..42f1ee66 --- /dev/null +++ b/docs/admin/deployment/infrastructure-deployment/kubernetes.mdx @@ -0,0 +1,1004 @@ +--- +id: infrastructure-deployment-kubernetes +title: Kubernetes Infrastructure Deployment +sidebar_label: Kubernetes +sidebar_position: 2 +pagination_prev: admin/deployment/infrastructure-deployment/infrastructure-deployment-overview +pagination_next: admin/deployment/infrastructure-deployment/infrastructure-deployment-on-vm +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 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: + +- [**Scripted Deployment**](#scripted-deployment) - Automated shell script handles all Terraform phases in sequence +- [**Manual Deployment**](#manual-deployment) - Step-by-step Terraform commands for full control over each phase + +:::tip Recommended Approach +Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of Terraform operations automatically. +::: + +:::info Existing Infrastructure +If you already have a provisioned Kubernetes cluster with all required services, skip this page and proceed directly to [Platform Deployment](../platform-deployment/index.mdx). +::: + +## 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 + +:::warning Authentication Required +You must have configured AWS credentials before running the deployment. Verify with `aws sts get-caller-identity`. +::: + + + + +**Verification Checklist** + +- [ ] **Azure Access**: Contributor role with Entra ID App Registration access +- [ ] **Tools Installed**: Terraform 1.13.5+, Azure CLI, kubectl, Helm, gcloud CLI, Docker +- [ ] **Azure Authentication**: Logged in via `az login` and subscription set +- [ ] **Repository Access**: Access to `codemie-terraform-azure` repository +- [ ] **Network Planning**: Prepared list of allowed networks +- [ ] **Domain & Certificate**: DNS zone and TLS certificate ready (for public access) or will use private DNS + +:::warning Authentication Required +You must be authenticated to Azure CLI before running the deployment script. Run `az login` and verify with `az account show`. +::: + + + + +**Verification Checklist** + +- [ ] **GCP Access**: Project Owner or Editor role with IAM permissions +- [ ] **Required APIs Enabled**: Cloud IAP, Service Networking, Secret Manager, Vertex AI APIs +- [ ] **Tools Installed**: tfenv, Terraform 1.13.5+, gcloud CLI, kubectl, Helm, Docker +- [ ] **GCP Authentication**: Logged in with gcloud CLI and application default credentials configured +- [ ] **Repository Access**: Access to Terraform and Helm repositories +- [ ] **Network Planning**: Prepared list of authorized networks (if accessing GKE API from workstation) + +:::warning Authentication Required +You must be authenticated to GCP CLI before running Terraform. Run `gcloud auth login` and `gcloud auth application-default login`. Verify the active project with `gcloud config get-value project`. +::: + + + + +--- + +## Scripted Deployment + +Scripted deployment runs all Terraform phases automatically in the correct order and generates `deployment_outputs.env` upon completion. + + + + +**Deployment Phases (AWS)** + +| Phase | Description | Required | +| ------------------------------------ | ---------------------------------------------------------------- | ------------------------------------- | +| **Phase 1: IAM Deployer Role** | Creates IAM role with required permissions for deployment | Can be skipped if role already exists | +| **Phase 2: State Backend** | Creates S3 bucket with native locking for Terraform state files | Yes | +| **Phase 3: Platform Infrastructure** | Deploys EKS, networking, storage, databases, security components | Yes | + +**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.** + +1. Clone the IAM Terraform repository: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git +cd codemie-terraform-aws-iam +``` + +2. Create `terraform.tfvars`: + +```hcl +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" +} +``` + +3. Initialize and apply Terraform: + +```bash +terraform init +terraform plan +terraform apply +``` + +**Phase 2 & 3: Deploy Platform Infrastructure** + +1. Clone the platform repository: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git +cd codemie-terraform-aws-platform +``` + +2. Edit `deployment.conf`: + +```bash +# 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}' +``` + +:::info Complete Variable List +For all available configuration options, refer to the `variables.tf` file in the platform repository. +::: + +3. Run the deployment script: + +```bash +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` + +:::warning 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 Phases (Azure)** + +| Phase | Description | Required | +| ------------------------------------ | ---------------------------------------------------------------- | -------- | +| **Phase 1: State Backend** | Creates Azure Storage Account for Terraform state files | Yes | +| **Phase 2: Platform Infrastructure** | Deploys AKS, networking, storage, databases, security components | Yes | +| **Phase 3: AI Models** | Provisions Azure OpenAI services | Optional | + +:::info Skipping AI Models +Set `DEPLOY_AI_MODELS="false"` to skip Phase 3 if using external AI providers. +::: + +**Step 1: Clone Repository** + +```bash +git clone git@gitbud.epam.com:epm-cdme/codemie-terraform-azure.git +cd codemie-terraform-azure +``` + +**Step 2: Configure Deployment** + +Edit `deployment.conf`: + +```bash +# Required: Azure Account Information +AZURE_TENANT_ID="00000000-0000-0000-0000-000000000000" +AZURE_SUBSCRIPTION_ID="11111111-1111-1111-1111-111111111111" + +# Required: Basic Configuration +TF_VAR_customer="airun" +TF_VAR_location="West Europe" +TF_VAR_resource_group_name="" # Leave empty to auto-generate + +# Required: AKS Admin Access +TF_VAR_admin_group_object_ids='["3a459347-0000-1111-2222-e73413cfa80a"]' + +# Optional: Resource Tagging +TF_VAR_tags='{"createdWith":"Terraform","environment":"production"}' + +# Optional: AI Models Deployment +DEPLOY_AI_MODELS="true" + +# Optional: Dedicated PostgreSQL Flexible Server Instances +TF_VAR_keycloak_db_config='{"enabled":true}' +TF_VAR_langfuse_db_config='{"enabled":false}' +TF_VAR_litellm_db_config='{"enabled":false}' +``` + +:::info Azure OpenAI Configuration +When `DEPLOY_AI_MODELS="true"`, configure the `TF_VAR_cognitive_regions` variable to specify which Azure OpenAI models to deploy, in which regions, and with what capacity. See `variables.tf` in the `platform/` directory for the full variable schema. +::: + +**Step 3: Run Deployment Script** + +```bash +bash ./azure-terraform.sh +``` + +The script automatically executes: + +1. **Validate Environment** — Check for required tools and Azure authentication +2. **Verify Configuration** — Validate `deployment.conf` parameters +3. **Deploy State Backend** — Create Azure Storage Account +4. **Deploy Platform Infrastructure** — Provision AKS, networking, storage, databases +5. **Deploy AI Models** — Provision Azure OpenAI services (if `DEPLOY_AI_MODELS="true"`) +6. **Generate Outputs** — Create `deployment_outputs.env` + + + + +**Deployment Phases (GCP)** + +| Phase | Description | Required | +| ------------------------------------ | ---------------------------------------------------------------------------------- | -------- | +| **Phase 1: State Backend** | Creates GCS bucket for Terraform state files | Yes | +| **Phase 2: Platform Infrastructure** | Deploys GKE, networking, storage, databases, security components, and Bastion Host | Yes | + +**Step 1: Clone Platform Repository** + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform.git +cd codemie-terraform-gcp-platform +``` + +**Step 2: Configure Deployment** + +Edit `deployment.conf`: + +```bash +TF_VAR_project_id="my-gcp-project-id" +TF_VAR_region="europe-west3" +TF_VAR_storage_bucket_name="codemie-terraform-states" +TF_VAR_labels='{"sys_name":"ai_run","environment":"development","project":"ai_run"}' +TF_VAR_platform_name="codemie" + +# Whether to create a private GKE cluster (also deploys a bastion host) +TF_VAR_private_cluster=false + +# Users/groups allowed to access the bastion host via IAP (only when private_cluster=true) +TF_VAR_bastion_members='["user:user@example.com"]' + +TF_VAR_node_pool_machine_type="e2-standard-8" +TF_VAR_node_pool_min_count=2 +TF_VAR_node_pool_max_count=3 +TF_VAR_extra_authorized_networks='[]' + +# Optional: Dedicated Cloud SQL Instances +TF_VAR_keycloak_db_config='{"enabled":true}' +TF_VAR_langfuse_db_config='{"enabled":false}' +TF_VAR_litellm_db_config='{"enabled":false}' + +# Optional: Cloud Memorystore Redis +TF_VAR_codemie_cache_config='{"enabled":false}' +``` + +:::info Complete Variable List +For all available configuration options, refer to the `platform/terraform.tfvars.example` file in the repository. +::: + +**Step 3: Run Deployment Script** + +```bash +bash ./gcp-terraform.sh +``` + +The script automatically executes: + +1. **Validate Configuration** — Check `deployment.conf` for required variables +2. **Verify Prerequisites** — Check for required tools +3. **Check Terraform Version** — Ensure correct version via tfenv +4. **Verify GCP Authentication** — Validate active gcloud session +5. **Deploy State Backend** — Create GCS bucket for Terraform state +6. **Deploy Platform Infrastructure** — Provision GKE, networking, storage, databases +7. **Generate Outputs** — Create `deployment_outputs.env` + +:::info Private Cluster Post-Deployment +For a **private GKE cluster** (`TF_VAR_private_cluster=true`), configure [Bastion Host access](#phase-3-configure-bastion-host-access-optional) before proceeding to platform deployment. +::: + + + + +--- + +## Deployment Outputs + +Upon successful deployment, a `deployment_outputs.env` file is generated containing infrastructure details needed for the platform deployment phase. + + + + +```bash +# 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" +``` + + + + +```bash +# Platform Infrastructure +AZURE_CLIENT_ID="00000000-0000-0000-0000-000000000000" +AZURE_KEY_VAULT_URL="https://codemie-kv-abc123.vault.azure.net" +AZURE_KEY_NAME="codemie-key" +AZURE_STORAGE_ACCOUNT_NAME="codemiestorage123" +AZURE_RESOURCE_GROUP="airun-codemie" +CODEMIE_DOMAIN_NAME="airun.example.com" + +# AI Models (if DEPLOY_AI_MODELS="true") +AZURE_AI_TENANT_ID="00000000-0000-0000-0000-000000000000" +AZURE_AI_CLIENT_ID="00000000-0000-0000-0000-000000000000" +AZURE_AI_CLIENT_SECRET="some-secret" + +# PostgreSQL +CODEMIE_POSTGRES_DATABASE_HOST="codemie-psql-abc123.postgres.database.azure.com" +CODEMIE_POSTGRES_DATABASE_PORT="5432" +CODEMIE_POSTGRES_DATABASE_NAME="codemie" +CODEMIE_POSTGRES_DATABASE_USER="pgadmin" +CODEMIE_POSTGRES_DATABASE_PASSWORD="password" +``` + + + + +```bash +# GKE Cluster +GKE_CLUSTER_NAME=codemie-gke +GKE_LOCATION=europe-west3 +KUBECTL_COMMAND=gcloud container clusters get-credentials --project my-gcp-project --zone europe-west3 codemie-gke + +# GCP +VERTEX_PROJECT=my-gcp-project + +# PostgreSQL +CODEMIE_POSTGRES_DATABASE_HOST= +CODEMIE_POSTGRES_DATABASE_PORT=5432 +CODEMIE_POSTGRES_DATABASE_NAME=codemie +CODEMIE_POSTGRES_DATABASE_USER=admin +CODEMIE_POSTGRES_DATABASE_INSTANCE=codemie-postgresql +CODEMIE_POSTGRES_DATABASE_SECRET=codeemiePGDB +CODEMIE_POSTGRES_DATABASE_PASSWORD=generated-password +``` + + + + +:::tip 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 + + + + +```bash +# List all resources in the region +aws resourcegroupstaggingapi get-resources --region + +# Verify EKS cluster status +aws eks describe-cluster --name --region --query "cluster.status" + +# Verify RDS instance status +aws rds describe-db-instances --db-instance-identifier --region +``` + +Review deployment logs: + +```bash +less logs/codemie_aws_deployment_YYYY-MM-DD-HHMMSS.log +``` + + + + +```bash +# List all resources in the resource group +az resource list --resource-group --output table + +# Verify AKS cluster status +az aks show --resource-group --name CodeMieAks --query "provisioningState" + +# Verify PostgreSQL server status +az postgres flexible-server show --resource-group --name +``` + +Review deployment logs: + +```bash +cat logs/codemie_azure_deployment_YYYY-MM-DD-HHMMSS.log +``` + +**Access Jumpbox VM via Bastion** + +After deployment, access the Jumpbox VM to configure AKS access: + +1. In the Azure Portal, navigate to your resource group (default: `CodeMieRG`) +2. Select the Jumpbox VM (`CodeMieVM`) → **Connect** → **Connect via Bastion** +3. Use **SSH Private Key from Azure Key Vault** authentication with `azadmin` user and the `codemie-vm-private-key` secret + +Once connected via RDP, configure kubectl: + +```bash +az login +az account set --subscription +az aks get-credentials \ + --resource-group \ + --name CodeMieAks \ + --overwrite-existing +kubelogin convert-kubeconfig -l azurecli +kubectl get nodes +``` + + + + +```bash +# Verify GKE cluster status +gcloud container clusters list --project= + +# Check Cloud SQL instance +gcloud sql instances list --project= + +# Check Memorystore Redis instance (if enabled) +gcloud redis instances list --project= --region= + +# Verify GCS state bucket +gcloud storage buckets list | grep terraform +``` + +Review deployment logs: + +```bash +less logs/codemie_gcp_deployment_YYYY-MM-DD-HHMMSS.log +``` + +:::info Private Cluster Next Step +If you deployed a **private GKE cluster** (`TF_VAR_private_cluster=true`), proceed to [Bastion Host Access Configuration](#phase-3-configure-bastion-host-access-optional) before deploying platform components. +::: + + + + +--- + +## 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. + +:::info 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: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam.git +cd codemie-terraform-aws-iam +``` + +2. Create `terraform.tfvars`: + +```hcl +region = "us-east-1" +platform_name = "codemie" +deployer_role_name = "AIRunDeployerRole" +``` + +3. Apply Terraform: + +```bash +terraform init +terraform plan +terraform apply +``` + +**Phase 2: Terraform State Backend** + +1. Clone the remote backend repository: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend.git +cd codemie-terraform-aws-remote-backend +``` + +2. Create `terraform.tfvars`: + +```hcl +region = "us-east-1" +role_arn = "arn:aws:iam::123456789012:role/AIRunDeployerRole" +s3_states_bucket_name = "codemie-terraform-states" +``` + +3. Apply Terraform and note the outputs: + +```bash +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: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform.git +cd codemie-terraform-aws-platform/platform +``` + +2. Create `terraform.tfvars`: + +```hcl +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 } +``` + +3. Initialize Terraform with backend configuration: + +```bash +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 +``` + + + + +**Phase 1: Terraform State Backend** + +1. Clone the repository: + +```bash +git clone git@gitbud.epam.com:epm-cdme/codemie-terraform-azure.git +cd codemie-terraform-azure/remote-backend +``` + +2. Create `terraform.tfvars`: + +```hcl +subscription_id = "11111111-1111-1111-1111-111111111111" +customer = "airun" # 3-24 chars, lowercase letters and digits only +location = "West Europe" +``` + +3. Authenticate, apply Terraform, and note the outputs: + +```bash +az login +az account set --subscription "11111111-1111-1111-1111-111111111111" + +terraform init +terraform plan -out=tfplan +terraform apply tfplan + +export BC_RESOURCE_GROUP_NAME=$(terraform output -raw terraform_state_resource_group_name) +export BC_STORAGE_ACCOUNT_NAME=$(terraform output -raw terraform_state_storage_account) +export STORAGE_ACCOUNT_KEY=$(terraform output -raw terraform_state_storage_account_key) +``` + +**Phase 2: Platform Infrastructure** + +1. Navigate to the platform directory: + +```bash +cd ../platform +``` + +2. Create `terraform.tfvars`: + +```hcl +customer = "airun" # Must match Phase 1 +product_name = "airun-codemie" +codemie_domain_name = "private.lab.com" +location = "West Europe" +admin_group_object_ids = ["3a459347-0000-1111-2222-e73413cfa80a"] +keycloak_db_config = { enabled = true } +langfuse_db_config = { enabled = false } +litellm_db_config = { enabled = false } +``` + +:::info Complete Variable List +For all available configuration options (node pool sizing, Container Registry, Langfuse blob storage, etc), refer to the `variables.tf` file in the `platform/` directory. +::: + +3. Initialize Terraform with backend configuration and apply: + +```bash +export TF_VAR_script_storage_account_key="$STORAGE_ACCOUNT_KEY" +export TF_VAR_script_storage_account_name="$BC_STORAGE_ACCOUNT_NAME" + +# Required only if you plan to run Phase 3 (AI Models) afterwards: +export TF_VAR_grant_openai_access=true + +terraform init \ + -backend-config="resource_group_name=${BC_RESOURCE_GROUP_NAME}" \ + -backend-config="storage_account_name=${BC_STORAGE_ACCOUNT_NAME}" \ + -backend-config="container_name=tfstate" \ + -backend-config="key=platform.terraform.tfstate" + +terraform plan -out=tfplan +terraform apply tfplan +terraform output + +export AZURE_RESOURCE_GROUP=$(terraform output -raw codemie_resource_group) +``` + +**Phase 3: AI Models (Optional)** + +Skip this phase if you're using external AI providers or already have Azure OpenAI services deployed. + +1. Navigate to the AI models directory: + +```bash +cd ../ai-models +``` + +2. Create `terraform.tfvars`: + +```hcl +resource_group_name = "airun-codemie" # From Phase 2 output: codemie_resource_group +location = "West Europe" + +cognitive_regions = { + "eastus" = { + count = 2 + custom_domain_name = true + available_models = [ + { + format = "OpenAI" + name = "gpt-4.1-2025-04-14" + model_name = "gpt-4.1" + version = "2025-04-14" + capacity = 200 + type = "GlobalStandard" + } + ] + } +} +``` + +:::info Configuration Reference +See [ai-models/variables.tf](https://gitbud.epam.com/epm-cdme/codemie-terraform-azure/-/blob/main/ai-models/variables.tf) for the complete list of available configuration options. +::: + +3. Initialize Terraform with backend configuration, reusing the state backend from Phase 1, and apply: + +```bash +export TF_VAR_resource_group_name="$AZURE_RESOURCE_GROUP" + +terraform init \ + -backend-config="resource_group_name=${BC_RESOURCE_GROUP_NAME}" \ + -backend-config="storage_account_name=${BC_STORAGE_ACCOUNT_NAME}" \ + -backend-config="container_name=tfstate" \ + -backend-config="key=ai_models.terraform.tfstate" + +terraform plan -out=tfplan +terraform apply tfplan +``` + + + + +**Phase 1: Terraform State Backend** + +1. Clone the platform repository: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform.git +cd codemie-terraform-gcp-platform/remote-backend +``` + +2. Create `terraform.tfvars`: + +```hcl +project_id = "your-gcp-project-id" +region = "europe-west3" +storage_bucket_name = "codemie-terraform-states" +``` + +3. Apply Terraform and note the bucket name: + +```bash +terraform init +terraform plan -out=tfplan +terraform apply tfplan + +export BACKEND_BUCKET=$(terraform output -raw terraform_states_storage_bucket_name) +``` + +**Phase 2: Platform Infrastructure** + +1. Navigate to the platform directory: + +```bash +cd ../platform +``` + +2. Create `terraform.tfvars`: + +```hcl +project_id = "your-gcp-project-id" +platform_name = "codemie" +private_cluster = false +bastion_members = ["user:admin@airun.example.com"] +keycloak_db_config = { enabled = true } +langfuse_db_config = { enabled = false } +litellm_db_config = { enabled = false } +codemie_cache_config = { enabled = false } +``` + +3. Initialize and apply: + +```bash +terraform init \ + -backend-config="bucket=${BACKEND_BUCKET}" \ + -backend-config="prefix=${TF_VAR_region}/codemie/platform_terraform.tfstate" + +terraform plan -out=tfplan +terraform apply tfplan +terraform output +``` + +#### Phase 3: Configure Bastion Host Access (Optional) + +:::warning Private Cluster Only +This section is only required if you deployed a **completely private GKE cluster** with private DNS. For public clusters or clusters with authorized networks configured, you can access the GKE API and CodeMie application directly from your workstation. +::: + +The Bastion Host is a secure jump server that provides access to your private GKE cluster and applications running inside the VPC. This VM enables both command-line management (SSH) and browser-based access (RDP) to internal resources. + +**Connection Methods Overview** + +| Connection Type | Use Case | Access Method | +| --------------- | ------------------------------------------------------------- | --------------------- | +| **SSH** | Deploy and manage Kubernetes workloads using kubectl and Helm | Terminal/SSH client | +| **RDP** | Access web UIs exposed via private DNS (Kibana, Keycloak) | Remote Desktop client | + +**Option 1: SSH Connection for Cluster Management** + +Use SSH to connect to the Bastion Host for deploying and managing Kubernetes resources. + +1. Retrieve the SSH command from Terraform outputs and connect: + +```bash +# Get the SSH connection command +terraform output bastion_ssh_command + +# Example output: +# gcloud compute ssh bastion-vm --project=your-project --zone=europe-west3-a + +# Use this command to connect +gcloud compute ssh bastion-vm --project=your-project --zone=europe-west3-a +``` + +:::tip IAM Permissions +Ensure your user account is listed in the `bastion_members` variable from Phase 2 configuration. Only authorized users can SSH into the Bastion Host. +::: + +**Step 2: Set user password (Required for RDP)** + +After connecting via SSH, set a password for the `ubuntu` user for later RDP access: + +```bash +# Set password for the ubuntu user (you'll be prompted to enter it twice) +sudo passwd ubuntu +``` + +:::info Save Your Password +The `ubuntu` user password you set here will be used to login via RDP. Make sure to remember it or store it securely. +::: + +3. Fetch GKE cluster credentials to enable kubectl commands: + +```bash +# Get the kubectl configuration command +terraform output get_kubectl_credentials_for_private_cluster + +# Example output: +# gcloud container clusters get-credentials your-cluster-name --region=europe-west3 --project=your-project + +# Run the command to configure kubectl +gcloud container clusters get-credentials your-cluster-name --region=europe-west3 --project=your-project +``` + +4. Transfer the Helm charts repository to the Bastion Host. + +:::warning VPN Required for gitbud.epam.com +`gitbud.epam.com` is only accessible through VPN and is not reachable from the Bastion Host directly. Clone the repository on your local machine first, then transfer it using `gcloud scp`. +::: + +On your **local machine** (with VPN active): + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-helm-charts.git +``` + +Then transfer the cloned directory to the Bastion Host: + +```bash +gcloud compute scp --recurse ./codemie-helm-charts bastion-vm:~/ \ + --project=your-project --zone=europe-west3-a +``` + +On the **Bastion Host**, navigate to the transferred directory: + +```bash +cd ~/codemie-helm-charts +``` + +You're now ready to proceed with [Platform Deployment](../platform-deployment/index.mdx). + +**Option 2: RDP Connection for Web UI Access** + +Use RDP to access application web interfaces that are only available via private DNS (such as Kibana, Keycloak Admin Console). + +:::tip When to Use RDP +RDP is useful when you need to access web-based administrative interfaces that aren't exposed publicly. For kubectl/Helm operations, SSH access is sufficient. +::: + +1. Retrieve the RDP forwarding command from Terraform outputs and start the IAP tunnel: + +```bash +# Get the RDP forwarding command +terraform output bastion_rdp_command + +# Example output: +# gcloud compute start-iap-tunnel bastion-vm 3389 --local-host-port=localhost:3389 --zone=europe-west3-a --project=your-project +``` + +Run the command to create an IAP tunnel that forwards RDP traffic (keep this terminal open): + +```bash +gcloud compute start-iap-tunnel bastion-vm 3389 \ + --local-host-port=localhost:3389 \ + --zone=europe-west3-a \ + --project=your-project +``` + +2. Open your Remote Desktop client and connect: + +| Setting | Value | +| ------------ | -------------------------- | +| **Computer** | `localhost:3389` | +| **Username** | `ubuntu` | +| **Password** | Password set in SSH Step 2 | + +**Tips for Using the Bastion Host** + +**Pasting Commands into Terminal** + +Use the correct keyboard shortcut for pasting in Linux terminal: + +``` +Shift + Ctrl + V +``` + +(Regular `Ctrl + V` won't work in most Linux terminal applications) + +**File Transfer to/from Bastion** + +Transfer files between your local machine and Bastion using `gcloud scp`: + +```bash +# Upload file to Bastion +gcloud compute scp local-file.txt bastion-vm:~/remote-file.txt \ + --project=your-project --zone=europe-west3-a + +# Download file from Bastion +gcloud compute scp bastion-vm:~/remote-file.txt ./local-file.txt \ + --project=your-project --zone=europe-west3-a +``` + + + + +--- + +## Next Steps + +After successful infrastructure deployment, proceed to [Platform Deployment](../platform-deployment/index.mdx) to install AI/Run CodeMie application components. diff --git a/docs/admin/deployment/infrastructure-deployment/on-vm.mdx b/docs/admin/deployment/infrastructure-deployment/on-vm.mdx new file mode 100644 index 00000000..fc3f12f9 --- /dev/null +++ b/docs/admin/deployment/infrastructure-deployment/on-vm.mdx @@ -0,0 +1,658 @@ +--- +id: infrastructure-deployment-on-vm +title: On-VM Infrastructure Deployment +sidebar_label: On VM +sidebar_position: 3 +pagination_prev: admin/deployment/infrastructure-deployment/infrastructure-deployment-kubernetes +pagination_next: admin/deployment/platform-deployment/automated/on-vm +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# On-VM Infrastructure Deployment + +This guide covers deploying AI/Run CodeMie on a single virtual machine using Docker Compose. All three cloud providers are supported: AWS (EC2), GCP (Compute Engine), and Azure (VM). + +This guide covers two deployment methods: + +- [**Scripted Deployment**](#scripted-deployment) - Automated shell script handles all Terraform phases in sequence +- [**Manual Deployment**](#manual-deployment) - Step-by-step Terraform commands for full control over each phase + +The `deploy.sh` script handles the full lifecycle: Terraform provisions cloud resources (VM, storage, networking, DNS), and Docker Compose brings up the CodeMie application stack on the provisioned VM. + +:::tip Recommended Approach +Scripted deployment is the recommended method as it handles prerequisite checks, configuration validation, and proper sequencing of all operations automatically. +::: + +## Prerequisites + +Before you begin, make sure you have completed all the requirements described in the [On-VM Deployment Prerequisites](../../prerequisites/prerequisites-on-vm) section — account access, deployment machine tools, GCP Container Registry access (`key.json`), cloud authentication, and repository access for your chosen cloud provider. + +--- + +## Scripted Deployment + +### Step 1: Clone the Repository + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git +cd codemie-on-vm +``` + +### Step 2: Place the GCP Registry Key + +Copy your `key.json` file to the repository root: + +```bash +cp /path/to/key.json ./key.json +``` + +### Step 3: Create Deployment Configuration + + + + +:::info One-Time Setup: IAM Deployer Role +Before running `deploy.sh` for the first time, create the IAM deployer role. + +Navigate to the IAM module and apply Terraform: + +```bash +cd terraform/aws/codemie-on-vm-aws-iam/ +``` + +Create `terraform.tfvars`: + +```hcl +region = "eu-north-1" +platform_name = "codemie" +deployer_role_name = "CodemieOnVmDeployerRole" +``` + +Deploy: + +```bash +terraform init +terraform plan +terraform apply +terraform output deployer_iam_role_arn +# Example: arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole +``` + +Then return to the repository root. +::: + +```bash +cp deployment.conf.example deployment.conf +``` + +Edit `deployment.conf`: + +```bash +# AWS credentials +AWS_PROFILE="" +TF_VAR_region="eu-north-1" +TF_VAR_role_arn="arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" + +# Terraform State +TF_VAR_s3_states_bucket_name="codemie-terraform-states" + +# Platform +TF_VAR_platform_name="codemie" + +# EC2 +TF_VAR_instance_type="r5.xlarge" # 4 vCPU, 32 GB RAM +TF_VAR_volume_size=100 +TF_VAR_access_prefix_list_ids='[]' +TF_VAR_private_ip_only=false + +# Domain & TLS (optional) +TF_VAR_platform_domain_name="" + +# CodeMie +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" +``` + + + + +```bash +cp deployment.conf.azure.example deployment.conf +``` + +Edit `deployment.conf`: + +```bash +CLOUD_PROVIDER="azure" + +# Azure +AZURE_SUBSCRIPTION_ID="" +AZURE_TENANT_ID="" + +# Terraform +TF_VAR_location="westeurope" +TF_VAR_platform_name="codemie" +TF_VAR_vm_size="Standard_E4s_v5" # 4 vCPU, 32 GB RAM +TF_VAR_vm_os_disk_size=100 +TF_VAR_platform_domain_name="" + +# CodeMie +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" + +# Azure OpenAI / AI Models +DEPLOY_AI_MODELS="true" +# Required only when DEPLOY_AI_MODELS=false: +# AZURE_OPENAI_ENDPOINT="" +# AZURE_CLIENT_ID="" +# AZURE_CLIENT_SECRET="" +``` + + + + +```bash +cp deployment.conf.gcp.example deployment.conf +``` + +Edit `deployment.conf`: + +```bash +CLOUD_PROVIDER="gcp" + +# GCP +TF_VAR_project_id="" +TF_VAR_region="europe-west3" +TF_VAR_zone_suffix="a" + +# Terraform State +TF_VAR_states_bucket_name="" + +# Platform +TF_VAR_platform_name="codemie" + +# VM +TF_VAR_machine_type="n2-highmem-4" # 4 vCPU, 32 GB RAM +TF_VAR_disk_size=100 + +# Domain & Private DNS (optional) +TF_VAR_platform_domain_name="" + +# CodeMie +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" +``` + + + + +### Step 4: Authenticate with Cloud Provider + + + + +```bash +# If using AWS SSO: +aws sso login --profile your-profile +export AWS_PROFILE=your-profile + +# Verify credentials: +aws sts get-caller-identity +``` + + + + +```bash +az login +az account set --subscription "" + +# Verify: +az account show +``` + + + + +```bash +gcloud auth application-default login + +# Verify active project: +gcloud config get-value project +``` + + + + +### Step 5: Run the Deployment + +```bash +./deploy.sh +``` + +The script executes the following phases: + + + + +| Phase | Description | +| ------------------------------ | ------------------------------------------------------- | +| Loading config | Validates `deployment.conf` variables | +| Checking prerequisites | Verifies required tools are installed | +| Verifying AWS credentials | Confirms valid AWS session | +| Initializing S3 remote backend | Creates S3 bucket for Terraform state | +| Running terraform | Plans and applies infrastructure (with approval prompt) | +| Reading terraform outputs | Fetches EC2 ID, IPs, S3 bucket, KMS key | +| Generating .env | Creates secrets and renders Docker Compose environment | +| Provisioning EC2 | Installs Docker, syncs files, starts services | +| Writing outputs | Saves credentials to `deployment_outputs.env` | +| Deployment summary | Prints URL, SSH command, credentials | + +:::warning Interactive Prompts +The script pauses twice for approval: remote backend Terraform plan and platform Terraform plan. Review plans carefully before typing `y`. +::: + + + + +| Phase | Description | +| ------------------------------ | ---------------------------------------------------------------------- | +| Loading config | Validates `deployment.conf` variables | +| Checking prerequisites | Verifies required tools are installed | +| Verifying Azure credentials | Confirms valid `az` session and subscription | +| Initializing Terraform backend | Creates Azure Storage container for Terraform state | +| Running platform Terraform | Plans and applies VM, Storage Account, Key Vault, DNS, NSG | +| Running AI models Terraform | Plans and applies Azure OpenAI accounts (if `DEPLOY_AI_MODELS="true"`) | +| Reading Terraform outputs | Fetches VM private IP, Storage Account name, Key Vault URL | +| Generating .env | Creates secrets and renders Docker Compose environment | +| Provisioning VM | Installs Docker, syncs files, starts services via Azure Bastion | +| Writing outputs | Saves credentials to `deployment_outputs.env` | +| Deployment summary | Prints URL, SSH command, credentials | + + + + +| Phase | Description | +| ------------------------------ | ---------------------------------------------------------------- | +| Loading config | Validates `deployment.conf` variables | +| Checking prerequisites | Verifies required tools are installed | +| Verifying GCP credentials | Confirms valid `gcloud` session and project | +| Initializing Terraform backend | Creates GCS bucket for Terraform state | +| Running platform Terraform | Plans and applies VM, GCS bucket, Cloud KMS key, DNS, firewall | +| Reading Terraform outputs | Fetches VM private IP, GCS bucket name, KMS key ID | +| Generating .env | Creates secrets and renders Docker Compose environment | +| Provisioning VM | Installs Docker, syncs files, starts services via IAP SSH tunnel | +| Writing outputs | Saves credentials to `deployment_outputs.env` | +| Deployment summary | Prints URL, SSH command, credentials | + + + + +### Step 6: Verify Deployment + +```bash +curl -k https:///v1/healthcheck +``` + +Expected response: `{"status":"ok"}` + +## Deployment Outputs + +The script creates `deployment_outputs.env` with: + +- **CODEMIE_URL** — Application URL +- **SSH_COMMAND** — Full SSH command for access +- **Credentials** — Keycloak admin or superadmin password +- **Internal secrets** — Preserved across re-runs + +:::danger Sensitive File +`deployment_outputs.env` contains passwords and secrets. Do not commit it to version control. +::: + +## SSH Access + + + + +SSH uses AWS Systems Manager Session Manager as a proxy (no need to open port 22): + +```bash +ssh -i codemie-key.pem \ + -o "ProxyCommand=aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p" \ + ubuntu@ +``` + + + + +SSH via Azure Bastion: + +```bash +az network bastion ssh \ + --name "" \ + --resource-group "" \ + --target-resource-id "" \ + --auth-type "ssh-key" \ + --username "azadmin" \ + --ssh-key "~/.ssh/codemie-key.pem" +``` + + + + +SSH via Identity-Aware Proxy (IAP) tunnel: + +```bash +gcloud compute ssh \ + --project \ + --zone \ + --tunnel-through-iap +``` + + + + +## Re-deploying / Updating + +To update CodeMie version or configuration: + +1. Edit `deployment.conf` (e.g., change `CODEMIE_VERSION`) +2. Run `./deploy.sh` again + +The script detects the existing `deployment_outputs.env` and preserves all secrets. Only the Docker Compose services are updated. + +--- + +## Manual Deployment + +Manual deployment provides full control over each Terraform phase. Use this when you need fine-grained customization or are integrating with existing infrastructure management workflows. + +After provisioning the infrastructure manually, the application is deployed using BYO mode: `./deploy.sh --byo`. + + + + +**Deployment Phases (AWS)** + +| Phase | Description | Directory | +| ------------------------------------ | ------------------------------------------ | -------------------------------------- | +| **Phase 1: IAM Deployer Role** | Creates IAM role with required permissions | `terraform/aws/codemie-on-vm-aws-iam/` | +| **Phase 2: State Backend** | Creates S3 bucket for Terraform state | `terraform/aws/remote-backend/` | +| **Phase 3: Platform Infrastructure** | Provisions VPC, EC2, S3, KMS, ALB | `terraform/aws/platform/` | + +**Phase 1: IAM Deployer Role** + +:::info One-Time Setup +This phase only needs to run once per AWS account. +::: + +```bash +cd terraform/aws/codemie-on-vm-aws-iam/ +``` + +Create `terraform.tfvars`: + +```hcl +region = "eu-north-1" +platform_name = "codemie" +deployer_role_name = "CodemieOnVmDeployerRole" +``` + +Deploy: + +```bash +terraform init +terraform plan -out=tfplan +terraform apply tfplan +terraform output deployer_iam_role_arn +``` + +**Phase 2: Terraform State Backend** + +```bash +cd terraform/aws/remote-backend/ +terraform init +terraform plan -out=tfplan \ + -var="region=eu-north-1" \ + -var="role_arn=arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" \ + -var="bucket_name=codemie-terraform-states" +terraform apply tfplan +``` + +**Phase 3: Platform Infrastructure** + +```bash +cd terraform/aws/platform/ +``` + +Create `backend.tfvars`: + +```hcl +bucket = "codemie-terraform-states" +key = "codemie/terraform.tfstate" +region = "eu-north-1" +use_lockfile = true +``` + +Create `terraform.tfvars`: + +```hcl +region = "eu-north-1" +role_arn = "arn:aws:iam::123456789012:role/CodemieOnVmDeployerRole" +platform_name = "codemie" +instance_type = "r5.xlarge" +volume_size = 100 +private_ip_only = false +platform_domain_name = "" +access_prefix_list_ids = [] +``` + +```bash +terraform init -backend-config=backend.tfvars +terraform plan -out=tfplan +terraform apply tfplan + +# Note outputs for Phase 4: +terraform output ec2_instance_id +terraform output ec2_public_ip +terraform output s3_bucket_name +terraform output kms_key_id +terraform output ssm_ec2_private_key +``` + +Fetch the SSH key from SSM: + +```bash +aws ssm get-parameter \ + --name "$(terraform output -raw ssm_ec2_private_key)" \ + --region eu-north-1 \ + --with-decryption \ + --query "Parameter.Value" \ + --output text > codemie-key.pem +chmod 600 codemie-key.pem +``` + +After completing infrastructure provisioning, proceed to [Application Provisioning (BYO Mode)](../../platform-deployment/automated/on-vm) to deploy the CodeMie stack. + + + + +**Deployment Phases (Azure)** + +| Phase | Description | Directory | +| ------------------------------------ | --------------------------------------------------- | --------------------------------- | +| **Phase 1: State Backend** | Creates Azure Storage container for Terraform state | `terraform/azure/remote-backend/` | +| **Phase 2: Platform Infrastructure** | Provisions VM, Storage Account, Key Vault, DNS, NSG | `terraform/azure/platform/` | +| **Phase 3: AI Models** (optional) | Provisions Azure OpenAI cognitive accounts | `terraform/azure/ai-models/` | + +**Phase 1: Terraform State Backend** + +```bash +cd terraform/azure/remote-backend/ +terraform init +``` + +Create `terraform.tfvars`: + +```hcl +location = "westeurope" +platform_name = "codemie" +``` + +```bash +terraform plan -out=tfplan +terraform apply tfplan + +terraform output storage_account_name +terraform output container_name +``` + +**Phase 2: Platform Infrastructure** + +```bash +cd terraform/azure/platform/ +``` + +Create `backend.tfvars`: + +```hcl +resource_group_name = "codemie-terraform-state" +storage_account_name = "codemiestate" +container_name = "tfstate" +key = "codemie/terraform.tfstate" +``` + +Create `terraform.tfvars`: + +```hcl +location = "westeurope" +platform_name = "codemie" +vm_size = "Standard_E4s_v5" +vm_os_disk_size = 100 +platform_domain_name = "" +``` + +```bash +terraform init -backend-config=backend.tfvars +terraform plan -out=tfplan +terraform apply tfplan + +# Note outputs for Phase 4: +terraform output vm_private_ip +terraform output storage_account_name +terraform output key_vault_url +terraform output bastion_name +terraform output resource_group_name +terraform output vm_resource_id +``` + +**Phase 3: AI Models (Optional)** + +Skip this phase if `DEPLOY_AI_MODELS="false"` or you have an existing Azure OpenAI endpoint. + +```bash +cd terraform/azure/ai-models/ +``` + +Create `backend.tfvars` (reuse same state backend): + +```hcl +resource_group_name = "codemie-terraform-state" +storage_account_name = "codemiestate" +container_name = "tfstate" +key = "codemie/ai-models.tfstate" +``` + +```bash +terraform init -backend-config=backend.tfvars +terraform plan -out=tfplan +terraform apply tfplan + +terraform output azure_openai_endpoint +terraform output azure_client_id +terraform output azure_client_secret +``` + +After completing infrastructure provisioning, proceed to [Application Provisioning (BYO Mode)](../../platform-deployment/automated/on-vm) to deploy the CodeMie stack. + + + + +**Deployment Phases (GCP)** + +| Phase | Description | Directory | +| ------------------------------------ | ------------------------------------------------------- | ------------------------------- | +| **Phase 1: State Backend** | Creates GCS bucket for Terraform state | `terraform/gcp/remote-backend/` | +| **Phase 2: Platform Infrastructure** | Provisions VM, GCS bucket, Cloud KMS key, DNS, firewall | `terraform/gcp/platform/` | + +**Phase 1: Terraform State Backend** + +```bash +cd terraform/gcp/remote-backend/ +terraform init +``` + +Create `terraform.tfvars`: + +```hcl +project_id = "my-codemie-project" +region = "europe-west3" +states_bucket_name = "codemie-tfstate" +``` + +```bash +terraform plan -out=tfplan +terraform apply tfplan +# Note the GCS bucket name from outputs +``` + +**Phase 2: Platform Infrastructure** + +```bash +cd terraform/gcp/platform/ +``` + +Create `backend.tfvars`: + +```hcl +bucket = "codemie-tfstate" +prefix = "codemie/platform" +``` + +Create `terraform.tfvars`: + +```hcl +project_id = "my-codemie-project" +region = "europe-west3" +zone_suffix = "a" +platform_name = "codemie" +machine_type = "n2-highmem-4" +disk_size = 100 +platform_domain_name = "" +``` + +```bash +terraform init -backend-config=backend.tfvars +terraform plan -out=tfplan +terraform apply tfplan + +# Note outputs for Phase 3: +terraform output vm_private_ip +terraform output gcs_bucket_name +terraform output kms_key_id +terraform output instance_name +terraform output zone +``` + +After completing infrastructure provisioning, proceed to [Application Provisioning (BYO Mode)](../../platform-deployment/automated/on-vm) to deploy the CodeMie stack. + + + + +--- + +## Next Steps + +Infrastructure provisioning is complete. Proceed to [Application Provisioning (BYO Mode)](../../platform-deployment/automated/on-vm) to deploy the CodeMie stack onto the provisioned VM. diff --git a/docs/admin/deployment/platform-deployment/automated/index.mdx b/docs/admin/deployment/platform-deployment/automated/index.mdx new file mode 100644 index 00000000..0c0f3356 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/automated/index.mdx @@ -0,0 +1,37 @@ +--- +id: platform-automated-overview +title: Automated Platform Deployment +sidebar_label: Automated Deployment +sidebar_position: 1 +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + +# Automated Platform Deployment + +Automated deployment uses scripts to install all AI/Run CodeMie components in the correct dependency order. + +:::tip Recommended Approach +Scripted deployment is recommended for standard installations as it automates component ordering, validates prerequisites, and ensures consistent configuration across all components. +::: + +## Deployment Tracks + + + + +
+ diff --git a/docs/admin/deployment/platform-deployment/automated/kubernetes.mdx b/docs/admin/deployment/platform-deployment/automated/kubernetes.mdx new file mode 100644 index 00000000..9cd569c9 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/automated/kubernetes.mdx @@ -0,0 +1,379 @@ +--- +id: platform-automated-kubernetes +title: Automated Kubernetes Platform Deployment +sidebar_label: Kubernetes +sidebar_position: 2 +pagination_prev: admin/deployment/platform-deployment/automated/platform-automated-overview +pagination_next: null +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Automated Kubernetes Platform Deployment + +This guide walks you through deploying all AI/Run CodeMie application components onto a Kubernetes cluster using the `helm-charts.sh` script. The script handles component installation in the correct dependency order for AWS (EKS), GCP (GKE), and Azure (AKS). + +:::tip Recommended Approach +Scripted deployment is recommended for standard installations as it automates component ordering, validates prerequisites, and ensures consistent configuration across all components. +::: + +## Overview + +The `helm-charts.sh` script from the [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) repository automates the installation of: + +- **Infrastructure services** — Nginx Ingress Controller, cloud-specific Storage Class +- **Data layer** — Elasticsearch +- **Security components** — Keycloak Operator, Keycloak, OAuth2 Proxy +- **Messaging system** — NATS, NATS Auth Callout +- **Core CodeMie services** — API, UI, MCP Connect, Mermaid Server +- **Observability stack** — Fluent Bit, Kibana, Kibana Dashboards + +## Prerequisites + +### Verification Checklist + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: `kubectl` configured for EKS cluster +- [ ] **Container Registry**: Completed [Container Registry Access](../../prerequisites/kubernetes.mdx#container-registry-access) setup (pull secret `gcp-artifact-registry` exists) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Deployment Outputs**: Have `deployment_outputs.env` from infrastructure deployment +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI, `aws` CLI + + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: Connected to Jumpbox VM and `kubectl` configured for AKS +- [ ] **Container Registry**: Completed [Container Registry Access](../../prerequisites/kubernetes.mdx#container-registry-access) setup (pull secret `gcp-artifact-registry` exists) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Deployment Outputs**: Have `deployment_outputs.env` from infrastructure deployment +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI, `az` CLI + + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: Connected to Bastion Host (for private clusters) or `kubectl` configured for GKE +- [ ] **Container Registry**: Completed [Container Registry Access](../../prerequisites/kubernetes.mdx#container-registry-access) setup (pull secret `gcp-artifact-registry` exists) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI + + + + + +:::warning Container Registry Access Required +The `gcp-artifact-registry` pull secret must exist before running the script. Complete [Container Registry Access](../../prerequisites/kubernetes.mdx#container-registry-access) setup before proceeding. +::: + +--- + +## Quick Start + +### Step 1: Clone Repository + +```bash +git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git +cd codemie-helm-charts +``` + +### Step 2: Configure Cloud-Specific Values + + + + +Source the infrastructure outputs and update AWS-specific placeholders in the values files: + +```bash +# Source the deployment outputs +source deployment_outputs.env + +# Update CodeMie API values with AWS-specific configuration +sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_DEFAULT_REGION%%/${AWS_DEFAULT_REGION}/g" codemie-api/values-aws.yaml +sed -i "s|%%EKS_AWS_ROLE_ARN%%|${EKS_AWS_ROLE_ARN}|g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_KMS_KEY_ID%%/${AWS_KMS_KEY_ID}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_S3_BUCKET_NAME%%/${AWS_S3_BUCKET_NAME}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_S3_REGION%%/${AWS_S3_REGION}/g" codemie-api/values-aws.yaml + +# Update domain in all remaining values-aws.yaml files +CODEMIE_DOMAIN_NAME="airun.example.com" +find . -name "values-aws.yaml" -exec sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" {} \; +``` + +| Placeholder | Description | Source | +| ------------------------ | ----------------- | ------------------------------------------------ | +| `%%DOMAIN%%` | DNS zone name | `deployment_outputs.env` → `CODEMIE_DOMAIN_NAME` | +| `%%AWS_DEFAULT_REGION%%` | AWS region | `deployment_outputs.env` → `AWS_DEFAULT_REGION` | +| `%%EKS_AWS_ROLE_ARN%%` | EKS IRSA role ARN | `deployment_outputs.env` → `EKS_AWS_ROLE_ARN` | +| `%%AWS_KMS_KEY_ID%%` | KMS key ID | `deployment_outputs.env` → `AWS_KMS_KEY_ID` | +| `%%AWS_S3_BUCKET_NAME%%` | S3 bucket name | `deployment_outputs.env` → `AWS_S3_BUCKET_NAME` | +| `%%AWS_S3_REGION%%` | S3 bucket region | `deployment_outputs.env` → `AWS_S3_REGION` | + + + + +Update the domain placeholder in all Azure values files: + +```bash +# Use your DNS zone name from deployment_outputs.env +CODEMIE_DOMAIN_NAME="airun.example.com" + +# Update all values-azure.yaml files (default placeholder is private.lab.com) +find . -name "values-azure.yaml" -exec sed -i "s/private.lab.com/$CODEMIE_DOMAIN_NAME/g" {} \; +``` + +| Component | File | Placeholder | +| ---------------- | --------------------------------- | ------------------------- | +| **Kibana** | `kibana/values-azure.yaml` | `*.private.lab.com` | +| **Keycloak** | `keycloak-helm/values-azure.yaml` | `*.private.lab.com` | +| **OAuth2 Proxy** | `oauth2-proxy/values-azure.yaml` | `*.private.lab.com` | +| **CodeMie UI** | `codemie-ui/values-azure.yaml` | `codemie.private.lab.com` | +| **CodeMie API** | `codemie-api/values-azure.yaml` | `*.private.lab.com` | + + + + +Replace domain and GCP-specific placeholders in the values files: + +```bash +# Set your values (from Terraform outputs or deployment_outputs.env) +DOMAIN="airun.example.com" +PROJECT_ID="my-gcp-project" +REGION="europe-west3" + +# Replace domain in all GCP values files +find . -name "values-gcp.yaml" -exec sed -i "s/%%DOMAIN%%/$DOMAIN/g" {} \; + +# Replace GCP parameters in CodeMie API +sed -i "s/%%GOOGLE_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_REGION%%/$REGION/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_KMS_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_KMS_REGION%%/$REGION/g" codemie-api/values-gcp.yaml +``` + +| Placeholder | Description | Source | +| --------------------------- | ----------------------- | -------------------------------- | +| `%%DOMAIN%%` | DNS zone name | Terraform outputs → `dns_name` | +| `%%GOOGLE_PROJECT_ID%%` | GCP project ID | Terraform outputs → `project_id` | +| `%%GOOGLE_REGION%%` | GCP region | Terraform outputs → `region` | +| `%%GOOGLE_KMS_PROJECT_ID%%` | GCP project ID with KMS | Same as `project_id` | +| `%%GOOGLE_KMS_REGION%%` | GCP KMS region | Same as `region` | + +**Files requiring domain configuration:** +`kibana/values-gcp.yaml`, `keycloak-helm/values-gcp.yaml`, `oauth2-proxy/values-gcp.yaml`, `codemie-ui/values-gcp.yaml`, `codemie-api/values-gcp.yaml` + +--- + +**Create Service Account Key** + +Create the service account key for Kubernetes to access GCP services (Vertex AI, Cloud KMS): + +1. Open **IAM & Admin** in Google Cloud Console +2. Locate the `codemie-gsa` service account (created by Terraform) +3. Create a new JSON key +4. Save it as `codemie-helm-charts/codemie-gsa-key.json` + +```bash +ls -la codemie-gsa-key.json +``` + +:::warning Key Security +This key grants access to Vertex AI and Cloud KMS. Keep it secure and do not commit it to version control. +::: + +--- + +**Configure LoadBalancer Type** (private vs public) + +The default configuration is **private access** (Internal LoadBalancer). No changes are needed for a private cluster. + +For **public access**, modify these files before running the deployment script: + +Edit `ingress-nginx/values-gcp.yaml`: + +```yaml +ingress-nginx: + controller: + service: + annotations: {} # Remove the Internal annotation + type: LoadBalancer + loadBalancerSourceRanges: + - x.x.x.x/24 # Your office network (required for security) + enableHttp: false +``` + +Edit `codemie-nats/values-gcp.yaml`: + +```yaml +service: + merge: + metadata: + annotations: {} # Remove the Internal annotation + spec: + type: LoadBalancer + loadBalancerSourceRanges: + - x.x.x.x/24 +``` + +:::danger Security Critical +Never deploy a public LoadBalancer without `loadBalancerSourceRanges` configured. +::: + + + + +### Step 3: Authenticate to Container Registry + +```bash +export GOOGLE_APPLICATION_CREDENTIALS=key.json + +gcloud auth application-default print-access-token | \ + helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev +``` + +### Step 4: Get Latest CodeMie Version + +```bash +bash get-codemie-latest-release-version.sh -c key.json +# Note the version (e.g., 2.26.0) for the next step +``` + +### Step 5: Configure Optional Components (If Required) + +| Component | Description | +| --------- | ------------------------------------------------------------------- | +| `litellm` | LiteLLM Proxy — unified LLM API, multi-model routing, cost tracking | +| `pgadmin` | PostgreSQL admin interface for database inspection | + +:::warning LiteLLM Configuration Required +If deploying with `--optional litellm`, complete the [LiteLLM Proxy Installation and Configuration Guide](../../extensions/litellm-proxy/index.md) **before** running the deployment script. +::: + +Skip this step if not deploying optional components. + +### Step 6: Run Deployment Script + + + + +```bash +# Standard installation with all core components +bash helm-charts.sh --cloud aws --version --mode all + +# With LiteLLM proxy for multi-model routing +bash helm-charts.sh --cloud aws --version --mode all --optional litellm + +# With all optional components +bash helm-charts.sh --cloud aws --version --mode all --optional litellm,pgadmin + +# Cluster with existing Nginx Ingress (skip ingress installation) +bash helm-charts.sh --cloud aws --version --mode recommended + +# Update existing installation (core components only) +bash helm-charts.sh --cloud aws --version --mode update +``` + + + + +```bash +# Initial installation with all core components +bash helm-charts.sh --cloud azure --version --mode all + +# Upgrade existing deployment to new version +bash helm-charts.sh --cloud azure --version --mode update + +# Add LiteLLM to existing installation +bash helm-charts.sh --cloud azure --version --mode recommended --optional litellm + +# Enterprise installation with all optional components +bash helm-charts.sh --cloud azure --version --mode all --optional litellm,pgadmin +``` + + + + +```bash +# Standard installation with all core components +bash helm-charts.sh --cloud gcp --version --mode all + +# With database management tools +bash helm-charts.sh --cloud gcp --version --mode all --optional pgadmin + +# With LiteLLM for multi-model AI testing +bash helm-charts.sh --cloud gcp --version --mode recommended --optional litellm + +# Full-featured installation with all optional components +bash helm-charts.sh --cloud gcp --version --mode all --optional litellm,pgadmin +``` + + + + +Replace `` with the version obtained in Step 4 (e.g., `2.26.0`). + +:::tip Idempotent Script +The deployment script is idempotent — you can safely re-run it after a failure. Simply run it again with the same parameters to continue or retry. +::: + +--- + +## Configuration Reference + +### Script Parameters + +| Parameter | Description | Required | Values | +| --------------- | ------------------------- | -------- | -------------------------------------- | +| `-h, --help` | Show help message | No | — | +| `-c, --cloud` | Target cloud provider | Yes | `aws`, `gcp`, `azure` | +| `-v, --version` | CodeMie component version | Yes | e.g., `2.26.0` | +| `-m, --mode` | Installation mode | Yes | `all`, `recommended`, `update` | +| `--optional` | Optional components | No | `litellm`, `pgadmin` (comma-separated) | + +### Deployment Modes + +| Mode | Components Installed | Use Case | +| ------------- | ------------------------------------------------------------ | -------------------------------------- | +| `all` | All components including Nginx Ingress Controller | Fresh cluster without existing ingress | +| `recommended` | All components except Nginx Ingress Controller | Cluster with existing ingress | +| `update` | Only CodeMie core components (API, UI, MCP Connect, Mermaid) | Updating an existing installation | + +--- + +## GCP: Post-Deployment DNS Configuration + +For GCP clusters with **public access**, configure DNS records after LoadBalancers are provisioned: + +**Wildcard record for Nginx Ingress** (covers all subdomains): + +```bash +kubectl get service ingress-nginx-controller -n ingress-nginx \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}' +``` + +Add an A record: `*.airun.example.com → ` + +**NATS record for Plugin Engine**: + +```bash +kubectl get service codemie-nats -n codemie \ + -o jsonpath='{.status.loadBalancer.ingress[0].ip}' +``` + +Add an A record: `nats-codemie.airun.example.com → ` + +--- + +## Next Steps + +After successful deployment, proceed to **[Accessing Applications](../../accessing-applications.mdx)** to verify access and complete initial configuration. diff --git a/docs/admin/deployment/platform-deployment/automated/on-vm.mdx b/docs/admin/deployment/platform-deployment/automated/on-vm.mdx new file mode 100644 index 00000000..13fe1342 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/automated/on-vm.mdx @@ -0,0 +1,157 @@ +--- +id: on-vm +title: On-VM Application Deployment (BYO Mode) +sidebar_label: On VM +sidebar_position: 2 +pagination_prev: admin/deployment/infrastructure-deployment/infrastructure-deployment-on-vm +pagination_next: null +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# On-VM Application Deployment (BYO Mode) + +After the infrastructure is provisioned manually (VM, storage, networking, DNS), this step deploys the AI/Run CodeMie application stack using BYO (Bring Your Own) mode: `./deploy.sh --byo`. + +:::info Prerequisites +Complete all infrastructure phases from [On-VM Infrastructure Deployment](../../../infrastructure-deployment/infrastructure-deployment-on-vm) before proceeding. +::: + +## Application Provisioning + + + + +**Configure deployment.conf (BYO Mode)** + +`BYO_EC2_HOST` determines the application URL. Set it based on your network mode: + +| Network Mode | `BYO_EC2_HOST` | Access | +| ------------ | ------------------------------------------------- | ------------------- | +| Public IP | `ec2_public_ip` from Terraform outputs | Direct HTTPS to EIP | +| Private IP | `ec2_private_ip` from Terraform outputs | HTTPS via VPN only | +| Domain + ALB | Any IP (overridden by `BYO_PLATFORM_DOMAIN_NAME`) | HTTPS via ALB | + +Example `deployment.conf` for Public IP mode: + +```bash +TF_VAR_region="eu-north-1" +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" + +BYO_EC2_HOST="*.*.*.*" +BYO_EC2_USER="ubuntu" +BYO_EC2_SSH_KEY="./terraform/platform/codemie-key.pem" +BYO_EC2_SSH_MODE="ssm" +BYO_EC2_INSTANCE_ID="i-xxxxxxxxxxxxxxxxx" +BYO_AWS_S3_BUCKET_NAME="codemie-user-data" +BYO_AWS_KMS_KEY_ID="" +BYO_PLATFORM_DOMAIN_NAME="" +``` + +**Run BYO Deployment** + +```bash +cp /path/to/key.json ./key.json +./deploy.sh --byo +``` + +**Verify** + +```bash +curl -k https:///v1/healthcheck +``` + +Expected response: `{"status":"ok"}` + + + + +**Configure deployment.conf (BYO Mode)** + +Fill in the values from Terraform outputs (Phase 2 and Phase 3): + +```bash +CLOUD_PROVIDER="azure" +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" + +BYO_VM_HOST="" +BYO_VM_USER="azadmin" +BYO_VM_SSH_KEY="/path/to/codemie-key.pem" +BYO_VM_SSH_MODE="bastion" +BYO_AZURE_BASTION_NAME="" +BYO_AZURE_RESOURCE_GROUP="" +BYO_AZURE_VM_RESOURCE_ID="" +BYO_AZURE_STORAGE_ACCOUNT_NAME="" +BYO_AZURE_KEY_VAULT_URL="" +BYO_AZURE_KEY_NAME="codemie-key" +BYO_PLATFORM_DOMAIN_NAME="" + +# If DEPLOY_AI_MODELS=false: +# AZURE_OPENAI_ENDPOINT="" +# AZURE_CLIENT_ID="" +# AZURE_CLIENT_SECRET="" +``` + +**Run BYO Deployment** + +```bash +cp /path/to/key.json ./key.json +./deploy.sh --byo +``` + +**Verify** + +```bash +curl -k https:///v1/healthcheck +``` + +Expected response: `{"status":"ok"}` + + + + +**Configure deployment.conf (BYO Mode)** + +Fill in the values from Terraform outputs (Phase 2): + +```bash +CLOUD_PROVIDER="gcp" +CODEMIE_VERSION="2.26.0" +COMPOSE_PROFILE="enterprise" + +BYO_VM_HOST="" +BYO_VM_USER="ubuntu" +BYO_VM_SSH_KEY="/path/to/codemie-key" +BYO_VM_SSH_MODE="iap" +BYO_GCP_PROJECT_ID="" +BYO_GCP_ZONE="" +BYO_GCP_INSTANCE_NAME="" +BYO_GCS_BUCKET_NAME="" +BYO_GCP_KMS_KEY_ID="" +BYO_PLATFORM_DOMAIN_NAME="" +``` + +**Run BYO Deployment** + +```bash +cp /path/to/key.json ./key.json +./deploy.sh --byo +``` + +**Verify** + +```bash +curl -k https:///v1/healthcheck +``` + +Expected response: `{"status":"ok"}` + + + + +## Next Steps + +For configuration and onboarding proceed to the [Configuration Guide](../../../../configuration/). diff --git a/docs/admin/deployment/platform-deployment/index.mdx b/docs/admin/deployment/platform-deployment/index.mdx new file mode 100644 index 00000000..a2968f33 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/index.mdx @@ -0,0 +1,37 @@ +--- +id: platform-deployment-overview +title: Platform Deployment +sidebar_label: Platform Deployment +sidebar_position: 1 +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + +# Platform Deployment + +This section covers deploying AI/Run CodeMie application components onto a provisioned infrastructure. All guides support AWS, GCP, and Azure in a unified format using cloud tabs. + +:::info Prerequisites +Before proceeding, ensure you have completed [Infrastructure Deployment](../infrastructure-deployment/) and have a running Kubernetes cluster or VM with the `deployment_outputs.env` file from the infrastructure phase. +::: + +## Deployment Methods + + + + +
+ diff --git a/docs/admin/deployment/platform-deployment/manual/index.mdx b/docs/admin/deployment/platform-deployment/manual/index.mdx new file mode 100644 index 00000000..19983683 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/index.mdx @@ -0,0 +1,48 @@ +--- +id: platform-manual-overview +title: Manual Platform Deployment +sidebar_label: Manual Deployment +sidebar_position: 1 +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + +# Manual Platform Deployment + +Manual deployment installs each AI/Run CodeMie component individually using Helm charts, giving you granular control over configuration and installation order. + +:::info When to Use Manual Deployment +Use manual deployment when you need fine-grained control over individual component configuration, want to selectively deploy certain components, or are troubleshooting specific services. + +If you prefer automated deployment, see [Automated Deployment](../automated/) instead. +::: + +## Deployment Tracks + + + +
+
+ + +## Kubernetes Component Installation Order + +For Kubernetes, components must be installed in the following order to satisfy dependencies: + +1. [Kubernetes Components](./kubernetes/k8s-components.mdx) — Storage Class + Nginx Ingress +2. [Data Layer](./kubernetes/data-layer.mdx) — Elasticsearch +3. [Security and Identity](./kubernetes/security-and-identity.mdx) — Keycloak Operator, Keycloak, OAuth2 Proxy +4. [Plugin Engine](./kubernetes/plugin-engine.mdx) — NATS, NATS Auth Callout +5. [Core Components](./kubernetes/core-components.mdx) — CodeMie API, UI, MCP Connect, Mermaid +6. [Observability](./kubernetes/observability.mdx) — Fluent Bit, Kibana, Dashboards + +:::warning Respect Installation Order +Installing components out of order will cause deployment failures. Always follow the numbered sequence. +::: diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/core-components.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/core-components.mdx new file mode 100644 index 00000000..1ed5c4b8 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/core-components.mdx @@ -0,0 +1,117 @@ +--- +id: core-components +title: Core Components +sidebar_label: Core Components +sidebar_position: 6 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/plugin-engine +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/observability +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CoreComponentsOverview from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-overview.mdx'; +import CoreComponentsMcpConnect from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-mcp-connect.mdx'; +import CoreComponentsMermaid from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-mermaid.mdx'; +import CoreComponentsUi from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-ui.mdx'; +import CoreComponentsApi from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-api.mdx'; +import CoreComponentsAccess from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-access.mdx'; +import CoreComponentsValidation from '../../../common/deployment/components-deployment/manual-deployment/core/_core-components-validation.mdx'; + + + + + + + +## CodeMie UI Installation + + + + + + + + + + + + + +## CodeMie API Installation + + + + + + + + + + +CodeMie API is the backend service that handles all business logic, AI orchestration, and data processing. + +**Step 1: Configure API Values** + +Verify the values in `codemie-api/values-gcp.yaml` are correct: + +- `%%DOMAIN%%` should be replaced with your DNS zone name (e.g., `airun.example.com`) +- `%%GOOGLE_PROJECT_ID%%` should be replaced with your GCP project ID where Vertex AI is available +- `%%GOOGLE_KMS_PROJECT_ID%%` should be replaced with your GCP project ID where KMS key is available +- `%%GOOGLE_REGION%%` should be replaced with your GCP region (e.g., `europe-west3`) +- `%%GOOGLE_KMS_REGION%%` should be replaced with your GCP KMS region (e.g., `europe-west3`) + +:::tip Domain Configuration +If you followed the Getting Started steps, these replacements should already be done. +::: + +**Step 2: Copy Elasticsearch Credentials** + +```bash +kubectl get secret elasticsearch-master-credentials -n elastic -o yaml | \ + sed '/namespace:/d' | \ + kubectl apply -n codemie -f - +``` + +**Step 3: Create Google Service Account Secret** + +```bash +kubectl create secret generic google-service-account \ + --namespace codemie \ + --from-file=gcp-service-account.json=codemie-gsa-key.json +``` + +:::warning Service Account Key +Ensure the `codemie-gsa-key.json` file exists in your current directory. This key grants access to Vertex AI and Cloud KMS. +::: + +**Step 4: Install CodeMie API Helm Chart** + +```bash +helm upgrade --install codemie-api \ + oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie \ + --version x.y.z \ + --namespace codemie \ + -f ./codemie-api/values-gcp.yaml \ + --wait \ + --timeout 600s +``` + +**Step 5: Verify CodeMie API Deployment** + +```bash +kubectl get pods -n codemie | grep codemie-api +kubectl get deployment -n codemie codemie-api +kubectl logs -n codemie deployment/codemie-api --tail=100 +kubectl exec -n codemie deployment/codemie-api -- curl -s http://localhost:8080/health +``` + + + + + + + diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/data-layer.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/data-layer.mdx new file mode 100644 index 00000000..efb9c9b1 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/data-layer.mdx @@ -0,0 +1,65 @@ +--- +id: data-layer +title: Data Layer +sidebar_label: Data Layer +sidebar_position: 3 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/k8s-components +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/security-and-identity +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import DataLayerOverview from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-overview.mdx'; +import DataLayerElasticsearch from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-elasticsearch.mdx'; +import DataLayerPostgresConfig from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-config.mdx'; +import DataLayerPostgresIamSetup from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-iam-setup.mdx'; +import DataLayerPostgresSecretAws from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-aws.mdx'; +import DataLayerPostgresSecretCommon from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-postgresql-secret-common.mdx'; +import DataLayerValidation from '../../../common/deployment/components-deployment/manual-deployment/data-layer/_data-layer-validation.mdx'; + + + +Elasticsearch installation is identical across cloud providers except for the Helm values file. Substitute `values-.yaml` with `values-aws.yaml`, `values-azure.yaml`, or `values-gcp.yaml` for your cloud. + + + +## PostgreSQL Configuration + +PostgreSQL setup differs on AWS, which uses IAM database authentication instead of a static password. Azure and GCP both connect with a static password and only differ in their managed service name and host. + + + + + + + + + + + +Substitute `` with your managed PostgreSQL service's connection host: + +| Cloud Provider | Managed Service | Example Host | +| -------------- | ----------------------------- | ---------------------------------------------- | +| Azure | Azure Database for PostgreSQL | `codemie-postgres.postgres.database.azure.com` | +| GCP | GCP Cloud SQL PostgreSQL | `10.0.0.5:5432` (private IP) | + + + + + + + + diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/index.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/index.mdx new file mode 100644 index 00000000..4eb4676f --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/index.mdx @@ -0,0 +1,158 @@ +--- +id: platform-manual-kubernetes-overview +title: Manual Kubernetes Deployment Overview +sidebar_label: Overview +sidebar_position: 1 +pagination_prev: admin/deployment/platform-deployment/manual/platform-manual-overview +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/k8s-components +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Manual Kubernetes Deployment + +Manual deployment installs each AI/Run CodeMie component individually using Helm charts. All three cloud providers are supported: AWS (EKS), GCP (GKE), and Azure (AKS). + +:::info When to Use Manual Deployment +Use manual deployment when you need fine-grained control over individual component configuration, want to selectively deploy certain components, or are troubleshooting specific services. + +For automated installation, see [Automated Deployment](../../automated/kubernetes.mdx) instead. +::: + +## Component Installation Order + +Components must be installed in the following order to satisfy dependencies: + +| Step | Component | Purpose | +| ---- | ---------------------------------------------------- | ----------------------------------------- | +| 1 | [Kubernetes Components](./k8s-components.mdx) | Storage Class + Nginx Ingress Controller | +| 2 | [Data Layer](./data-layer.mdx) | Elasticsearch + PostgreSQL connection | +| 3 | [Security and Identity](./security-and-identity.mdx) | Keycloak Operator, Keycloak, OAuth2 Proxy | +| 4 | [Plugin Engine](./plugin-engine.mdx) | NATS, NATS Auth Callout | +| 5 | [Core Components](./core-components.mdx) | CodeMie API, UI, MCP Connect, Mermaid | +| 6 | [Observability](./observability.mdx) | Fluent Bit, Kibana, Kibana Dashboards | + +:::warning Respect Installation Order +Installing components out of order will cause deployment failures. Always follow the numbered sequence to ensure dependencies are satisfied. +::: + +## Prerequisites + +### Verification Checklist + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: `kubectl` configured for EKS cluster (see [Cluster Access](../../../prerequisites/kubernetes.mdx#cluster-access)) +- [ ] **Container Registry**: `gcp-artifact-registry` pull secret exists (see [Container Registry Access](../../../prerequisites/kubernetes.mdx#container-registry-access)) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Deployment Outputs**: Have `deployment_outputs.env` from infrastructure deployment +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI, `aws` CLI + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: Connected to Jumpbox VM and `kubectl` configured for AKS (see [Cluster Access](../../../prerequisites/kubernetes.mdx#cluster-access)) +- [ ] **Container Registry**: `gcp-artifact-registry` pull secret exists (see [Container Registry Access](../../../prerequisites/kubernetes.mdx#container-registry-access)) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Deployment Outputs**: Have `deployment_outputs.env` from infrastructure deployment +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI, `az` CLI + + + + +- [ ] **Infrastructure Deployed**: Completed [Infrastructure Deployment](../../../infrastructure-deployment/kubernetes.mdx) phase +- [ ] **Cluster Access**: Connected to Bastion Host (private cluster) or `kubectl` configured for GKE (see [Cluster Access](../../../prerequisites/kubernetes.mdx#cluster-access)) +- [ ] **Container Registry**: `gcp-artifact-registry` pull secret exists (see [Container Registry Access](../../../prerequisites/kubernetes.mdx#container-registry-access)) +- [ ] **Helm Installed**: Helm 3.16.0+ +- [ ] **Repository Cloned**: `codemie-helm-charts` available locally +- [ ] **Tools**: `kubectl`, `helm`, `gcloud` CLI + + + + +## Getting Started + +### Step 1: Clone Repository + +```bash +git clone git@gitbud.epam.com:epm-cdme/codemie-helm-charts.git +cd codemie-helm-charts +``` + +### Step 2: Configure Cloud-Specific Values + + + + +```bash +source deployment_outputs.env + +sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_DEFAULT_REGION%%/${AWS_DEFAULT_REGION}/g" codemie-api/values-aws.yaml +sed -i "s|%%EKS_AWS_ROLE_ARN%%|${EKS_AWS_ROLE_ARN}|g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_KMS_KEY_ID%%/${AWS_KMS_KEY_ID}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_S3_BUCKET_NAME%%/${AWS_S3_BUCKET_NAME}/g" codemie-api/values-aws.yaml +sed -i "s/%%AWS_S3_REGION%%/${AWS_S3_REGION}/g" codemie-api/values-aws.yaml + +CODEMIE_DOMAIN_NAME="airun.example.com" +find . -name "values-aws.yaml" -exec sed -i "s/%%DOMAIN%%/${CODEMIE_DOMAIN_NAME}/g" {} \; +``` + + + + +```bash +CODEMIE_DOMAIN_NAME="airun.example.com" +find . -name "values-azure.yaml" -exec sed -i "s/private.lab.com/$CODEMIE_DOMAIN_NAME/g" {} \; +``` + + + + +```bash +DOMAIN="airun.example.com" +PROJECT_ID="my-gcp-project" +REGION="europe-west3" + +find . -name "values-gcp.yaml" -exec sed -i "s/%%DOMAIN%%/$DOMAIN/g" {} \; +sed -i "s/%%GOOGLE_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_REGION%%/$REGION/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_KMS_PROJECT_ID%%/$PROJECT_ID/g" codemie-api/values-gcp.yaml +sed -i "s/%%GOOGLE_KMS_REGION%%/$REGION/g" codemie-api/values-gcp.yaml +``` + +Also create the GCP service account key file: + +1. Open **IAM & Admin** in Google Cloud Console +2. Locate the `codemie-gsa` service account +3. Create and download a new JSON key +4. Save as `codemie-helm-charts/codemie-gsa-key.json` + + + + +### Step 3: Authenticate to Container Registry + +```bash +export GOOGLE_APPLICATION_CREDENTIALS=key.json + +gcloud auth application-default print-access-token | \ + helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev +``` + +### Step 4: Get CodeMie Version + +```bash +bash get-codemie-latest-release-version.sh -c key.json +# Note the version (e.g., 2.26.0) — you will use it in each helm install command +``` + +## Begin Installation + +Start the installation process with **[Kubernetes Components](./k8s-components.mdx)** and follow each guide in numbered order. diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/k8s-components.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/k8s-components.mdx new file mode 100644 index 00000000..4ede8432 --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/k8s-components.mdx @@ -0,0 +1,115 @@ +--- +id: k8s-components +title: Kubernetes Components +sidebar_label: Kubernetes Components +sidebar_position: 2 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/platform-manual-kubernetes-overview +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/data-layer +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorageIngressOverview from '../../../common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-overview.mdx'; +import StorageIngressNginx from '../../../common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-nginx.mdx'; +import StorageClassInstallation from '../../../common/deployment/components-deployment/manual-deployment/k8s/_storage-class-installation.mdx'; +import StorageIngressValidation from '../../../common/deployment/components-deployment/manual-deployment/k8s/_storage-ingress-validation.mdx'; + + + + + +### Step 4: Configure DNS Record + +Create a DNS record pointing to the ingress controller's load balancer. The exact steps depend on your cloud provider's DNS service. + + + + +```bash +INGRESS_HOST=$(kubectl get service ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') +echo "Ingress Host: ${INGRESS_HOST}" +``` + +Using **Route 53**: + +```bash +HOSTED_ZONE_ID=$(aws route53 list-hosted-zones-by-name \ + --dns-name airun.example.com \ + --query 'HostedZones[0].Id' \ + --output text | cut -d'/' -f3) + +aws route53 change-resource-record-sets \ + --hosted-zone-id ${HOSTED_ZONE_ID} \ + --change-batch '{ + "Changes": [{ + "Action": "UPSERT", + "ResourceRecordSet": { + "Name": "codemie.airun.example.com", + "Type": "CNAME", + "TTL": 300, + "ResourceRecords": [{"Value": "'${INGRESS_HOST}'"}] + } + }] + }' +``` + +**Parameters to adjust**: replace `airun.example.com` and `codemie.airun.example.com` with your domain values from `deployment_outputs.env`. + +**Verification**: + +```bash +aws route53 list-resource-record-sets \ + --hosted-zone-id ${HOSTED_ZONE_ID} \ + --query "ResourceRecordSets[?Name=='codemie.airun.example.com.']" + +nslookup codemie.airun.example.com +``` + + + + +Create an A record in your Azure Private DNS zone pointing to the ingress controller's IP: + +```bash +ingressip=$(kubectl get service ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].ip}') +echo "Ingress IP: ${ingressip}" + +az network private-dns record-set a add-record \ + -g CodeMieRG \ + -z airun.example.com \ + -n codemie \ + -a ${ingressip} +``` + +**Parameters to adjust**: + +- `-g CodeMieRG` — replace with your resource group name +- `-z airun.example.com` — replace with your Private DNS zone name +- `-n codemie` — replace with your desired hostname (subdomain) + +**Verification**: + +```bash +az network private-dns record-set a list \ + -g CodeMieRG \ + -z airun.example.com \ + -o table + +nslookup codemie.airun.example.com +``` + + + + +:::info DNS for GCP +For **private clusters**, DNS is automatically configured by the Terraform infrastructure deployment. No manual DNS step is required here. + +For **public clusters**, refer to the [Automated Deployment DNS guide](../../automated/kubernetes.mdx#gcp-post-deployment-dns-configuration) for adding the required A records. +::: + + + + + + + diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/observability.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/observability.mdx new file mode 100644 index 00000000..48b28a6b --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/observability.mdx @@ -0,0 +1,35 @@ +--- +id: observability +title: Observability +sidebar_label: Observability +sidebar_position: 7 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/core-components +pagination_next: null +--- + +import ObservabilityOverview from '../../../common/deployment/components-deployment/manual-deployment/observability/_observability-overview.mdx'; +import ObservabilityFluentBit from '../../../common/deployment/components-deployment/manual-deployment/observability/_observability-fluent-bit.mdx'; +import ObservabilityKibana from '../../../common/deployment/components-deployment/manual-deployment/observability/_observability-kibana.mdx'; +import ObservabilityDashboards from '../../../common/deployment/components-deployment/manual-deployment/observability/_observability-dashboards.mdx'; +import ObservabilityValidation from '../../../common/deployment/components-deployment/manual-deployment/observability/_observability-validation.mdx'; + + + + + +The steps below are identical across cloud providers except for the Helm values file and the Kibana URL. Substitute `values-.yaml` and `` with the values for your cloud: + +| Cloud Provider | Values File | Kibana URL | +| -------------- | ------------------- | ------------------------------ | +| AWS | `values-aws.yaml` | `https://kibana.` | +| Azure | `values-azure.yaml` | `https:///kibana` | +| GCP | `values-gcp.yaml` | `https://kibana.` | + +AWS and GCP expose Kibana on a dedicated subdomain; Azure exposes it as a path under your main domain. + + + + diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/plugin-engine.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/plugin-engine.mdx new file mode 100644 index 00000000..d5effbcf --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/plugin-engine.mdx @@ -0,0 +1,87 @@ +--- +id: plugin-engine +title: Plugin Engine +sidebar_label: Plugin Engine +sidebar_position: 5 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/security-and-identity +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/core-components +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import PluginEngineOverview from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-overview.mdx'; +import PluginEngineNatsInstallation from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-installation.mdx'; +import PluginEngineNatsAuthCallout from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-nats-auth-callout.mdx'; +import PluginEngineTlsConfiguration from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-tls-configuration.mdx'; +import PluginEnginePostValidation from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-post-validation.mdx'; +import PluginEngineNextSteps from '../../../common/deployment/components-deployment/manual-deployment/plugin-engine/_plugin-engine-next-steps.mdx'; + +## Overview + + + +## NATS Installation + +:::warning Deprecated +NATS is currently deprecated as part of the NATS retirement direction. +::: + + + + + + + + + + + + + +## NATS Auth Callout Installation + + + + + + + + + + + + + +## TLS Configuration + + + + + + + + + + + + + +## Post-Installation Validation + +After completing plugin engine installation, verify the following: + + + + + + + + + + + + + +## Next Steps + + diff --git a/docs/admin/deployment/platform-deployment/manual/kubernetes/security-and-identity.mdx b/docs/admin/deployment/platform-deployment/manual/kubernetes/security-and-identity.mdx new file mode 100644 index 00000000..4859ad8a --- /dev/null +++ b/docs/admin/deployment/platform-deployment/manual/kubernetes/security-and-identity.mdx @@ -0,0 +1,34 @@ +--- +id: security-and-identity +title: Security and Identity +sidebar_label: Security and Identity +sidebar_position: 4 +pagination_prev: admin/deployment/platform-deployment/manual/kubernetes/data-layer +pagination_next: admin/deployment/platform-deployment/manual/kubernetes/plugin-engine +--- + +import SecurityOverview from '../../../common/deployment/components-deployment/manual-deployment/security/_security-overview.mdx'; +import SecurityKeycloakOperator from '../../../common/deployment/components-deployment/manual-deployment/security/_security-keycloak-operator.mdx'; +import SecurityKeycloakInstall from '../../../common/deployment/components-deployment/manual-deployment/security/_security-keycloak-install.mdx'; +import SecurityOauth2Proxy from '../../../common/deployment/components-deployment/manual-deployment/security/_security-oauth2-proxy.mdx'; +import SecurityValidation from '../../../common/deployment/components-deployment/manual-deployment/security/_security-validation.mdx'; + + + + + +The steps below are identical across cloud providers except for the Helm values file and the Keycloak Admin URL. Substitute `values-.yaml` and `` with the values for your cloud: + +| Cloud Provider | Values File | Keycloak Admin URL | +| -------------- | ------------------- | ------------------------------------------- | +| AWS | `values-aws.yaml` | `https://keycloak./auth/admin` | +| Azure | `values-azure.yaml` | `https:///keycloak/admin` | +| GCP | `values-gcp.yaml` | `https://keycloak./auth/admin` | + +AWS and GCP expose Keycloak on a dedicated subdomain; Azure exposes it as a path under your main domain. + + + + + + diff --git a/docs/admin/deployment/prerequisites/index.mdx b/docs/admin/deployment/prerequisites/index.mdx new file mode 100644 index 00000000..8d242fb1 --- /dev/null +++ b/docs/admin/deployment/prerequisites/index.mdx @@ -0,0 +1,37 @@ +--- +id: prerequisites-overview +title: Prerequisites +sidebar_label: Prerequisites +sidebar_position: 2 +pagination_prev: admin/architecture/architecture-on-vm +--- + +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; +import NextSteps from '../common/deployment/prerequisites/_next-steps.mdx'; + +# Prerequisites + +This section outlines the requirements and prerequisites necessary for deploying AI/Run CodeMie. All requirements must be met before proceeding with the installation. + +## Prerequisite Sets + + + + +
+ + + diff --git a/docs/admin/deployment/prerequisites/kubernetes.mdx b/docs/admin/deployment/prerequisites/kubernetes.mdx new file mode 100644 index 00000000..571c1381 --- /dev/null +++ b/docs/admin/deployment/prerequisites/kubernetes.mdx @@ -0,0 +1,373 @@ +--- +id: prerequisites-kubernetes +title: Kubernetes Deployment Prerequisites +sidebar_label: Kubernetes +sidebar_position: 3 +pagination_prev: admin/deployment/prerequisites/prerequisites-overview +pagination_next: admin/deployment/prerequisites/prerequisites-on-vm +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import NetworkRequirements from '../common/deployment/prerequisites/_network-requirements.mdx'; +import ClusterRequirements from '../common/deployment/prerequisites/_cluster-requirements.mdx'; +import DeploymentMachineTools from '../common/deployment/prerequisites/_deployment-machine-tools.mdx'; + +# 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 + + + + +**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 +- **Sufficient Quota** for the required resources (EKS, RDS, networking, storage, etc.) + :::info Complete Resource List + For a detailed list of all AWS resources that will be provisioned, refer to the [Architecture](../../architecture/kubernetes.mdx) 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.) + :::info Complete Resource List + For a detailed list of all Azure resources that will be provisioned, refer to the [Architecture](../../architecture/kubernetes.mdx) 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.) + :::info Complete Resource List + For a detailed list of all GCP resources that will be provisioned, refer to the [Architecture](../../architecture/kubernetes.mdx) 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 access + - `roles/storage.admin` - For Cloud Storage management + - `roles/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](https://console.cloud.google.com/marketplace/product/google/iap.googleapis.com) | Secure identity-based access control | +| [Service Networking API](https://console.cloud.google.com/marketplace/product/google/servicenetworking.googleapis.com) | Private service connectivity | +| [Secret Manager API](https://console.cloud.google.com/marketplace/product/google/secretmanager.googleapis.com) | Centralized secrets management | +| [Vertex AI API](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com) | AI model integration and inference | + +:::info Vertex AI Models +Make sure you are familiar with Gemini models, their parameters, available regions, and other crucial details in the [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models). +::: + + + + +## Network Requirements + +### DNS and Certificate Requirements + + + + +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 + +:::tip Automatic Setup +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: + + + + +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](https://kubernetes.github.io/ingress-nginx/user-guide/tls/)) + + + + + + + + + + + + + + + + +## Kubernetes Cluster Requirements + + + + + + + + + + + + + + + + +_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** + +:::info GCP-Specific Requirement +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_NATIVE` with IP allocation policy (secondary ranges for pods and services) +- **HTTP Load Balancing Addon:** Enabled (default) + +:::warning Network Policy Disables Automatic NEGs +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: + +```yaml +service: + type: ClusterIP + port: 8080 + annotations: + cloud.google.com/neg: '{"ingress": true}' +``` + +::: + + + + + + + + + +**Cloud-Specific Tools:** + +| Tool | Version | Purpose | +| ---------------------------------------------------------------------------------------- | ------- | ----------------------- | +| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) | latest | AWS resource management | + + + + +**Cloud-Specific Tools:** + +| Tool | Version | Purpose | +| -------------------------------------------------------------------------- | ------- | ------------------------- | +| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | latest | Azure resource management | +| [kubelogin](https://azure.github.io/kubelogin/install.html) | latest | AKS authentication plugin | + + + + +:::note gcloud CLI Multi-Purpose +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](../infrastructure-deployment/kubernetes.mdx). + + + + +Obtain kubeconfig credentials for the EKS cluster: + +```bash +aws eks update-kubeconfig --region --name +``` + +Verify access: + +```bash +kubectl get nodes +``` + + + + +Connect to the Jumpbox VM via Bastion, then obtain kubeconfig credentials for the AKS cluster: + +```bash +az login +az account set --subscription +az aks get-credentials \ + --resource-group \ + --name \ + --overwrite-existing +kubelogin convert-kubeconfig -l azurecli +``` + +Verify access: + +```bash +kubectl get nodes +``` + + + + +For **private clusters**, connect via the Bastion Host first. Then obtain kubeconfig credentials for the GKE cluster: + +```bash +gcloud container clusters get-credentials --project --region +``` + +Verify access: + +```bash +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. + +:::info Obtaining key.json +Contact your CodeMie administrator or EPAM delivery team to obtain the `key.json` file for registry access. +::: + +Create the namespace and pull secret: + +```bash +kubectl create namespace codemie + +kubectl create secret docker-registry gcp-artifact-registry \ + --docker-server=https://europe-west3-docker.pkg.dev \ + --docker-email=`` \ + --docker-username=_json_key \ + --docker-password="$(cat key.json)" \ + -n codemie +``` + +Verify the secret: + +```bash +kubectl get secret gcp-artifact-registry -n codemie +``` + +:::info Pull Secret Usage +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: + +```yaml +imagePullSecrets: + - name: gcp-artifact-registry +``` + +::: + +## Required Repository Access + +You will need access to the following repositories to complete the deployment: + + + + +- **Terraform IAM Module:** [codemie-terraform-aws-iam](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-iam) +- **Terraform Platform Module:** [codemie-terraform-aws-platform](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-platform) +- **Terraform Remote Backend:** [codemie-terraform-aws-remote-backend](https://gitbud.epam.com/epm-cdme/codemie-terraform-aws-remote-backend) +- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) + + + + +- **Terraform Modules:** [codemie-terraform-azure](https://gitbud.epam.com/epm-cdme/codemie-terraform-azure) +- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) + + + + +- **Terraform Platform Modules:** [codemie-terraform-gcp-platform](https://gitbud.epam.com/epm-cdme/codemie-terraform-gcp-platform) +- **Helm Charts:** [codemie-helm-charts](https://gitbud.epam.com/epm-cdme/codemie-helm-charts) + + + + +:::info Air-Gapped Environments +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. +::: diff --git a/docs/admin/deployment/prerequisites/on-vm.mdx b/docs/admin/deployment/prerequisites/on-vm.mdx new file mode 100644 index 00000000..7b37892f --- /dev/null +++ b/docs/admin/deployment/prerequisites/on-vm.mdx @@ -0,0 +1,242 @@ +--- +id: prerequisites-on-vm +title: On-VM Deployment Prerequisites +sidebar_label: On VM +sidebar_position: 4 +pagination_prev: admin/deployment/prerequisites/prerequisites-kubernetes +pagination_next: admin/deployment/infrastructure-deployment/infrastructure-deployment-overview +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# On-VM Deployment Prerequisites + +This page outlines the requirements for the lightweight [On-VM deployment](../../infrastructure-deployment/) option, which runs the full AI/Run CodeMie platform on a single virtual machine using Docker Compose. + +## Account Requirements + + + + +- **Active AWS Account** with a region that supports [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) +- **IAM permissions** to create an IAM deployer role (one-time setup) +- **Sufficient quota** for: 1 EC2 instance, 1 VPC, 1 S3 bucket, 1 KMS key, 1 EIP +- **Network access**: Outbound internet access from EC2 (to pull Docker images, access Bedrock API); optional Route 53 hosted zone (if using a custom domain with ALB + ACM) + +:::tip IAM Deployer Role +The deployment uses a dedicated IAM role with scoped permissions. You only need broad IAM access to create this role once — subsequent deployments use the role. +::: + + + + +- **Active Azure Subscription** with sufficient quota for the required resources +- **Contributor role** (or equivalent) on the subscription to create VMs, Storage Accounts, Key Vaults, and DNS zones +- **AZURE_SUBSCRIPTION_ID** and **AZURE_TENANT_ID** — available in the Azure Portal under **Azure Active Directory → Overview** + +**Quota Requirements:** + +| Resource | Count | +| ---------------- | ----- | +| Standard_E4s_v5 | 1 | +| Azure Key Vault | 1 | +| Storage Account | 1 | +| Private DNS Zone | 1 | + + + + +- **Active GCP Project** with sufficient quota for the required resources +- The operator account must have the following roles or equivalent permissions: + - `roles/iap.tunnelResourceAccessor` — SSH access to the VM via IAP + - `roles/secretmanager.secretAccessor` — fetch SSH key from Secret Manager + - Permissions to create: GCE VM, GCS bucket, Cloud KMS key, Cloud DNS private zone, VPC firewall rules + +**Quota Requirements:** + +| Resource | Count | +| ---------------------- | ------------ | +| n2-highmem-4 VM | 1 | +| GCS Bucket | 1 | +| Cloud KMS Key | 1 | +| Cloud DNS Private Zone | 1 (optional) | + + + + +## Deployment Machine Tools + +The following tools must be installed on the machine where you run `./deploy.sh`: + + + + +| Tool | Version | Purpose | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------- | +| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | +| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) | latest | AWS resource management | +| [Session Manager Plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) | latest | SSH access via AWS SSM | +| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | +| openssl | latest | Secret generation | +| envsubst | latest | Template rendering | + +Verify installation: + +```bash +terraform version # Should show 1.15.x +aws --version # AWS CLI v2 +session-manager-plugin # Should print version info +jq --version +openssl version +envsubst --version +``` + + + + +| Tool | Version | Purpose | +| -------------------------------------------------------------------------- | ------- | ----------------------------------- | +| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | +| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | latest | Azure authentication and management | +| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | +| openssl | latest | Secret generation | +| envsubst | latest | Template rendering | + +Verify installation: + +```bash +terraform version # Should show 1.15.x +az version # Azure CLI +jq --version +openssl version +envsubst --version +``` + + + + +| Tool | Version | Purpose | +| -------------------------------------------------------------- | ------- | --------------------------------- | +| [Terraform](https://developer.hashicorp.com/terraform/install) | 1.15.x | Infrastructure provisioning | +| [gcloud CLI](https://cloud.google.com/sdk/docs/install) | latest | GCP authentication and management | +| [jq](https://jqlang.github.io/jq/download/) | latest | JSON parsing | +| openssl | latest | Secret generation | +| envsubst | latest | Template rendering | + +Verify installation: + +```bash +terraform version # Should show 1.15.x +gcloud version +jq --version +openssl version +envsubst --version +``` + + + + +:::info Enterprise Profile Only +If deploying the **Enterprise profile**, [nsc](https://github.com/nats-io/nsc) (latest) is also required on the deployment machine for NATS key generation. +::: + +## GCP Container Registry Access + +CodeMie container images are hosted on `europe-west3-docker.pkg.dev`. You need a **GCP service account key file** (`key.json`) with read access to the registry — this applies regardless of the cloud provider you deploy to. + +:::info Obtaining key.json +Contact your CodeMie administrator or EPAM delivery team to obtain the `key.json` file for registry access. +::: + +## Cloud Authentication + +Authenticate to your cloud provider before running the deployment: + + + + +```bash +# If using AWS SSO: +aws sso login --profile your-profile +export AWS_PROFILE=your-profile + +# Verify credentials: +aws sts get-caller-identity +``` + + + + +```bash +az login +az account set --subscription "" + +# Verify active subscription +az account show +``` + + + + +```bash +gcloud auth application-default login + +# Verify active project +gcloud config get-value project +``` + + + + +## Repository Access + +Clone the deployment repository: + +```bash +git clone https://gitbud.epam.com/epm-cdme/codemie-on-vm.git +cd codemie-on-vm +``` + +The repository structure: + + + + +| Directory | Purpose | +| -------------------------------------- | ---------------------------------------------- | +| `compose/` | Docker Compose files and service configuration | +| `deploy.sh` | Deployment script | +| `terraform/aws/codemie-on-vm-aws-iam/` | IAM deployer role Terraform module | +| `terraform/aws/remote-backend/` | S3 Terraform state bucket | +| `terraform/aws/platform/` | EC2, VPC, ALB, S3, KMS infrastructure | + + + + +| Directory | Purpose | +| --------------------------------- | ---------------------------------------------- | +| `compose/` | Docker Compose files and service configuration | +| `deploy.sh` | Deployment script | +| `destroy.sh` | Destroy script | +| `terraform/azure/remote-backend/` | Azure Storage Terraform state backend | +| `terraform/azure/platform/` | VM, Storage Account, Key Vault, DNS, NSG | +| `terraform/azure/ai-models/` | Azure OpenAI cognitive accounts (optional) | + + + + +| Directory | Purpose | +| ------------------------------- | ---------------------------------------------- | +| `compose/` | Docker Compose files and service configuration | +| `deploy.sh` | Deployment script | +| `destroy.sh` | Destroy script | +| `terraform/gcp/remote-backend/` | GCS bucket for Terraform state | +| `terraform/gcp/platform/` | VM, GCS bucket, KMS key, DNS, firewall | + + + + +:::info Air-Gapped Environments +If your deployment machine operates in an isolated environment without direct internet or repository access, the repository can be provided as a ZIP/TAR archive and transferred through approved channels. +::: diff --git a/docs/admin/index.mdx b/docs/admin/index.mdx index b3c08f45..8fa4010d 100644 --- a/docs/admin/index.mdx +++ b/docs/admin/index.mdx @@ -16,159 +16,44 @@ import FeatureGrid from '@site/src/components/FeatureGrid'; Welcome to the AI/Run CodeMie Administration Guide. This section provides comprehensive documentation for system administrators responsible for deploying, configuring, maintaining, and securing the CodeMie platform. -## Core Administration Areas - -### Deployment & Infrastructure - -Set up AI/Run CodeMie in your cloud environment with comprehensive deployment guides. - -## Kubernetes - - - - - - - -## VM - - - - - - - -## Other +## Administration Areas - - - - -### Configuration & Customization - -Configure the platform to meet your organization's requirements and integrate with existing systems. - - - - - -### Updates & Maintenance - -Keep your CodeMie platform up-to-date with the latest features, security patches, and component upgrades. - - - - - -## Additional Resources - - - ## Getting Help diff --git a/docs/admin/security/data-processing-storage.md b/docs/admin/security/data-processing-storage.md index 2630a319..cbb0298b 100644 --- a/docs/admin/security/data-processing-storage.md +++ b/docs/admin/security/data-processing-storage.md @@ -78,7 +78,7 @@ Keycloak uses a dedicated PostgreSQL cluster in Kubernetes that stores SSO feder **Elasticsearch** - **Vector Embeddings**: Semantic search vectors (generated by embeddings models) -- **Platform Components Logs**: Logs from core platform services (see [Core Components](../deployment/aws/kubernetes/components-deployment/manual-deployment/core-components.md)) +- **Platform Components Logs**: Logs from core platform services (see [Core Components](../deployment/platform-deployment/manual/kubernetes/core-components.mdx)) ## Data Processing Flows diff --git a/docs/admin/security/index.md b/docs/admin/security/index.md index e4342eaa..f9ff2e6f 100644 --- a/docs/admin/security/index.md +++ b/docs/admin/security/index.md @@ -7,10 +7,48 @@ pagination_prev: null pagination_next: admin/security/data-processing-storage --- +import FeatureCard from '@site/src/components/FeatureCard'; +import FeatureGrid from '@site/src/components/FeatureGrid'; + # Security & Compliance Welcome to the AI/Run CodeMie Security & Compliance documentation. This section provides comprehensive information about the platform's security architecture, data processing policies, storage mechanisms, and compliance controls. +## Security Topics + + + + + + +
+
+ + ## Overview The CodeMie platform is built with security-first principles, implementing industry-standard encryption, access controls, and data isolation mechanisms. The platform supports deployment in customer-controlled cloud environments, ensuring data sovereignty and compliance with regional data protection regulations. @@ -43,10 +81,7 @@ The CodeMie platform is built with security-first principles, implementing indus ## Core Security Principles & Architecture -This section describes the fundamental security patterns and practices implemented in the CodeMie platform: - -- **[Data Processing & Storage Architecture](./data-processing-storage.md)**: Detailed explanation of how data flows through the platform, storage layers, and regional distribution -- **[Image Allow-List for LLM Output](./llm-output-image-allow-list.md)**: Domain allow-list that gates every image rendered from assistant output, closing the prompt-injection exfiltration channel +The following principles underpin the fundamental security patterns and practices implemented in the CodeMie platform: ### 1. Defense in Depth diff --git a/docs/admin/update/3rd-party-components/elasticsearch/metrics-index-rotation.md b/docs/admin/update/3rd-party-components/elasticsearch/metrics-index-rotation.md index 3df77b21..3953da58 100644 --- a/docs/admin/update/3rd-party-components/elasticsearch/metrics-index-rotation.md +++ b/docs/admin/update/3rd-party-components/elasticsearch/metrics-index-rotation.md @@ -106,10 +106,7 @@ codemie_metrics_logs_write Change only the metrics output. Keep the infrastructure-log output and its `logs-codemie-infra` index configuration unchanged. -The cloud-specific deployment guides provide more information about the two output -types: [AWS](../../../../deployment/aws/kubernetes/components-deployment/manual-deployment/observability), -[Azure](../../../../deployment/azure/kubernetes/components-deployment/manual-deployment/observability), or -[GCP](../../../../deployment/gcp/kubernetes/components-deployment/manual-deployment/observability). +The [Observability Components Deployment](../../../../deployment/platform-deployment/manual/kubernetes/observability) guide provides more information about the two output types for AWS, Azure, and GCP. ## Step 4: Enable the rotation scheduler diff --git a/docs/admin/update/release-notes/release-notes.md b/docs/admin/update/release-notes/release-notes.md index 5401157c..4ba08cf1 100644 --- a/docs/admin/update/release-notes/release-notes.md +++ b/docs/admin/update/release-notes/release-notes.md @@ -281,8 +281,8 @@ No third-party component updates in this release. ```bash aws s3 cp s3:/// s3:/// --recursive ``` - - **Terraform state bucket encryption switched to SSE-KMS**, restricted to the deployer role. `aws-terraform.sh` migrates existing deployments automatically; for manual deployments, see [updated backend init commands](../../deployment/aws/kubernetes/infrastructure-deployment/manual-deployment.md#phase-2-terraform-backend-resources-deployment). - - **RDS PostgreSQL now uses IAM database authentication** — `codemie-api` on AWS connects to the RDS PostgreSQL instance using short-lived IAM authentication tokens instead of a static password. Existing deployments must be migrated — see [Upgrading an Existing Deployment to IAM Authentication](../../deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer.md#upgrading-an-existing-deployment-to-iam-authentication). + - **Terraform state bucket encryption switched to SSE-KMS**, restricted to the deployer role. `aws-terraform.sh` migrates existing deployments automatically; for manual deployments, see [updated backend init commands](../../deployment/infrastructure-deployment/kubernetes.mdx#manual-deployment). + - **RDS PostgreSQL now uses IAM database authentication** — `codemie-api` on AWS connects to the RDS PostgreSQL instance using short-lived IAM authentication tokens instead of a static password. Existing deployments must be migrated — see [Upgrading an Existing Deployment to IAM Authentication](../../deployment/platform-deployment/manual/kubernetes/data-layer.mdx#upgrading-an-existing-deployment-to-iam-authentication).

Hotfixes

diff --git a/sidebars.ts b/sidebars.ts index 7d60009a..d30c8206 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -413,6 +413,19 @@ const sidebars: SidebarsConfig = { }, collapsed: true, items: [ + { + type: 'category', + label: 'Architecture', + link: { + type: 'doc', + id: 'admin/architecture/architecture-overview', + }, + collapsed: true, + items: [ + 'admin/architecture/architecture-kubernetes', + 'admin/architecture/architecture-on-vm', + ], + }, { type: 'category', label: 'Deployment', @@ -424,310 +437,87 @@ const sidebars: SidebarsConfig = { items: [ { type: 'category', - label: 'AWS', + label: 'Prerequisites', + link: { + type: 'doc', + id: 'admin/deployment/prerequisites/prerequisites-overview', + }, collapsed: true, items: [ - { - type: 'category', - label: 'Kubernetes (EKS)', - link: { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/overview', - }, - collapsed: true, - items: [ - { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/prerequisites', - label: 'Prerequisites', - }, - { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/architecture', - label: 'Architecture', - }, - { - type: 'category', - label: 'Infrastructure Deployment', - link: { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment', - 'admin/deployment/aws/kubernetes/infrastructure-deployment/infrastructure-manual-deployment', - ], - }, - { - type: 'category', - label: 'CodeMie Components Deployment', - link: { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/components-deployment/components-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/aws/kubernetes/components-deployment/components-scripted-deployment', - { - type: 'category', - label: 'CodeMie Manual Deployment', - link: { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/manual-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/k8s-components', - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/data-layer', - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/security-and-identity', - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/plugin-engine', - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/core-components', - 'admin/deployment/aws/kubernetes/components-deployment/manual-deployment/observability', - ], - }, - ], - }, - { - type: 'doc', - id: 'admin/deployment/aws/kubernetes/accessing-applications', - label: 'Accessing Applications', - }, - ], - }, - { - type: 'category', - label: 'On VM (EC2)', - link: { - type: 'doc', - id: 'admin/deployment/aws/on-vm/overview', - }, - collapsed: true, - items: [ - 'admin/deployment/aws/on-vm/prerequisites', - 'admin/deployment/aws/on-vm/architecture', - { - type: 'category', - label: 'Deployment', - link: { - type: 'doc', - id: 'admin/deployment/aws/on-vm/deployment/deployment', - }, - collapsed: true, - items: [ - 'admin/deployment/aws/on-vm/deployment/scripted-deployment', - 'admin/deployment/aws/on-vm/deployment/manual-deployment', - 'admin/deployment/aws/on-vm/deployment/byo', - ], - }, - ], - }, + 'admin/deployment/prerequisites/prerequisites-kubernetes', + 'admin/deployment/prerequisites/prerequisites-on-vm', ], }, { type: 'category', - label: 'Azure', + label: 'Infrastructure Deployment', + link: { + type: 'doc', + id: 'admin/deployment/infrastructure-deployment/infrastructure-deployment-overview', + }, collapsed: true, items: [ - { - type: 'category', - label: 'Kubernetes (AKS)', - link: { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/overview', - }, - collapsed: true, - items: [ - { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/prerequisites', - label: 'Prerequisites', - }, - { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/architecture', - label: 'Architecture', - }, - { - type: 'category', - label: 'Infrastructure Deployment', - link: { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/azure/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment', - ], - }, - { - type: 'category', - label: 'CodeMie Components Deployment', - link: { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/components-deployment/components-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/azure/kubernetes/components-deployment/components-scripted-deployment', - { - type: 'category', - label: 'CodeMie Manual Deployment', - link: { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/manual-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/k8s-components', - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/data-layer', - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/security-and-identity', - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/plugin-engine', - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/core-components', - 'admin/deployment/azure/kubernetes/components-deployment/manual-deployment/observability', - ], - }, - ], - }, - { - type: 'doc', - id: 'admin/deployment/azure/kubernetes/accessing-applications', - label: 'Accessing Applications', - }, - ], - }, - { - type: 'category', - label: 'On VM (Azure VM)', - link: { - type: 'doc', - id: 'admin/deployment/azure/on-vm/overview', - }, - collapsed: true, - items: [ - 'admin/deployment/azure/on-vm/prerequisites', - 'admin/deployment/azure/on-vm/architecture', - { - type: 'category', - label: 'Deployment', - link: { - type: 'doc', - id: 'admin/deployment/azure/on-vm/deployment/deployment', - }, - collapsed: true, - items: [ - 'admin/deployment/azure/on-vm/deployment/scripted-deployment', - 'admin/deployment/azure/on-vm/deployment/manual-deployment', - 'admin/deployment/azure/on-vm/deployment/byo', - ], - }, - ], - }, + 'admin/deployment/infrastructure-deployment/infrastructure-deployment-kubernetes', + 'admin/deployment/infrastructure-deployment/infrastructure-deployment-on-vm', ], }, { type: 'category', - label: 'GCP', + label: 'Platform Deployment', + link: { + type: 'doc', + id: 'admin/deployment/platform-deployment/platform-deployment-overview', + }, collapsed: true, items: [ { type: 'category', - label: 'Kubernetes (GKE)', + label: 'Automated Deployment', link: { type: 'doc', - id: 'admin/deployment/gcp/kubernetes/overview', + id: 'admin/deployment/platform-deployment/automated/platform-automated-overview', }, collapsed: true, items: [ - { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/prerequisites', - label: 'Prerequisites', - }, - { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/architecture', - label: 'Architecture', - }, - { - type: 'category', - label: 'Infrastructure Deployment', - link: { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-scripted-deployment', - 'admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-manual-deployment', - 'admin/deployment/gcp/kubernetes/infrastructure-deployment/infrastructure-bastion-host-access', - ], - }, - { - type: 'category', - label: 'CodeMie Components Deployment', - link: { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/components-deployment/components-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/gcp/kubernetes/components-deployment/components-scripted-deployment', - { - type: 'category', - label: 'CodeMie Manual Deployment', - link: { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/manual-deployment-overview', - }, - collapsed: true, - items: [ - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/k8s-components', - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/data-layer', - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/security-and-identity', - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/plugin-engine', - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/core-components', - 'admin/deployment/gcp/kubernetes/components-deployment/manual-deployment/observability', - ], - }, - ], - }, - { - type: 'doc', - id: 'admin/deployment/gcp/kubernetes/accessing-applications', - label: 'Accessing Applications', - }, + 'admin/deployment/platform-deployment/automated/platform-automated-kubernetes', + 'admin/deployment/platform-deployment/automated/on-vm', ], }, { type: 'category', - label: 'On VM (GCE)', + label: 'Manual Deployment', link: { type: 'doc', - id: 'admin/deployment/gcp/on-vm/overview', + id: 'admin/deployment/platform-deployment/manual/platform-manual-overview', }, collapsed: true, items: [ - 'admin/deployment/gcp/on-vm/prerequisites', - 'admin/deployment/gcp/on-vm/architecture', { type: 'category', - label: 'Deployment', + label: 'Kubernetes', link: { type: 'doc', - id: 'admin/deployment/gcp/on-vm/deployment/deployment', + id: 'admin/deployment/platform-deployment/manual/kubernetes/platform-manual-kubernetes-overview', }, collapsed: true, items: [ - 'admin/deployment/gcp/on-vm/deployment/scripted-deployment', - 'admin/deployment/gcp/on-vm/deployment/manual-deployment', - 'admin/deployment/gcp/on-vm/deployment/byo', + 'admin/deployment/platform-deployment/manual/kubernetes/k8s-components', + 'admin/deployment/platform-deployment/manual/kubernetes/data-layer', + 'admin/deployment/platform-deployment/manual/kubernetes/security-and-identity', + 'admin/deployment/platform-deployment/manual/kubernetes/plugin-engine', + 'admin/deployment/platform-deployment/manual/kubernetes/core-components', + 'admin/deployment/platform-deployment/manual/kubernetes/observability', ], }, ], }, ], }, + { + type: 'doc', + id: 'admin/deployment/accessing-applications', + label: 'Accessing Applications', + }, { type: 'category', label: 'Extensions',