如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

為 Kubernetes 設定工作負載身分識別同盟

使用 Kubernetes 作為工作負載身分識別提供者,以 Kubernetes 投射的服務帳戶權杖換取短效 OpenAI 存取權杖。

設定 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,進一步限制透過這項對應簽發的存取權杖可執行的操作。若無須額外限制 WIF 的授權範圍,請將權限留白。權杖仍會以對應的服務帳戶身分取得授權。

在程式碼中使用權杖

設定 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-5.6-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,可能會導致權杖交換失敗。