安装 Secure Profile 依赖项

secure profile 需要在目标集群上安装 cert-manager、SPIRE、Keycloak 和 Istio（ambient 模式）。cert-manager 随平台一起提供；本指南将安装其余三个组件。请在启用 secure profile 之前完成安装。

通用安装模式

每个组件都以平台包的形式交付——即 OLM operator 或 Cluster Plugin。有关通用的软件包下载、violet 配置和上传操作步骤，请参见上架软件包。所有组件的模式都相同：

从 Customer Portal 下载组件包。
按照上架软件包将其上传到平台。violet 会将软件包中的镜像重新定位到平台镜像仓库，因此这些组件可以安装到 air-gapped 集群。
从 Web 控制台进行安装——进入 Administrator → Marketplace / OperatorHub，选择目标集群——或者使用 kubectl（OLM operator 使用 Subscription，Cluster Plugin 使用 ModuleInfo）。

以下各节介绍每个组件的单独配置。

SPIRE

SPIRE 会签发 AuthBridge 用于 mTLS 的工作负载 SVID。它以 Cluster Plugin 的形式交付。

按照上架软件包上传 SPIRE 软件包，并将其安装到 workload cluster（在 Marketplace 中安装到集群，或者在 global cluster 中创建 ModuleInfo）。安装时请进行如下配置：

设置	说明
`trustDomain`	SPIFFE trust domain，例如 `kagenti.local`。请记录此值——它必须与 `Kagenti` operand 上的 `defaults.spiffe.trustDomain` 保持一致。
`clusterName`	此集群的名称。
`persistence.storageClass`	SPIRE server datastore 使用的真实 `StorageClass`（请替换默认占位符）。
`caSubject`	SPIRE trust bundle 的 CA subject（国家 / 组织 / common name）。

验证：

# server, agent, and CSI driver running
kubectl get pods -n spire-server
kubectl get pods -n spire-system

# the trust bundle ConfigMap (key bundle.spiffe) and the ClusterSPIFFEID CRD
kubectl get configmap spire-bundle -n spire-system
kubectl get crd clusterspiffeids.spire.spiffe.io

SPIRE 会通过 csi.spiffe.io CSI driver 自动为每个 pod 注册（通过默认 ClusterSPIFFEID），格式为 spiffe://<trustDomain>/ns/<namespace>/sa/<serviceaccount>。

Keycloak

Keycloak 会签发 AuthBridge 验证的 OAuth2/JWT token。它以 OLM operator 加上您创建的 Keycloak 实例形式交付。

1. 安装 operator

按照上架软件包上传 Keycloak operator 软件包，然后从 OperatorHub 安装。平台 operator 需要 Manual 升级批准——请批准生成的 InstallPlan 以完成安装。

2. 部署 Keycloak 实例

创建一个 Keycloak 自定义资源。请将其命名为 keycloak，这样 operator 才会生成 Kagenti operator 会读取的 keycloak-initial-admin secret：

apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
metadata:
  name: keycloak
  namespace: keycloak
spec:
  instances: 1
  image: <relocated-keycloak-image>
  startOptimized: false
  db:
    vendor: dev-file
  http:
    httpEnabled: true
  hostname:
    strict: false
  features:
    enabled:
      - token-exchange
      - admin-fine-grained-authz

image —— 由 violet 重新定位后的 Keycloak server 镜像（集群无法直接拉取 quay.io）。
db.vendor: dev-file 会在 pod 内运行 H2 数据库——适合 dev/test（重启后数据不会持久化）。在 production 中，请设置 vendor: postgres，并将 db.host / db.usernameSecret / db.passwordSecret 指向外部 PostgreSQL。
hostname.strict: false 允许 Keycloak 从请求中解析其 hostname，这适合集群内访问。除非您同时设置了 hostname.hostname，否则不要将 hostname.backchannelDynamic: true 设为 true，否则 server 将无法启动。
token-exchange（配合 admin-fine-grained-authz）是 Kagenti audience / token-exchange 流程所必需的。

WARNING

不要预先创建 keycloak-initial-admin secret。Keycloak operator 会创建并拥有它；如果该名称的 secret 已存在，会阻止 operator 的 reconcile（Keycloak 实例将永远不会启动）。

