Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.crewai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Visão Geral

Este guia o orienta na configuração do Google Cloud Secret Manager como provedor de segredos para sua organização na CrewAI Platform, usando credenciais de service account. Ao final, a CrewAI Platform poderá ler segredos armazenados no seu projeto Google Cloud e injetá-los como valores de variáveis de ambiente em runtime.
Este guia cobre o caminho de credenciais estáticas — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação, veja GCP Workload Identity Federation.
Este guia cobre a configuração do lado GCP e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja Usando o Secrets Manager.

​
Pré-requisitos

Antes de começar, certifique-se de que você tem:
  • Um projeto Google Cloud com a Secret Manager API habilitada. Habilite-a no console APIs & Services ou via gcloud: 
    gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
  • Permissão no projeto para criar service accounts, conceder papéis IAM e (se necessário) criar segredos.
  • Uma organização na CrewAI Platform onde seu usuário tem a permissão secret_providers: manage. Veja Permissões (RBAC).

​
Passo 1 — Criar uma Service Account

Uma service account é a identidade do lado GCP como a qual a CrewAI Platform irá se autenticar. No console IAM & Admin → Service Accounts, clique em Create Service Account.
  • Service account name: crewai-secrets-reader
  • Service account ID: preenchido automaticamente a partir do nome (ex. crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com)
  • Description (optional): “Read-only access to Secret Manager for CrewAI Platform”
Clique em Create and Continue. Pule as concessões opcionais nesta tela — você anexará o papel no Passo 2. Clique em Done. Para detalhes completos, veja a documentação GCP: Create service accounts.

​
Passo 2 — Conceder Acesso ao Secret Manager

A CrewAI Platform precisa de permissão para listar e ler segredos no seu projeto. Use um de dois escopos — a nível de projeto para simplicidade ou por segredo para menor privilégio.
No console IAM, clique em Grant Access e:
  • New principals: o email da service account do Passo 1.
  • Role: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor).
Clique em Save.Ou via gcloud:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"
O papel roles/secretmanager.secretAccessor concede acesso somente leitura aos valores de segredos. A CrewAI Platform também chama secretmanager.secrets.list para a experiência de autocomplete no formulário de env-var — essa permissão está incluída no papel no escopo de projeto, mas não no escopo por segredo. Com vínculos por segredo, o autocomplete não sugerirá segredos; você precisará digitar o nome completo do segredo.

​
Passo 3 — Criar uma Chave de Service Account

Abra a service account do Passo 1 no console IAM & Admin → Service Accounts.
  • Clique na aba Keys.
  • Clique em Add Key → Create new key.
  • Key type: JSON.
  • Clique em Create. O navegador baixa um arquivo JSON — mantenha-o seguro; não pode ser baixado novamente.
Ou via gcloud: 
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
  --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
A chave de service account é uma credencial estática de longa duração. Armazene-a com segurança (em um gerenciador de senhas ou no seu próprio cofre de segredos) e rotacione-a em uma cadência regular. Para eliminar credenciais estáticas completamente, use GCP Workload Identity Federation.

​
Passo 4 — Adicionar a Credencial na CrewAI Platform

Na CrewAI Platform, navegue até Settings → Secret Provider Credentials e clique em Add Credential. Preencha o formulário:
  • Name: Um nome descritivo, ex. gcp-prod.
  • Provider: Google Cloud Secret Manager.
  • Project ID: O ID do seu projeto GCP (ex. my-crewai-prod).
  • Service Account JSON: Cole o conteúdo inteiro do arquivo JSON que você baixou no Passo 3.
  • (Opcional) Marque Set as default credential for this provider. A credencial padrão é usada por variáveis de ambiente que referenciam segredos GCP sem especificar uma credencial explicitamente.
Clique em Create.

​
Passo 5 — Criar Pelo Menos Um Segredo no GCP

Se você ainda não tem segredos no GCP Secret Manager, crie um agora para que possa verificar a conexão no Passo 6. No console Secret Manager, clique em Create secret.
  • Name: Um nome único, ex. openai-api-key.
  • Secret value: Cole um valor bruto ou faça upload de um arquivo.
  • Deixe as configurações de rotação, replicação e outras em seus padrões a menos que tenha um requisito específico.
Clique em Create secret. Ou via gcloud: 
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
  --data-file=- \
  --project=YOUR_PROJECT_ID \
  --replication-policy=automatic
Sintaxe de referência por chave JSON. O GCP Secret Manager trata valores de segredos como blobs opacos. Se o valor do seu segredo for uma string JSON, a CrewAI Platform pode extrair um único campo usando a sintaxe secret-name#json_key (ex. database-credentials#password). Veja Usando o Secrets Manager para detalhes.
Para detalhes completos, veja a documentação GCP: Create a secret.

​
Passo 6 — Testar a Conexão

De volta à CrewAI Platform, na página Secret Provider Credentials, encontre a credencial que você acabou de criar e clique em Test Connection. Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar no GCP e ler segredos do seu projeto. Se o teste falhar, verifique as causas mais comuns:
SintomaCausa provável
PERMISSION_DENIED ao listar segredosA service account está sem roles/secretmanager.secretAccessor, ou você escopou por segredo (list não é concedido). Reconfira o Passo 2.
PERMISSION_DENIED em secretmanager.secrets.accessMesmo que acima, mas para um segredo específico. Confirme que a service account tem o papel accessor no segredo em questão.
unauthorized_client / invalid_grantO JSON de Service Account colado é inválido, expirado ou pertence a uma service account excluída. Recrie a chave (Passo 3) e cole novamente.
Project ID does not matchO campo Project ID na CrewAI Platform não corresponde ao projeto dono da service account / segredos. Reconfira o Passo 4.
API not enabledSecret Manager API não está habilitada no projeto. Veja Pré-requisitos.

​
Próximos Passos

Agora que o GCP está conectado, vá para Usando o Secrets Manager para:
  • Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager.
  • Referenciar seus segredos GCP a partir de variáveis de ambiente da CrewAI Platform.
Se você quiser segredos conscientes de rotação que se propagam sem novo deploy, mude para GCP Workload Identity Federation — mesmo cofre de segredos, sem credenciais estáticas, segredos buscados por kickoff.