ghcr.io/k8sgpt-ai/k8sgpt-operator:dev-202609261617

[!IMPORTANT] 自动修复功能现已正式上线，新增了完备的安全管控机制

自动修复功能已上线 — 附带实时安全校验门限

K8sGPT Operator 现已支持自动修复选定的 Kubernetes 工作负载镜像故障。完整的端到端实测流程已验证全链路可用性：由 AI 提供商分析 ImagePullBackOff 故障，Operator 生成单镜像修复方案，Kubernetes 滚动更新已校正的 Deployment，最终 Mutation 状态变为 Successful。

该功能目前处于 alpha 阶段，需用户主动选择开启：LLM 始终不会获得集群写入权限，Operator 会重新拉取对象、自行计算语义化 JSON 补丁，仅允许通过校验的单镜像更新路径，通过 Kubernetes API 服务端执行预演校验，同时会拒绝过时、范围过宽或存在安全风险的修改提议。识别到的关联 Pod 故障会通过其所属的上层工作负载进行修复，所有变更将更新工作负载的期望状态，而非直接修改临时 Pod 实例。

你可以直接开始使用自动修复功能，并选择适配自身环境的 AI 提供商配置。

该 Operator 设计用于在 Kubernetes 集群内部署 K8sGPT，你可通过自定义资源定义托管 K8sGPT 工作负载的行为与作用范围，分析规则与输出格式也支持自定义配置，可灵活集成到现有工作流中。

安装

helm repo add k8sgpt https://charts.k8sgpt.ai/
helm repo update
helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespace

自动修复快速入门

在 K8sGPT 自定义资源中同时启用自动修复功能，并配置你选择的 AI 后端与关联 Secret。AI 提供商配置与修复策略相互独立，Operator 会对所有后端应用完全一致的安全防护规则。

kubectl apply -n k8sgpt-operator-system \
-f config/samples/autoremediation/valid_k8sgpt_remediation_sample.yaml

针对不同 AI 提供商的专用配置清单，请参考示例配置文件。在启用自动修复前，请先阅读自动修复相关文档，了解其策略模型、支持的工作负载类型、审计字段与运行限制。

运行示例

• 按照上方安装章节的指引完成 Operator 部署
• 创建 Secret：

kubectl create secret generic k8sgpt-sample-secret --from-literal=openai-api-key=$OPENAI_TOKEN -n k8sgpt-operator-system

• 应用 K8sGPT 配置对象：

kubectl apply -f - # 如需隐藏 Webhook URL，可使用独立存储的 Secret
# secret:
#   name: slack-webhook
#   key: url
# extraOptions:
#   backstage:
#     enabled: true
EOF

当 spec.ai.secret 引用的 AI Secret 内的数据发生变更时，Operator 会自动滚动更新 K8sGPT Deployment，自动加载更新后的凭证，无需手动重启。

[!NOTE] 滚动更新的触发条件为引用 Secret 内任意数据键的变更，不限于 spec.ai.secret.key 指定的键；仅修改 Secret 的标签或注解不会触发滚动更新。

• 自定义资源应用完成后，K8sGPT Deployment 会自动部署，数分钟后你即可查看分析生成的 Result 对象（集群存在问题时才会生成）：

