Usar WIF com Kubernetes

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

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

Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Um cluster Kubernetes com a flag --service-account-issuer configurada no servidor de API. 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 servidor de API.
• Uma das seguintes opções para que a Anthropic possa validar as assinaturas dos tokens:
  • O endpoint JWKS do emissor é acessível pela internet pública via HTTPS na porta 443, ou
  • Você pode obter o JWKS de dentro do cluster e registrá-lo no modo inline (abordado em Configurar a Anthropic).
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.

Configurar o Kubernetes

Projete um token de conta de serviço 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 contém sub: "system:serviceaccount:inference:inference-worker" e aud: ["https://api.anthropic.com"].

Configurar a Anthropic

Siga o passo a passo de configuração para registrar um emissor de federação, criar uma conta de serviço Anthropic e criar uma regra de federação no Claude Console. Use estes valores específicos do Kubernetes.

Emissor de federação: Muitos clusters autogerenciados usam uma URL de emissor como https://kubernetes.default.svc.cluster.local, que não é acessível pela internet pública. Se esse for o caso do seu cluster, escolha a fonte JWKS inline e cole as chaves do cluster. Obtenha-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 wrapper {"keys": [...]} ao redor):

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks_source": "inline",
  "jwks_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_source": "discovery" em vez disso e omita jwks_keys.

Regra de federação: Faça a correspondência com a claim sub da conta de serviço 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 o workload permitir. Afrouxe subject_prefix para system:serviceaccount:inference:* (o * no final torna isso uma correspondência por prefixo) apenas se todas as contas de serviço no namespace devem ser mapeadas para a mesma conta de serviço Anthropic. Adicione o ID fdrl_... da regra à variável de ambiente ANTHROPIC_FEDERATION_RULE_ID do seu pod.

Obter e usar o token

A especificação do pod em Configurar o Kubernetes define ANTHROPIC_IDENTITY_TOKEN_FILE como 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Verificar 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, obtenha novamente com kubectl get --raw /openid/v1/jwks e atualize o emissor).

Definir o escopo da sua regra

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

• Fixe o namespace e o nome da conta de serviço: 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 e uma conta de serviço Anthropic distintas para cada namespace em vez de ampliar uma única regra.
• Limite 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 regras apenas a esse emissor.

Próximos passos

• Workload Identity Federation: conceitos, o fluxo de troca de token 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.