Использование WIF с Kubernetes

Самоуправляемые кластеры Kubernetes (kubeadm, k3s, OpenShift и локальные дистрибутивы) подписывают OIDC JSON Web Tokens (JWT) для каждого пода через проецируемые токены сервисных аккаунтов. API-сервер кластера выступает в роли издателя OIDC, а утверждение sub каждого токена имеет форму system:serviceaccount:<namespace>:<service-account>. Вы можете найти URL издателя вашего кластера, прочитав его документ обнаружения:

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



Предварительные требования

• Знакомство с концепциями WIF: сервисные аккаунты, издатели федерации и правила федерации.
• Кластер Kubernetes с флагом --service-account-issuer, настроенным на API-сервере. Большинство дистрибутивов устанавливают его по умолчанию; кластеры kubeadm обычно используют https://kubernetes.default.svc.cluster.local. Ваша команда платформы может подтвердить значение, если у вас нет прямого доступа к конфигурации API-сервера.
• Одно из следующего, чтобы Anthropic мог проверять подписи токенов:
  • Конечная точка JWKS издателя доступна из публичного интернета по HTTPS на порту 443, или
  • Вы можете получить JWKS изнутри кластера и зарегистрировать его в режиме inline (рассматривается в разделе Настройка Anthropic).
• Разрешение на создание сервисных аккаунтов, издателей федерации и правил федерации в Claude Console для вашей организации Anthropic.



Настройка Kubernetes

Спроецируйте токен сервисного аккаунта в ваш под с аудиторией и временем жизни, которые ожидает ваше правило федерации. Проекция serviceAccountToken записывает свежий JWT по пути монтирования и ротирует его до истечения expirationSeconds.

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

Токен, выданный для этого пода, содержит sub: "system:serviceaccount:inference:inference-worker" и aud: ["https://api.anthropic.com"].



Настройка Anthropic

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите плитку Kubernetes. Мастер проведёт вас через регистрацию издателя, создание сервисного аккаунта и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

Издатель федерации: Многие самоуправляемые кластеры используют URL издателя, такой как https://kubernetes.default.svc.cluster.local, который недоступен из публичного интернета. Если это относится к вашему кластеру, выберите источник JWKS inline и вставьте ключи кластера. Получите их изнутри кластера:

kubectl get --raw /openid/v1/jwks

Затем настройте издателя с содержимым возвращённого массива keys (без окружающей обёртки {"keys": [...]}):

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks": {
    "type": "inline",
    "keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
  }
}

В режиме inline значение issuer_url сравнивается только с утверждением iss в JWT; Anthropic никогда не пытается обратиться к нему. Если ваш издатель публично доступен, используйте вместо этого "jwks": {"type": "discovery"}.

Правило федерации: Сопоставьте утверждение sub сервисного аккаунта и аудиторию, которую вы установили для проецируемого токена.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Будьте настолько конкретны, насколько позволяет рабочая нагрузка. Ослабляйте subject_prefix до system:serviceaccount:inference:* (завершающий * делает его сопоставлением по префиксу) только в том случае, если каждый сервисный аккаунт в пространстве имён должен сопоставляться с одним и тем же сервисным аккаунтом Anthropic. Добавьте идентификатор правила fdrl_... в переменную окружения ANTHROPIC_FEDERATION_RULE_ID вашего пода.



Получение и использование токена

Спецификация пода в разделе Настройка Kubernetes устанавливает ANTHROPIC_IDENTITY_TOKEN_FILE на путь проецируемого монтирования, вместе с ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID и ANTHROPIC_WORKSPACE_ID. При их наличии SDK считывает токен с диска при каждом обмене и автоматически обновляет токен доступа Anthropic.

import anthropic

# Считывает ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID и ANTHROPIC_WORKSPACE_ID
# из окружения пода.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))



Проверка настройки

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. При ошибке 400 invalid_grant см. Устранение неполадок при неудачном обмене; наиболее распространённая причина на стороне Kubernetes — несоответствие ключа JWKS (для режима inline повторно получите его с помощью kubectl get --raw /openid/v1/jwks и обновите издателя).



Ограничение области действия правила

Ограничьте блок match правила до самой узкой области, подходящей для вашего случая использования:

• Закрепите пространство имён и имя сервисного аккаунта: Используйте полное значение system:serviceaccount:<namespace>:<name> без завершающего *.
• Всегда устанавливайте аудиторию: Требуйте audience в правиле и установите то же значение в проекции serviceAccountToken пода, чтобы токены с аудиторией по умолчанию отклонялись.
• Используйте отдельное правило для каждого пространства имён: Создавайте отдельное правило и сервисный аккаунт Anthropic для каждого пространства имён вместо расширения одного правила.
• Ограничивайте издателей с inline-JWKS одним кластером: Когда несколько кластеров используют один и тот же URL издателя, регистрируйте JWKS каждого кластера как отдельного издателя федерации и привязывайте правила только к этому издателю.



Следующие шаги

• Workload Identity Federation: концепции, поток обмена токенами и параметры конфигурации SDK.
• Справочник WIF: переменные окружения, режимы источников JWKS и режимы сопоставления правил.