安装 Secure Profile 依赖项

secure profile 需要目标集群上安装 cert-manager、SPIRE、Keycloak 和 Istio (ambient 模式)。cert-manager 随平台一起提供;本指南安装另外三个组件。请在启用 secure profile 之前先完成它们的安装。

通用安装模式

每个组件都作为一个平台包交付——一个 OLM operator 或一个集群插件。所有组件的操作步骤相同:

  1. 从 customer portal 下载组件包 — https://cloud.alauda.cn(中国)或 https://cloud.alauda.io(国际)。

  2. 使用 violet 将其上传到平台:

    violet push \
      --platform-address=<platform-access-address> \
      --platform-username=<platform-admin> \
      --platform-password=<platform-admin-password> \
      <package>.tgz

    violet 会将包中的镜像迁移到平台镜像仓库,因此组件可以安装在 air-gapped 集群上。

  3. 在 Web 控制台中安装 — Administrator → Marketplace / OperatorHub,选择目标集群;或者使用 kubectl 安装(OLM operator 使用 Subscription,集群插件使用 ModuleInfo)。

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

SPIRE

SPIRE 会签发 AuthBridge 用于 mTLS 的 workload SVID。它作为 集群插件交付。

使用 violet 上传 SPIRE 包,并将其安装到 业务集群 上(Marketplace → install on cluster,或者从 global 集群创建 ModuleInfo)。安装时进行如下配置:

设置说明
trustDomainSPIFFE trust domain,例如 kagenti.local。请记录此值 — 它必须与 Kagenti operand 上的 defaults.spiffe.trustDomain 一致。
clusterName此集群的名称。
persistence.storageClassSPIRE server datastore 使用的真实 StorageClass(替换默认占位符)。
caSubjectSPIRE trust bundle 的 CA subject(country / organization / 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 令牌。它作为一个 OLM operator 以及你创建的 Keycloak 实例交付。

1. 安装 operator

使用 violet 上传 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
  1. image — 由 violet 迁移后的 Keycloak server 镜像(集群不能直接拉取 quay.io)。
  2. db.vendor: dev-file 会在 pod 内运行 H2 database——适合开发/测试(数据不会在重启后持久化)。生产环境中,请将 vendor 设为 postgres,并将 db.host / db.usernameSecret / db.passwordSecret 指向外部 PostgreSQL。
  3. hostname.strict: false 允许 Keycloak 从请求中解析其 hostname,适合集群内访问。除非你同时设置了 hostname.hostname,否则不要将 hostname.backchannelDynamic: true 设为 true,否则 server 无法启动。
  4. token-exchange(配合 admin-fine-grained-authz)是 Kagenti audience / token-exchange flow 所必需的。
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。请使用你获取令牌时将使用的相同 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 会 自动导入 kagenti realm——它会将名为 kagenti-realm-import 的 KeycloakRealmImport(包含 platform client 和 kagenti-platform-audience scope)应用到你的 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)。简而言之:

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 模式 workload 将继续正常工作,且 istiod 会原地更新。

Kagenti operator 会自动为每个已加入的 agent namespace 标记 istio.io/dataplane-mode: ambient 和 istio-discovery: enabled — 你无需手动为 agent namespace 添加标签。

下一步

在 cert-manager、SPIRE、Keycloak 和 Istio ambient 配置完成后,请继续 启用 Secure Profile。