如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为 Kubernetes 配置工作负载身份联合

将 Kubernetes 用作工作负载身份提供方,即可用 Kubernetes 投射的服务账号令牌换取短期有效的 OpenAI 访问令牌。

配置 Kubernetes

本指南假设您的 Kubernetes 集群已启用服务账号令牌投射。较新的 Kubernetes 版本默认提供此功能。OpenAI 工作负载身份联合要求使用兼容 OIDC 的投射服务账号令牌,不支持存储在 Secret 中的旧版 Kubernetes 服务账号令牌。

为需要调用 OpenAI API 的工作负载指定一个 Kubernetes ServiceAccount。如果您还没有服务账号,请创建一个:

kubectl create serviceaccount openai-wif --namespace default

获取 Kubernetes 集群的 OIDC 签发者:

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

即使您上传了 JWKS,OpenAI 无需通过 OIDC 签发者发现 JWKS,此处返回的签发者仍必须与工作负载身份提供方中配置的签发者一致。

获取集群的 JWKS,并保存返回的密钥集。配置工作负载身份提供方时需要用到它:

kubectl get --raw /openid/v1/jwks

将投射服务账号令牌的受众设为 OpenAI 预期的值,并根据工作负载的需要设置有效期。OpenAI 会验证令牌的签发者、签名、受众和过期时间。在此示例中,令牌文件挂载在 /var/run/secrets/tokens/token,令牌的受众为 https://api.openai.com/v1,有效期为 3600 秒。您也可以使用其他受众值,只要投射令牌的受众与 OpenAI 工作负载身份提供方中配置的受众一致即可:

apiVersion: v1
kind: Pod
metadata:
  name: openai-wif-app
  namespace: default
spec:
  serviceAccountName: openai-wif
  containers:
    - name: app
      image: my-image
      volumeMounts:
        - name: ksa-token
          mountPath: /var/run/secrets/tokens
          readOnly: true
  volumes:
    - name: ksa-token
      projected:
        sources:
          - serviceAccountToken:
              path: token
              audience: "https://api.openai.com/v1"
              expirationSeconds: 3600

验证令牌

配置工作负载身份联合之前,请先在本地解码一个投射服务账号令牌样本,检查其中的声明。从已挂载投射令牌且正在运行的 Pod 中读取令牌,并将其导出为环境变量 TOKEN:

TOKEN=$(kubectl exec -n default openai-wif-app -- cat /var/run/secrets/tokens/token)
export TOKEN

然后运行以下脚本:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

此命令仅解码 JWT 载荷,不会验证令牌签名。请使用本地解码器处理生产环境的令牌,避免将这些令牌粘贴到第三方工具中。

Kubernetes 投射服务账号令牌解码后的内容与以下示例类似:

{
  "iss": "https://kubernetes.example.com",
  "aud": ["https://api.openai.com/v1"],
  "sub": "system:serviceaccount:default:openai-wif",
  "iat": 1716235422,
  "exp": 1716239022,
  "kubernetes.io": {
    "namespace": "default",
    "serviceaccount": {
      "name": "openai-wif",
      "uid": "11111111-2222-3333-4444-555555555555"
    }
  }
}

将解码后的载荷与 OpenAI 中配置的签发者、受众和映射值逐项核对。在交换令牌之前,检查 iss、aud 和 sub 声明就能发现大多数配置问题。

配置工作负载身份联合

在 OpenAI 中为 Kubernetes 签发者创建工作负载身份提供方,然后添加服务账号映射,用于匹配投射令牌中的属性。

请先配置工作负载身份提供方,再创建服务账号映射。