❯ kubectl get results -n k8sgpt-operator-system -o json | jq .
{
  "apiVersion": "v1",
  "items": [
    {
      "apiVersion": "core.k8sgpt.ai/v1alpha1",
      "kind": "Result",
      "spec": {
        "details": "该错误表示 Kubernetes 中的服务未关联任何标注有 \"control-plane=controller-manager\" 的端点。\n\n要解决此问题，你需要为与该服务匹配的端点添加 \"control-plane=controller-manager\" 标签。端点标签配置正确后，Kubernetes 即可将其与服务关联，该故障将被修复。"

多集群监控

k8sgpt.ai Operator 支持通过提供 kubeconfig 值实现多集群监控。 如果你面向多个业务方运维 Kubernetes 集群舰队，想要落地平台工程实践，该功能会非常实用。该功能专门针对基于 Cluster API 的基础设施设计，k8sgpt.ai Operator 需要安装在 Cluster API 管理集群中，由管理集群根据基础设施提供商的定义完成下游集群的创建。

基于 Cluster API 部署完成集群后，符合命名规范 ${CLUSTERNAME}-kubeconfig 的 kubeconfig Secret 会自动创建在同名命名空间中，该 Secret 的内置数据键固定为 value，你可直接使用该 Secret 指示 k8sgpt.ai Operator 监控远程集群，无需在下游集群中部署任何额外资源。

$: kubectl get clusters
NAME             PHASE         AGE  VERSION
capi-quickstart  Provisioned   8s   v1.28.0

$: kubectl get secrets
NAME                         TYPE    DATA  AGE
capi-quickstart-kubeconfig   Opaque  1     8s

[!WARNING] 安全提示：如果你的环境要求遵循最小权限原则，则必须自行提供独立的 kubeconfig，因为 Cluster API 自动生成的 kubeconfig 绑定了拥有 cluster-admin 集群权限的管理员用户。

获取合法 kubeconfig 后，即可按如下方式创建 K8sGPT 实例：

apiVersion: core.k8sgpt.ai/v1alpha1
kind: K8sGPT
metadata:
  name: capi-quickstart
  namespace: k8sgpt-operator-system
spec:
  ai:
    anonymized: true
    backend: openai
    language: english
    model: gpt-4o-mini
    secret:
      key: api_key
      name: my_openai_secret
  kubeconfig:
    key: value
    name: capi-quickstart-kubeconfig

配置应用后，k8sgpt.ai Operator 会使用 /spec/kubeconfig 字段中定义的下游集群 kubeconfig 创建对应的 k8sgpt.ai Deployment。生成的 Result 对象会保存在 k8sgpt.ai 实例部署所在的命名空间中，并自动添加以下标签：

• k8sgpts.k8sgpt.ai/name：k8sgpt.ai 实例的名称
• k8sgpts.k8sgpt.ai/namespace：k8sgpt.ai 实例的命名空间
• k8sgpts.k8sgpt.ai/backend：使用的 AI 后端（如已指定）

通过这些标签可根据集群维度过滤分析结果，既无需在下游集群中部署 k8sgpt.ai CRDs、占用下游集群计算资源，也能保证 AI 后端驱动凭证的安全性。

[!NOTE] 如果未配置 /spec/kubeconfig 字段，k8sgpt.ai Operator 将通过挂载自身的 ServiceAccount，监控当前部署所在的集群。

如果未配置 /spec/kubeconfig 字段，k8sgpt.ai Operator 将追踪自身所部署的当前集群：该功能通过挂载所提供的 ServiceAccount 实现。

分布式缓存

Interplex 是专为 K8sGPT 优化、基于 RPC 运行的缓存系统。你可以在常规 helm 安装流程中，无需任何凭证即可将该缓存安装在本地集群中。

• 启用 Interplex 安装 K8sGPT Operator

helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespace --set interplex.enabled=true

• 为你的 AI 后端创建 Secret（以下示例使用 OPENAI）：

kubectl create secret generic k8sgpt-sample-secret --from-literal=openai-api-key=$OPENAI_TOKEN -n k8sgpt-operator-system

• 将 K8sGPT 自定义资源指向 Interplex 缓存：（请将 helm 发布名称与缓存前缀匹配，例如 myrelease-interplex-service:8084）

kubectl apply -f - --from-literal=azure_tenant_id= --from-literal=azure_client_secret= -n k8sgpt-operator-system

• 应用 K8sGPT 配置对象：

kubectl apply -f - --from-literal=aws_secret_access_key= -n k8sgpt-operator-system

• 应用 K8sGPT 配置对象：

kubectl apply -f - .svc.cluster.local:8080/v1.

baseUrl 取值格式为 http://local-ai. .svc.cluster.local:8080/v1

• 后续操作与上述示例中的第 4 步完全一致。

K8sGPT 配置选项

时间间隔的格式需兼容 Go 语言 time.ParseDuration 函数的解析规则（例如 "30s"、"1m"、"2h"）。如未指定该字段，默认时间间隔为 30 秒。

配置示例：

kubectl apply -f -
...

以下为 Sink 的可选参数（其中 type、webhook 为必填参数）：

filters 字段可指定 K8sGPT 扫描集群时需要使用的分析器。默认情况下，K8sGPT 会启用一组核心分析器。你可以通过 filters 启用额外的可选分析器，或是将扫描范围限制在特定资源类型。

默认启用的核心分析器如下：

• Pod
• Deployment
• ReplicaSet
• PersistentVolumeClaim
• Service
• Ingress
• StatefulSet
• Job
• CronJob
• Node
• ValidatingWebhookConfiguration
• MutatingWebhookConfiguration
• ConfigMap

默认禁用的可选分析器如下：

• HorizontalPodAutoscaler
• PodDisruptionBudget
• NetworkPolicy
• Log
• GatewayClass
• Gateway
• HTTPRoute

[!IMPORTANT] 当你指定 filters 字段时，该字段会直接覆盖默认的分析器列表。如果希望在保留所有默认分析器的同时启用可选分析器，你必须显式列出所有需要使用的分析器。

filters 使用示例：同时启用 Log、HPA 分析器与部分核心分析器：

kubectl apply -f -

---

[!IMPORTANT] 自动修复功能现已上线 — 内置真实安全闸门

K8sGPT Operator 现已支持自动修复选定 Kubernetes 工作负载的镜像故障。完整的端到端实测流程已验证全链路有效性：AI 提供商分析 ImagePullBackOff 故障，Operator 生成针对单个镜像的修复方案，Kubernetes 滚动更新修正后的 Deployment，最终 Mutation 状态变为 Successful。

该功能目前处于 Alpha 阶段，需手动选择启用。大语言模型永远不会获得写入权限：Operator 会重新获取目标对象，自行计算语义化 JSON 补丁，仅允许一个经过核准的镜像路径，通过 Kubernetes API 服务器执行干运行校验，并且会拒绝过时、范围过宽或不安全的修复提案。所有归属 Pod 的异常都会通过其所属的工作负载进行修复，所有变更都会更新资源的期望状态，而非直接修改临时 Pod 实例。

你可以查阅 Auto Remediation 快速上手，选择适配你环境的提供商配置方案。

该 Operator 专为在 Kubernetes 集群中部署 https://github.com/k8sgpt-ai/k8sgpt/ 而设计。你可以通过创建自定义资源来定义托管 K8sGPT 工作负载的行为和扫描范围，同时支持自定义分析规则与输出格式，便于集成到现有工作流中。

安装

helm repo add k8sgpt https://charts.k8sgpt.ai/
helm repo update
helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespace

自动修复快速入门

你可以在 K8sGPT 资源中与所选 AI 后端及关联 Secret 一同开启自动修复功能。提供商配置与修复相互独立，Operator 会对所有后端应用统一的安全防护规则。

kubectl apply -n k8sgpt-operator-system \
-f config/samples/autoremediation/valid_k8sgpt_remediation_sample.yaml

如需获取不同提供商对应的清单文件，请参考示例配置。在启用自动修复之前，请务必先阅读 Auto Remediation，了解其策略模型、支持的工作负载类型、审计字段以及运行限制。

运行示例

1. 按照安装小节的步骤完成 Operator 安装。

2. 创建 Secret：

kubectl create secret generic k8sgpt-sample-secret --from-literal=openai-api-key=$OPENAI_TOKEN -n k8sgpt-operator-system

3. 应用 K8sGPT 配置对象：

kubectl apply -f - # 如需隐藏 webhook 地址，可使用 Sink Secret
# secret:
# name: slack-webhook
# key: url
#extraOptions:
# backstage:
# enabled: true
EOF

[!NOTE] 当 spec.ai.secret 引用的 AI Secret 中的数据发生变更时，Operator 会自动滚动更新 K8sGPT Deployment 以加载更新后的凭证，无需手动重启。

滚动更新的触发条件是引用 Secret 下任意数据键的变更，而非仅变更 spec.ai.secret.key 指定的键。Secret 的标签或注解变更不会触发滚动更新。

4. 应用自定义资源后，K8sGPT 部署将自动安装完成。数分钟后，你就可以查看生成的分析结果对象（前提是集群中存在可检测的异常）：

❯ kubectl get results -n k8sgpt-operator-system -o json | jq .
{
"apiVersion": "v1",
"items": [
{
"apiVersion": "core.k8sgpt.ai/v1alpha1",
"kind": "Result",
"spec": {
"details": "该错误表示 Kubernetes 中的 Service 没有关联的 Endpoints，而这些 Endpoints 本应带有标签 \"control-plane=controller-manager\"。\n\n要解决该问题，你需要为与 Service 匹配的 Endpoint 添加 \"control-plane=controller-manager\" 标签。正确标记后，Kubernetes 即可将其与 Service 关联，该错误将被解决。"

多集群监控

k8sgpt.ai Operator 支持通过提供 kubeconfig 值实现多集群监控。

如果您希望践行平台工程实践，例如为多个利益相关方运行一组 Kubernetes 集群，该特性将十分实用。 专门为基于 Cluster API 的基础设施设计的 k8sgpt.ai Operator 将安装在同一个 Cluster API 管理集群中：该集群负责根据种子集群的基础设施提供者创建所需的集群。

基于 Cluster API 的集群配置完成后，遵循命名约定 ${CLUSTERNAME}-kubeconfig 的 kubeconfig 将在同一命名空间中可用： 该常规 Secret 的数据键为 value，您可以使用它指示 k8sgpt.ai Operator 监控远程集群，而无需向种子集群部署任何资源。

$: kubectl get clusters
NAME PHASE AGE VERSION
capi-quickstart Provisioned 8s v1.28.0

$: kubectl get secrets
NAME TYPE DATA AGE
capi-quickstart-kubeconfig Opaque 1 8s

[!WARNING] 若您的环境需要遵循最小权限原则，必须提供自定义的 kubeconfig，因为 Cluster API 生成的 kubeconfig 绑定了拥有 cluster-admin 权限的 admin 用户。

获取有效 kubeconfig 后，您可以按如下方式创建 k8sgpt 实例。

apiVersion: core.k8sgpt.ai/v1alpha1
kind: K8sGPT
metadata:
  name: capi-quickstart
  namespace: k8sgpt-operator-system
spec:
  ai:
    anonymized: true
    backend: openai
    language: english
    model: gpt-4o-mini
    secret:
      key: api_key
      name: my_openai_secret
  kubeconfig:
    key: value
    name: capi-quickstart-kubeconfig

资源应用完成后，k8sgpt.ai Operator 将通过 /spec/kubeconfig 字段中定义的种子集群 kubeconfig 创建 k8sgpt.ai Deployment。 生成的 Result 对象将存放在部署 k8sgpt.ai 实例的同一命名空间中，并带有以下标签作为标识：

• k8sgpts.k8sgpt.ai/name：k8sgpt.ai 实例的名称
• k8sgpts.k8sgpt.ai/namespace：k8sgpt.ai 实例的命名空间
• k8sgpts.k8sgpt.ai/backend：AI 后端（若已指定）

借助这些标签，您可以根据指定的被监控集群过滤结果，既不会通过 k8sgpt.ai CRD 污染底层集群，也不会占用种子集群的计算工作负载，同时可保障 AI 后端驱动凭证的保密性。

[!NOTE] 如果未配置 /spec/kubeconfig 字段，k8sgpt.ai Operator 将监控自身部署所在的集群：该功能通过挂载系统提供的 ServiceAccount 实现。

分布式缓存

Interplex 缓存

https://github.com/interplex-ai/interplex.git 是专为 K8sGPT 优化的 RPC 缓存系统，可在无需任何凭证的情况下，通过常规 helm 安装流程部署到本地集群。

1. 安装启用 Interplex 的 K8sGPT Operator

helm install release k8sgpt/k8sgpt-operator -n k8sgpt-operator-system --create-namespace --set interplex.enabled=true

2. 为您的 AI 后端创建 Secret（以下示例使用 OPENAI）：

kubectl create secret generic k8sgpt-sample-secret --from-literal=openai-api-key=$OPENAI_TOKEN -n k8sgpt-operator-system

3. 将 K8sGPT 自定义资源指向 Interplex 缓存：（请将 helm 发布名称与缓存前缀保持一致，例如 myrelease-interplex-service:8084）

kubectl apply -f -

远程缓存

Azure Blob 存储

1. 参照安装指南完成 Operator 安装。
2. 创建 Secret：

kubectl create secret generic k8sgpt-sample-cache-secret --from-literal=azure_client_id= --from-literal=azure_tenant_id= --from-literal=azure_client_secret= -n k8sgpt-operator-system

3. 应用 K8sGPT 配置对象：

kubectl apply -f -

S3

1. 参照安装指南完成 Operator 安装。
2. 创建 Secret：

kubectl create secret generic k8sgpt-sample-cache-secret --from-literal=aws_access_key_id= --from-literal=aws_secret_access_key= -n k8sgpt-operator-system

3. 应用 K8sGPT 配置对象：

kubectl apply -f -

其他 AI 后端示例

AzureOpenAI

1. 参照安装指南完成 Operator 安装。
2. 创建 Secret：

kubectl create secret generic k8sgpt-sample-secret --from-literal=azure-api-key=$AZURE_TOKEN -n k8sgpt-operator-system

3. 应用 K8sGPT 配置对象：

kubectl apply -f -

Amazon Bedrock

1. 参照安装指南完成 Operator 安装。
2. 在 AWS 环境中运行时，您可以通过多种方式为托管 K8sGPT 工作负载授予访问 Amazon Bedrock 的权限。

• 使用 Kubernetes Service Account 授予 Bedrock 访问权限。这是https://aws.github.io/aws-eks-best-practices/security/docs/iam/#identities-and-credentials-for-eks-pods，具体实现方式包括：
  • 在 Amazon EKS 上使用 https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html
  • 在 Amazon EKS 上使用 https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html
  • 在自行搭建的 Kubernetes 上，结合https://github.com/aws/amazon-eks-pod-identity-webhook 使用服务账户 IAM 角色 (IRSA)
• 在 Kubernetes Secret 中配置 AWS 凭证以授予 Bedrock 访问权限。请注意该方式不符合 https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles，请谨慎使用。

若要通过 Kubernetes 服务账户授予 Bedrock 访问权限，请创建一个拥有 Bedrock 权限的 IAM 角色，下方提供了策略示例：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    }
  ]
}

若要通过 Kubernetes Secret 中的 AWS 凭证授予访问权限，请创建如下 Secret：

kubectl create secret generic bedrock-sample-secret --from-literal=AWS_ACCESS_KEY_ID="$(echo $AWS_ACCESS_KEY_ID)" --from-literal=AWS_SECRET_ACCESS_KEY="$(echo $AWS_SECRET_ACCESS_KEY)" -n k8sgpt-operator-system

3. 应用 K8sGPT 配置对象：

kubectl apply -f -

LocalAI

1. 参照安装指南完成 Operator 安装。
2. 参照 https://github.com/go-skynet/helm-charts#readme部署 LocalAI。（使用 LocalAI 时无需配置 OpenAI Secret）。
3. 将 K8sGPT 自定义资源指向 LocalAI 服务地址 localhost:8080/v1。
4. 执行上述示例中步骤 4 对应的操作。

K8sGPT 配置选项

分析间隔

您可以通过在 K8sGPT 自定义资源中设置 analysis.interval 字段，配置 K8sGPT 调谐器两次调谐操作之间的间隔时长，以此控制 Operator 对集群执行分析的频率。

该间隔需使用可被 Go 语言 time.ParseDuration 函数解析的格式进行指定（例如 "30s"、"1m"、"2h"）。若未指定，默认间隔为 30 秒。

配置示例：

kubectl apply -f -

---

ImagePullPolicy

K8sGPT 容器的 imagePullPolicy 与镜像标签会决定 kubelet 尝试拉取（下载）指定镜像的时机。

更多细节请参考 Kubernetes 官方文档：https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy。

默认值：Always

---

ImagePullSecrets

您可以通过修改 repository、version、imagePullSecrets 字段使用自定义的 k8sgpt 镜像，其中 version 字段实际作为镜像标签生效。

kubectl apply -f -

---

资源配置

您可以通过 resources 字段自定义 k8sgpt 容器的资源使用规则。

kubectl apply -f -

---

服务账号 IAM 角色（IRSA）

对于使用 IRSA 的用户，可以在 K8sGPT 自定义资源中配置当前集群内服务账号对应的 ARN，相关示例如下：

apiVersion: core.k8sgpt.ai/v1alpha1
kind: K8sGPT
metadata:
  name: k8sgpt-sample
  namespace: k8sgpt-operator-system
spec:
  extraOptions:
    serviceAccountIRSA:
...

---

Sink（集成）

以下为 Sink 可用的可选参数（type、webhook 为必填参数）：

---

过滤器（分析器）

filters 字段可指定 K8sGPT 扫描集群时需要使用的分析器。默认情况下，K8sGPT 会启用一组核心分析器，您可以通过过滤器启用额外的可选分析器，或将分析范围限制在特定资源类型上。

核心分析器（默认启用）：

• Pod
• Deployment
• ReplicaSet
• PersistentVolumeClaim
• Service
• Ingress
• StatefulSet
• Job
• CronJob
• Node
• ValidatingWebhookConfiguration
• MutatingWebhookConfiguration
• ConfigMap

可选分析器（默认禁用）：

• HorizontalPodAutoscaler
• PodDisruptionBudget
• NetworkPolicy
• Log
• GatewayClass
• Gateway
• HTTPRoute

[!IMPORTANT] 当您指定 filters 字段时，它会完全替换默认的分析器列表。如果希望在保留默认分析器的同时启用可选分析器，必须显式列出所有需要使用的分析器。

示例 - 在部分核心分析器之外，同时启用 Log 和 HPA 分析器：

kubectl apply -f -

---

Helm Values

相关详情请参见 此处

许可证