kuboard-press Documentation

Zh User Index (`docs/zh/user/index.md`) Copy Section

用户与认证

本节覆盖 Kuboard V4 在身份与访问管理（IAM, Identity and Access Management）方向的完整能力：账号登录、安全策略、组织与权限模型，以及与外部身份提供方（IdP）的对接。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 首次登录：先看 登录，按 密码策略 修改默认密码；
2. 安全加固：为管理员账号开启 MFA 多因素认证；
3. 多人协作：通过 用户管理 与 用户组 维护账号，再用 角色与权限 授权；
4. 自动化集成：通过 访问密钥 让自动化脚本与 AI 智能体获得受控 API 访问能力；
5. 企业接入：通过 OIDC 或 Webhook 外部用户库 将 Kuboard 接入企业既有身份体系。

::: tip 谁应该看本节

• 集群使用者（开发者 / SRE）只需了解 登录、密码策略、访问密钥；
• Kuboard 管理员 应完整阅读本节，重点关注 角色与权限 与外部身份对接方案；
• 安全合规负责人 重点关注 密码策略、MFA 与 OIDC 三节。
  :::

En Guide Cluster Resources Index (`docs/en/guide/cluster-resources/index.md`) Copy Section

Cluster Resources

This section covers Kubernetes resources that operate at the cluster or infrastructure layer. These objects rarely carry business traffic directly, but they define capacity, quota, scheduling and policy boundaries.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. First-time organization — split the cluster by team or environment with Namespace, then set boundaries via ResourceQuota / LimitRange;
2. Day-to-day operations — read Node for bring-up and tear-down; read the PDB section of Scheduling / PDB / Lease / RuntimeClass for rolling upgrades and self-healing;
3. Platform team — read Admission Webhook and FlowControl;
4. AI and heterogeneous resources — read DRA (Dynamic Resource Allocation).

::: tip Tier 1 resources
LimitRange, ResourceQuota, PriorityClass, PodDisruptionBudget, EndpointSlice and Lease are classified as Tier 1 resources. Kuboard does not cache them by default — they are fetched directly from the apiserver. Their form pages accept ?demo=true to preload sample data so you can verify the controls without a live cluster.
:::

En Guide Cluster Index (`docs/en/guide/cluster/index.md`) Copy Section

Cluster Management

A cluster is the core object Kuboard manages. This section walks through the full lifecycle — connecting the first Kubernetes cluster, day-to-day maintenance of the connection and cache, and moving resources between clusters.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. First connection — start with Import Cluster and fill in the apiserver address and credentials;
2. Day-to-day maintenance — tune cache strategy and defaults from Edit Cluster;
3. Troubleshooting — when something looks wrong in the cluster list, start at Sync Status to separate sync-pipeline issues from connection problems;
4. Cross-cluster moves — use Resource Export and Import for bulk migration.

::: tip Where to go next
After Import Cluster, continue to the Workloads section to deploy your first application. In a multi-cluster setup, auth.clusterIds and auth.clusterNames (from useAuthStore) determine which clusters appear in the left sidebar.
:::

En Guide Config Storage Index (`docs/en/guide/config-storage/index.md`) Copy Section

Config and Storage

Application configuration and persistent storage are the two foundations of any workload running on Kubernetes. This section covers Kuboard's "application config" and "storage" resource types, along with related snapshot and CSI (Container Storage Interface) capabilities.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. Application config first — read ConfigMap / Secret and learn how to reference them from a Deployment or StatefulSet;
2. Persistent storage — read PVC / PV / StorageClass to understand how the three relate, and pick the right StorageClass;
3. Data protection — add VolumeSnapshot / CSI for snapshots and clones on critical stateful workloads.

::: tip Secret hygiene
Once a Secret is referenced by a workload, its content is exposed inside the Pod as files or environment variables. Grant users the minimal privilege on the secrets resource in Users and Authentication, and protect administrator accounts with MFA.
:::

En Guide Crd Index (`docs/en/guide/crd/index.md`) Copy Section

Custom Resources

The Kubernetes extension mechanism lets platforms and applications define their own API types. This section covers how Kuboard discovers, presents and manages CRDs (CustomResourceDefinition, Kubernetes Custom Resource Definitions) and their CR (Custom Resource) instances.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. Survey cluster capabilities — open CRDs to see what is already registered and confirm the resource you need is available;
2. Daily operations — move to the relevant CRD's Custom Resource Instances list to perform CRUD (Create, Read, Update, Delete) operations;
3. Missing resources — if a CRD is installed in the cluster but not shown by Kuboard, it usually means the cache has not synced yet. Trigger a full sync or wait for the next cycle.

::: tip Auto-discovery
CRDs do not require manual menu registration: LoginServiceMenuLoader.populateCustomResourceMenu automatically builds the "Custom Resources" group in the left sidebar from any synchronized CRD. Common CRDs (Cert-Manager, Argo CD, Ingress-NGINX, etc.) usually appear within one sync cycle of installation.
:::

En Guide Network Index (`docs/en/guide/network/index.md`) Copy Section

Services and Networking

External exposure and in-cluster network isolation are central to both reachability and security on Kubernetes. This section covers Service, Ingress, NetworkPolicy and the next-generation Gateway API.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. Expose first, tighten second — when shipping a service, start with Service / Ingress to make it reachable;
2. Layer on security — use NetworkPolicy to restrict Pod-to-Pod traffic at the namespace or service level;
3. Move to Gateway API last — when you outgrow Ingress (many rules, cross-namespace sharing, or advanced TCP / TLS needs), migrate to Gateway API.

::: tip Picking the right backend

• If the cluster already has the Gateway API CRDs (gateway.networking.k8s.io), go straight to Gateway API;
• If the cluster only has Ingress-NGINX or another classic Ingress, keep using Service / Ingress.
  :::

En Guide Ops Index (`docs/en/guide/ops/index.md`) Copy Section

Operations Visualization

This section is about "seeing what the cluster is doing" and "extending what the cluster can do". It includes the time-ordered event stream, the object-relationship resource map, and the Kuboard addon marketplace.

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. Routine inspection — open Events to see recent warnings for the cluster and namespaces;
2. Complex troubleshooting — when "I changed config but nothing happened", trace the chain with Resource Map;
3. Capability gaps — close them with Addon Marketplace for common dependencies such as metrics-server or NFS Provisioner.

::: tip About addons
Kuboard V4 addons are backward-compatible with V3: addons installed in V3 continue to work after an upgrade to V4 without reinstallation. Addons are implemented as Kuboard custom resources, so they are managed using the same flow as the Custom Resources section.
:::

En Guide Workload Index (`docs/en/guide/workload/index.md`) Copy Section

Workloads

Kuboard covers every built-in Kubernetes workload type — Deployment, StatefulSet, DaemonSet, Job, CronJob and Pod — along with HPA (Horizontal Pod Autoscaling) and Continuous Deployment (CD).

Quick Navigation Copy Chapter

Recommended Reading Order Copy Chapter

1. First deployment — open Deployment and ship a stateless application;
2. Stateful workloads — move to StatefulSet once the application needs stable identity or persistent storage;
3. Node-level workloads — read DaemonSet for cluster-wide agents;
4. Batch jobs — read Job / CronJob for one-off or scheduled tasks;
5. Autoscaling — configure HPA to handle variable load;
6. Release automation — integrate CI with Continuous Deployment (CD) to replace manual restarts.

::: tip Where to go next
After you have a workload running, configure its ConfigMap / Secret and PVC bindings. Use the Operations section's Events and Resource Map to keep an eye on the workload in production.
:::

Zh Guide Cluster Resources Index (`docs/zh/guide/cluster-resources/index.md`) Copy Section

集群资源

本节覆盖 Kubernetes 中"作用于整个集群或基础设施层面"的资源类型。这些对象通常不直接承载业务，但决定了集群的容量、配额、调度与策略边界。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 首次整理集群：先按团队 / 环境用 Namespace 划分空间，再配 ResourceQuota / LimitRange 设置边界；
2. 运维场景：节点上下线时阅读 Node；滚动升级或自愈时阅读 调度 / PDB / Lease / RuntimeClass 中的 PDB 部分；
3. 平台团队：阅读 Admission Webhook 与 FlowControl；
4. AI / 异构资源：阅读 DRA 动态资源分配。

::: tip Tier 1 资源
本节包含的 LimitRange、ResourceQuota、PriorityClass、PodDisruptionBudget、EndpointSlice、Lease 等被称为 Tier 1 资源：Kuboard 默认不缓存，按需走 apiserver 直查。其表单页支持 ?demo=true 查询参数预填演示数据，无需真实 K8s 集群即可独立验证。
:::

Zh Guide Cluster Index (`docs/zh/guide/cluster/index.md`) Copy Section

集群管理

集群是 Kuboard 管理的核心对象。本节覆盖从"接入第一个 Kubernetes 集群"到"日常维护连接、同步缓存、跨集群搬运资源"的完整生命周期。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 首次接入：从 导入集群 开始，按页面引导填入 apiserver 地址与凭证；
2. 日常维护：在 编辑集群 中调整缓存策略与默认参数；
3. 排障：集群列表出现异常时，先看 同步状态 定位是同步链路还是连接问题；
4. 跨集群搬运：使用 资源导入导出 完成批量迁移。

::: tip 与后续章节的关系
完成 导入集群 后，建议继续阅读 工作负载 章节发布第一个应用；多集群场景下，auth.clusterIds 与 auth.clusterNames（来自 useAuthStore）会决定左侧栏可见的集群清单。
:::

Zh Guide Config Storage Index (`docs/zh/guide/config-storage/index.md`) Copy Section

配置与存储

应用配置与持久化存储是 Kubernetes 上业务运行的两大基础。本节覆盖 Kuboard 中"应用配置层"与"存储层"的资源类型，以及相关的快照与 CSI（Container Storage Interface，容器存储接口）能力。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 应用配置起步：先看 ConfigMap / Secret，学会在 Deployment / StatefulSet 中引用；
2. 持久化存储：阅读 PVC / PV / StorageClass 理解三者的关系，并选择合适的 StorageClass；
3. 数据保护：在关键有状态应用上引入 VolumeSnapshot / CSI 做快照与克隆。

::: tip Secret 安全
Secret 一旦被工作负载引用，即可在 Pod 内以文件或环境变量形式挂载。建议在 用户与认证 中为相关人员配置 secret 资源的最小权限，并通过 MFA 保护管理员账号。
:::

Zh Guide Crd Index (`docs/zh/guide/crd/index.md`) Copy Section

自定义资源

Kubernetes 的扩展机制让平台与业务可以定义自己的 API 类型。本节介绍 Kuboard 如何发现、展示并管理 CRD（CustomResourceDefinition，Kubernetes 自定义资源定义）及其 CR（Custom Resource，自定义资源）实例。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 了解集群能力：先在 CRD 页面查看已注册的 CRD，确认目标资源是否可用；
2. 日常操作：进入对应 CRD 的 自定义资源实例 列表，进行 CRUD（Create / Read / Update / Delete，数据的增删查改）操作；
3. 缺失资源：若集群已安装 CRD 但 Kuboard 未列出，多为缓存未同步，重启一次全量同步或等待下一个同步周期即可。

::: tip 自动发现机制
CRD 无需手动注册菜单：LoginServiceMenuLoader.populateCustomResourceMenu 会按已同步的 CRD 自动生成左侧"自定义资源"分组。常见 CRD（如 CertManager、ArgoCD、IngressNginx 等）安装后通常在一个同步周期内出现在菜单中。
:::

Zh Guide Network Index (`docs/zh/guide/network/index.md`) Copy Section

服务与网络

应用对外暴露与集群内部网络隔离，是 Kubernetes 上业务可访问性与安全性的关键。本节覆盖 Service、Ingress、NetworkPolicy 与新一代 Gateway API 四类对象。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 先暴露，后收敛：业务上线先用 Service / Ingress 把应用暴露出来；
2. 再叠加安全策略：按命名空间或服务等级用 NetworkPolicy 收紧 Pod 间网络；
3. 最后迁向 Gateway API：当 Ingress 规则数量多、跨命名空间共享路由，或需要 TCP / TLS 高级能力时，迁移到 Gateway API。

::: tip 后端实现选择

• 若集群已安装 Gateway API CRD（gateway.networking.k8s.io），推荐直接使用 Gateway API；
• 若集群仅安装 IngressNginx 或其他传统 Ingress，继续使用 Service / Ingress 即可。
  :::

Zh Guide Ops Index (`docs/zh/guide/ops/index.md`) Copy Section

运维可视化

