安装 Secure Profile 依赖项
secure profile 需要目标集群上安装 cert-manager、SPIRE、Keycloak 和 Istio (ambient 模式)。cert-manager 随平台一起提供;本指南安装另外三个组件。请在启用 secure profile 之前先完成它们的安装。
通用安装模式
每个组件都作为一个平台包交付——一个 OLM operator 或一个集群插件。所有组件的操作步骤相同:
-
从 customer portal 下载组件包 —
https://cloud.alauda.cn(中国)或https://cloud.alauda.io(国际)。 -
使用
violet将其上传到平台:violet会将包中的镜像迁移到平台镜像仓库,因此组件可以安装在 air-gapped 集群上。 -
在 Web 控制台中安装 — Administrator → Marketplace / OperatorHub,选择目标集群;或者使用
kubectl安装(OLM operator 使用Subscription,集群插件使用ModuleInfo)。
下面的各节介绍每个组件的单独配置。
SPIRE
SPIRE 会签发 AuthBridge 用于 mTLS 的 workload SVID。它作为 集群插件交付。
使用 violet 上传 SPIRE 包,并将其安装到 业务集群 上(Marketplace → install on cluster,或者从 global 集群创建 ModuleInfo)。安装时进行如下配置:
验证:
SPIRE 会通过 csi.spiffe.io CSI driver 自动注册每个 pod(通过默认的 ClusterSPIFFEID)为 spiffe://<trustDomain>/ns/<namespace>/sa/<serviceaccount>。
Keycloak
Keycloak 会签发 AuthBridge 验证的 OAuth2/JWT 令牌。它作为一个 OLM operator 以及你创建的 Keycloak 实例交付。
1. 安装 operator
使用 violet 上传 Keycloak operator 包,然后从 OperatorHub 安装。平台 operator 需要 Manual 升级批准 — 通过批准生成的 InstallPlan 完成安装。
2. 部署 Keycloak 实例
创建一个 Keycloak 自定义资源。将其命名为 keycloak,这样 operator 就会生成 Kagenti operator 读取的 keycloak-initial-admin secret:
image— 由violet迁移后的 Keycloak server 镜像(集群不能直接拉取quay.io)。db.vendor: dev-file会在 pod 内运行 H2 database——适合开发/测试(数据不会在重启后持久化)。生产环境中,请将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 flow 所必需的。
不要预先创建 keycloak-initial-admin secret。Keycloak operator 会创建并拥有它;如果存在同名的预先创建 secret,会阻止 operator 的 reconcile(Keycloak 实例将永远不会启动)。
该 operator 会在集群内通过 http://keycloak-service.<namespace>.svc:8080 暴露该实例 — 请将此 URL 作为 Kagenti operand 上的 keycloak.publicUrl。
你为 keycloak.publicUrl 设置的值将成为 AuthBridge 验证的 JWT issuer(iss)claim。请使用你获取令牌时将使用的相同 hostname 形式——通常是简短的集群内 service URL http://keycloak-service.keycloak.svc:8080(上游示例约定)。如果你选择 FQDN 形式(…svc.cluster.local…),那么获取令牌的客户端也必须使用该 FQDN;混用这两种形式会导致原本有效的令牌出现 iss 不匹配的 401。
何时创建 KeycloakRealmImport
KeycloakRealmImport 是 Keycloak operator 声明式导入 realm 的方式(spec.keycloakCRName + spec.realm)。secure profile 需要一个包含平台 client 和 audience scope 的 kagenti realm。
- 通常不需要手动创建。 当
authbridgeConfig.enabled为true且已经存在Keycloak实例时,Kagenti operator 会 自动导入kagentirealm——它会将名为kagenti-realm-import的KeycloakRealmImport(包含 platform client 和kagenti-platform-audiencescope)应用到你的 Keycloak 中。 - 仅在以下情况手动创建: 你没有使用自动导入(例如
authbridgeConfig关闭,但仍希望使用该 realm),或者你需要自定义该 realm。请应用一个引用你的实例(spec.keycloakCRName: keycloak)的KeycloakRealmImport,并在spec.realm下提供你的 realm 表示。
Istio (ambient 模式)
secure profile 使用 Istio ambient mesh(ztunnel)为命名空间级别的 mTLS 提供支持,作为 Service Mesh v2(servicemesh-operator2 / Sail operator)交付。
从 Marketplace 安装 Alauda Service Mesh v2 operator(download → violet → install),版本需为 2.1.1 或更高(支持 ambient)。ACP 上的 ambient 还需要 Multus CNI plugin 和 kube-ovn ≥ v4.1.5。
然后通过创建 profile: ambient 的 IstioCNI、Istio 和 ZTunnel 资源来启用 ambient。首先创建 istio-cni、istio-system 和 ztunnel namespaces,并分别标记 istio-discovery=enabled。完整且权威的操作步骤(前置条件、namespace 标签、验证)请参见 Alauda Service Mesh v2 文档 —— Installing Istio ambient mode (alauda/servicemesh2-docs)。简而言之:
如果该集群已经运行共享 Istio(例如用于平台 dashboard),请以增量方式启用 ambient——在现有的 Istio 和 IstioCNI 资源上设置 profile: ambient(保留其现有的 spec.values,例如自定义的 meshConfig),并添加一个 ZTunnel。现有的 sidecar 模式 workload 将继续正常工作,且 istiod 会原地更新。
Kagenti operator 会自动为每个已加入的 agent namespace 标记 istio.io/dataplane-mode: ambient 和 istio-discovery: enabled — 你无需手动为 agent namespace 添加标签。
下一步
在 cert-manager、SPIRE、Keycloak 和 Istio ambient 配置完成后,请继续 启用 Secure Profile。