配置工作负载身份提供方

  1. 创建工作负载身份提供方。 将名称设为唯一值,例如 kubernetes-prod。在描述中填写 Production Kubernetes cluster 等说明,方便管理员识别集群。

  2. 设置签发者和受众。 将 OIDC 签发者 URL 设为 kubectl get --raw /.well-known/openid-configuration | jq -r .issuer 返回的签发者。此值必须与投射令牌中的 iss 声明一致。将受众设为投射服务账号令牌卷中配置的同一个不透明受众字符串。在此示例中,该值为 https://api.openai.com/v1。

  3. 上传 Kubernetes JWKS。 启用使用上传的 JWKS 验证令牌,然后将 JWKS JSON 设为 kubectl get --raw /openid/v1/jwks 的输出。OpenAI 使用这组公钥验证 Kubernetes 投射的服务账号令牌。请上传完整的密钥集,包括外层的 keys 字段。

    注意: 对于自托管的 Kubernetes 集群,OpenAI 仅支持本地 JWKS 模式。请上传集群返回的 JWKS。OpenAI 不会通过配置的签发者执行 OIDC 发现,但仍会将配置的签发者与令牌中的 iss 字段进行比对。

    如果您的集群会轮换服务账号签名密钥,请在工作负载身份提供方配置中更新已上传的 JWKS。如果用于签署令牌的密钥未包含在配置的 JWKS 中,OpenAI 将拒绝该令牌。如果 JWKS 包含多个有效公钥,请上传完整的 keys 数组。

  4. 仅在需要派生映射属性时添加属性转换。 您可以在映射断言中直接使用 sub、aud 和 iss 等原始令牌声明。如果您使用转换后的属性进行匹配,控制台会自动为这些属性添加 openai. 前缀。例如,输入属性名 workload_subject 和表达式 assertion.sub 即可创建 openai.workload_subject。对于本身就以 openai. 开头的原始令牌声明,除非配置了相应的转换,否则系统在匹配以 openai. 开头的映射键时会忽略这些声明。

配置服务账号映射

  1. 创建服务账号映射。 将名称设为在该工作负载身份提供方内唯一的值,例如 openai-mapping-kubernetes。在描述中填写 Workload Identity Provider Mapping for Kubernetes Workloads 等说明,指出哪些工作负载可以使用此映射。

  2. 匹配 Kubernetes 服务账号主体。 将键设为 sub,将值设为 system:serviceaccount:default:openai-wif。Kubernetes 服务账号的主体格式为 system:serviceaccount:<namespace>:<service-account-name>。

  3. 选择 OpenAI 目标。 将项目设为目标服务账号所属的 OpenAI 项目。将服务账号设为 Kubernetes 工作负载可以使用的 OpenAI 服务账号,例如 kubernetes-prod-openai-wif。如果您希望为此映射创建新的服务账号,而不复用现有账号,请勾选 Create a new service account in this project。

  4. 按需缩小 API 权限范围。 在权限中选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限范围。如果您无需为工作负载身份联合额外限制权限范围,请将权限留空。使用该令牌发起的请求仍以映射的服务账号身份获得授权。

在代码中使用令牌

配置 OpenAI SDK 客户端,使其读取 Kubernetes 投射的令牌,并用它换取 OpenAI 签发的访问令牌。

将令牌的挂载路径(例如 /var/run/secrets/tokens/token)指定为 SDK 工作负载身份联合提供方的主体令牌来源。SDK 会用该 Kubernetes 令牌换取 OpenAI 签发的访问令牌,再使用 OpenAI 令牌对 API 请求进行身份验证。

以下示例使用自定义主体令牌提供方初始化 OpenAI 客户端。该提供方从挂载的文件中读取 Kubernetes 投射的服务账号令牌,并将其用作工作负载身份联合的主体令牌。

使用 Kubernetes 投射的服务账号令牌进行身份验证
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const tokenPath = "/var/run/secrets/tokens/token";
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (!identityProviderId || !serviceAccountId) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

function mountedServiceAccountTokenProvider(path: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const token = (await readFile(path, "utf8")).trim();
      if (!token) {
        throw new Error("The mounted service account token file is empty.");
      }
      return token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: mountedServiceAccountTokenProvider(tokenPath),
  },
});

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  input: "Say hello from Kubernetes workload identity federation.",
});

console.log(response.output_text);

Kubernetes 最佳实践

  • 使用稳定的 OIDC 签发者。签发者 URL 必须与投射服务账号令牌的 iss 声明一致,并应在集群升级和维护期间保持不变。
  • 妥善保护签名密钥。任何能访问集群服务账号签名密钥的人都可以签发 OpenAI 可能接受的令牌。
  • 为 OpenAI 集成使用专用服务账号。避免复用同时用于访问无关基础设施或应用的服务账号。
  • 及时更新已上传的 JWKS。在本地 JWKS 模式下,OpenAI 使用配置的 JWKS 验证工作负载身份令牌,因此请在切换到新的签名密钥之前更新工作负载身份提供方配置。
  • 尽量简化自定义声明。优先使用 sub 和 aud 等标准声明进行匹配,也可以使用直接从这些声明转换得到的属性。
  • 将命名空间的管理权纳入安全模型。如果命名空间管理员可以创建服务账号,请确保映射的适用范围恰当,以防意外提权。
  • 监控签发者和签名密钥的变更。如果轮换签名密钥时未更新工作负载身份提供方的 JWKS,令牌交换可能会失败。