Use WIF com Kubernetes

Clusters Kubernetes autogerenciados (kubeadm, k3s, OpenShift e distribuições on-premises) assinam JSON Web Tokens (JWTs) OIDC para cada pod por meio de tokens de service account projetados. O API server do cluster atua como o emissor OIDC, e a claim sub de cada token segue a forma system:serviceaccount:<namespace>:<service-account>. Você pode encontrar a URL do emissor do seu cluster lendo seu documento de descoberta:

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



Pré-requisitos

• Familiaridade com os conceitos de WIF: service accounts, emissores de federação e regras de federação.
• Um cluster Kubernetes com a flag --service-account-issuer configurada no API server. A maioria das distribuições define isso por padrão; clusters kubeadm normalmente usam https://kubernetes.default.svc.cluster.local. Sua equipe de plataforma pode confirmar o valor se você não tiver acesso direto à configuração do API server.
• Um dos seguintes para que a Anthropic possa validar as assinaturas dos tokens:
  • O endpoint JWKS do emissor é acessível a partir da internet pública via HTTPS na porta 443, ou
  • Você pode buscar o JWKS de dentro do cluster e registrá-lo no modo inline (abordado em Configure a Anthropic).
• Permissão para criar service accounts, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.



Configure o Kubernetes

Projete um token de service account no seu pod com a audiência e o tempo de vida que sua regra de federação espera. A projeção serviceAccountToken grava um JWT novo no caminho de montagem e o rotaciona antes que expirationSeconds expire.

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

O token emitido para este pod carrega sub: "system:serviceaccount:inference:inference-worker" e aud: ["https://api.anthropic.com"].



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Kubernetes. O assistente orienta você no registro do emissor, na criação de um service account e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: Muitos clusters autogerenciados usam uma URL de emissor como https://kubernetes.default.svc.cluster.local que não é acessível a partir da internet pública. Se isso se aplica ao seu cluster, escolha a fonte JWKS inline e cole as chaves do cluster. Busque-as de dentro do cluster:

kubectl get --raw /openid/v1/jwks

Em seguida, configure o emissor com o conteúdo do array keys retornado (não o invólucro {"keys": [...]} ao redor):

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

No modo inline, a issuer_url é apenas comparada com a claim iss do JWT; a Anthropic nunca tenta acessá-la. Se o seu emissor for acessível publicamente, use "jwks": {"type": "discovery"} em vez disso.

Regra de federação: Faça a correspondência com a claim sub do service account e a audiência que você definiu no token projetado.

{
  "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
}

Seja tão específico quanto a carga de trabalho permitir. Afrouxe subject_prefix para system:serviceaccount:inference:* (o * no final o torna uma correspondência de prefixo) apenas se todo service account no namespace deve ser mapeado para o mesmo service account da Anthropic. Adicione o ID fdrl_... da regra à variável de ambiente ANTHROPIC_FEDERATION_RULE_ID do seu pod.



Adquira e use o token

A especificação do pod em Configure o Kubernetes define ANTHROPIC_IDENTITY_TOKEN_FILE para o caminho de montagem projetado, junto com ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID. Com isso configurado, o SDK lê o token do disco a cada troca e atualiza o token de acesso da Anthropic automaticamente.

import anthropic

# Lê ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID
# do ambiente do pod.
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"))



Verifique a configuração

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado do Kubernetes é uma incompatibilidade de chave JWKS (para o modo inline, busque novamente com kubectl get --raw /openid/v1/jwks e atualize o emissor).



Defina o escopo da sua regra

Restrinja o bloco match da regra ao escopo mais estreito que atenda ao seu caso de uso:

• Fixe o namespace e o nome do service account: Use o valor completo system:serviceaccount:<namespace>:<name> sem * no final.
• Sempre defina uma audiência: Exija audience na regra e defina o mesmo valor na projeção serviceAccountToken do pod para que tokens de audiência padrão sejam rejeitados.
• Use uma regra separada por namespace: Crie uma regra distinta e um service account da Anthropic para cada namespace em vez de ampliar uma única regra.
• Restrinja emissores com JWKS inline a um único cluster: Quando vários clusters compartilham uma URL de emissor, registre o JWKS de cada cluster como seu próprio emissor de federação e vincule as regras apenas a esse emissor.



Próximos passos

• Workload Identity Federation: conceitos, o fluxo de troca de tokens e opções de configuração do SDK.
• Referência de WIF: variáveis de ambiente, modos de fonte JWKS e modos de correspondência de regras.