From 161816c8227b04935477048c54dab69771907118 Mon Sep 17 00:00:00 2001 From: Stanislav Kostenko Date: Fri, 3 Jul 2026 19:29:32 +0300 Subject: [PATCH] docs(config): update code executor documentation (epmcdme-12549) --- .../codemie/api-configuration.md | 7 ++-- .../codemie/code-executor-configuration.md | 39 +++++++++++-------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/docs/admin/configuration/codemie/api-configuration.md b/docs/admin/configuration/codemie/api-configuration.md index a8302ca3..254081b8 100644 --- a/docs/admin/configuration/codemie/api-configuration.md +++ b/docs/admin/configuration/codemie/api-configuration.md @@ -735,7 +735,8 @@ Configure secure Python code execution in isolated Kubernetes pods for running u | Parameter | Type | Default | Description | | -------------------------------------- | ------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CODE_EXECUTOR_EXECUTION_MODE` | string | `"local"` | Execution mode: `sandbox` (isolated K8s pod, recommended for production), `local` (embedded kernel, less secure) | +| `CODE_EXECUTOR_ENABLED` | boolean | `false` | Enable the Code Executor tool. When `false`, the tool is neither listed in the tools catalog nor executed. Set `true` to opt in. | +| `CODE_EXECUTOR_EXECUTION_MODE` | string | `"sandbox"` | Execution mode. Code runs in an isolated Kubernetes sandbox pod. | | `CODE_EXECUTOR_KUBECONFIG_PATH` | string | `""` | Path to kubeconfig for Kubernetes authentication (optional, uses in-cluster config if empty). Set if you want to move code execution to a dedicated cluster | | `CODE_EXECUTOR_WORKDIR_BASE` | string | `"/home/codemie"` | Base working directory for code execution inside containers | | `CODE_EXECUTOR_NAMESPACE` | string | `"codemie-runtime"` | Kubernetes namespace for executor pods | @@ -752,14 +753,14 @@ Configure secure Python code execution in isolated Kubernetes pods for running u | `CODE_EXECUTOR_RUN_AS_USER` | integer | `1001` | Unix user ID for pod security context (non-root execution) | | `CODE_EXECUTOR_RUN_AS_GROUP` | integer | `1001` | Unix group ID for pod security context | | `CODE_EXECUTOR_FS_GROUP` | integer | `1001` | Filesystem group ID for pod volume permissions | -| `CODE_EXECUTOR_SECURITY_THRESHOLD` | string | `"LOW"` | Security policy: `SAFE` (permissive), `LOW`, `MEDIUM`, `HIGH` (restrictive) | +| `CODE_EXECUTOR_SECURITY_THRESHOLD` | string | `"LOW"` | Required security policy threshold: `SAFE`, `LOW`, `MEDIUM`, `HIGH` | | `CODE_EXECUTOR_YAML_POLICY_PATH` | string | `""` | Path to custom YAML security policy file (optional, overrides default policy) | | `CODE_EXECUTOR_VERBOSE` | boolean | `false` | Enable verbose logging for executor debugging | | `CODE_EXECUTOR_KEEP_TEMPLATE` | boolean | `true` | Persist pod template after execution for performance optimization | | `CODE_EXECUTOR_SKIP_ENVIRONMENT_SETUP` | boolean | `false` | Skip environment initialization in sandbox (faster startup but may break dependencies) | :::warning Security Considerations -**Local Mode:** `CODE_EXECUTOR_EXECUTION_MODE=local` provides less isolation and security. Use `sandbox` mode in production where untrusted code execution is required. +**Sandbox Isolation:** `CODE_EXECUTOR_EXECUTION_MODE=sandbox` runs user-supplied code in a dedicated Kubernetes pod, isolated from the CodeMie API. This is the execution model for running untrusted code safely in production. **Security Threshold:** The security policy controls what operations are allowed: diff --git a/docs/admin/configuration/codemie/code-executor-configuration.md b/docs/admin/configuration/codemie/code-executor-configuration.md index babb3966..2df7b0e3 100644 --- a/docs/admin/configuration/codemie/code-executor-configuration.md +++ b/docs/admin/configuration/codemie/code-executor-configuration.md @@ -10,26 +10,31 @@ import TabItem from '@theme/TabItem'; # Code Executor Configuration -The Code Executor runs Python code in isolated Kubernetes pods with enforced resource limits and security policies. +The Code Executor runs Python code in isolated Kubernetes sandbox pods with enforced resource limits and security policies. Every execution request is dispatched to a dedicated sandbox pod, keeping user-supplied code isolated from the CodeMie API. -It supports four deployment modes: local execution inside the API pod, sandbox pods in the same cluster with shared namespace, sandbox pods in the same cluster with dedicated namespace, or sandbox pods in a dedicated cluster. +You choose where those sandbox pods run: in the same cluster as CodeMie API sharing its namespace, in the same cluster in a dedicated namespace, or in a separate dedicated cluster. -## Choosing a Deployment Mode +## Enabling the Code Executor -| Mode | When to use | Isolation | RBAC required | +The Code Executor is disabled by default. To make it available, set `CODE_EXECUTOR_ENABLED=true` in the CodeMie API environment: + +```yaml +extraEnv: + - name: CODE_EXECUTOR_ENABLED + value: "true" +``` + +While disabled, the tool is neither listed in the tools catalog nor executed at runtime. + +## Choosing a Deployment Topology + +| Topology | When to use | Isolation | RBAC required | | ------------------------------------- | ------------------------------------- | -------------------------------- | --------------------- | -| **Local** | No Kubernetes, quick prototyping | None — runs inside the API pod | No | | **Same cluster, shared namespace** | Standard production setup | Separate pod | Yes | | **Same cluster, dedicated namespace** | Namespace-level workload isolation | Separate pod, separate namespace | Yes (cross-namespace) | | **Dedicated cluster** | Compliance, multi-tenant environments | Full cluster isolation | No (kubeconfig) | -## Deployment Modes - -### Local Mode - -The default mode. Code is executed directly inside the CodeMie API pod via subprocess. No Kubernetes resources needed. - -No changes required. The default value of `CODE_EXECUTOR_EXECUTION_MODE` is `local`. +## Deployment Topologies ### Same Cluster as CodeMie API @@ -47,7 +52,7 @@ features: tools: code_executor: rbac: - enabled: true # Creates role and assign it to the service account configured for codemie-api + enabled: true namespace: "" # defaults to the CodeMie release namespace extraEnv: @@ -119,14 +124,14 @@ extraEnv: value: "/secrets/kubeconfig" ``` -## Updating CodeMie API +## Applying CodeMie API Settings -After configuring a sandbox deployment mode (Same Cluster or Dedicated Cluster), add the following environment variables and apply the chart: +The Code Executor is disabled by default, so `CODE_EXECUTOR_ENABLED` must be set to `true` to make the tool available. Tune the remaining Code Executor settings as needed and apply the chart: ```yaml extraEnv: - - name: CODE_EXECUTOR_EXECUTION_MODE - value: "sandbox" + - name: CODE_EXECUTOR_ENABLED + value: "true" - name: CODE_EXECUTOR_MAX_POD_POOL_SIZE value: "5" - name: CODE_EXECUTOR_DOCKER_IMAGE