operator 会在集群内将该实例暴露为 http://keycloak-service.<namespace>.svc:8080 —— 请将此 URL 作为 Kagenti operand 上的 keycloak.publicUrl。

WARNING

您设置为 keycloak.publicUrl 的值会成为 AuthBridge 用于验证的 JWT issuer（iss）claim。请使用与获取 token 时相同的 hostname 形式——通常是较短的集群内 service URL http://keycloak-service.keycloak.svc:8080（上游示例约定）。如果您选择 FQDN 形式（…svc.cluster.local…），那么获取 token 的客户端也必须使用该 FQDN；混用这两种形式会导致原本有效的 token 因 iss 不匹配而返回 401。

何时创建 `KeycloakRealmImport`

KeycloakRealmImport 是 Keycloak operator 声明式导入 realm 的方式（spec.keycloakCRName + spec.realm）。secure profile 需要一个带有平台 client 和 audience scope 的 kagenti realm。

通常无需手动创建。 当 authbridgeConfig.enabled 为 true 且已经存在 Keycloak 实例时，Kagenti operator 会自动导入 kagenti realm——它会向您的 Keycloak 应用名为 kagenti-realm-import 的 KeycloakRealmImport（包含平台 client 和 kagenti-platform-audience scope）。
仅当以下情况时才手动创建： 您不使用自动导入（例如 authbridgeConfig 关闭，但仍希望使用该 realm），或者需要自定义 realm。请应用一个引用您的实例（spec.keycloakCRName: keycloak）且在 spec.realm 下包含 realm 表示的 KeycloakRealmImport。

Istio（ambient 模式）

secure profile 使用 Istio ambient mesh（ztunnel）实现命名空间级 mTLS，作为 Service Mesh v2（servicemesh-operator2 / Sail operator）交付。

从 Marketplace 安装 Alauda Service Mesh v2 operator（下载 → 通过上架软件包上传 → 安装），版本需为 2.1.1 或更高（支持 ambient）。ACP 上的 ambient 还要求 Multus CNI plugin 和 kube-ovn ≥ v4.1.5。

然后通过创建 IstioCNI、Istio 和 ZTunnel 资源并将 profile 设为 ambient 来启用 ambient。请先创建 istio-cni、istio-system 和 ztunnel 命名空间，并分别为其添加 istio-discovery=enabled 标签。完整且权威的操作步骤（先决条件、命名空间标签、验证）请参见 Alauda Service Mesh v2 文档——Installing Istio ambient mode (alauda/servicemesh2-docs)。简而言之：

apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata: { name: default }
spec:
  namespace: istio-cni
  profile: ambient
  values:
    cni:
      cniConfDir: /etc/cni/multus/net.d
      ambient: { reconcileIptablesOnStartup: true }
---
apiVersion: sailoperator.io/v1
kind: Istio
metadata: { name: default }
spec:
  namespace: istio-system
  profile: ambient
  values:
    pilot: { trustedZtunnelNamespace: ztunnel }
---
apiVersion: sailoperator.io/v1
kind: ZTunnel
metadata: { name: default }
spec:
  namespace: ztunnel   # must match pilot.trustedZtunnelNamespace

NOTE

如果集群中已经运行了共享 Istio（例如用于平台 dashboard），请以增量方式启用 ambient——在现有的 Istio 和 IstioCNI 资源上设置 profile: ambient（保留其现有的 spec.values，例如自定义 meshConfig），并添加一个 ZTunnel。现有的 sidecar 模式工作负载会继续运行，istiod 也会在原地更新。

Kagenti operator 会自动将每个已接入的 agent 命名空间标记为 istio.io/dataplane-mode: ambient 和 istio-discovery: enabled——您无需手动为 agent 命名空间添加这些标签。

下一步

在完成 cert-manager、SPIRE、Keycloak 和 Istio ambient 的安装后，请继续执行启用 Secure Profile。

#安装 Secure Profile 依赖项

#目录

#通用安装模式

#SPIRE

#Keycloak

#1. 安装 operator

#2. 部署 Keycloak 实例

#何时创建 KeycloakRealmImport

#Istio（ambient 模式）

#下一步