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

Самоуправляемые кластеры Kubernetes (kubeadm, k3s, OpenShift и локальные дистрибутивы) подписывают OIDC «JSON Web Tokens» (веб-токены JSON), или 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

Следуйте пошаговому руководству по настройке, чтобы зарегистрировать эмитент федерации, создать сервисный аккаунт Anthropic и создать правило федерации в Claude Console. Используйте следующие значения, специфичные для Kubernetes.

Эмитент федерации: Многие самоуправляемые кластеры используют 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_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

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

Правило федерации: Сопоставьте утверждение 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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 и режимы сопоставления правил.