andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-07-03 14:09:24 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity
Files
05ab1ece8ed952e54c9775ccbfdda79f84cb8271
crewAI/docs/edge/pt-BR/enterprise/features/secrets-manager/usage.mdx
Lucas Gomide a237ebabba feat: adopt directory-based docs versioning with Edge channel (#6202) 
* feat: adopt directory-based docs versioning with Edge channel

Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.

Layout:
- docs/edge/<lang>/*         rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/*     frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/               shared, append-only
- docs/docs.json             nav + redirects

URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.

Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
  docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
  snapshot, inserts the version into every language block in
  docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
  Phase 2 of devtools release. Edge changelogs are updated first (so
  the snapshot freeze picks them up), then the snapshot is staged
  alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
  is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
  — the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
  enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
  Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
  docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
  and never accidentally touch a frozen snapshot.

Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
  historical snapshots (v1.10.0 .. v1.14.7) from git tags via
  git archive | tar, rewriting openapi: MDX refs so each snapshot
  reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
  rewrites every page path in 16 versioned blocks to point under
  docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
  v1.14.7 as Latest (default), prunes pages whose target file
  doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
  v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
  around docs_versioning.freeze for manual one-off freezes (e.g.
  retroactively snapshotting a forgotten release).

CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
  title contains [docs-freeze] (i.e. release-cut PRs generated by
  devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
  single image directory. Deleting or renaming an image breaks every
  historical snapshot that still references it.

Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.

Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
  copy, openapi rewrite, version insertion, default demotion, redirect
  upserts, per-section redirect rewriting, idempotency, and invalid
  inputs.

Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).

AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style: resolve linter issues

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-17 11:56:59 -04:00

138 lines
10 KiB
Plaintext
Raw Blame History

---
title: Usando o Secrets Manager
description: Gerencie permissões e referencie segredos gerenciados a partir de variáveis de ambiente na CrewAI Platform
sidebarTitle: Uso e Permissões
icon: "list-check"
---
## Visão Geral
Este guia é agnóstico em relação ao provedor. Ele assume que você (ou outro admin) já configurou pelo menos uma Credencial de Provedor de Segredos. Escolha seu guia de configuração com base no caminho que deseja:
- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp)
- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
Use este guia para:
- Conceder as permissões corretas aos membros da organização.
- Referenciar segredos a partir de variáveis de ambiente nas suas automações.
- Verificar se tudo é resolvido corretamente em runtime.
## Permissões (RBAC)
Três features da CrewAI Platform são relevantes ao trabalhar com o Secrets Manager:
- `secret_providers` — controla o acesso à página **Secret Provider Credentials**.
- `workload_identity_configs` — controla o acesso à página **Workload Identity** (relevante apenas se você usar o caminho WI).
- `environment_variables` — controla quem pode criar ou editar variáveis de ambiente.
Cada feature tem dois níveis de ação: `read` e `manage`. Conceder `manage` implica automaticamente em `read`.
### O que Conceder
| Objetivo | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|---|---|---|---|
| Usar credenciais estáticas existentes em variáveis de ambiente (sem edição de provedor) | `read` | — | `manage` |
| Criar, editar ou excluir credenciais estáticas | `manage` | — | `manage` |
| Usar credenciais existentes baseadas em Workload Identity em env vars | `read` | — | `manage` |
| Criar, editar ou excluir configs de Workload Identity (e credenciais que as referenciam) | `manage` | `manage` | `manage` |
<Note>
**Owners** automaticamente têm acesso total a todas as features. O papel padrão **Member** intencionalmente exclui `secret_providers` e `workload_identity_configs` — admins devem incluir explicitamente os membros por meio de um papel customizado.
</Note>
### Como Atribuir
1. Na CrewAI Platform, navegue até **Settings** → **Roles**. Nesta página você pode criar novos papéis, editar as permissões de cada papel e atribuir papéis aos membros existentes da organização.
{/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */}
{/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}
2. Clique em **Create Role** para criar um novo papel ou abra um papel existente para editar suas permissões.
3. No editor de permissões do papel, alterne as features relevantes conforme a tabela acima:
- `secret_providers`: escolha **read** se este papel só precisa usar credenciais existentes, ou **manage** se também deve ser capaz de criar, editar e excluir credenciais.
- `environment_variables`: escolha **manage** para que o papel possa criar variáveis de ambiente que referenciam segredos.
{/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */}
{/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}
4. Salve o papel.
5. Atribua o papel aos membros relevantes pela mesma página de Roles (ou pela lista de Membros da organização).
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
## Referenciando Segredos em Variáveis de Ambiente
Uma vez que uma credencial de provedor exista e seu papel tenha as permissões corretas, você pode referenciar segredos gerenciados a partir de qualquer variável de ambiente.
Na CrewAI Platform, navegue até **Environment Variables** e clique em **Add Environment Variables**.
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
Preencha o formulário:
- **Key** — o nome da variável de ambiente. Deve começar com uma letra ou underscore e conter apenas letras, números e underscores. Convencionalmente em maiúsculas, ex. `OPENAI_API_KEY`.
- **Value Source** — escolha de onde vem o valor:
- **Direct Value** — um valor em texto puro que você digita. Use isto quando não quiser envolver um provedor.
- **Use AWS default** (ou o equivalente para o seu provedor) — usa a credencial atualmente marcada como padrão para aquele tipo de provedor.
- **A specific named credential** — selecione a credencial pelo nome. Use isto se você tiver múltiplas credenciais para o mesmo provedor (por exemplo, `aws-prod` e `aws-staging`) e quiser escolher uma explicitamente.
{/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */}
- **Secret Name** — o nome do segredo no seu provedor. Uma vez que uma credencial é selecionada, este campo oferece autocomplete: comece a digitar e a CrewAI Platform consulta seu provedor por nomes de segredos correspondentes.
Use a sintaxe `secret-name#json_key` para extrair um único campo de um segredo estruturado (JSON). Por exemplo, dado um segredo `database-credentials` com valor `{"username": "...", "password": "..."}`, referencie `database-credentials#password` para injetar apenas a senha.
{/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */}
<Note>
**Nota sobre Azure Key Vault:** Nomes de segredos do Azure não podem conter underscores. A CrewAI Platform converte automaticamente underscores no seu campo `Secret Name` para hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`).
</Note>
Clique em **Create** para salvar a variável.
{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */}
<Tip>
Ao editar uma variável de ambiente existente, deixar o campo **Value** em branco preserva o valor atual. Isto é intencional — permite que você altere outros campos (como o nome do segredo ou a credencial) sem precisar digitar o valor novamente.
</Tip>
## Verificando se Funciona
Para verificar de ponta a ponta:
1. Referencie a variável de ambiente em uma automação, crew ou deployment exatamente como você faria com qualquer outra variável de ambiente.
2. Faça o deploy da automação.
3. Dispare uma execução e confirme que ela é concluída com sucesso.
### O comportamento de rotação depende do caminho da credencial
| Caminho da credencial | Quando o segredo é lido | O que a rotação requer |
|---|---|---|
| **Credenciais estáticas** (chaves de acesso AWS, JSON de service account GCP) | No **momento do deploy** — o valor é incorporado à imagem do deployment | Fazer novo deploy da automação após rotacionar o segredo |
| **Workload Identity** (federação OIDC, AWS ou GCP) | A **cada kickoff de automação** — o valor é buscado de forma fresca da sua nuvem | Nada — o próximo kickoff após a rotação verá o novo valor |
<Note>
**Se você precisa de segredos conscientes de rotação** (sem novo deploy na rotação), use o caminho Workload Identity: [AWS WI](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) ou [GCP WI](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). O trade-off é mais esforço de configuração inicial (registrar a CrewAI Platform como provedor OIDC na sua nuvem), mas operações mais simples no longo prazo.
</Note>
Se o deploy ou a execução falhar com um erro relacionado ao seu segredo, verifique as causas mais comuns:
| Sintoma | Causa provável |
|---|---|
| `no credential found` | A variável de ambiente referencia um provedor, mas nenhuma credencial específica foi selecionada e não há credencial padrão definida para aquele tipo de provedor. Selecione uma credencial explicitamente na variável, ou marque uma credencial como padrão na página **Secret Provider Credentials**. |
| `secret not found` | Erro de digitação no **Secret Name**, ou o segredo não existe na conta/região do provedor para a qual a credencial aponta. Reconfira ambos. |
| Automação executa com o valor antigo após rotação (caminho de credenciais estáticas) | O valor anterior está incorporado à imagem do contêiner do deployment. Faça novo deploy da automação para pegar o valor rotacionado. Para evitar isso completamente, mude a credencial para o caminho Workload Identity. |
| Automação executa com o valor antigo após rotação (caminho Workload Identity) | Confirme que a env var referencia uma credencial baseada em WI (não uma de chaves estáticas). Com WI, o próximo kickoff após a rotação deve ver o novo valor. Se não vir, verifique se o segredo foi realmente atualizado na sua nuvem (ex.: `aws secretsmanager get-secret-value`). |
| `JSON key not found` | Ao usar `secret-name#json_key`, o segredo subjacente deve ser um objeto JSON válido contendo essa chave. Verifique lendo o segredo diretamente no seu provedor. |
## Próximos Passos
- [Voltar à visão geral do Secrets Manager](/pt-BR/enterprise/features/secrets-manager/overview)
- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp)
- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity)
Reference in New Issue View Git Blame Copy Permalink