本节聚焦"看清集群在做什么"与"扩展集群能做什么"。包括按时间线聚合的事件流、按对象关系组织的资源全景图，以及 Kuboard 套件市场。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 日常巡检：进入 事件 查看集群与命名空间的近期告警；
2. 复杂排障：遇到"改了配置但没生效"等链路问题时，用 资源全景图 理清上下游；
3. 能力补齐：通过 套件市场 一键补齐 metrics-server、NFS Provisioner 等常见依赖。

::: tip 与套件的关系
Kuboard v4 的套件与 v3 兼容：v3 中已安装的套件在升级到 v4 后继续生效，无需重复安装。套件以 Kuboard 自定义资源形式存在，遵循 自定义资源 章节的通用管理方式。
:::

Zh Guide Workload Index (`docs/zh/guide/workload/index.md`) Copy Section

工作负载

Kuboard 覆盖 Kubernetes 所有内置工作负载类型：Deployment、StatefulSet、DaemonSet、Job、CronJob 与 Pod，并提供 HPA（水平 Pod 自动伸缩）与持续部署（CD）能力。运维和应用 owner 可以从这里进入不同负载类型的创建、管理与排障页面。

快速导航 Copy Chapter

推荐阅读顺序 Copy Chapter

1. 首次部署：先读 Deployment，部署一个无状态应用；
2. 有状态工作负载：应用需要稳定网络标识或持久化存储时，再看 StatefulSet；
3. 节点级工作负载：需要集群范围内的代理时，读 DaemonSet；
4. 批量任务：一次性或定时任务，读 Job / CronJob；
5. 自动伸缩：流量有波动时，用 HPA 自动调整副本数；
6. 发布自动化：接入 CI 流水线，用 持续部署（CD） 替代手动重启。

::: tip 接下来读什么
把工作负载跑起来之后，接着配置它的 ConfigMap / Secret 与 PVC 绑定；生产环境运行期间，用「运维」分组里的 事件 和 资源地图 持续观察工作负载的健康状况。
:::

Public Robots (`docs/public/robots.txt`) Copy Section

User-agent: *
Allow: /

Sitemap: https://kuboard.cn/sitemap.xml

En Changelog V4.X (`docs/en/changelog/v4.x.md`) Copy Section

Kuboard v4.x Changelog

Kuboard v4 release notes. If you have already installed Kuboard v4.x (a version number starting with v4, e.g. kuboard v4.0.0.0 / v4.0.0.1 / v4.2.1.0), upgrading to a newer v4.x version only requires changing the image tag.

v4.3.1.1 Copy Chapter

Release date: 2026-10-12

• Bug Fixes:
  • AI Change Approval:
    • Fixed the approve / confirm / view-YAML action buttons not displaying on the plan detail page

v4.3.1.0 Copy Chapter

Release date: 2026-10-12

• New Features:
  • Monitoring:
    • Added dual-source monitoring on the Pod detail page: metrics-server real-time data alongside metrics-scraper 30-minute charts, with Prometheus-first probing and automatic fallback
    • Added the metrics.server.installed capability probe to surface monitoring capabilities per cluster version
  • Cluster Management:
    • Full sync now writes to the database in batches (multi-row REPLACE for MySQL / ON CONFLICT upsert for PostgreSQL), significantly speeding up large-cluster sync
• Improvements:
  • Cluster Management:
    • The sync status table now scrolls within the list with a fixed header, with a dedicated empty state for filtered results
    • Split the batch write lock down to each (cluster, resource) pair, easing long-tail queuing on large clusters
  • K8s Object Management:
    • Uncached resource lists now load in limit/continue chunks, eliminating lag when loading large lists
    • Optimized cache query performance for Pod lists and the cluster namespace tree
• Bug Fixes:
  • Cluster Management:
    • Fixed the full-sync pagination modeling bug: resources beyond 500 per kind were only ever syncing the first page
    • Fixed full-sync pagination aborting without recovery on transient 410/504/5xx errors
    • Fixed incremental-sync watch falling back to full sync on transient interruptions, causing sync oscillation
  • Audit:
    • Fixed audit index creation failing on database dialects that surface "already exists" with a different exception type
  • Monitoring:
    • Restored the metrics-server and metrics-scraper install entries, and fixed the broken 30-minute chart and real-time data paths on the Pod detail page

v4.3.0.0 Copy Chapter

Release date: 2026-10-07

• New Features:
  • Login & Authentication:
    • Added OIDC Single Sign-On (SSO) with multiple IdP support, Silent SSO token refresh and trusted-IdP MFA
    • Redesigned the login page with an architecture-diagram layout, animated background and improved button placement
  • Users & Permissions:
    • Added a business view to role authorization: grant view/create/edit/delete permissions by ticking the left-hand menu tree
    • Role authorization now supports a button-level operation registry and quick role templates
  • Helm:
    • Support installing and upgrading from an offline Chart package upload
    • Added a "Resources" tab on the release detail page, listing the managed K8s objects and their status
  • K8s Object Management:
    • Added a "Related Resources" tab on detail pages, reusing the resource-map capability; the context menu supports "focus on this resource"
    • Rebuilt the namespace overview page as a categorized dashboard
    • Unified list-page optimization across 10+ resource types (Deployments/StatefulSets/DaemonSets/nodes/services/ingresses, etc.): expandable rows, adaptive columns, i18n
    • Container rows now display ports; click a port to open the proxy dialog
  • Cluster Management:
    • Rebuilt the sync status table (sync mode/duration/error highlighting/filtering) and added sync task log querying
    • Support multi-instance high-availability deployment: Redis-coordinated scheduling election, cache invalidation broadcast, cross-instance ID collision avoidance
  • Visual & Branding:
    • Introduced a design-token system and brand theming; detail pages fully card-styled
    • Unified the menu/overview/resource-map icon set onto resourceMap resource icons
• Improvements:
  • Related Resource Map:
    • Canvas now uses a tree layout and bezier edges; the depth slider persists across sessions
  • K8s Object Management:
    • Detail-page experience optimization for workloads (Deployments/StatefulSets/DaemonSets)
    • Reorganized the node detail page information architecture; events fully internationalized
  • Agent Change Approval:
    • Restored list search with server-side filtering by Agent / Plan ID
• Bug Fixes:
  • Security:
    • Fixed the tightened /k8s-api proxy authorization, preventing unauthorized reads of K8s resources
    • Fixed SQL injection in the user/group/role list APIs and several missing button-level authorizations
    • Fixed container file-browser privilege escalation and a missing ownership check on the user profile API
    • Fixed stored XSS via innerHTML rendering and addon documents
    • Fixed JWT weak-key startup blocking (auto-rotating self-heal) and Webhook signature verification
    • Fixed missing rate limiting on login endpoints and SSRF on cluster access URLs
    • Upgraded dependencies to fix high-severity vulnerabilities (CVE-2024-7254, etc.)
  • Cluster Management:
    • Fixed sync task memory exhaustion and scheduler SQL full-table scans
    • Fixed Redis dirty cache data causing frequent sync scheduler errors
    • Fixed PostgreSQL failing to connect on startup
  • Terminal:
    • Fixed the log viewer not auto-reconnecting after a disconnect
  • Agent Change Approval:
    • Fixed irregular resource-name derivation errors and step time-semantics issues
  • K8s Object Management:
    • Fixed unscheduled Pods rendering empty node links and charts not refreshing after switching Pods
    • Fixed the CronJob detail task list stacking and detail-page button wrapping
  • Helm:
    • Fixed the install button 404 navigation and startup failure caused by stale keystore files
  • Build & Integration:
    • Fixed the app version not being injected and new-version check errors
    • Upgraded the runtime base image to GA JDK and improved the container startup script

En Helm Events (`docs/en/helm/events.md`) Copy Section

Release Operation Events

Install, Upgrade, Rollback, and Uninstall are all executed asynchronously in Kuboard: the operation returns immediately after submission, while the actual work is done by a helm CLI subprocess in the background. The Operation Events page is the "live window" of this background execution — it shows helm's execution logs, the status of the involved resources, and the overall progress in real time.

Entry Copy Chapter

The Operation Events page is a hidden route; it does not need to be (and cannot be) entered from the menu. After submitting an operation on any of the following pages, the browser automatically navigates to the events page:

The page URL after the navigation looks like:

/helm/events/<clusterId>/<namespace>/<releaseName>?sessionId=<sessionId>

Here sessionId is the session identifier of this background operation; the events page uses it to find the event stream of the corresponding operation on the server.

When the operation finishes, two buttons appear at the top right of the page:

• View Release — navigates to the detail page of this Release
• Back to Releases — returns to the Releases list

Event Stream Display Copy Chapter

What You See Copy Section

The events page is divided into four sections from top to bottom:

1. Connection status tag — the current state of the event stream:

   Status	Meaning
   Connecting	Establishing the event stream connection
   Connected	Event stream established, receiving events in real time
   Completed	Operation ended successfully (green)
   Failed	Operation ended with a non-zero exit code (red)
   Canceled	Operation was canceled by the user

2. Progress bar — shows elapsed seconds / timeout seconds (default timeout is 300 seconds). When the run exceeds 90%, the progress bar turns yellow, warning that it is about to time out.

3. Resource status — the resources currently created and their readiness:

   Resource	Shown content
   Deployment	Status (Ready / Progressing) and the replica count ready/total
   Pod	Status (Pending, Running, ImagePullBackOff, CrashLoopBackOff, etc.)

   When a Pod is in an abnormal status, hover over the warning icon next to the status to view the specific reason (message).

4. Log panel — dark terminal-style helm execution output that scrolls line by line in real time and automatically scrolls to the latest line:

   • Normal output: grayish white
   • helm execution log (LOG): blue
   • Failure information (FAILED): red
   • Completion information (COMPLETED): green
   • The panel shows at most the latest 500 lines

How Events Are Produced Copy Section

Every background operation produces a series of events (Event). The main types are as follows:

::: tip Real-time refresh mechanism
The events page subscribes to the event stream through a long-lived SSE (Server-Sent Events) connection. Once the connection is established, the server first replays the historical events already produced by this operation, then pushes new events in real time — so refreshing the page during the operation does not lose any logs. The corresponding server endpoint is GET /{clusterId}/namespaces/{ns}/releases/{name}/events (produces = text/event-stream).
:::

When to Use Copy Chapter

Observing Long-Running Operations Copy Section

When installing a large Chart, or when wait is enabled and the operation needs to wait for resources to become ready, the operation may last for several minutes. In this case:

1. After submitting an install / upgrade, you automatically enter the events page.
2. Watch the progress bar to confirm the operation is still running (heartbeats keep being pushed and the time keeps increasing).
3. Watch the resource status: when a Deployment changes from Progressing to Ready and a Pod becomes Running, the resources are ready.
4. After the status tag turns Completed, click View Release to enter the details.

Locating the Cause of Failures Copy Section

When an operation fails (the status tag turns red), the cause is usually recorded in two places:

Canceling an Operation Copy Section

While an operation is in progress (status is Connected), you can click Cancel Operation at the top right and confirm:

• The background helm process is terminated, the event stream ends with CANCELED (exit code 137), and the page status changes to Canceled.
• The page warns: resources created before the cancellation will not be automatically deleted; please clean them up manually.

::: warning
Canceling an operation essentially terminates the background process; it does not clean up the resources already created. After canceling, go to the cluster to confirm and clean up any leftover resources.
:::

Notes Copy Chapter

• Events are a real-time stream during the operation: events are only produced while the background operation is alive. If you open the events page directly after the operation ends without a sessionId, you will see the message "No active session found. The operation may have completed."
• Connection dropped: when the event stream is interrupted due to network fluctuations, the status tag shows Failed. Refresh the page to resubscribe and replay the historical events of this operation.
• Log limit: the log panel only keeps the latest 500 lines; earlier output is truncated.
• Timeout: the progress bar is computed as elapsed / timeout and turns yellow beyond 90%. After a timeout, the background helm subprocess is forcibly terminated and the operation ends as failed.
• The final result is determined by the Release: whether the operation succeeded can ultimately be confirmed in the Release details and Revision comparison (./releases).

En Helm Install (`docs/en/helm/install.md`) Copy Section

Install Helm Release

When you want to install a Chart into a namespace, use the "Install Release" wizard. One installation creates a Release (Helm's encapsulation of a single installation), which can then be viewed and managed in the Release List.

Entry Copy Chapter

The installation wizard has two entry points; choose either one to suit your habit:

When entering from the marketplace, the wizard automatically pre-fills the Chart name, the currently selected Chart version, and the default values of that version; you only need to confirm the Release name and similar information before submitting.

::: tip Permission requirements
Opening the installation wizard requires create permission on the namespace-level helm.kuboard.cn releases resource. If not authorized, the Install Release button on the list page is not shown.
:::

Filling in the Installation Wizard Copy Chapter

The form fields on the page are as follows:

Choosing the Chart Source and Version Copy Section

• Pick from the marketplace: find the target Chart in the Chart Marketplace → click View Details → select a version on the right → click Install This Chart, and the wizard automatically brings in the Chart and version;
• Specify manually: after entering the wizard from the list page, directly fill in a name in the repository/Chart format. The Chart name must actually exist in the Chart repositories (repo) already added to your cluster, otherwise the installation fails.

After filling in the Chart name and selecting the cluster and namespace, the wizard tries to fetch that Chart's values-schema from the marketplace; if it succeeds, the Values editor gains a "Form" mode (see below).

::: tip Release name auto-generation
When a Chart is brought in from the marketplace, the Release name is automatically pre-filled as the last segment of the Chart name (converted to lowercase, non-alphanumeric characters replaced with -). For example, Chart bitnami/redis → default Release name redis. You can change it.
:::

Configuring values Copy Section

Values are the parameters passed to the Chart, used to override the Chart's default configuration. The wizard provides two editing modes:

• Direct YAML editing: always available; edit the YAML text directly;
• Form mode: available only when the wizard successfully fetches that Chart's values-schema. In this case the Form / YAML tabs appear above the Values area, and the two editing modes stay bidirectionally synchronized when you switch between them.

In Form mode, fields are rendered into the corresponding controls by field type:

Fields marked Required in the form come from the schema's required declaration; the field description text is used as the placeholder hint of the input.

::: warning Schema nesting too deep
When fields are nested more than 5 levels deep, Form mode prompts "Schema nesting is too deep. Consider using YAML editor." In this case switch to the YAML tab and write the configuration directly.
:::

Advanced Options Copy Section

Keep Wait for ready enabled when installing new applications, so that the progress page intuitively shows the creation and readiness of each resource; if you only care whether the installation succeeded, you can disable it to speed up the return.

::: tip Values automatically restored after a failed dry-run
If validation fails after checking Dry-Run Only (e.g. a values configuration error), the values you edited are saved temporarily and automatically restored the next time you enter the installation wizard within 30 minutes — no need to fill them in again.
:::

What Happens After Submitting Copy Chapter

After clicking Install, the wizard submits the request for asynchronous execution in the backend, and the page jumps to the Operation Progress page (which shares the same event-stream mechanism with uninstall and upgrade, see Operation Events for details):

1. Submit and return immediately: the installation task runs in the backend via an event stream (SSE), and the page receives progress in real time without waiting for the request to return;
2. Progress display: the progress page contains three parts —
   • Progress bar: shows the elapsed time and the total timeout;
   • Resource status: lists the resources being created row by row (type, name, status; Deployments additionally show ready replicas / desired replicas);
   • Log panel: scrolls the real-time logs of the helm command, with failed lines marked red and completed lines marked green;
3. Installation result:
   • Success: the status tag becomes Completed; click View Release to go to that Release's detail page; click Back to Releases to return to the list, where the new Release now appears (status deployed);
   • Failure: the status tag becomes Failed; the specific error can be seen in the log panel, then adjust the Chart version, values, or permissions and retry.

::: warning Canceling mid-way
The Cancel Operation button in the top-right of the progress page can terminate the installation. After canceling, the resources already created before the cancellation are not deleted automatically and must be cleaned up manually.
:::

Common Notes Copy Chapter

• Release names are unique within a namespace: two Releases with the same name are not allowed in the same namespace. If you install using an existing name, helm reports an error directly (release already exists), and the progress page log shows the failure. Different namespaces do not affect each other, so Releases with the same name can exist;
• Leaving the version empty means the latest version, but the latest version may contain incompatible changes; for production environments it is recommended to explicitly specify a version;
• values take effect only once, at installation time: modifying values after installation requires going through Upgrade, rather than reinstalling;
• A failed installation produces no Release record (or leaves only a failed status record); you can confirm this in the Release list.

En Helm Marketplace (`docs/en/helm/marketplace.md`) Copy Section

Chart Marketplace

Kuboard ships with a built-in Chart Marketplace, which lets you browse and search available Helm Charts just like browsing an app store (a Chart is Helm's installable package, containing a set of Kubernetes resource templates and default configuration), view each Chart's documentation, default values (the default parameters in values.yaml) and metadata, and then jump to the installation page with one click to complete the deployment.

This article is for users who want to find a ready-made Chart and install it. It covers the complete flow from entering the marketplace, browsing and filtering, viewing details, and managing repositories, to landing on the installation page. For operations on the installation page, see Install Helm Release.

Enter the Marketplace Copy Chapter

1. In the left menu, select the target cluster, then go to Application Management → Helm Release → Marketplace Browse.

   Menu level	Description
   Application Management	The "Application Management" group in the left navigation
   Helm Release	The "Helm Release" submenu under Application Management
   Marketplace Browse	The Chart marketplace page, showing the list of installable Charts

2. Once opened, you are on the Chart marketplace home page, which by default shows all available Charts.

::: tip
The visibility of the marketplace page depends on your permissions: regular members can only see repositories with a status of ready and the Charts in them; viewing the repository list additionally requires the list permission on the chart-repos resource under helm.kuboard.cn.
:::

Browse the Chart Marketplace Copy Chapter

The marketplace home page displays Charts in a card grid. Each card contains:

Click anywhere on a card, or the View Details button on it, to open that Chart's details drawer.

Search and Filter Copy Section

The top toolbar provides two ways to find Charts, which can be used in combination:

1. Filter by repository: click the "Repository" dropdown and select a repository to refresh the list immediately, showing only the Charts in that repository; select "All Repositories" to restore the full list.
2. Search by keyword: type a name keyword (e.g. redis, nginx) in the search box, then press Enter or click the Search button to filter the list.
3. Refresh: click the Refresh button to reload the repository list and the Chart list (right after a repository has been added or refreshed, use it to make the marketplace page show the latest data).

::: tip
Search and filtering are done server-side: the keyword (name keyword) and repoName (repository name) conditions are passed in. Both take effect at the same time, for example "search for redis in the bitnami repository".
:::

View Chart Details Copy Chapter

The details slide out from the right in a drawer. From top to bottom:

::: tip
The detail content is read in real time server-side via helm show readme / helm show values / helm show chart; the README and values both come from the currently selected version of the Chart.
:::

Select a Version Copy Section

1. The "Version" dropdown near the top of the details page lists all historical versions of the Chart, with the latest version selected by default (the first item in the list).
2. After switching versions, the README, default values and Chart metadata refresh in sync to that version's content.
3. Pay attention to the selected version's kubeVersion constraint: if the Kubernetes version of the target cluster does not meet the requirement, the page shows a yellow compatibility warning — in that case, switch to a compatible version before installing.

Manage Helm Repositories Copy Chapter

All Charts in the marketplace come from Helm repositories (Repository, the remote indexing service that stores Chart packages). On first use, the repository list is empty and you need to add repositories first; after adding, you can edit, delete or refresh them at any time.

1. Click the Repository Management button at the top right of the marketplace browse page to open the repository management drawer (this button requires the create permission on the chart-repos resource).

2. The drawer lists all repositories as cards. Each card shows:

   Info	Description
   Name / URL	Repository identifier and address
   Status	ready / refreshing / pending / failed
   Chart count	The total number of Charts currently indexed in the repository
   Last updated	The time of the last successful refresh
   Error message	The reason for a failed refresh (shown in red)

Add a Repository Copy Section

1. Click the Add button at the top of the drawer.

2. Fill in the repository information in the form:

   Field	Required	Description
   Preset	No	Dropdown of common public repositories; selecting one auto-fills the name and URL
   Name	Yes	Unique identifier of the repository; cannot be changed after creation
   URL	Yes	Repository index address, e.g. https://charts.bitnami.com/bitnami
   Username / password	No	Access credentials for private repositories
   Insecure TLS	No	Enable for repositories that use self-signed certificates to skip certificate validation
   Pass Credentials	No	Reuse this repository's credentials when downloading dependent sub-Charts

3. Click Save. After a successful add, the repository enters the pending / refreshing state; the server automatically pulls the repository index, and when it is done, the status changes to ready and the Charts become visible on the marketplace page.

About built-in repositories: Kuboard does not come with any pre-installed repositories; you must add them on first use. For convenience, the "Preset" dropdown offers 11 common public repositories, which auto-fill the name and URL when selected:

You can also skip the presets and fill in any valid repository name and URL yourself.

Edit, Delete and Refresh Copy Section

• Refresh: repository content (new Charts, new versions) is not synced automatically; click the Refresh button on the repository card to pull the latest index manually. While refreshing, the button shows a loading state and the status returns to ready when done. The marketplace page also provides a global Refresh button to reload the list.
• Edit: click Edit to modify the URL, credentials, etc.; the repository name cannot be changed after creation.
• Delete: click Delete and confirm in the confirmation dialog to remove the repository and its Charts.

::: warning

• Credentials for private repositories are used only by the server to pull the repository index; after saving, they are not shown in plain text in the list.
• Deleting a repository only removes it and its index from the marketplace; it does not affect Releases that are already installed.
  :::

From the Marketplace to Installation Copy Chapter

Click the Install button at the bottom of the Chart details drawer, and the page navigates to the Install Release page with the following automatically filled in:

1. Chart: the full name of the selected Chart (repository name + Chart name); no need to type it manually.
2. Version: the version currently selected on the details page.
3. Default values: the Chart's default values are pre-filled into the install form as a modifiable starting point (large defaults are also brought in automatically).

Once on the install page, simply select the target cluster and namespace, adjust parameters as needed, and the deployment is complete.

En Helm Releases (`docs/en/helm/releases.md`) Copy Section

Release Management

A Release is Helm's encapsulation of a single installation: one Release corresponds to a set of Kubernetes resources under a Namespace, and every install, upgrade or rollback produces a new revision. This page explains how to view and maintain already-installed Releases. To install a new application, see Install a Release; for upgrade and rollback, see Upgrade and Rollback.

Entering the Release List Copy Chapter

1. In the left navigation, go to cluster → Application Management → Helm Release;
2. Click the Release List menu item to open the Release list page.

::: tip Permission requirements
Opening the list page requires the list permission on the releases resource of helm.kuboard.cn; viewing details, upgrading, rolling back and uninstalling respectively require the corresponding get / create / delete permissions. Operation buttons you are not authorized for are not shown.
:::

List Page Copy Chapter

At the top of the list page there are two dropdown selectors:

• Cluster: defaults to the first cluster the current user can access;
• Namespace: defaults to default.

After switching the cluster or Namespace, the list refreshes automatically. Releases are isolated by Namespace; Releases with the same name in different Namespaces do not affect each other.

The table columns are as follows:

Meaning of Status Tags Copy Section

Status tags use different colors to distinguish the meanings below:

The Install Release button at the top-right corner of the list page is used to install a new application; see Install a Release for how to do it.

Release Detail Copy Chapter

Click a Release name or Detail in the list to enter that Release's detail page.

Overview Copy Section

The top of the page shows:

• Cluster / Namespace / Name / Chart / App Version;
• The status tag, Chart Version, Revision and Updated (time of the latest update);
• Description: when the content is long, only one line is shown; hovering the mouse over it displays the full text.

The top-right corner provides the Upgrade and Uninstall operation buttons (shown according to permissions).

Revision History and Comparison Copy Section

The Revision History tab lists the complete revision history of the Release, one revision per row:

To compare two revisions:

1. Check the checkboxes at the start of the rows to select two or more revisions (when multiple are selected, the comparison is between the earliest and the latest revision in the selected range);
2. A Compare (N) button appears below the table; click it to open the "Revision Diff" window;
3. At the top of the window you can adjust the Revision 1 / Revision 2 to compare, and at the bottom there are two tabs:
   • Values: the values differences between the two revisions;
   • Manifest: the differences between the Kubernetes resource manifests rendered by the two revisions.

For the detailed steps of a rollback, see Upgrade and Rollback.

Viewing values / manifest / notes Copy Section

The other three tabs of the detail page are all read-only views (a Copy button is provided at the top right):

::: tip values and manifest of historical revisions
The Revision Diff window loads the values and manifest of the selected revisions on demand, so even for revisions from long ago, you can view and compare their complete configuration.
:::

Uninstalling a Release Copy Chapter

1. Click Uninstall at the top right of the Release detail page;
2. In the Uninstall Release confirmation dialog, verify the Release name and Namespace, and confirm the message: this operation will delete all Kubernetes resources managed by this Release;
3. Click Confirm Uninstall.

There is no additional checkbox in the uninstall confirmation dialog: uninstalling with Helm 3 by default also deletes the Release record together with its revision history (equivalent to the --purge of older Helm versions), so there is no "keep the record or not" choice.

After Uninstalling Copy Section

• After clicking confirm, you are taken to the Operation Events page, which shows the uninstall progress and logs in real time until it completes;
• After the uninstall completes, the Release disappears from the list page;
• Uninstalling cannot be undone; before proceeding, make sure the application is no longer needed, or that a data backup has been made.

::: warning Scope of an uninstall
Uninstalling deletes all Kubernetes resources managed by this Release (Deployment, Service, ConfigMap, etc.), but does not delete resources created externally (not managed by Helm). If you want to keep the Release record for traceability, you can run the helm uninstall --keep-history command directly on the cluster.
:::

Long-running tasks such as install, upgrade, rollback and uninstall are all recorded on the Operation Events page, where you can review them at any time.

En Helm Upgrade Rollback (`docs/en/helm/upgrade-rollback.md`) Copy Section

Upgrade and Rollback a Release

Helm records every install, upgrade, and rollback as a Revision. An Upgrade replaces the current deployment with a new Chart version and values; a Rollback restores the Release to the content of a historical Revision. Both operations generate a new Revision; after submission, follow the execution result on the Operation Progress page.

This page is for users who want to upgrade an installed Release to a newer version, or roll back when something goes wrong. For viewing and comparing Revisions, see Release List and Revision History.

Upgrade a Release Copy Chapter

Entry Points Copy Section

Once inside, the "Upgrade Release: <name>" page opens.

Select the Target Chart Version Copy Section

::: tip
When the kubeVersion constraint of the selected version (the Chart's requirement on the Kubernetes version) does not match the current cluster version, a yellow compatibility warning is shown at the top of the page; in this case, switch to a compatible version before upgrading.
:::

Adjust Values Copy Section

• The Values (YAML) editor loads the current Revision's values by default, so you start from the existing configuration instead of rewriting everything from scratch;
• Whether the editor provides a form tab depends on whether the Chart ships a values schema (a description of the parameter structure): when a schema exists, you can switch between the Form / YAML tabs (the form renders fields according to the schema, YAML edits the code directly, and the two sides stay in sync in real time); without a schema, only YAML editing is available;
• Editing works exactly the same as on the Install Release page.

# values snippet: modify on top of the existing configuration
replicaCount: 3        # adjust the replica count
image:
  repository: nginx
  tag: "1.27"          # upgrade the image version

Dry-Run and Submission Copy Section

Below the form are Options and Timeout:

Order of operations:

1. When you need to validate first, check Dry-Run Preview and click Upgrade: only a dry-run executes, the Release is not actually changed;
2. Once confirmed, uncheck Dry-Run Preview and click Upgrade again to submit for real;
3. After submission you are automatically taken to the Operation Progress page: you can watch the upgrade progress, resource status, and logs in real time, and click Cancel Operation at any point; when done, click View Release to return to the detail page.

::: warning Values are restored automatically when Dry-Run fails
When a Dry-Run preview fails, the values you filled in are saved in the browser (valid for 30 minutes); the next time you enter the upgrade page they are filled back automatically, with the hint "Restored values from previous dry-run", so you do not need to re-enter them. Note: values are saved only when Dry-Run fails; a failed real upgrade is not saved and does not affect the Release's existing configuration.
:::

After the Upgrade Copy Section

• The Release gets a new Revision, and the Revision and update time in the metadata of the detail page are refreshed accordingly;
• The upgrade result can be reviewed in the Revision History tab of the detail page, and compared with any historical Revision (see Notes).

Rollback a Release Copy Chapter

Entry Point Copy Section

The rollback entry is at Release detail page → Revision History tab:

1. On the Release list page, click the Release name to enter the detail page;
2. Open the Revision History tab; the table lists all historical Revisions (Revision / Updated / Status / Chart / Description);
3. On the row of the target Revision, click Rollback to this (for a Revision currently in the deployed state, the button is greyed out and cannot be clicked).

Select the Target Revision and Confirm Copy Section

Clicking it opens the rollback confirmation dialog:

When the confirmation information is correct, click Confirm Rollback; you are automatically taken to the Operation Progress page, where you can watch the rollback progress in real time or click Cancel Operation.

::: tip
Rollback does not support Dry-Run preview; submission means execution. When you are not sure about the content of the target Revision, first confirm it via the "Compare" function in Revision History (see Notes).
:::

After the Rollback Copy Section

• The rollback itself also generates a new Revision: Helm does not delete or overwrite any historical Revision; instead it redeploys the content of the target Revision as the newest Revision;
• The Revision on the detail page changes to the new value, and Revision History gains a new row; the target Revision and all earlier records are kept, and you can roll back to any of them again at any time.

Notes Copy Chapter

Check the Diff or confirm values before upgrading

1. In the Revision History tab of the detail page, select two Revisions (at least 2) and click Compare to open the Revision Diff dialog;
2. Review the differences in the Values / Manifest tabs (Manifest is the complete resource list rendered by that Revision) to make sure the changes you are about to make match your expectations;
3. For an uncertain upgrade, first check Dry-Run Preview to validate with a dry-run, then submit for real.

Behavior of the target Revision on rollback

• Rolling back to a target Revision redeploys that Revision's values and Manifest as a new Revision; after the rollback, the content in effect is that of the target Revision, regardless of the current Revision's status;
• All historical Revisions are kept, and you can roll back to any step again at any time from Revision History.

Permission requirements (namespace-scoped helm.kuboard.cn)

Related pages

• Release List and Revision History: view, compare, and inspect Revisions
• Operation Progress (Events): real-time progress, logs, and cancellation of upgrades / rollbacks
• Install a Helm Release: the complete flow for installing a new Release
• Chart Marketplace: find and browse available Charts

En Install Ha (`docs/en/install/ha.md`) Copy Section

High Availability Deployment

This document describes the Kuboard v4 High Availability (HA) production deployment: multiple Kuboard instances form a service cluster, a load balancer in front distributes traffic, and the database and Redis provide high availability and cross-instance state sharing respectively. The content is based on the official orchestration file deploy/docker-compose/docker-compose-ha-opengauss.yaml and the kuboard-server source implementation.

::: tip Intended audience
Teams that have already completed a single-node deployment (see Quick Start) and are ready to run Kuboard as a production system over the long term.
:::

Deployment Topology Copy Chapter

Kuboard v4 is a stateless Spring Boot service that scales horizontally into multiple replicas; the real cross-instance state lives in the database and Redis. The recommended topology is as follows:

The load balancer, HA database and Redis distributed cache shown above are external infrastructure that you provide and operate yourself; Kuboard only runs the multi-replica application instances:

• Multiple Kuboard replicas: 2 or more kuboard-server containers (kuboard-1 / kuboard-2 in the official orchestration);
• A load balancer in front: Nginx or HAProxy distributes user requests to the replicas (the official orchestration uses Nginx upstream + reverse proxy);
• A highly available database: MySQL master/slave replication, OpenGauss primary/standby, or PostgreSQL + Patroni. Kuboard points to the database HA connection address via DB_URL;
• Redis distributed cache: provides shared cache and event distribution across instances, supporting three access modes:
  • Redis Standalone (single instance, good performance, no failover);
  • Redis Sentinel (sentinel mode, automatic failover, described in official scenario 3);
  • Redis Cluster (cluster mode, actually used by the official HA orchestration: 6 nodes, 3 masters and 3 replicas).

Port Model Copy Section

• Browser access: nginx exposes host 9001 → container nginx 80 → upstream kuboard-1 / kuboard-2 replicas' 80
• The replica containers listen on 80 internally (browser entry); the Spring Boot backend port 9090 is not exposed
• The management endpoints 9091 are not exposed by default; decide when you integrate monitoring
• Dependency component ports (database 5432 / 3306, Redis 7001–7006) communicate within the orchestration only; no need to expose them to the host
• Changing ports: only change nginx's 9001 mapping; the replica containers keep 80

The component list of the official docker-compose-ha-opengauss.yaml is as follows:

services:
  kuboard-1:
    image: ${KUBOARD_IMAGE_REPO}:${KUBOARD_VERSION}
    environment:
      - DB_DRIVER=org.opengauss.Driver
      - DB_URL=jdbc:opengauss://db:5432/kuboard?serverTimezone=Asia/Shanghai
      - DB_USERNAME=kuboard
      - DB_PASSWORD=Kuboard@123
      - KUBOARD_CACHE_PROVIDER=redis
      - KUBOARD_CACHE_REDIS_MODE=cluster
      - KUBOARD_CACHE_REDIS_NODES=redis-node-1:7001,redis-node-2:7002,redis-node-3:7003,redis-node-4:7004,redis-node-5:7005,redis-node-6:7006
      - KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123
    volumes:
      - ./docker-compose-ha-postgres-data/kuboard-1-logs:/app/logs
    depends_on:
      db:
        condition: service_healthy
      redis-cluster-creator:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
    networks:
      kuboard_v4_ha_opengauss:

::: tip Note

• The kuboard-1 / kuboard-2 containers in the orchestration listen on port 80 internally (the image ships an Nginx front-end); the Spring Boot port 9090 is not exposed;
• KUBOARD_IMAGE_REPO / KUBOARD_VERSION must be provided by the deployer through environment variables;
• The KUBOARD_CACHE_* configuration of the two replicas must be exactly the same.
  :::

Why Multiple Instances Must Use KUBOARD_CACHE_PROVIDER=redis Copy Chapter

Kuboard's cache falls into two categories: the shared cache managed by Spring CacheManager and the in-process Caffeine local cache. The cache provider is switched via kuboard.application.cache.provider (environment variable KUBOARD_CACHE_PROVIDER, default caffeine); the code auto-wires CaffeineConfig or RedisConfig based on @ConditionalOnProperty.

In single-instance (caffeine) mode, the following cross-instance state all lives in each instance's own JVM and is invisible to other replicas in a multi-replica deployment:

Two important conclusions follow:

1. Configuration-change consistency depends on the shared cache: caches such as SystemConfig go through Spring CacheManager. In caffeine mode each replica keeps its own copy (stale for up to 5 minutes); in redis mode all replicas share the same Redis cache, so once any instance updates a configuration and evicts it, other replicas immediately read the new value.
2. Stateful session features (MCP SSE subscription push, OIDC login callback, global rate limiting) only take effect on the local instance in caffeine mode; with multiple replicas behind a load balancer you get the classic "the request landed on instance A but the state is on instance B" failure. In redis mode this is solved through Pub/Sub and shared keys.

::: warning About the MCP confirm token
The confirmToken mechanism mentioned in older versions of the documentation is deprecated in the current source code (KuboardMcpResult / McpAuditAppender only keep compatibility signatures, and McpSubscriptionScheduledCleanup no longer calls confirmToken cleanup). High-risk operation approval has been replaced by agent-mutation-approval (change approval plan). The plan and approvalToken are all persisted to the database, and approval/consumption is performed atomically with SQL-level CAS, so this mechanism guarantees consistency across multiple instances without needing Redis.
:::

Redis Environment Variable Reference Copy Chapter

Cache-related configuration is defined in kuboard-server/src/main/resources/application.yaml (kuboard.application.cache.*):

Behavior per mode (see RedisConfig.lettuceConnectionFactory()):

# Redis Standalone (single-node production, see docker-compose-mysql-redis.yaml)
export KUBOARD_CACHE_PROVIDER=redis
export KUBOARD_CACHE_REDIS_MODE=standalone
export KUBOARD_CACHE_REDIS_NODES=redis:6379
export KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123

# Redis Sentinel (1 master, 1 replica, 3 sentinels)
export KUBOARD_CACHE_PROVIDER=redis
export KUBOARD_CACHE_REDIS_MODE=sentinel
export KUBOARD_CACHE_REDIS_NODES=sentinel-1:26379,sentinel-2:26379,sentinel-3:26379
export KUBOARD_CACHE_REDIS_SENTINEL_MASTER=mymaster
export KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123

# Redis Cluster (3 masters, 3 replicas, see docker-compose-ha-opengauss.yaml)
export KUBOARD_CACHE_PROVIDER=redis
export KUBOARD_CACHE_REDIS_MODE=cluster
export KUBOARD_CACHE_REDIS_NODES=redis-node-1:7001,redis-node-2:7002,redis-node-3:7003,redis-node-4:7004,redis-node-5:7005,redis-node-6:7006
export KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123

::: tip

• The environment variable table in deploy/docker-compose/README.md writes the Sentinel master variable as KUBOARD_CACHE_REDIS_MASTER_NAME, but the actual code (application.yaml) uses KUBOARD_CACHE_REDIS_SENTINEL_MASTER — follow the latter.
• In Redis Cluster mode, all keys and Pub/Sub channels use the hash tags {kuboard:mcp} / {kuboard:mcp}:..., so they land on the same slot under sharded routing, keeping related keys and subscription events routed consistently.
  :::

Cache Invalidation Propagation Mechanism Copy Chapter

Kuboard's cache invalidation is handled jointly by K8sCapabilityCacheEvictNotifier (a static notification bridge) and K8sCapabilityCacheEvictListener (a Spring component). The trigger chain is as follows:

Update system config (SystemConfigService.updateSystemConfigById)
  ├─ Write to database (keep current version + up to 10 versions of history, switch the `current` flag)
  ├─ systemConfig.evict(t)                → evict the shared cache entry in CacheManager
  ├─ publishEvent(SystemConfigChangedEvent)  → McpToolsetRefresher rebuilds the toolset (local)
  └─ if the target type is ConfigClusterSync (cacheResources change):
       ├─ ConfigClusterSync.onCacheResourcesChanged()
       │    └─ K8sCapabilityCacheEvictNotifier.notifyEvictAll()   // static bridge, multiple handlers
       │         ├─ K8sCapabilityCacheEvictListener → capabilityCache.evictAll() (clear L3 source-probe cache)
       │         └─ McpNotificationToolsChangedListener → broadcast notifications/tools/list_changed to SSE subscribers
       └─ Publish EnvironmentChangeEvent (injected-style config) → triggers local listeners such as dynamic thread-pool adjustments

Key points:

• The notifier is a static bridge: K8sCapabilityCacheEvictNotifier maintains a CopyOnWriteArrayList; Spring components register handlers in @PostConstruct (K8sCapabilityCacheEvictListener clears the capability cache, McpNotificationToolsChangedListener broadcasts to MCP), and notifyEvictAll() runs all handlers in sequence;
• Cluster CRUD also triggers invalidation: ClusterService calls K8sCapabilityCacheEvictListener.notifyEvictCluster(clusterId) after importing / updating / deleting a cluster, clearing that cluster's version and entry caches;
• A cacheResources change does not rebuild the context: the code deliberately does not run contextRefresher.refresh() for ConfigClusterSync (a full refresh would disconnect MCP SSE long connections); instead it publishes an EnvironmentChangeEvent, and when the key contains cacheResources, K8sCapabilityCacheEvictListener.onEnvironmentChange executes evictAllCapabilities().

::: warning The real cross-replica behavior
All of the events above are local events within the Spring application context; they are not forwarded to other replicas via Redis Pub/Sub. Consistency across replicas is guaranteed by two layers:

1. Shared cache layer: SystemConfig and other CacheManager caches live in Redis, so after any instance evicts them, the "next read" on every replica falls through to the database (immediately globally consistent);
2. Local cache layer: K8sCapabilityCache is always in-process Caffeine; on replica B the invalidation event only fires on the local instance. After importing a cluster on replica A, replica B's capability cache keeps serving the old value until it expires naturally via the 1-hour TTL and is re-probed.

SystemConfigService also carries a // FIXME refresh configuration in a cluster environment comment, indicating that proactive cross-replica refresh notification is not yet implemented at the code level. In production, accept the "eventual consistency within the local cache TTL" behavior (feature correctness is unaffected; there is only a short window of stale capability judgment after a change).
:::

Database High Availability Recommendations Copy Chapter

Kuboard accesses the database through four environment variables — DB_DRIVER / DB_URL / DB_USERNAME / DB_PASSWORD (spring.datasource) — and is itself unaware of the database HA architecture, so it can plug directly into an existing database HA solution:

• MySQL / MariaDB master/slave: configure semi-synchronous replication plus automatic failover (MHA / Orchestrator, etc.), and point DB_URL at a virtual IP (VIP) or include multiple candidate addresses in the connection string;
• OpenGauss primary/standby: the db service in docker-compose-ha-opengauss.yaml is a single-node example (enmotech/opengauss:5.0.1); in production, enable OpenGauss primary/standby or use a cloud database (RDS);
• PostgreSQL: Patroni + etcd forms an automatic failover cluster, and DB_URL points at the Patroni VIP;
• Cloud database: use the vendor's MySQL / PostgreSQL HA instance directly and let the cloud platform handle primary/standby switchover.

# The database service connection config in docker-compose-ha-opengauss.yaml (single-node example)
services:
  db:
    image: enmotech/opengauss:5.0.1
    environment:
      GS_PASSWORD: Kuboard@123
      TZ: Asia/Shanghai
    healthcheck:
      test: ["CMD-SHELL", "gsql -U kuboard -W Kuboard@123 -d kuboard -c 'SELECT 1'"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 180s

::: tip Write patterns are master/slave friendly
Kuboard writes system configuration using the "insert a new version + current flag" approach (10 versions of history are kept), which is low-frequency, lightweight writing; cluster capability detection is read-heavy and write-light. Compared to the write amplification of the control-plane K8s, Kuboard tolerates master/slave lag fairly well, but you should still monitor master/slave delay to avoid reading a stale value from a replica right after saving a configuration.
:::

Official HA Orchestration Examples Copy Chapter

Redis Cluster + OpenGauss + Nginx (docker-compose-ha-opengauss.yaml) Copy Section

The Redis cluster part (6 nodes, 3 masters and 3 replicas, password auth + AOF persistence):

services:
  redis-node-1:
    image: redis:7.2-alpine
    configs:
      - source: redis_node_1_conf
        target: /redis/redis.conf
    volumes:
      - ./docker-compose-ha-postgres-data/redis-node-1:/data
    command: redis-server /redis/redis.conf
    ports:
      - 7001:7001
    healthcheck:
      test: ["CMD", "redis-cli", "-p", "7001", "-a", "Kuboard123", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      kuboard_v4_ha_opengauss:

  redis-cluster-creator:
    image: redis:7.2-alpine
    command: /bin/sh -c "sleep 10 && redis-cli -p 7001 -a Kuboard123 --cluster check redis-node-1:7001 >/dev/null 2>&1 && echo 'Redis cluster already exists, skipping creation' && exit 0; redis-cli -p 7001 -a Kuboard123 --cluster create redis-node-1:7001 redis-node-2:7002 redis-node-3:7003 redis-node-4:7004 redis-node-5:7005 redis-node-6:7006 --cluster-replicas 1 --cluster-yes; redis-cli -p 7001 -a Kuboard123 --cluster check redis-node-1:7001 >/dev/null 2>&1"
    depends_on:
      redis-node-1: { condition: service_healthy }
      redis-node-2: { condition: service_healthy }
      redis-node-3: { condition: service_healthy }
      redis-node-4: { condition: service_healthy }
      redis-node-5: { condition: service_healthy }
      redis-node-6: { condition: service_healthy }
    networks:
      kuboard_v4_ha_opengauss:

Node configuration (injected via docker config, identical for all nodes):

# redis_node_X_conf
port 7001
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes
requirepass Kuboard123
masterauth Kuboard123

The Nginx load balancer part (including the kuboard reverse proxy and WebSocket upgrades for cluster APIs):

upstream kuboard_backend {
  server kuboard-1:80;
  server kuboard-2:80;
}

server {
  listen 80;
  server_name localhost;

  location / {
    proxy_pass http://kuboard_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location /api/k8s.kuboard.cn/v4/clusters/ {
    proxy_pass http://kuboard_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
  }
}

services:
  nginx:
    image: nginx:1.25-alpine
    configs:
      - source: nginx_conf
        target: /etc/nginx/conf.d/default.conf
    ports:
      - "9001:80"
    depends_on:
      - kuboard-1
      - kuboard-2
    networks:
      kuboard_v4_ha_opengauss:

Redis Standalone + MySQL (docker-compose-mysql-redis.yaml) Copy Section

The cache configuration of the single-replica production environment, shown for comparison:

services:
  redis:
    image: redis:7.2-alpine
    command: redis-server --appendonly yes --requirepass Kuboard123
    volumes:
      - ./docker-compose-mysql-redis-data/kuboard-redis:/data
    ports:
      - 6379:6379
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "Kuboard123", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  kuboard:
    image: ${KUBOARD_IMAGE_REPO}:${KUBOARD_VERSION}
    environment:
      - DB_DRIVER=com.mysql.cj.jdbc.Driver
      - DB_URL=jdbc:mysql://db:3306/kuboard?serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
      - DB_USERNAME=kuboard
      - DB_PASSWORD=kuboardpwd
      - KUBOARD_CACHE_PROVIDER=redis
      - KUBOARD_CACHE_REDIS_MODE=standalone
      - KUBOARD_CACHE_REDIS_NODES=redis:6379
      - KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123
    volumes:
      - ./docker-compose-mysql-redis-data/kuboard-logs:/app/logs
    ports:
      - "8000:80"

Failover Behavior Copy Chapter

A Single Kuboard Instance Goes Down Copy Section

• The load balancer layer (nginx upstream) round-robins by default; when an instance refuses connections (connection refused), nginx automatically forwards the request to the next upstream instance, so service is not interrupted;
• Established WebSocket / SSE long connections break; after reconnecting, clients are distributed to a live instance by the load balancer (MCP clients typically reconnect and re-initialize);
• Because the instances are stateless, the remaining instances can serve requests independently (all cross-instance state lives in the database and Redis);
• It is recommended to add restart: always to the orchestration so a downed instance is pulled back up automatically, and to wire up monitoring and alerting.

Redis Unavailable Copy Section

Redis plays the role of "hard dependency with bounded degradation" in kuboard-server:

Database Failure Copy Section

• Multiple replicas cannot compensate for a database failure: all of Kuboard's business data, system configuration, and change approval plans are persisted in the database;
• During database primary/standby switchover, reads and writes that depend on the database fail until the new primary is available (the connection pool recovers automatically);
• Use a highly available database solution (see above) and run backup and restore drills for the database (see Upgrade and Backup).

Recovery Checklist Copy Section

• Keep the environment variables of all replicas consistent, especially KUBOARD_CACHE_PROVIDER / KUBOARD_CACHE_REDIS_*;
• Configure max_fails / fail_timeout for the nginx upstream, or switch to a load balancer with active health checks;
• Monitor three things: Redis connectivity and memory, database master/slave status, and Kuboard instance health (/actuator/health, management port defaults to 9091);
• When upgrading / scaling, roll the replicas one at a time: restart one replica, confirm it is healthy, then proceed to the next (MCP sessions and SSE connections are rebuilt per instance, avoiding a complete simultaneous interruption).

Related Documentation Copy Chapter

• Quick Start — single-node deployment
• Reverse Proxy — HTTPS and WebSocket configuration
• Upgrade — version upgrade and data backup
• Installation Index — other deployment scenarios

En Install Migration From V3 (`docs/en/install/migration-from-v3.md`) Copy Section

Migrating from Kuboard v3 to v4

Kuboard v3 and v4 are two independent products, and v3 cannot be upgraded in place to v4. Clusters must be re-imported into v4, and users, licenses, add-ons, and configurations must be recreated in v4.

This article builds on the "A Note for Kuboard v3 Users" section in Install Kuboard v4, which covers the basic compatibility conclusions; this article provides the concrete migration steps.

v3 and v4 Can Run Side by Side Copy Chapter

During the migration, v3 and v4 can run side by side without affecting each other:

• Deployment level: v3 and v4 are mutually independent. v3 uses built-in storage, while v4 requires its own database instance (MySQL / MariaDB / OpenGauss, choose one). You can deploy the two in different servers or containers, or in different namespaces of the same Kubernetes cluster, accessed via different domains.
• Cluster level: The same Kubernetes cluster can be imported into both v3 and v4 at the same time; both versions can manage the cluster normally.
• Same-named clusters: If a cluster has the same name in v3 and v4, add-ons are not affected and work normally in both v3 and v4; if the names differ, the add-on resources still remain in the cluster, but you need to re-run the add-on initialization / activation flow in v4.

::: tip About this documentation site
The old v3 documentation site will move to a separate domain, v3.kuboard.cn, separated from the v4 documentation site (this site), so that v3 users can keep reading historical materials.
:::

v3 and v4 Licensing Are Mutually Independent Copy Chapter

v3 license files and v4 licensing are mutually independent: a v3 license cannot be imported into v4, and a v4 license cannot be used in v3. When migrating to v4, you need to obtain and import a license for v4 separately; while v3 and v4 run side by side, each needs its own license. For the differences between the free and Enhanced editions, see Licensing and Support.

::: tip
After importing a license file in the v4 UI, you can check its status (Valid / Invalid / Expired) on the license list page; only proceed with subsequent steps once the import is confirmed successful.
:::

Recommended Migration Path Copy Chapter

The migration path is an operational recommendation — validate it against your environment before executing.

1. Deploy a v4 instance and initialize it
   Follow Install Kuboard v4 to prepare the database (MySQL / MariaDB / OpenGauss, choose one), and start v4 per Quick Start or High Availability. Log in with the default administrator admin (default password Kuboard123) and change the password immediately.

2. Import the cluster
   Import the cluster from the v4 UI. We recommend keeping the cluster name the same as in v3, so that add-ons work normally in both v3 and v4; after importing, first verify that the cluster status and synchronization are normal.

3. Rebuild workload views and cluster resource configuration
   Reconfigure the display and access of nodes, namespaces, and workloads in v4. Check whether resource types you used in v3 but have not yet validated in v4 (StorageClass, Ingress, gateways, etc.) display correctly in v4.

4. Check add-on compatibility
   Go to the v4 add-on market and check whether the add-ons you need can be installed / activated; if initialization scripts (e.g., CRD, RBAC) are required, complete the initialization per the add-on documentation before activating.

5. Migrate users and permissions
   Recreate users and user groups in v4 and configure authorization rules. v4's authorization model differs from v3's; reconfigure it per v4's authorization approach — see the "Manual Adjustments Checklist" below.

6. Validate
   Validate with a regular user account: log in, view clusters, operate workloads, open terminals and logs (dependent on WebSocket — make sure the reverse proxy allows it), and verify that the audit log and MCP (if used) chains work normally.

7. Take v3 offline
   After all features pass validation, gradually take the v3 instance offline. We don't recommend stopping v3 before validation is complete — running the two versions side by side is cheap.

Manual Adjustments Checklist Copy Chapter

The following items have no automatic migration channel in v4 and must be done manually:

Common Migration Mapping Table Copy Chapter

::: tip
For v3 features not listed in the table, verify them one by one against the v4 UI and the Usage Guide.
:::

Version Upgrade vs. Version Migration Copy Chapter

These two concepts are easy to confuse, so note the difference:

• In-version upgrade of v4 (v4.x → v4.y): just change the image tag; the database is migrated automatically by v4 — see Upgrade Kuboard;
• v3 → v4 migration (this article): a migration between two independent products; there is no in-place upgrade channel and you must follow the steps in this article.

Related Documents Copy Chapter

• Install Kuboard v4 — installation, database preparation, environment variables, reverse proxy, and HA parameters
• Quick Start — quickly bring up a v4 instance with docker compose
• Upgrade Kuboard — in-version upgrades of v4
• High Availability — v4 high-availability deployment
• Reverse Proxy — Nginx / Ingress configuration and WebSocket passthrough
• Usage Guide — an overview of v4 features (clusters, workloads, add-on market, etc.)
• Licensing and Support — v4 free / Enhanced edition feature comparison

En Install Reverse Proxy (`docs/en/install/reverse-proxy.md`) Copy Section

Reverse Proxy

Configure HTTPS and WebSocket for Kuboard (via an Nginx reverse proxy or a Kubernetes Ingress) for use in production.

Why Use a Reverse Proxy Copy Chapter

Kuboard uses plain HTTP by default so that you can try it out quickly. In production, make sure HTTPS is enabled. You can either enable HTTPS directly on a Kubernetes Ingress and forward traffic to the Kuboard Service, or set up your own Nginx in front of Kuboard and configure HTTPS on it.

Two Things to Note Copy Chapter

• WebContextRoot (root path): Kuboard must be served from the root path, e.g. https://kuboard.yourcompany.com/; sub-paths such as https://yourcompany.com/kuboard/ are not supported.
• WebSocket must be enabled: the terminal and log features rely on WebSocket, so the reverse proxy must allow WebSocket upgrade requests, otherwise the terminal and logs will not work.

Nginx Configuration Example Copy Chapter

When using Nginx as the reverse proxy, replace the two addresses marked in the comments with your domain and Kuboard node address, then use it directly; if HTTPS is enabled on Nginx, also uncomment the # proxy_set_header X-Forwarded-Proto https; line in both location blocks.

server {
  listen  80;
  server_name kuboard.yourdomain.com;   # replace with your domain
  location / {
    proxy_pass  http://192.168.2.39:32567;  # replace with your node address
    proxy_http_version 1.1;
    proxy_pass_header Authorization;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    # proxy_set_header X-Forwarded-Proto https; # enable this if you have enabled HTTPS on the reverse proxy
  }
  location /k8s-ws/ {
    proxy_pass  http://192.168.2.39:32567;  # replace with your node address
    proxy_http_version 1.1;
    proxy_pass_header Authorization;
    proxy_set_header Upgrade "websocket";
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    # proxy_set_header X-Forwarded-Proto https; # enable this if you have enabled HTTPS on the reverse proxy
  }
  gzip on;
}

Ingress Configuration Example Copy Chapter

When using nginx-ingress as the Ingress Controller, save the following configuration as ingress.yaml, replace the domain and the certificate Secret (which must be created in advance), then run kubectl apply -f ingress.yaml; for other Ingress controllers (traefik, ingress-nginx, etc.), refer to the official documentation and configure WebSocket and PassHeader yourself.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kuboard
  namespace: kube-system
  annotations:
    nginx.org/websocket-services: kuboard
    nginx.org/proxy-pass-headers: 'Upgrade,Connection,Authorization'
spec:
  rules:
    - host: demo.kuboard.cn
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kuboard
                port:
                  name: http
  tls:
    - hosts:
        - demo.kuboard.cn
      secretName: demo.kuboard.cn

• The two annotations nginx.org/websocket-services and nginx.org/proxy-pass-headers enable WebSocket and forward the authorization header (for session affinity or display name, you can add the nginx.com/sticky-cookie-services and k8s.kuboard.cn/displayName annotations yourself).

Related Documentation Copy Chapter

• Quick Start — single-node deployment
• High Availability (HA) — multi-replica deployment and load balancing
• Index — other deployment scenarios
• Upgrade — version upgrades and data backup
• Migrating from v3 — migrating from v3 to v4

En Install Upgrade (`docs/en/install/upgrade.md`) Copy Section

Upgrading Kuboard V4

Upgrading Kuboard V4 requires only two steps: change the image tag and recreate the container. On startup the database schema migrates automatically, and the data volumes stay unchanged. This article covers the image tag strategy, the upgrade steps and the rollback strategy.

::: tip Intended audience

• Single-node instances deployed with the docker compose quick start or the Installation Guide;
• Multi-replica instances deployed with the High Availability (HA) Deployment (the migration mechanism is the same);
• Readers upgrading from Kuboard v3 should refer to Migrating from v3: the architectures of v3 and v4 are incompatible and cannot be upgraded directly.

:::

Image Tag Strategy Copy Chapter

Kuboard V4 images are published in the following two registries:

Each registry publishes the following types of tag:

::: tip Production recommendation

• In production, deploy and upgrade with the fixed version tag (e.g. v4.2.2.0), not the rolling tag v4;
• When upgrading, only do "switch from the old version tag to the new version tag", so that on rollback you can return precisely to the last known good version.

:::

Tag Location in a docker compose Deployment Copy Section

In all compose files under the deploy/docker-compose/ directory, the Kuboard service image is uniformly written as:

image: ${KUBOARD_IMAGE_REPO}:${KUBOARD_VERSION}

The two variables are defined in the .env file in the same directory:

KUBOARD_IMAGE_REPO=swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard
KUBOARD_VERSION=v4.2.2.0

• KUBOARD_IMAGE_REPO: the image registry address; fill in eipwork/kuboard or the Huawei Cloud SWR address according to your network environment;
• KUBOARD_VERSION: on upgrade you only need to change this variable to point to the new version tag.

The sample value 192.168.3.109:5001/kuboard in the repository's .env is an internal private registry address, used only for development; use a public registry address in production.

Users who deployed with a single container via docker run (see the Installation Guide) can simply replace the image tag in the startup command with the new version, keeping all other environment variables unchanged.

Automatic Database Schema Migration Copy Chapter

On startup, the new version automatically performs the database schema migration (DDL); no manual SQL is needed. The migration scripts are idempotent, so you can upgrade directly across several minor versions without upgrading version by version.

::: tip

"Startup succeeded" means the database schema is ready: the migration finishes automatically before the application starts serving traffic, and multiple replicas starting at the same time do not conflict. No manual SQL is needed, but backing up the database before the upgrade is still recommended (commands below in "Pre-upgrade Preparation").

:::

Pre-upgrade Preparation Copy Chapter

Back Up the Database Copy Section

::: danger Back up first, then upgrade

• A backup is a mandatory step before upgrading — do not skip it: the database schema migration is not reversible (there are no downgrade scripts); once the upgrade starts, the old-version code may no longer be compatible with the migrated table structure;
• Without a pre-upgrade backup, rollback may fail: if you need to revert to an older version after upgrading, the only reliable recovery path is to first restore the pre-upgrade database backup and then start the old-version image. Without such a backup, rollback loses its reliable data foundation and is likely to fail;
• So run the backup commands below first, confirm the backup file was created successfully, and only then continue with the upgrade steps.

:::

• MySQL / MariaDB:

  sh Copy

  mysqldump -h <db_host> -ukuboard -p --single-transaction kuboard > kuboard-backup-$(date +%F).sql

• PostgreSQL / OpenGauss:

  sh Copy

  pg_dump -h <db_host> -U kuboard kuboard > kuboard-backup-$(date +%F).sql

Confirm the Data Directories Are Intact Copy Section

::: warning

The upgrade only recreates the Kuboard container; the database, Redis and log data directories are not touched. Never run docker compose down -v, and do not delete or rm -rf the data directories, or the data will be lost. The list of data directories is in "Data Volume Retention" below.

:::

Upgrade Steps (docker compose) Copy Chapter

The following uses the docker-compose-mysql-redis.yaml from the docker compose quick start as an example; the other compose files (MariaDB, HA, etc.) work in exactly the same way.

Step 1: Back Up the Database Copy Section

Run a backup following "Back Up the Database" above, and keep the backup file outside the data directories.

Step 2: Change the Image Tag Copy Section

Edit deploy/docker-compose/.env and set KUBOARD_VERSION to the target version:

KUBOARD_IMAGE_REPO=swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard
KUBOARD_VERSION=v4.2.2.0

Step 3: Pull the New Image Copy Section

docker compose -f docker-compose-mysql-redis.yaml pull kuboard

Step 4: Start (Recreate the Container) Copy Section

docker compose -f docker-compose-mysql-redis.yaml up -d

Because the image tag has changed, compose recreates the kuboard container; the database and Redis containers are not affected and are not recreated. If you are worried about a service outage window, run docker compose -f docker-compose-mysql-redis.yaml stop kuboard first, and then run the up -d above. In a single-instance deployment, the downtime caused by container recreation is usually only a few seconds.

Step 5: Observe the Migration Logs Copy Section

docker compose -f docker-compose-mysql-redis.yaml logs -f kuboard

The startup logs show the migration execution records; if an error log message about failing to execute an SQL file appears (the application's log messages are output in Chinese; the equivalent English message is "failed to execute SQL file"), the migration is abnormal. After the migration finishes, the application becomes ready normally, and the compose health check (curl -f http://localhost:80/) passes.

::: warning Behavior when the migration fails

When the migration hits an exception, the container fails to start and stays in an exited / restart-loop state; it never runs in a degraded state. In this case, keep the logs for troubleshooting, and if necessary roll back to the old version tag (see "Rollback Strategy" below).

:::

Step 6: Verify Copy Section

• Open the Kuboard UI (mapped to http://localhost:8000 in the compose example) and confirm the core features work normally: login, cluster list, namespaces, etc.;
• Check whether the entries for the new features listed in the new-version release notes exist.

Upgrade Notes Copy Chapter

Data Volume Retention Copy Section

The upgrade only recreates the kuboard container; never delete the following directories:

Environment Variable Consistency Copy Section

During an upgrade, change only KUBOARD_VERSION (and KUBOARD_IMAGE_REPO when necessary); do not casually change the database-related environment variables. The environment variables of the kuboard service in the compose file are as follows (docker-compose-mysql-redis.yaml):

environment:
  - DB_DRIVER=com.mysql.cj.jdbc.Driver
  - DB_URL=jdbc:mysql://db:3306/kuboard?serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
  - DB_USERNAME=kuboard
  - DB_PASSWORD=kuboardpwd
  - KUBOARD_CACHE_PROVIDER=redis
  - KUBOARD_CACHE_REDIS_MODE=standalone
  - KUBOARD_CACHE_REDIS_NODES=redis:6379
  - KUBOARD_CACHE_REDIS_PASSWORD=Kuboard123

• The DB_* variables point to the same database instance (the data volumes have not been touched); changing them would make the new container unable to connect to the existing data;
• TZ, KUBOARD_CACHE_*, etc. are unrelated to the version; keeping them unchanged is fine;
• KUBOARD_CACHE_PROVIDER only affects the runtime cache (in-memory cache or Redis distributed cache, see High Availability (HA) Deployment); switching the cache mode does not trigger any data migration and has nothing to do with the database schema.

High-Availability Multi-replica Scenario Copy Section

Multiple replicas point to the same database. It is recommended to roll the replicas one at a time: upgrade one replica first, confirm the migration logs are normal, then upgrade the remaining replicas, to narrow the risk window. The migration scripts are idempotent, so concurrent migration across replicas does not conflict either.

Rollback Strategy Copy Chapter

Compatibility Copy Section

Upgrade scripts are mainly incremental changes (adding columns, tables, and indexes), so an old-version image can usually still run on the upgraded database schema. Therefore, upgrading directly from any old version to the latest version, as well as rolling back immediately after an upgrade, are both feasible.

Rollback Steps Copy Section

# 1. Edit .env and set KUBOARD_VERSION back to the old version tag
# 2. Pull the old image and recreate the container
docker compose -f docker-compose-mysql-redis.yaml pull kuboard
docker compose -f docker-compose-mysql-redis.yaml up -d
# 3. Observe the logs to confirm the rolled-back version starts normally
docker compose -f docker-compose-mysql-redis.yaml logs -f kuboard

Risk Warning: the Migration Is Not Reversible Copy Section

::: danger Evaluate before rolling back

• There are no downgrade scripts: once the schema has been migrated by the new version, "switching back to the old image" cannot automatically restore the table structure;
• New data formats do not roll back: data written while the new version runs may be unreadable by the old-version code, manifesting as broken features or errors.

Therefore: you must back up the database before upgrading (see "Back Up the Database"); rollback is only suitable for "an anomaly found immediately after the upgrade, with a very small amount of new data"; if the new version has been running for a while and a lot of new data has been produced, prefer continuing to upgrade to the latest version to fix the problem rather than rolling back.

:::

Related Documentation Copy Chapter

• Install Kuboard V4
• Quick Start
• High Availability (HA) Deployment
• Migrating from v3

En Mcp Approval Flow (`docs/en/mcp/approval-flow.md`) Copy Section

Agent Change Approval Flow

An agent cannot modify the cluster directly: it first submits a "Change Plan", and only after you approve it and the agent obtains a one-time approval token does the actual write happen.

This page is for users who approve AI changes in the Kuboard Web UI and developers who configure the change flow for agents. It expands on the "Agent Change Approval" section of the MCP integration overview.

5-Phase Flow Overview Copy Chapter

A change plan's full approval flow (Approval Flow) consists of 5 phases, mapped to the various statuses of the plan on the server:

flowchart LR
    A["CREATED<br/>Agent appends steps"] -->|finalize_plan| B["PENDING<br/>Waiting for manual approval"]
    B -->|Approve| C["APPROVED<br/>Issue one-time token"]
    C -->|apply_plan with token| D["APPLYING<br/>Execute step by step"]
    D --> E["APPLIED<br/>All succeeded"]
    D --> F["PARTIAL_APPLIED<br/>Partially applied, cannot resume apply"]
    D --> G["FAILED<br/>First step failed"]
    B -->|Reject| H["REJECTED"]
    A -->|Timeout| I["EXPIRED"]
    B -->|Timeout| I
    C -->|Timeout| I

The plan moves forward one way along the arrows: the agent proposes a plan → you approve it in the UI → the agent receives the token → the agent executes step by step → results are collected. Execution can land in one of three terminal states; "Rejected" or "Expired" voids the plan outright.

Phase 1: The Agent Proposes a Plan Copy Chapter

The agent builds and submits a plan using 3 tools:

1. create_plan(description) creates an empty plan. description is the purpose of the operation shown to the approver (e.g. "restore the nginx deployment and open its port"), displayed at the top of the approval screen.
2. append_step_to_plan(planId, tool, args, description) appends each object to be changed as a step of the plan. A dry-run rehearsal is performed before appending:
   • Rehearsal passes → the step enters the plan;
   • The cluster does not support dry-run (Kubernetes 1.15~1.17) → degraded pass;
   • Rehearsal fails → the step is rejected; the agent must fix the parameters and retry, or drop the object.
3. finalize_plan(planId) submits the plan so it appears on the approval page. After submission, no more steps can be appended; an empty plan cannot be submitted.

The tools that can be appended form the write-operation whitelist (also the criterion for "whether approval is mandatory"):

["apply_k8s", "patch_k8s", "delete_k8s", "delete_k8s_collection",
 "drain_node", "evict_pod",
 "restart_workload", "scale_workload", "update_image_tag", "rollback_workload"]

::: tip One plan = one operation intent
Multiple objects to be changed under the same intent should be aggregated into the same plan as much as possible, so that it is approved only once.
:::

Phase 2: Approval in the Kuboard UI Copy Chapter

After logging into Kuboard, open "Agent Change Approval" at the top of the left-side menu (path /agent-change-plans). Plans awaiting approval expand automatically, showing each step's purpose, cluster, namespace, resource and action. You can perform three operations:

• Approve All: confirm directly without selecting anything; every step is approved.
• Approve Selected: in the step selection table, uncheck the objects you do not want to run, then click "Approve Selected". Unchecked steps are skipped and nothing changes in the cluster; the confirm button is disabled when 0 steps are selected.
• Reject: after filling in the rejection reason (required), the plan is voided and the cluster is not modified. Rejection is allowed in both the "Pending" and "Approved" states.

::: tip Verify after partial approval
After a partial approval, the agent can use get_plan_approve_status(planId) to query the approval result of each step and clearly tell you in the session: which objects were approved, which were skipped, and the potential consequences.
:::

To abandon a submitted plan, reject it (the cancel operation is currently not exposed to users).

Phase 3: The One-Time Token Copy Chapter

After approval, the server issues a one-time token (approval token). In the UI, click "View Token" to copy it (this button appears only when the plan is approved and not expired). Token rules:

Hand the planId and the token together to the agent so that it can execute.

::: warning A token equals write authorization
The token is the credential authorizing writes to the cluster. Do not leak it to anyone other than the plan holder; it expires if unused within 15 minutes, and you must approve again afterwards.
:::

Phase 4: Step-by-Step Execution Copy Chapter

After the agent calls apply_plan(planId, approvalToken), the server executes the steps in order:

• Validates that the token matches the plan and is not expired, then executes each step in turn;
• After each step completes, the approval page refreshes the execution progress in real time;
• Stops at the first failure: all subsequent steps are marked as skipped and execution does not continue.

The execution outcomes map to three terminal states:

::: danger No resuming apply after partial success
When apply fails halfway or the process is interrupted, unexecuted steps are not retried automatically and you are never asked "continue?" — you must create a new plan and go through the full approval again. This is a deliberate design to avoid retrying failed changes without the user's knowledge.
:::

Special skip rules during execution:

• Steps unchecked under partial approval → skipped;
• Steps already succeeded or already skipped → skipped (idempotent);
• Steps that failed dry-run but stayed in the plan → converted to skipped during execution.

Phase 5: Result Collection Copy Chapter

Once the plan reaches a terminal state, all parties collect the results:

Agent side

• apply_plan returns the plan's terminal state with applied / failed / skipped counts, plus each step's status and error message;
• get_plan_approve_status is used before execution to check which objects were approved / skipped.

User side (UI)

• The list and detail views show each step's rehearsal and execution results;
• Rollback: works only on apply_k8s steps that carry a pre-execution snapshot in PARTIAL_APPLIED / APPLIED plans, restoring to the pre-change state in one click; objects created by the change (did not exist before) cannot be rolled back automatically;
• Delete: only plans that are "expired and not fully successful" can be deleted (physical deletion, unrecoverable); successfully executed plans are kept forever as evidence of the change.

Timeouts and Recovery Copy Chapter

::: tip

• A plan not handled within 30 minutes by default expires automatically, and its list status becomes "Expired"; plans in the "Building / Pending / Approved" states are converted to expired automatically when read.
• After approval, the token is valid for 15 minutes; after expiry, execution is rejected and you must create a new plan and approve again.
• If apply fails halfway and the plan enters the PARTIAL_APPLIED terminal state, it cannot be re-approved or re-applied; you must create a new plan.
• Each user can hold at most 50 plans that have not reached a terminal state at the same time.
  :::

Danger Levels and Approval Copy Chapter

Every plan and step carries a danger level:

The danger level only affects the emphasis on the approval screen (LOW blue / MEDIUM yellow / HIGH red highlight); it does not decide whether approval is mandatory.

::: warning Mandatory approval is decoupled from the danger level
The criterion is the write-operation whitelist: every MCP tool that issues a persistent write to the cluster is on the whitelist and must go through approval, regardless of its labeled danger level — an operation marked LOW cannot bypass approval. See Danger level mechanism. The mandatory-approval switch is in Server configuration.
:::

Related Pages Copy Chapter

• MCP integration overview
• MCP tools
• Danger level mechanism
• Server configuration

En Mcp Danger Levels (`docs/en/mcp/danger-levels.md`) Copy Section

Danger Level Mechanism

This page explains the danger level of Kuboard MCP tools: how the three tiers are defined, which tier each tool is labeled with, and how it works together with Agent Change Approval to protect the cluster. It is written for ops / platform engineers configuring a change flow for agents. We recommend reading the Approval flow first.

Three Danger Levels and the Tool Map Copy Chapter

Every MCP tool carries a danger level that answers "how dangerous is this AI operation and how much control does it need", with three tiers:

::: tip What the level is based on
The level reflects the real blast radius of the operation, not "whether it writes to the cluster": delete_k8s_collection deletes a whole resource collection at once, so it is HIGH; delete_k8s only touches one object, so it is MEDIUM.
:::

Levels are assigned when the tools are registered: read tools default to LOW, write tools declare their level explicitly. You do not need to know the details of the assignment — just look up the table below to see which level each tool is:

::: warning LOW-labeled tools can still be write operations
The 4 CD write tools such as restart_workload are labeled LOW but are real write operations. Whether approval is required is decided by the write-tool whitelist, not the danger level — a LOW label does not let you bypass approval. See the next section.
:::

From Confirm Token to Approval Gate Copy Chapter

The danger level mechanism has gone through two generations of control.

First generation · confirm token (deprecated): in the early days, HIGH-level operations were confirmed with a one-time token. The agent fetched a token and executed directly with it — the token traveled back and forth within the session, and once obtained it could apply immediately. You only noticed afterwards, and you could not vet the many changes in a single plan one by one.

Second generation · Agent Change Approval (current): the confirm token has been fully retired and replaced by "change plan + manual approval gate": the agent adds write operations to a plan one by one → you approve in the Kuboard UI → a one-time approval token is issued → the agent executes step by step with it.

First generation: agent fetches the token itself → executes with it (passes as soon as it is obtained, you only know afterwards)
Second generation: agent builds a plan → you approve in the UI → receives an approval token → only then can it execute (cannot bypass you)

::: tip The difference between the two tokens
The confirm token was "the agent's self-confirmation"; the approval token is "the credential of your manual approval". Danger levels exist in both generations — the only thing that changed is who performs the second confirmation that HIGH operations require.
:::

Danger Levels and the Approval Gate Copy Chapter

Whether approval is mandatory is decided by the Force Agent Change Approval switch (enabled by default, see Server configuration) together with a write-tool whitelist. When enabled, the 10 write tools on the whitelist are completely invisible to the agent and cannot be called directly — they can only be executed through the plan flow; even if the agent bypasses enumeration and calls them directly, the call is rejected at call time.

["apply_k8s", "patch_k8s", "delete_k8s", "delete_k8s_collection",
 "drain_node", "evict_pod",
 "restart_workload", "scale_workload", "update_image_tag", "rollback_workload"]

Danger level and whether approval is required are fully decoupled: the criterion is the whitelist, not the danger level. restart_workload is labeled LOW but is still on the list and still requires approval.

The Role of Danger Levels in Approval and Audit Copy Chapter

Once inside the approval flow, the danger level plays three roles: tier management + UI hint + audit trail.

• Step level: each step's danger level comes from the tool's own label; if missing, it defaults to MEDIUM
• Plan level: a plan's danger level is the highest of all its steps — a single HIGH step makes the whole plan HIGH
• UI hint: LOW shows in blue, MEDIUM in yellow, HIGH in red and highlighted. The tier only decides how prominent the hint is, not whether approval is required

Danger levels are also written into audit and monitoring, to answer "which agent did what high-risk operation, and when":

Monitoring metrics carry a danger-level label, so you can directly answer "how many HIGH-level operations were executed / approved / blocked in the last hour".

Common Misconceptions Copy Chapter

1. "A LOW label lets you bypass approval" — Wrong. Approval looks at the whitelist, not the danger level; LOW write tools such as restart_workload are still blocked.
2. "confirmToken is still in use" — Wrong. It has been fully replaced by Agent Change Approval; the token parameter sent by old clients is only a backward-compatibility shell and takes part in no validation.
3. "The danger level only affects the hint" — True as far as "whether approval is required" goes, but it also decides the emphasis strength on the approval screen.
4. "A plan's level is the average of its steps" — It is the highest value, not the average.

Related Pages Copy Chapter

• MCP integration overview — entry to "Agent Change Approval"
• Server configuration — the Force Agent Change Approval switch and other settings
• MCP tools — the full tool list and write-operation whitelist
• Agent Change Approval Flow — the full submit → approve → execute flow

En Mcp Prompts (`docs/en/mcp/prompts.md`) Copy Section

Kuboard MCP Server Built-in Prompts (Prompt Templates)

A prompt is a server-side preset "prompt template": the client fills in parameters and receives a block of instruction text that can be handed directly to an AI. This page lists the purpose, parameters, and template text of the 3 prompts built into Kuboard, and explains how clients trigger them. Reading ./server-config and ./tools first is recommended for background.

What a Prompt Is and How It Differs from Tools Copy Chapter

Prompts and tools are both "capabilities" that the MCP protocol exposes to clients, but they play entirely different roles:

::: tip Use them like slash commands
The typical use of a prompt is "give the AI a high-quality task instruction". For example, diagnose_pod returns the instruction "analyze the Pod's state", and the AI then calls several read tools to collect data before answering, which is why prompts are often compared to the client's slash commands.
:::

Built-in Prompts at a Glance Copy Chapter

Kuboard ships 3 prompts in total:

The {parameter name} placeholders in a template are automatically replaced with the parameters you provide; the rest of the text is kept as-is.

Each Prompt in Detail Copy Chapter

diagnose_pod: Diagnose a Pod Copy Section

When a Pod is in an abnormal state (CrashLoopBackOff, ImagePullBackOff, Pending, etc.), let the AI analyze it in a consistent way.

Template text:

Analyze the current state of Pod {namespace}/{name} in cluster {clusterId}. Focus on: Warning events / status phase and conditions / restartCount changes. If there is ImagePullBackOff or CrashLoopBackOff, provide troubleshooting steps.

Typical usage: After the AI receives this instruction, it calls read tools (such as get_pod, event queries, see ./tools) to collect events / status / restartCount, then outputs a structured diagnosis. The template deliberately focuses on "evidence dimensions" so the AI does not talk in generalities.

generate_deployment_yaml: Generate a Deployment YAML Copy Section

Directly translates "image + replica count" into a ready-to-use Deployment YAML draft.

Template text:

Generate a Deployment YAML from image {image}. If the replicas parameter is provided, generate with {replicas} replicas.

Typical usage: The AI can produce the YAML directly after receiving the instruction; if it needs to be applied to the cluster, it goes through the plan-approval flow (see ./approval-flow).

cleanup_orphaned_pvc: Scan for Orphaned PVCs Copy Section

Finds PVCs in the cluster that are no longer referenced by any Pod and gives cleanup suggestions — scan only, zero writes.

Template text:

Scan cluster {clusterId} for orphaned PVCs (no Pod references) and provide cleanup suggestions.

Typical usage: There is only one required parameter, so the client does not need to be aware of namespace details. The template says "provide cleanup suggestions" rather than "execute the deletion" — an actual deletion is a write operation that goes through the approval gate (see ./danger-levels and ./approval-flow).

::: warning The prompt itself performs no cluster operations
cleanup_orphaned_pvc only has the AI list PVCs / check reference relationships and give suggestions; if the AI then initiates a deletion, that step is still a tool call, governed as usual by RBAC, danger levels, and the approval gate.
:::

How Clients Trigger Prompts Copy Chapter

The client and the MCP Server communicate via JSON-RPC 2.0 (Streamable HTTP, see ./server-config); there are only two prompt-related methods: prompts/list and prompts/get.

prompts/list: Enumerate All Prompts Copy Section

The request must carry Authorization: Bearer <ACCESS_KEY>.<SECRET_KEY> (format see ./server-config), and the endpoint is /mcp:

curl -X POST http://<backend-host>:9090/mcp \
  -H "Authorization: Bearer <ACCESS_KEY>.<SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"prompts/list","params":{}}'

The response returns the name, description, and parameter definitions of every prompt (only the first is shown here; the full list has 3 entries):

{
  "prompts": [
    {
      "name": "diagnose_pod",
      "description": "Diagnose the current state of a Pod: output a structured analysis based on events / status / restartCount",
      "arguments": [
        { "name": "clusterId", "required": true },
        { "name": "namespace", "required": true },
        { "name": "name", "required": true }
      ]
    }
  ]
}

prompts/get: Get the Rendered Prompt Copy Section

params supplies name and arguments; the messages[0] of the response is the instruction with parameters filled in, ready to feed to an AI:

curl -X POST http://<backend-host>:9090/mcp \
  -H "Authorization: Bearer <ACCESS_KEY>.<SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"prompts/get","params":{"name":"diagnose_pod","arguments":{"clusterId":"prod","namespace":"default","name":"nginx-7d8f9"}}}'

Using Prompts in AI Clients Copy Section

Clients such as opencode and Claude Code expose prompts in a session as selectable templates (like slash commands): after you pick a prompt name and fill in the parameters, the client automatically issues prompts/get and hands the returned user message together with the subsequent tool calls to the model. A prompt is a prompt template, not an automation script — after triggering, the AI still has to call tools itself to perform the actual actions. The value of a prompt is that "how to analyze, what to look at first, what format to output" is written in advance.

Common Misconceptions Copy Chapter

1. "Prompts automatically run diagnostics / generation / cleanup" — wrong. A prompt returns instruction text; every actual action is done by the AI's subsequent tool calls.
2. "replicas is optional, so it's fine to omit it" — right. The optionality is expressed by the template's conditional clause "If the replicas parameter is provided..."; only when passed does it carry the replica-count constraint.
3. "Prompts can bypass authentication / approval" — wrong. Prompt requests require access-key authentication just the same (see ./server-config); any write operation prompted by a prompt is finally a tool call and is still blocked by the approval gate (see ./approval-flow).
4. "Prompts only have Chinese templates" — Chinese and English templates are both built in; no configuration is needed. When a template is missing, an empty instruction is returned.

Related Pages Copy Chapter

• ./server-config — MCP Server protocol version, endpoint, and overall configuration
• ./tools — the full set of MCP tools the AI actually uses after a prompt is triggered
• ./approval-flow — how write operations prompted by a prompt enter plan approval
• ./danger-levels — tool danger levels: why "giving suggestions" and "executing deletion" differ in control strength

En Mcp Server Config (`docs/en/mcp/server-config.md`) Copy Section

MCP Server Configuration

This page explains how to configure the MCP (Model Context Protocol) Server settings in System Settings → MCP Server. For agent client setup steps, see Quick Start.

::: tip Version note
The card-based sections, Test Connection, danger-switch warnings, and Agent Change Approval on the "MCP Server Settings" page are available since v4.2.2.0.
:::

The settings page is split into three cards: Service Overview, Transport & Limits, and Prometheus Tools, described in that order below.

Service Overview Copy Chapter

Enable MCP Server Copy Section

When enabled, the MCP endpoint is exposed to the outside; when disabled, requests to /mcp always return HTTP 404.

The MCP endpoint path is /mcp, supporting both POST (JSON-RPC over Streamable HTTP) and GET (SSE streaming connection, for clients such as opencode).

::: tip Reverse proxy
If you use a reverse proxy, make sure the /mcp path routes to the Kuboard backend service, not the frontend service.
:::

MCP Address and Test Connection Copy Section

The settings page shows the current MCP address (in the format "your Kuboard access address + /mcp"). Click Copy to copy it to the clipboard; click Test Connection to verify the address is reachable — a response of 200 / 401 / 405 is treated as "reachable" (401 means the endpoint is online but requires authentication).

Authentication Copy Section

The MCP endpoint authenticates with the same Access Key as Kuboard. Clients carry Authorization: Bearer <AK>.<SK> or Kb-Access-Key: <AK>.<SK> in the request header. Access keys are created under user menu (top-right) → Access Keys; the snippet generated when copying the MCP configuration fills in this header automatically.

Mandatory Approval for Agent Write Operations Copy Chapter

Enabled (default): write operations by agents (apply_k8s / delete_k8s / drain_node / evict_pod, etc.) are first staged as a change plan, and only take effect on the cluster after you approve each one in the Kuboard UI and pass the one-time approval token (approvalToken) back to the agent. Disabled: write calls execute directly and immediately, and a red warning banner appears on the page.

::: danger
Disabling "Force agent change approval" means giving up the human review of AI write operations; it is not recommended to disable it in production. For the full flow, see Change Approval Flow and Dangerous Operations and Confirmation Tokens.
:::

Transport & Limits Copy Chapter

Allowed CORS Origins Copy Section

Cross-origin browser clients (e.g. https://chat.openai.com) must be configured here, otherwise their cross-origin requests are rejected.

Every entry must start with http:// or https:// (the form validates it immediately). This setting applies only to the MCP endpoint; it does not affect the cross-origin behavior of other main-application APIs.

Maximum Request Body Size Copy Section

Limits the maximum byte size of a single MCP request (the JSON-RPC request body); default 10 MB, and requests exceeding the limit return HTTP 413. If your AI client sends large tool arguments, you can raise it; the UI steps in 1 MB increments.

Per-user Rate Limit Copy Section

When a user exceeds the limit within the sliding window, HTTP 429 is returned and the client should back off and retry accordingly. The configuration takes effect hot — no restart required.

Maximum SSE Subscriptions per User Copy Section

Limits the number of concurrent resource/prompt change subscriptions each user may hold; default 100 (unit: connections). Requesting one more subscription beyond the limit returns an error.

::: warning Restart required after saving
A Kuboard service restart is required after saving this value for it to take effect; the UI also shows this note.
:::

Prometheus Tools Copy Chapter

The settings in this section control the Prometheus metrics query tools exposed through MCP (prometheus_query / prometheus_query_range, etc.).

Master Switch Copy Section

On by default. When disabled, the tools still appear in the tool list, but calling them directly returns PROM_NOT_FOUND, and service discovery and per-query RBAC checks are skipped.

Query Limits and Authorization Copy Section

Aggregate Query Policy Copy Section

Three policies for "filter + aggregate" PromQL (e.g. sum, avg, count, topk):

Two companion numeric settings:

• Aggregate query rate multiplier: an aggregate query consumes this many times the rate-limit quota in one call; default 5×;
• Aggregate query max scope expansion: the maximum number of namespace/node dimensions a single aggregate query may expand to; default 100, preventing one broad aggregate query from scanning the whole cluster beyond its authorization.

Per-cluster Prometheus Service Discovery Copy Section

MCP locates the Prometheus instance inside the cluster. With no rows added, the built-in heuristic auto-discovery is used; to override, add one discovery rule per cluster:

Override rules take effect immediately.

Related Pages Copy Chapter

• Client Setup Quick Start —— steps to connect an agent client
• Tools List —— all tools for K8s clusters, workloads, resources, metrics, etc.
• Change Approval Flow —— plan approval, partial approval, and approval tokens
• Dangerous Operations and Confirmation Tokens —— danger levels and one-time confirmation tokens

En Mcp Tools (`docs/en/mcp/tools.md`) Copy Section

Kuboard MCP Tools

The Kuboard MCP Server provides 34 tools in total, grouped into three categories by purpose: read, write, and change approval. This page lists every tool's name, key parameters, and purpose for reference when configuring your agent.

Audience: operations / platform engineers who want to give an AI agent (Agent) access to Kuboard cluster operations.

::: tip Reading conventions

• Tool names keep their original English names (e.g. list_clusters); agents call these tools directly by name
• Parameters are marked required / (optional); most write tools carry a dryRun (optional) parameter — set to true it only validates and does not really execute, useful for previewing the change result
• This page is the detailed expansion of "What MCP provides" in the MCP capabilities overview
  :::

Three Tool Categories: Read / Write / Approval Copy Chapter

All tools are grouped by their real side effects into three categories: read tools only query and never modify; write tools issue persistent write operations to the cluster; change approval (Plan) tools are the entry through which write tools are executed after they get approval.

::: warning Write tools require approval
With "Force agent change approval" enabled, the 10 write tools are invisible and not directly callable by the agent. The agent must go through the change-plan flow: create_plan → append_step_to_plan → finalize_plan → you approve in the Kuboard UI → apply_plan(planId, approvalToken). See change approval flow and dangerous operations and confirmation tokens.
:::

::: warning Danger level markers
Write tools carry a danger level, treated differently by marker at approval time:

• MEDIUM: apply_k8s / patch_k8s / delete_k8s
• HIGH: delete_k8s_collection (especially deleting PVCs), drain_node, evict_pod — prominently marked at approval time; double-check the impact scope of these
  :::

With "Force agent change approval" disabled, the 5 change approval (Plan) tools are hidden and the write tools become directly callable by the agent again.

All Tools at a Glance (34) Copy Chapter

The table below lists all tools by the read / write / approval categories. Only key parameters are shown; refer to each tool's actual schema when configuring your agent.