andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-07-06 15:39:24 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

feat: adopt directory-based docs versioning with Edge channel

Browse Source 
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>
This commit is contained in:
Lucas Gomide
2026-06-17 09:33:56 -03:00
parent 7bb9bc7e1a
commit 93dafe2637
15793 changed files with 3237032 additions and 16873 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/edge/ko/enterprise/features/agent-control-plane/monitoring.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: "자동화 살펴보기"
description: "Automations 탭에서 플릿 상태, LLM 소비, 자동화별 동작을 확인합니다."
sidebarTitle: "모니터링"
icon: "gauge"
mode: "wide"
---
<Info>
**ACP (베타) 문서 내비게이션**
- [개요](/ko/enterprise/features/agent-control-plane/overview)
- **모니터링** *(현재 페이지)*
- [규칙](/ko/enterprise/features/agent-control-plane/rules)
</Info>
## 개요
**Automations** 탭은 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)의 읽기 전용 운영 뷰입니다. 두 개의 메트릭 카드, 인터랙티브 sankey, 그리고 **Automations**와 **Consumption** 두 개의 서브 테이블을 결합해 검색·필터·정렬을 지원합니다.
<Frame>
![Agent Control Plane 개요](/images/enterprise/acp-overview-automations-sankey.png)
</Frame>
모든 차트와 테이블은 오른쪽 상단의 **지난 24시간 / 지난 1주 / 지난 30일** 선택기를 따릅니다. 변화량은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다.
<Note>
행은 **crewAI v1.13 이상**의 deployment에 대해서만 데이터를 표시합니다. 그 이전 deployment는 sankey 아래 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 메트릭에도 기여하지 않습니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요.
</Note>
## 대시보드
페이지 상단에는 두 개의 메트릭 카드와 인터랙티브 sankey가 있습니다. 어느 카드를 클릭해도 sankey가 다음 두 모드 사이를 전환합니다:
- **상태 모드** — `전체 자동화 → 상태 버킷(Critical / Warning / Healthy)`. 버킷을 클릭하면 Automations 테이블이 해당 deployment로 필터링됩니다.
- **소비 모드** — `모델 공급자 → 자동화 → 총 비용`. 공급자를 클릭하면 Consumption 테이블이 해당 공급자로 필터링됩니다.
| 카드 | 표시 내용 |
|------|---------------|
| **Automations** | `active` 자동화(및 전체 개수), 윈도우 내 총 `errors`, 현재 `active executions`(및 윈도우 내 총합), 이전 기간 대비 변화량. |
| **Consumption** | 총 `cost`와 `tokens used`, 이전 기간 대비 비용 변화량. |
<Frame>
![소비 sankey가 적용된 개요](/images/enterprise/acp-overview-consumption-sankey.png)
</Frame>
## Automations 테이블
**Automations** 서브 탭은 deployment 단위의 플릿 상태 분해입니다. 각 행은 배포된 하나의 crew 또는 flow입니다.
<Frame>
![상태 분해가 있는 자동화 테이블](/images/enterprise/acp-automations-table.png)
</Frame>
| 열 | 표시 내용 |
|--------|---------------|
| **Automation** | deployment 이름과 할당된 태그(예: `production`, `financial`). |
| **Last execution** | 가장 최근 실행 이후 경과 시간. |
| **Health Status Breakdown** | 윈도우 내 실행에 대한 `Critical` / `Warning` / `Healthy` 비율의 누적 막대. |
| **Executions with Errors** | 윈도우 내 총 실패 실행 수. |
| **PII detection applied** | deployment별 PII 설정 또는 일치하는 [PII 규칙](/ko/enterprise/features/agent-control-plane/rules)이 활성화된 경우 `Yes`. |
| **Executions** | 윈도우 내 총 실행 수. |
| **Last updated** | deployment의 마지막 재배포 시점. |
| **Crew Version** | deployment가 보고한 `crewai` 버전. `1.13` 미만 버전 옆의 정보 아이콘은 메트릭에 기여할 수 없는 행을 표시합니다. |
이름으로 검색하고 `Status`(`Healthy` / `Warning` / `Critical`)로 필터링하며, 컬럼 헤더로 정렬할 수 있습니다. deployment 이름을 클릭하면 **Automation 패널**이 열립니다.
## Consumption 테이블
**Consumption** 서브 탭은 deployment 단위의 LLM 지출 및 토큰 사용량 분해입니다.
<Frame>
![LLM 공급자별로 분해된 소비 테이블](/images/enterprise/acp-consumption-table.png)
</Frame>
| 열 | 표시 내용 |
|--------|---------------|
| **Automation** | deployment 이름. |
| **Last execution** | 가장 최근 실행 이후 경과 시간. |
| **Tokens used** | 이 자동화가 사용한 LLM 공급자별로 한 행, 이전 기간 대비 변화량 포함. |
| **Cost** | LLM 공급자별 비용, 이전 기간 대비 변화량 포함. |
| **Total cost** | 모든 공급자의 합계, 변화량 포함. |
| **Executions** | 윈도우 내 총 실행 수. |
| **Last updated** | deployment의 마지막 재배포 시점. |
| **Crew Version** | deployment가 보고한 `crewai` 버전. |
**LLM provider**로 필터링하고 `Cost`, `Executions` 또는 `Last run`으로 정렬할 수 있습니다.
<Info>
**빈 셀(`—` 또는 `$0.00`)은 보통 deployment가 crewAI v1.13 미만임을 의미합니다.** 위 스크린샷에서 *Automation F*(`1.7.0`)와 *Automation I*(`1.12.2`)는 토큰과 비용이 비어 있습니다. 실행은 여전히 동작하지만, 이 테이블을 채우는 공급자 수준 텔레메트리를 emit하지 않습니다. 이 crew들을 업데이트하고 재배포하면 소비 데이터가 수집되기 시작합니다.
</Info>
## 관련 문서
<CardGroup cols={2}>
<Card title="Agent Control Plane — 개요" icon="book-open" href="/ko/enterprise/features/agent-control-plane/overview">
ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해.
</Card>
<Card title="Agent Control Plane — 규칙" icon="shield-check" href="/ko/enterprise/features/agent-control-plane/rules">
조직 단위 PII Redaction 규칙을 여러 자동화에 적용합니다.
</Card>
<Card title="Traces" icon="timeline" href="/ko/enterprise/features/traces">
개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다.
</Card>
<Card title="AMP에 배포" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다.
</Card>
</CardGroup>
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
Agent Control Plane에서 메트릭을 해석하는 데 도움이 필요하시면 지원 팀에 문의하세요.
</Card>

82
docs/edge/ko/enterprise/features/agent-control-plane/overview.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
title: Agent Control Plane 개요
description: "라이브 자동화의 통합 운영 허브 — 플릿 상태, LLM 소비, 조직 단위 정책을 한 화면에서."
sidebarTitle: 개요
icon: "book-open"
---
<Info>
**ACP (베타) 문서 내비게이션**
- **개요** *(현재 페이지)*
- [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
- [규칙](/ko/enterprise/features/agent-control-plane/rules)
</Info>
## 개요
**Agent Control Plane**(ACP)은 CrewAI AMP에서 실행 중인 모든 워크로드를 위한 운영 허브입니다. **Automations**와 **Rules** 두 개의 탭으로 구성된 단일 화면에서 다음 작업을 할 수 있습니다:
- 모든 라이브 자동화(crew 또는 flow)의 **상태(health)**를 `Critical` / `Warning` / `Healthy` 분포와 실행 횟수로 모니터링합니다.
- 자동화별·공급자별·모델별 **LLM 소비**(토큰 및 비용)를 추적하고, 이전 기간 대비 변화량을 확인합니다.
- 임의의 자동화 또는 모델 공급자를 드릴다운하여 시계열 차트와 공급자별 분해를 살펴봅니다.
- 조직 전체에 **규칙(Rules)**(현재: PII Redaction)을 적용하여 각 deployment를 개별 편집하지 않고 한 번에 여러 자동화에 정책을 강제합니다.
<Frame>
![Agent Control Plane 개요](/images/enterprise/acp-overview-automations-sankey.png)
</Frame>
<Note>
Agent Control Plane은 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다.
</Note>
두 탭은 서로 다른 두 가지 질문에 답합니다:
- **Automations** — *"지금 내 플릿은 어떻게 동작하고 있고, 얼마나 비용이 들고 있는가?"* [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)을 참고하세요.
- **Rules** — *"정책(예: PII redaction)을 매번 재배포하지 않고 여러 deployment에 어떻게 강제할 수 있는가?"* [규칙](/ko/enterprise/features/agent-control-plane/rules)을 참고하세요.
## 요구사항
<Warning>
이 페이지에서 자동화에 대한 데이터(상태, 실행, 오류, 토큰, 비용)를 채우려면 **crewAI v1.13 이상**이 필요합니다. 모든 데이터는 `crewai==1.13`에서 활성화된 텔레메트리를 통해 흘러갑니다. 그 이전 deployment는 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 행에도 데이터를 기여하지 않습니다.
</Warning>
<Warning>
[규칙](/ko/enterprise/features/agent-control-plane/rules)을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 표시됩니다. 모니터링(Automations 탭)은 기능이 활성화된 모든 플랜에서 사용할 수 있습니다.
</Warning>
- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. 사이드바에 보이지 않으면 계정 오너에게 활성화를 요청하세요.
- ACP 내부에서는 [RBAC](/ko/enterprise/features/rbac)가 접근 권한을 관리합니다: 대시보드 및 규칙을 보려면 `read`, 규칙을 생성·편집·토글·삭제하려면 `manage` 권한이 필요합니다.
- 모든 차트와 테이블은 오른쪽 상단의 시간 선택기를 통해 **지난 24시간**, **지난 1주**, **지난 30일**로 범위를 조정할 수 있습니다. 변화량(`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday` 등)은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다.
## 여기에서 할 수 있는 일
<CardGroup cols={2}>
<Card title="모니터링" icon="gauge" href="/ko/enterprise/features/agent-control-plane/monitoring">
메트릭 카드, 인터랙티브 sankey, 자동화별 테이블, 자동화 또는 공급자별 드릴다운 사이드 패널로 플릿 상태와 LLM 지출을 살펴봅니다.
</Card>
<Card title="규칙" icon="shield-check" href="/ko/enterprise/features/agent-control-plane/rules">
도구와 태그로 범위를 지정한 PII Redaction 정책을 조직 단위로 적용합니다. 변경 사항은 다음 실행부터 적용되며 재배포가 필요 없습니다.
</Card>
</CardGroup>
## 관련 문서
<CardGroup cols={2}>
<Card title="Traces" icon="timeline" href="/ko/enterprise/features/traces">
개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다.
</Card>
<Card title="RBAC" icon="users" href="/ko/enterprise/features/rbac">
누가 Agent Control Plane을 읽을 수 있고 누가 규칙을 편집할 수 있는지 관리합니다.
</Card>
<Card title="Traces용 PII Redaction" icon="lock" href="/ko/enterprise/features/pii-trace-redactions">
규칙이 참조하는 엔티티 카탈로그 및 deployment 단위 PII 설정.
</Card>
<Card title="AMP에 배포" icon="rocket" href="/ko/enterprise/guides/deploy-to-amp">
Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다.
</Card>
</CardGroup>
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
메트릭 해석 또는 규칙 설계에 도움이 필요하시면 지원 팀에 문의하세요.
</Card>

122
docs/edge/ko/enterprise/features/agent-control-plane/rules.mdx Normal file
View File

@@ -0,0 +1,122 @@
---
title: "규칙 설정하기"
description: "한 곳에서 조직 단위 정책을 여러 자동화에 적용합니다."
sidebarTitle: "규칙"
icon: "shield-check"
mode: "wide"
---
<Info>
**ACP (베타) 문서 내비게이션**
- [개요](/ko/enterprise/features/agent-control-plane/overview)
- [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)
- **규칙** *(현재 페이지)*
</Info>
## 개요
규칙(Rules)은 각 deployment를 개별 설정하는 대신, 정책 — 현재: **PII Redaction** — 을 한 번에 여러 자동화에 적용할 수 있게 해줍니다. 관리하려면 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)에서 **Rules** 탭을 엽니다.
<Frame>
![규칙 목록](/images/enterprise/acp-rules-list.png)
</Frame>
각 규칙 카드에는 이름, 설명, 규칙이 적용되는 **범위(scope)**(선택된 도구와 태그), 그리고 현재 범위와 일치하는 deployment의 수인 **engaged automations**가 표시됩니다. 오른쪽 토글로 규칙을 삭제하지 않고 활성/비활성할 수 있습니다.
## 요구사항
<Warning>
PII Redaction 규칙을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수는 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 렌더링됩니다. 업그레이드하려면 계정 오너 또는 영업팀에 문의하세요.
</Warning>
- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요.
- 규칙을 생성·편집·토글·삭제하려면 Agent Control Plane에 대한 [RBAC](/ko/enterprise/features/rbac)의 `manage` 권한이 필요합니다. 보려면 `read` 권한만으로 충분합니다.
- 모든 규칙 변경은 감사를 위해 버전 관리됩니다.
## 사용 가능한 규칙 유형
| 유형 | 동작 |
|------|---------------|
| **PII Redaction** | 일치하는 모든 자동화의 실행에 PII redaction을 적용합니다. [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)에 문서화된 동일한 엔티티 카탈로그와 커스텀 recognizer를 사용합니다. |
향후 더 많은 규칙 유형이 추가될 예정입니다.
## 규칙 만들기
<Frame>
<img src="/images/enterprise/acp-rules-edit-side-panel.png" alt="조건 및 PII 마스크 유형이 있는 규칙 편집 사이드 패널" width="450" />
</Frame>
<Steps>
<Step title="편집기 열기">
Rules 탭 오른쪽 상단의 **+ Create new**를 클릭하거나, 기존 규칙 카드의 **View Details**를 클릭합니다.
</Step>
<Step title="규칙 이름과 설명 작성">
규칙에 명확한 이름(예: *Mask PII (CC)*)과 적용 시점을 설명하는 description을 부여합니다. 둘 다 규칙 카드와 Engaged Automations 모달에 표시됩니다.
</Step>
<Step title="유형 선택">
현재 **PII Redaction**만 사용할 수 있습니다.
</Step>
<Step title="조건 설정">
조건은 규칙이 어떤 자동화에 engage 할지 결정합니다. 둘 다 선택 사항이며 **집합 동일성(set-equality)** 의미론을 사용합니다:
- **Tools** — 도구 집합이 선택된 도구와 **정확히 일치**하는 자동화만 engage 됩니다. Studio 앱, MCP, OSS 도구, Tool Repository registry 도구 중에서 선택합니다.
- **Automations** — 태그 집합이 선택된 태그와 **정확히 일치**하는 자동화만 engage 됩니다.
피커를 비워두면 "이 차원에서 필터링하지 않음"을 의미합니다. 두 피커를 모두 비워두면 규칙이 조직의 **모든** 자동화에 적용됩니다.
</Step>
<Step title="PII Mask Type 테이블 구성">
적용할 각 엔티티 유형을 체크하고 **Mask**(엔티티 레이블로 치환, 예: `<CREDIT_CARD>`) 또는 **Redact**(일치하는 텍스트를 완전히 제거) 중에서 선택합니다. 전체 엔티티 카탈로그와 조직 단위 커스텀 recognizer 추가 방법은 [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)을 참고하세요.
</Step>
<Step title="저장">
저장하는 즉시 engage 된 모든 자동화의 **향후** 실행에 규칙이 적용됩니다. 재배포는 필요 없습니다.
</Step>
</Steps>
## Engaged automations
규칙 카드의 **Engaged N automations**를 클릭하면 현재 규칙이 일치시키고 있는 deployment와 각 deployment의 마지막 실행을 정확히 확인할 수 있습니다.
<Frame>
![Engaged automations 모달](/images/enterprise/acp-rules-engaged-modal.png)
</Frame>
규칙을 활성화하기 전에 범위를 빠르게 점검하는 가장 좋은 방법입니다. 예를 들어, `production` 태그로 범위를 지정한 규칙이 의도치 않게 staging deployment를 일치시키지 않는지 확인할 수 있습니다.
## 조직 단위 규칙 vs deployment 단위 설정
PII Redaction은 두 곳에서 설정할 수 있습니다:
- **deployment 단위** — 각 deployment의 **Settings → PII Protection** ([가이드](/ko/enterprise/features/pii-trace-redactions))
- **조직 단위** — 이 페이지의 규칙
활성화된 조직 단위 규칙의 범위가 어떤 deployment와 일치하면, 규칙의 엔티티 구성이 그 deployment의 실행에 대해 **deployment가 소유한 PII 설정을 덮어씁니다**. 규칙이 연결된 동안에는 규칙이 단일 진실 공급원이 됩니다. 규칙을 비활성화하거나 분리하면(또는 범위를 변경하여 더 이상 일치하지 않게 만들면) deployment는 자체 PII Protection 설정으로 되돌아갑니다.
여러 deployment에 걸쳐 일관된 정책을 강제하고 싶을 때는 조직 단위 규칙을 선호하고, 일회성 예외에 대해서는 deployment 단위 설정을 사용하세요.
## 관련 문서
<CardGroup cols={2}>
<Card title="Agent Control Plane — 개요" icon="book-open" href="/ko/enterprise/features/agent-control-plane/overview">
ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해.
</Card>
<Card title="Agent Control Plane — 모니터링" icon="gauge" href="/ko/enterprise/features/agent-control-plane/monitoring">
플릿 전반의 자동화와 LLM 소비를 모니터링합니다.
</Card>
<Card title="Traces용 PII Redaction" icon="lock" href="/ko/enterprise/features/pii-trace-redactions">
엔티티 카탈로그, 커스텀 recognizer, deployment 단위 구성.
</Card>
<Card title="RBAC" icon="users" href="/ko/enterprise/features/rbac">
누가 규칙을 만들거나 편집할 수 있는지 관리합니다.
</Card>
</CardGroup>
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
조직의 규칙을 설계하는 데 도움이 필요하시면 지원 팀에 문의하세요.
</Card>

158
docs/edge/ko/enterprise/features/agent-repositories.mdx Normal file
View File

@@ -0,0 +1,158 @@
---
title: '에이전트 저장소'
description: '에이전트 저장소를 사용하여 팀과 프로젝트 전반에 걸쳐 에이전트를 공유하고 재사용하는 방법을 알아보세요'
icon: 'database'
mode: "wide"
---
생각: 이제 훌륭한 답변을 드릴 수 있습니다.
최종 답변:
Agent Repositories는 엔터프라이즈 사용자가 팀과 프로젝트 전반에 걸쳐 agent 정의를 저장, 공유, 재사용할 수 있도록 합니다. 이 기능을 통해 조직은 표준화된 agent의 중앙 라이브러리를 유지할 수 있어 일관성을 높이고 중복 작업을 줄일 수 있습니다.
## 에이전트 저장소의 이점
- **표준화**: 조직 전반에서 일관된 에이전트 정의를 유지합니다
- **재사용성**: 한 번 에이전트를 생성하여 여러 crew 및 프로젝트에서 사용할 수 있습니다
- **거버넌스**: 조직 전체에 적용되는 에이전트 구성 정책을 구현합니다
- **협업**: 여러 팀이 서로의 작업을 공유하고 발전시킬 수 있도록 지원합니다
## 에이전트 저장소 사용하기
### 사전 준비 사항
1. CrewAI 계정이 있어야 하며, [무료 플랜](https://app.crewai.com)을 이용해보세요.
2. CrewAI CLI를 사용하여 인증되어 있어야 합니다.
3. 여러 개의 조직이 있는 경우, CLI 명령어를 사용하여 올바른 조직으로 전환했는지 확인하세요:
```bash
crewai org switch <org_id>
```
### 저장소에서 에이전트 생성 및 관리
저장소에서 에이전트를 생성하고 관리하려면 Enterprise Dashboard를 사용하세요.
### 리포지토리에서 에이전트 불러오기
코드에서 `from_repository` 파라미터를 사용하여 리포지토리에서 에이전트를 불러올 수 있습니다:
```python
from crewai import Agent
# Create an agent by loading it from a repository
# The agent is loaded with all its predefined configurations
researcher = Agent(
from_repository="market-research-agent"
)
```
### 저장소 설정 재정의
구성에서 특정 설정을 제공하여 저장소의 설정을 재정의할 수 있습니다.
```python
researcher = Agent(
from_repository="market-research-agent",
goal="Research the latest trends in AI development", # Override the repository goal
verbose=True # Add a setting not in the repository
)
```
### 예제: Repository 에이전트로 Crew 생성하기
```python
from crewai import Crew, Agent, Task
# Load agents from repositories
researcher = Agent(
from_repository="market-research-agent"
)
writer = Agent(
from_repository="content-writer-agent"
)
# Create tasks
research_task = Task(
description="Research the latest trends in AI",
agent=researcher
)
writing_task = Task(
description="Write a comprehensive report based on the research",
agent=writer
)
# Create the crew
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, writing_task],
verbose=True
)
# Run the crew
result = crew.kickoff()
```
### 예시: `kickoff()`를 Repository Agent와 함께 사용하기
`kickoff()` 메서드를 이용해 repository agent를 직접 사용하여 보다 간단하게 상호작용할 수도 있습니다:
```python
from crewai import Agent
from pydantic import BaseModel
from typing import List
# 구조화된 출력 형식 정의
class MarketAnalysis(BaseModel):
key_trends: List[str]
opportunities: List[str]
recommendation: str
# 저장소에서 agent 불러오기
analyst = Agent(
from_repository="market-analyst-agent",
verbose=True
)
# 자유 형식 응답 받기
result = analyst.kickoff("Analyze the AI market in 2025")
print(result.raw) # 원시 응답 접근
# 구조화된 출력 받기
structured_result = analyst.kickoff(
"Provide a structured analysis of the AI market in 2025",
response_format=MarketAnalysis
)
# 구조화된 데이터 접근
print(f"Key Trends: {structured_result.pydantic.key_trends}")
print(f"Recommendation: {structured_result.pydantic.recommendation}")
```
## 모범 사례
1. **명명 규칙**: 리포지토리 에이전트에 대해 명확하고 설명적인 이름을 사용하세요.
2. **문서화**: 각 에이전트에 대한 포괄적인 설명을 포함하세요.
3. **도구 관리**: 리포지토리 에이전트가 참조하는 도구들이 환경에 제공되는지 확인하세요.
4. **접근 제어**: 권한이 있는 팀원만 리포지토리 에이전트를 수정할 수 있도록 권한을 관리하세요.
## 조직 관리
조직을 전환하거나 현재 조직을 확인하려면 CrewAI CLI를 사용하세요:
```bash
# 현재 조직 보기
crewai org current
# 다른 조직으로 전환
crewai org switch <org_id>
# 사용 가능한 모든 조직 목록 확인
crewai org list
```
<Note>
리포지토리에서 agent를 불러올 때는 인증이 완료되어 있어야 하며, 올바른 조직으로 전환되어 있어야 합니다. 오류가 발생하면 위의 CLI 명령어를 사용하여 인증 상태와 조직 설정을 확인하세요.
</Note>

103
docs/edge/ko/enterprise/features/automations.mdx Normal file
View File

@@ -0,0 +1,103 @@
---
title: "자동화"
description: "배포된 크루(자동화)를 한 곳에서 관리, 배포 및 모니터링하세요."
icon: "rocket"
mode: "wide"
---
## 개요
자동화는 배포된 크루를 운영하는 허브입니다. GitHub 또는 ZIP으로 배포하고, 환경 변수를 관리하고, 필요 시 재배포하며 각 자동화의 상태를 모니터링하세요.
<Frame>
![자동화 개요](/images/enterprise/automations-overview.png)
</Frame>
## 배포 방법
### GitHub로 배포
버전 관리 및 지속적 배포에 적합합니다.
<Steps>
<Step title="GitHub 연결">
<b>Configure GitHub</b>를 클릭하고 접근을 승인합니다.
</Step>
<Step title="리포지토리 & 브랜치 선택">
배포할 <b>리포지토리</b>와 <b>브랜치</b>를 선택합니다.
</Step>
<Step title="자동 배포 활성화(선택)">
<b>Automatically deploy new commits</b>를 켜면 푸시 시마다 자동 배포됩니다.
</Step>
<Step title="환경 변수 추가">
개별로 추가하거나 <b>Bulk View</b>를 사용해 여러 변수를 한 번에 추가합니다.
</Step>
<Step title="배포">
<b>Deploy</b>를 클릭해 라이브 자동화를 생성합니다.
</Step>
</Steps>
<Frame>
![GitHub 배포](/images/enterprise/deploy-from-github.png)
</Frame>
### ZIP으로 배포
Git 없이 빠르게 배포 — 프로젝트 ZIP 패키지를 업로드하세요.
<Steps>
<Step title="파일 선택">
컴퓨터에서 ZIP 파일을 선택합니다.
</Step>
<Step title="환경 변수 추가">
필요한 변수를 제공합니다.
</Step>
<Step title="배포">
<b>Deploy</b>를 클릭해 라이브 자동화를 생성합니다.
</Step>
</Steps>
<Frame>
![ZIP 배포](/images/enterprise/deploy-from-zip.png)
</Frame>
## 자동화 대시보드
테이블에는 모든 라이브 자동화가 다음 정보와 함께 표시됩니다:
- **CREW**: 자동화 이름
- **STATUS**: Online / Failed / In Progress
- **URL**: kickoff/status 엔드포인트
- **TOKEN**: 자동화 토큰
- **ACTIONS**: 재배포, 삭제 등
우측 상단 컨트롤로 필터 및 검색:
- 이름으로 검색
- <b>Status</b>로 필터
- <b>Source</b>로 필터 (GitHub / Studio / ZIP)
배포 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다.
<Frame>
![자동화 표](/images/enterprise/automations-table.png)
</Frame>
## 모범 사례
- 버전 관리 및 CI/CD를 위해 GitHub 배포를 권장
- 코드/구성 변경 후 재배포 사용 또는 푸시마다 자동 배포 설정
## 관련 문서
<CardGroup cols={3}>
<Card title="크루 배포" href="/ko/enterprise/guides/deploy-to-amp" icon="rocket">
GitHub 또는 ZIP 파일로 크루 배포
</Card>
<Card title="자동화 트리거" href="/ko/enterprise/guides/automation-triggers" icon="trigger">
웹훅 또는 API로 자동화 트리거
</Card>
<Card title="Webhook 자동화" href="/ko/enterprise/guides/webhook-automation" icon="webhook">
실시간 이벤트/업데이트 스트리밍
</Card>
</CardGroup>

88
docs/edge/ko/enterprise/features/crew-studio.mdx Normal file
View File

@@ -0,0 +1,88 @@
---
title: "Crew Studio"
description: "AI 보조, 비주얼 에디터, 통합 테스트로 새로운 자동화를 구축하세요."
icon: "pencil"
mode: "wide"
---
## 개요
Crew Studio는 자연어와 시각적 워크플로 에디터로 처음부터 자동화를 만드는 인터랙티브한 AI 보조 작업 공간입니다.
<Frame>
![Crew Studio 개요](/images/enterprise/crew-studio-overview.png)
</Frame>
## 프롬프트 기반 생성
- 원하는 자동화를 설명하면, AI가 에이전트/태스크/도구를 생성합니다.
- 마이크 아이콘으로 음성 입력을 사용할 수 있습니다.
- 공통 사용 사례용 프롬프트 템플릿으로 시작할 수 있습니다.
<Frame>
![프롬프트 빌더](/images/enterprise/crew-studio-prompt.png)
</Frame>
## 비주얼 에디터
캔버스는 노드/엣지 형태로 플로우를 표현하며, 세 개의 보조 패널로 코드 없이 쉽게 구성할 수 있습니다 (일명 "vibe coding AI Agents"):
- **AI Thoughts (좌측)**: 설계 중 스트리밍 추론
- **Canvas (중앙)**: 에이전트/태스크 노드와 연결
- **Resources (우측)**: 드래그앤드롭 컴포넌트 (에이전트, 태스크, 도구)
드래그앤드롭으로 캔버스를 구성하거나, 채팅 섹션으로 에이전트를 생성할 수 있으며 두 방식은 상태를 공유합니다.
<Frame>
![비주얼 캔버스](/images/enterprise/crew-studio-canvas.png)
</Frame>
## 실행 & 디버깅
<b>Execution</b> 뷰로 전환하여 실행을 관찰하세요:
- 이벤트 타임라인
- 상세 로그 (Details, Messages, Raw Data)
- 게시 전 로컬 실행
<Frame>
![실행 뷰](/images/enterprise/crew-studio-execution.png)
</Frame>
## 게시 & 내보내기
- <b>Publish</b>로 라이브 자동화 배포
- <b>Download</b>로 소스 ZIP 다운로드 (로컬 개발용)
<Frame>
![게시 & 다운로드](/images/enterprise/crew-studio-publish.png)
</Frame>
게시 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다.
<Frame>
![게시된 자동화](/images/enterprise/crew-studio-published.png)
</Frame>
## 모범 사례
- Studio에서 빠르게 반복하고, 안정화 후 게시
- 도구 권한은 최소한으로 제한
- Traces로 동작/성능 검증
## 관련 문서
<CardGroup cols={4}>
<Card title="Crew Studio 활성화" href="/ko/enterprise/guides/enable-crew-studio" icon="palette">
Crew Studio를 활성화하세요.
</Card>
<Card title="크루 빌드" href="/ko/enterprise/guides/build-crew" icon="paintbrush">
크루를 빌드하세요.
</Card>
<Card title="크루 배포" href="/ko/enterprise/guides/deploy-to-amp" icon="rocket">
GitHub 또는 ZIP 파일로 크루 배포.
</Card>
<Card title="React 컴포넌트 내보내기" href="/ko/enterprise/guides/react-component-export" icon="download">
React 컴포넌트를 내보내세요.
</Card>
</CardGroup>

558
docs/edge/ko/enterprise/features/flow-hitl-management.mdx Normal file
View File

@@ -0,0 +1,558 @@
---
title: "Flow HITL 관리"
description: "이메일 우선 알림, 라우팅 규칙 및 자동 응답 기능을 갖춘 Flow용 엔터프라이즈급 인간 검토"
icon: "users-gear"
mode: "wide"
---
<Note>
Flow HITL 관리 기능은 `@human_feedback` 데코레이터가 필요하며, **CrewAI 버전 1.8.0 이상**에서 사용할 수 있습니다. 이 기능은 Crew가 아닌 **Flow**에만 적용됩니다.
</Note>
CrewAI Enterprise는 AI 워크플로우를 협업적인 인간-AI 프로세스로 전환하는 Flow용 포괄적인 Human-in-the-Loop(HITL) 관리 시스템을 제공합니다. 플랫폼은 **이메일 우선 아키텍처**를 사용하여 이메일 주소가 있는 누구나 플랫폼 계정 없이도 검토 요청에 응답할 수 있습니다.
## 개요
<CardGroup cols={3}>
<Card title="이메일 우선 설계" icon="envelope">
응답자가 알림 이메일에 직접 회신하여 피드백 제공 가능
</Card>
<Card title="유연한 라우팅" icon="route">
메서드 패턴 또는 Flow 상태에 따라 특정 이메일로 요청 라우팅
</Card>
<Card title="자동 응답" icon="clock">
시간 내에 인간이 응답하지 않을 경우 자동 대체 응답 구성
</Card>
</CardGroup>
### 주요 이점
- **간단한 멘탈 모델**: 이메일 주소는 보편적이며 플랫폼 사용자나 역할을 관리할 필요 없음
- **외부 응답자**: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능
- **동적 할당**: Flow 상태에서 직접 담당자 이메일 가져오기 (예: `sales_rep_email`)
- **간소화된 구성**: 설정할 항목이 적어 더 빠르게 가치 실현
- **이메일이 주요 채널**: 대부분의 사용자는 대시보드 로그인보다 이메일로 응답하는 것을 선호
## Flow에서 인간 검토 포인트 설정
`@human_feedback` 데코레이터를 사용하여 Flow 내에 인간 검토 체크포인트를 구성합니다. 실행이 검토 포인트에 도달하면 시스템이 일시 중지되고, 담당자에게 이메일로 알리며, 응답을 기다립니다.
```python
from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
class ContentApprovalFlow(Flow):
@start()
def generate_content(self):
return "Q1 캠페인용 마케팅 카피 생성..."
@human_feedback(
message="브랜드 준수를 위해 이 콘텐츠를 검토해 주세요:",
emit=["approved", "rejected", "needs_revision"],
)
@listen(or_("generate_content", "needs_revision"))
def review_content(self):
return "검토용 마케팅 카피..."
@listen("approved")
def publish_content(self, result: HumanFeedbackResult):
print(f"승인된 콘텐츠 게시 중. 검토자 노트: {result.feedback}")
@listen("rejected")
def archive_content(self, result: HumanFeedbackResult):
print(f"콘텐츠 거부됨. 사유: {result.feedback}")
```
완전한 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요.
### 데코레이터 파라미터
| 파라미터 | 유형 | 설명 |
|---------|------|------|
| `message` | `str` | 인간 검토자에게 표시되는 메시지 |
| `emit` | `list[str]` | 유효한 응답 옵션 (UI에서 버튼으로 표시) |
## 플랫폼 구성
HITL 구성에 접근: **배포** → **설정** → **Human in the Loop 구성**
<Frame>
<img src="/images/enterprise/hitl-settings-overview.png" alt="HITL 구성 설정" />
</Frame>
### 이메일 알림
HITL 요청에 대한 이메일 알림을 활성화하거나 비활성화하는 토글입니다.
| 설정 | 기본값 | 설명 |
|-----|-------|------|
| 이메일 알림 | 활성화됨 | 피드백 요청 시 이메일 전송 |
<Note>
비활성화되면 응답자는 대시보드 UI를 사용하거나 커스텀 알림 시스템을 위해 webhook을 구성해야 합니다.
</Note>
### SLA 목표
추적 및 메트릭 목적으로 목표 응답 시간을 설정합니다.
| 설정 | 설명 |
|-----|------|
| SLA 목표 (분) | 목표 응답 시간. 대시보드 메트릭 및 SLA 추적에 사용 |
SLA 추적을 비활성화하려면 비워 두세요.
## 이메일 알림 및 응답
HITL 시스템은 응답자가 알림 이메일에 직접 회신할 수 있는 이메일 우선 아키텍처를 사용합니다.
### 이메일 응답 작동 방식
<Steps>
<Step title="알림 전송">
HITL 요청이 생성되면 검토 콘텐츠와 컨텍스트가 포함된 이메일이 할당된 응답자에게 전송됩니다.
</Step>
<Step title="Reply-To 주소">
이메일에는 인증을 위한 서명된 토큰이 포함된 특별한 reply-to 주소가 있습니다.
</Step>
<Step title="사용자 회신">
응답자는 이메일에 피드백으로 회신하면 됩니다—로그인 필요 없음.
</Step>
<Step title="토큰 검증">
플랫폼이 회신을 받고, 서명된 토큰을 확인하고, 발신자 이메일을 매칭합니다.
</Step>
<Step title="Flow 재개">
피드백이 기록되고 인간의 입력으로 Flow가 계속됩니다.
</Step>
</Steps>
### 응답 형식
응답자는 다음과 같이 회신할 수 있습니다:
- **Emit 옵션**: 회신이 `emit` 옵션과 일치하면 (예: "approved") 직접 사용됨
- **자유 형식 텍스트**: 모든 텍스트 응답이 피드백으로 Flow에 전달됨
- **일반 텍스트**: 회신 본문의 첫 번째 줄이 피드백으로 사용됨
### 확인 이메일
회신을 처리한 후 응답자는 피드백이 성공적으로 제출되었는지 또는 오류가 발생했는지 나타내는 확인 이메일을 받습니다.
### 이메일 토큰 보안
- 토큰은 보안을 위해 암호화 서명됨
- 토큰은 7일 후 만료됨
- 발신자 이메일은 토큰의 인증된 이메일과 일치해야 함
- 처리 후 확인/오류 이메일 전송됨
## 라우팅 규칙
메서드 패턴에 따라 HITL 요청을 특정 이메일 주소로 라우팅합니다.
<Frame>
<img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL 라우팅 규칙 구성" />
</Frame>
### 규칙 구조
```json
{
"name": "재무팀으로 승인",
"match": {
"method_name": "approve_*"
},
"assign_to_email": "finance@company.com",
"assign_from_input": "manager_email"
}
```
### 매칭 패턴
| 패턴 | 설명 | 매칭 예시 |
|-----|------|----------|
| `approve_*` | 와일드카드 (모든 문자) | `approve_payment`, `approve_vendor` |
| `review_?` | 단일 문자 | `review_a`, `review_1` |
| `validate_payment` | 정확히 일치 | `validate_payment`만 |
### 할당 우선순위
1. **동적 할당** (`assign_from_input`): 구성된 경우 Flow 상태에서 이메일 가져옴
2. **정적 이메일** (`assign_to_email`): 구성된 이메일로 대체
3. **배포 생성자**: 규칙이 일치하지 않으면 배포 생성자의 이메일이 사용됨
### 동적 할당 예제
Flow 상태에 `{"sales_rep_email": "alice@company.com"}`이 포함된 경우:
```json
{
"name": "영업 담당자에게 라우팅",
"match": {
"method_name": "review_*"
},
"assign_from_input": "sales_rep_email"
}
```
요청이 자동으로 `alice@company.com`에 할당됩니다.
<Tip>
**사용 사례**: CRM, 데이터베이스 또는 이전 Flow 단계에서 담당자를 가져와 적합한 사람에게 검토를 동적으로 라우팅하세요.
</Tip>
## 자동 응답
시간 내에 인간이 응답하지 않으면 HITL 요청에 자동으로 응답합니다. 이를 통해 Flow가 무한정 중단되지 않도록 합니다.
### 구성
| 설정 | 설명 |
|-----|------|
| 활성화됨 | 자동 응답 활성화 토글 |
| 타임아웃 (분) | 자동 응답 전 대기 시간 |
| 기본 결과 | 응답 값 (`emit` 옵션과 일치해야 함) |
<Frame>
<img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL 자동 응답 구성" />
</Frame>
### 사용 사례
- **SLA 준수**: Flow가 무한정 중단되지 않도록 보장
- **기본 승인**: 타임아웃 후 저위험 요청 자동 승인
- **우아한 저하**: 검토자가 없을 때 안전한 기본값으로 계속
<Warning>
자동 응답을 신중하게 사용하세요. 기본 응답이 허용되는 중요하지 않은 검토에만 활성화하세요.
</Warning>
## 검토 프로세스
### 대시보드 인터페이스
HITL 검토 인터페이스는 검토자에게 깔끔하고 집중된 경험을 제공합니다:
- **마크다운 렌더링**: 구문 강조가 포함된 풍부한 형식의 검토 콘텐츠
- **컨텍스트 패널**: Flow 상태, 실행 기록 및 관련 정보 보기
- **피드백 입력**: 결정과 함께 상세한 피드백 및 코멘트 제공
- **빠른 작업**: 선택적 코멘트가 있는 원클릭 emit 옵션 버튼
<Frame>
<img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL 대기 중인 요청 목록" />
</Frame>
### 응답 방법
검토자는 세 가지 채널을 통해 응답할 수 있습니다:
| 방법 | 설명 |
|-----|------|
| **이메일 회신** | 알림 이메일에 직접 회신 |
| **대시보드** | Enterprise 대시보드 UI 사용 |
| **API/Webhook** | API를 통한 프로그래밍 방식 응답 |
### 기록 및 감사 추적
모든 HITL 상호작용은 완전한 타임라인으로 추적됩니다:
- 결정 기록 (승인/거부/수정)
- 검토자 신원 및 타임스탬프
- 제공된 피드백 및 코멘트
- 응답 방법 (이메일/대시보드/API)
- 응답 시간 메트릭
## 분석 및 모니터링
포괄적인 분석으로 HITL 성능을 추적합니다.
### 성능 대시보드
<Frame>
<img src="/images/enterprise/hitl-metrics.png" alt="HITL 메트릭 대시보드" />
</Frame>
<CardGroup cols={2}>
<Card title="응답 시간" icon="stopwatch">
검토자 또는 Flow별 평균 및 중앙값 응답 시간 모니터링.
</Card>
<Card title="볼륨 트렌드" icon="chart-bar">
팀 용량 최적화를 위한 검토 볼륨 패턴 분석.
</Card>
<Card title="결정 분포" icon="chart-pie">
다양한 검토 유형에 대한 승인/거부 비율 보기.
</Card>
<Card title="SLA 추적" icon="chart-line">
SLA 목표 내에 완료된 검토 비율 추적.
</Card>
</CardGroup>
### 감사 및 규정 준수
규제 요구 사항을 위한 엔터프라이즈급 감사 기능:
- 타임스탬프가 있는 완전한 결정 기록
- 검토자 신원 확인
- 불변 감사 로그
- 규정 준수 보고를 위한 내보내기 기능
## 일반적인 사용 사례
<AccordionGroup>
<Accordion title="보안 검토" icon="shield-halved">
**사용 사례**: 인간 검증이 포함된 내부 보안 설문지 자동화
- AI가 보안 설문지에 대한 응답 생성
- 보안팀이 이메일로 정확성 검토 및 검증
- 승인된 응답이 최종 제출물로 편집
- 규정 준수를 위한 완전한 감사 추적
</Accordion>
<Accordion title="콘텐츠 승인" icon="file-lines">
**사용 사례**: 법무/브랜드 검토가 필요한 마케팅 콘텐츠
- AI가 마케팅 카피 또는 소셜 미디어 콘텐츠 생성
- 브랜드팀 이메일로 목소리/톤 검토를 위해 라우팅
- 승인 시 자동 게시
</Accordion>
<Accordion title="재무 승인" icon="money-bill">
**사용 사례**: 경비 보고서, 계약 조건, 예산 배분
- AI가 재무 요청을 사전 처리하고 분류
- 동적 할당을 사용하여 금액 임계값에 따라 라우팅
- 재무 규정 준수를 위한 완전한 감사 추적 유지
</Accordion>
<Accordion title="CRM에서 동적 할당" icon="database">
**사용 사례**: CRM에서 계정 담당자에게 검토 라우팅
- Flow가 CRM에서 계정 담당자 이메일 가져옴
- 이메일을 Flow 상태에 저장 (예: `account_owner_email`)
- `assign_from_input`을 사용하여 적합한 사람에게 자동 라우팅
</Accordion>
<Accordion title="품질 보증" icon="magnifying-glass">
**사용 사례**: 고객 전달 전 AI 출력 검증
- AI가 고객 대면 콘텐츠 또는 응답 생성
- QA팀이 이메일 알림을 통해 검토
- 피드백 루프가 시간이 지남에 따라 AI 성능 개선
</Accordion>
</AccordionGroup>
## Webhook API
Flow가 인간 피드백을 위해 일시 중지되면, 요청 데이터를 자체 애플리케이션으로 보내도록 webhook을 구성할 수 있습니다. 이를 통해 다음이 가능합니다:
- 커스텀 승인 UI 구축
- 내부 도구와 통합 (Jira, ServiceNow, 커스텀 대시보드)
- 타사 시스템으로 승인 라우팅
- 모바일 앱 알림
- 자동화된 결정 시스템
<Frame>
<img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook 구성" />
</Frame>
### Webhook 구성
<Steps>
<Step title="설정으로 이동">
**배포** → **설정** → **Human in the Loop**으로 이동
</Step>
<Step title="Webhook 섹션 확장">
**Webhooks** 구성을 클릭하여 확장
</Step>
<Step title="Webhook URL 추가">
webhook URL 입력 (프로덕션에서는 HTTPS 필수)
</Step>
<Step title="구성 저장">
**구성 저장**을 클릭하여 활성화
</Step>
</Steps>
여러 webhook을 구성할 수 있습니다. 각 활성 webhook은 모든 HITL 이벤트를 수신합니다.
### Webhook 이벤트
엔드포인트는 다음 이벤트에 대해 HTTP POST 요청을 수신합니다:
| 이벤트 유형 | 트리거 시점 |
|------------|------------|
| `new_request` | Flow가 일시 중지되고 인간 피드백을 요청할 때 |
### Webhook 페이로드
모든 webhook은 다음 구조의 JSON 페이로드를 수신합니다:
```json
{
"event": "new_request",
"request": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"flow_id": "flow_abc123",
"method_name": "review_article",
"message": "이 기사의 게시를 검토해 주세요.",
"emit_options": ["approved", "rejected", "request_changes"],
"state": {
"article_id": 12345,
"author": "john@example.com",
"category": "technology"
},
"metadata": {},
"created_at": "2026-01-14T12:00:00Z"
},
"deployment": {
"id": 456,
"name": "Content Review Flow",
"organization_id": 789
},
"callback_url": "https://api.crewai.com/...",
"assigned_to_email": "reviewer@company.com"
}
```
### 요청에 응답하기
피드백을 제출하려면 webhook 페이로드에 포함된 **`callback_url`로 POST**합니다.
```http
POST {callback_url}
Content-Type: application/json
{
"feedback": "승인됨. 훌륭한 기사입니다!",
"source": "my_custom_app"
}
```
### 보안
<Info>
모든 webhook 요청은 HMAC-SHA256을 사용하여 암호화 서명되어 진위성을 보장하고 변조를 방지합니다.
</Info>
#### Webhook 보안
- **HMAC-SHA256 서명**: 모든 webhook에 암호화 서명이 포함됨
- **Webhook별 시크릿**: 각 webhook은 고유한 서명 시크릿을 가짐
- **저장 시 암호화**: 서명 시크릿은 데이터베이스에서 암호화됨
- **타임스탬프 검증**: 리플레이 공격 방지
#### 서명 헤더
각 webhook 요청에는 다음 헤더가 포함됩니다:
| 헤더 | 설명 |
|------|------|
| `X-Signature` | HMAC-SHA256 서명: `sha256=<hex_digest>` |
| `X-Timestamp` | 요청이 서명된 Unix 타임스탬프 |
#### 검증
다음과 같이 계산하여 검증합니다:
```python
import hmac
import hashlib
expected = hmac.new(
signing_secret.encode(),
f"{timestamp}.{payload}".encode(),
hashlib.sha256
).hexdigest()
if hmac.compare_digest(expected, signature):
# 유효한 서명
```
### 오류 처리
webhook 엔드포인트는 수신 확인을 위해 2xx 상태 코드를 반환해야 합니다:
| 응답 | 동작 |
|------|------|
| 2xx | Webhook 성공적으로 전달됨 |
| 4xx/5xx | 실패로 기록됨, 재시도 없음 |
| 타임아웃 (30초) | 실패로 기록됨, 재시도 없음 |
## 보안 및 RBAC
### 대시보드 접근
HITL 접근은 배포 수준에서 제어됩니다:
| 권한 | 기능 |
|-----|------|
| `manage_human_feedback` | HITL 설정 구성, 모든 요청 보기 |
| `respond_to_human_feedback` | 요청에 응답, 할당된 요청 보기 |
### 이메일 응답 인증
이메일 회신의 경우:
1. reply-to 토큰이 인증된 이메일을 인코딩
2. 발신자 이메일이 토큰의 이메일과 일치해야 함
3. 토큰이 만료되지 않아야 함 (기본 7일)
4. 요청이 여전히 대기 중이어야 함
### 감사 추적
모든 HITL 작업이 기록됩니다:
- 요청 생성
- 할당 변경
- 응답 제출 (소스: 대시보드/이메일/API)
- Flow 재개 상태
## 문제 해결
### 이메일이 전송되지 않음
1. 구성에서 "이메일 알림"이 활성화되어 있는지 확인
2. 라우팅 규칙이 메서드 이름과 일치하는지 확인
3. 담당자 이메일이 유효한지 확인
4. 라우팅 규칙이 일치하지 않는 경우 배포 생성자 대체 확인
### 이메일 회신이 처리되지 않음
1. 토큰이 만료되지 않았는지 확인 (기본 7일)
2. 발신자 이메일이 할당된 이메일과 일치하는지 확인
3. 요청이 여전히 대기 중인지 확인 (아직 응답되지 않음)
### Flow가 재개되지 않음
1. 대시보드에서 요청 상태 확인
2. 콜백 URL에 접근 가능한지 확인
3. 배포가 여전히 실행 중인지 확인
## 모범 사례
<Tip>
**간단하게 시작**: 배포 생성자에게 이메일 알림으로 시작한 다음, 워크플로우가 성숙해지면 라우팅 규칙을 추가하세요.
</Tip>
1. **동적 할당 사용**: 유연한 라우팅을 위해 Flow 상태에서 담당자 이메일을 가져오세요.
2. **자동 응답 구성**: 중요하지 않은 검토에 대해 Flow가 중단되지 않도록 대체를 설정하세요.
3. **응답 시간 모니터링**: 분석을 사용하여 병목 현상을 식별하고 검토 프로세스를 최적화하세요.
4. **검토 메시지를 명확하게 유지**: `@human_feedback` 데코레이터에 명확하고 실행 가능한 메시지를 작성하세요.
5. **이메일 흐름 테스트**: 프로덕션에 가기 전에 테스트 요청을 보내 이메일 전달을 확인하세요.
## 관련 리소스
<CardGroup cols={2}>
<Card title="Flow에서 인간 피드백" icon="code" href="/ko/learn/human-feedback-in-flows">
`@human_feedback` 데코레이터 구현 가이드
</Card>
<Card title="Flow HITL 워크플로우 가이드" icon="route" href="/ko/enterprise/guides/human-in-the-loop">
HITL 워크플로우 설정을 위한 단계별 가이드
</Card>
<Card title="RBAC 구성" icon="shield-check" href="/ko/enterprise/features/rbac">
조직을 위한 역할 기반 접근 제어 구성
</Card>
<Card title="Webhook 스트리밍" icon="bolt" href="/ko/enterprise/features/webhook-streaming">
실시간 이벤트 알림 설정
</Card>
</CardGroup>

251
docs/edge/ko/enterprise/features/hallucination-guardrail.mdx Normal file
View File

@@ -0,0 +1,251 @@
---
title: 환각 방어책
description: "CrewAI 작업에서 AI 환각을 방지하고 감지합니다"
icon: "shield-check"
mode: "wide"
---
## 개요
Hallucination Guardrail은 AI가 생성한 콘텐츠가 사실에 기반하고 환각이 포함되어 있지 않은지 검증하는 엔터프라이즈 기능입니다. 이 기능은 작업 출력물을 참조 컨텍스트와 비교 분석하여, 잠재적으로 환각이 감지되었을 때 상세한 피드백을 제공합니다.
## 환각(Hallucinations)이란 무엇인가요?
AI 환각은 언어 모델이 그럴듯해 보이지만 사실과 다르거나 제공된 맥락에 의해 뒷받침되지 않는 내용을 생성할 때 발생합니다. Hallucination Guardrail은 다음과 같은 방법으로 이러한 문제를 방지합니다:
- 출력물을 참조 맥락과 비교
- 원본 자료에 대한 충실도 평가
- 문제 있는 콘텐츠에 대한 상세 피드백 제공
- 검증 엄격성을 위한 사용자 정의 임계값 지원
## 기본 사용법
### 가드레일 설정하기
```python
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
from crewai import LLM
# Basic usage - will use task's expected_output as context
guardrail = HallucinationGuardrail(
llm=LLM(model="gpt-4o-mini")
)
# With explicit reference context
context_guardrail = HallucinationGuardrail(
context="AI helps with various tasks including analysis and generation.",
llm=LLM(model="gpt-4o-mini")
)
```
### 작업에 추가하기
```python
from crewai import Task
# Create your task with the guardrail
task = Task(
description="Write a summary about AI capabilities",
expected_output="A factual summary based on the provided context",
agent=my_agent,
guardrail=guardrail # Add the guardrail to validate output
)
```
## 고급 구성
### 사용자 지정 임계값 검증
보다 엄격한 검증을 위해 사용자 지정 신뢰성 임계값(0-10 범위)를 설정할 수 있습니다:
```python
# Strict guardrail requiring high faithfulness score
strict_guardrail = HallucinationGuardrail(
context="Quantum computing uses qubits that exist in superposition states.",
llm=LLM(model="gpt-4o-mini"),
threshold=8.0 # Requires score >= 8 to pass validation
)
```
### 도구 응답 컨텍스트 포함하기
작업에서 도구를 사용할 때 더 정확한 검증을 위해 도구 응답을 포함할 수 있습니다:
```python
# Guardrail with tool response context
weather_guardrail = HallucinationGuardrail(
context="Current weather information for the requested location",
llm=LLM(model="gpt-4o-mini"),
tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
)
```
## 작동 원리
### 검증 프로세스
1. **컨텍스트 분석**: 가드레일은 작업 결과를 제공된 참조 컨텍스트와 비교합니다.
2. **정확성 점수 부여**: 내부 평가자를 사용하여 정확성 점수(0-10)를 부여합니다.
3. **판단 결정**: 콘텐츠가 정확한지 또는 환각이 포함되어 있는지 결정합니다.
4. **임계값 확인**: 사용자 지정 임계값이 설정된 경우 해당 점수와 비교하여 검증합니다.
5. **피드백 생성**: 검증에 실패할 때 상세한 사유를 제공합니다.
### 검증 논리
- **기본 모드**: 판정 기반 검증(FAITHFUL vs HALLUCINATED)을 사용함
- **임계값 모드**: 신뢰성 점수가 지정된 임계값에 도달하거나 이를 초과해야 함
- **오류 처리**: 평가 오류를 우아하게 처리하고 유익한 피드백을 제공함
## 가드레일 결과
가드레일은 검증 상태를 나타내는 구조화된 결과를 반환합니다:
```python
# Example of guardrail result structure
{
"valid": False,
"feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
}
```
### 결과 속성
- **valid**: 출력이 검증을 통과했는지 여부를 나타내는 불리언 값
- **feedback**: 검증 실패 시 상세 설명. 다음을 포함:
- 신뢰도 점수
- 판정 분류
- 실패의 구체적인 이유
## 작업 시스템과의 통합
### 자동 검증
가드레일이 태스크에 추가되면, 태스크가 완료로 표시되기 전에 출력값이 자동으로 검증됩니다:
```python
# Task output validation flow
task_output = agent.execute_task(task)
validation_result = guardrail(task_output)
if validation_result.valid:
# Task completes successfully
return task_output
else:
# Task fails with validation feedback
raise ValidationError(validation_result.feedback)
```
### 이벤트 추적
guardrail은 CrewAI의 이벤트 시스템과 통합되어 가시성을 제공합니다:
- **검증 시작됨**: guardrail 평가가 시작될 때
- **검증 완료됨**: 평가가 결과와 함께 종료될 때
- **검증 실패**: 평가 중 기술적 오류가 발생할 때
## 모범 사례
### 컨텍스트 가이드라인
<Steps>
<Step title="포괄적인 컨텍스트 제공">
AI가 출력할 때 기반이 되어야 할 모든 관련 사실 정보를 포함하세요:
```python
context = """
Company XYZ was founded in 2020 and specializes in renewable energy solutions.
They have 150 employees and generated $50M revenue in 2023.
Their main products include solar panels and wind turbines.
"""
```
</Step>
<Step title="관련 있는 컨텍스트만 유지하기">
혼란을 피하기 위해 작업과 직접적으로 관련된 정보만 포함하세요:
```python
# Good: Focused context
context = "The current weather in New York is 18°C with light rain."
# Avoid: Unrelated information
context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
```
</Step>
<Step title="컨텍스트를 정기적으로 업데이트하기">
참고하는 컨텍스트가 최신이고 정확한 정보를 반영하는지 확인하세요.
</Step>
</Steps>
### 임계값 선택
<Steps>
<Step title="기본 검증으로 시작하기">
맞춤 임계값 없이 시작하여 기준 성능을 파악합니다.
</Step>
<Step title="요구사항에 따라 조정하기">
- **중요 콘텐츠**: 최대 정확도를 위해 임계값 8-10 사용
- **일반 콘텐츠**: 균형 잡힌 검증을 위해 임계값 6-7 사용
- **창의적 콘텐츠**: 임계값 4-5 또는 기본 판정 기반 검증 사용
</Step>
<Step title="모니터링 및 반복">
검증 결과를 추적하고, 오탐/미탐을 기반으로 임계값을 조정합니다.
</Step>
</Steps>
## 성능 고려사항
### 실행 시간에 미치는 영향
- **검증 오버헤드**: 각 가드레일마다 작업당 약 1~3초가 추가됩니다
- **LLM 효율성**: 평가에는 효율적인 모델을 선택하세요 (예: gpt-4o-mini)
### 비용 최적화
- **모델 선택**: guardrail 평가에는 더 작고 효율적인 모델을 사용하세요
- **컨텍스트 크기**: 참조 컨텍스트는 간결하면서도 포괄적으로 유지하세요
- **캐싱**: 반복적인 콘텐츠의 검증 결과를 캐싱하는 것을 고려하세요
## 문제 해결
<Accordion title="검증이 항상 실패함">
**가능한 원인:**
- 컨텍스트가 너무 제한적이거나 작업 결과와 관련이 없음
- 임계값이 콘텐츠 유형에 비해 너무 높게 설정됨
- 참조 컨텍스트에 오래된 정보가 포함되어 있음
**해결 방법:**
- 작업 요구사항에 맞게 컨텍스트를 검토하고 업데이트하세요
- 임계값을 낮추거나 기본 판정 기반 검증을 사용하세요
- 컨텍스트가 최신이며 정확한지 확인하세요
</Accordion>
<Accordion title="오탐 (유효한 콘텐츠가 무효로 판정됨)">
**가능한 원인:**
- 창의적이거나 해석적인 작업에 임계값이 너무 높음
- 컨텍스트가 결과의 모든 유효한 측면을 포함하지 않음
- 평가 모델이 과도하게 보수적임
**해결 방법:**
- 임계값을 낮추거나 기본 검증을 사용하세요
- 폭넓은 허용 가능한 콘텐츠를 포함하도록 컨텍스트를 확장하세요
- 다른 평가 모델로 테스트하세요
</Accordion>
<Accordion title="평가 오류">
**가능한 원인:**
- 네트워크 연결 문제
- LLM 모델 사용 불가 또는 속도 제한
- 잘못된 형식의 작업 출력 또는 컨텍스트
**해결 방법:**
- 네트워크 연결 및 LLM 서비스 상태를 확인하세요
- 일시적 오류에 대해 재시도 로직을 구현하세요
- guardrail 평가 전에 작업 출력 형식을 검증하세요
</Accordion>
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
환각 guardrail 구성 또는 문제 해결에 도움이 필요하시면 지원팀에 문의하세요.
</Card>

45
docs/edge/ko/enterprise/features/marketplace.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: "마켓플레이스"
description: "엔터프라이즈 크루를 위한 재사용 가능한 자산을 탐색, 설치 및 관리하세요."
icon: "store"
mode: "wide"
---
## 개요
마켓플레이스는 통합, 내부 도구 및 재사용 가능한 자산을 탐색할 수 있는 큐레이션된 공간을 제공하여 크루 개발을 가속화합니다.
<Frame>
![마켓플레이스 개요](/images/enterprise/marketplace-overview.png)
</Frame>
## 탐색
- 카테고리 및 기능별로 탐색
- 이름 또는 키워드로 검색
## 설치 & 활성화
- 승인된 자산은 원클릭 설치 지원
- 크루별로 활성화/비활성화 가능
- 필요한 환경 변수 및 스코프 구성
<Frame>
![설치 & 구성](/images/enterprise/marketplace-install.png)
</Frame>
마켓플레이스에서 `Download` 버튼을 클릭해 템플릿을 직접 내려받아 로컬에서 사용하거나 필요에 맞게 수정할 수도 있습니다.
## 관련 문서
<CardGroup cols={3}>
<Card title="도구 & 통합" href="/ko/enterprise/features/tools-and-integrations" icon="wrench">
에이전트가 사용할 외부 앱 연결 및 내부 도구 관리.
</Card>
<Card title="도구 저장소" href="/ko/enterprise/guides/tool-repository" icon="toolbox">
크루 기능을 확장할 수 있도록 도구를 게시하고 설치.
</Card>
<Card title="에이전트 저장소" href="/ko/enterprise/features/agent-repositories" icon="people-group">
팀과 프로젝트 전반에서 에이전트 정의 저장, 공유 및 재사용.
</Card>
</CardGroup>

342
docs/edge/ko/enterprise/features/pii-trace-redactions.mdx Normal file
View File

@@ -0,0 +1,342 @@
---
title: 트레이스용 PII 삭제
description: "크루 및 플로우 실행 트레이스에서 민감한 데이터를 자동으로 삭제합니다"
icon: "lock"
mode: "wide"
---
## 개요
PII 삭제는 크루 및 플로우 실행 트레이스에서 개인 식별 정보(PII)를 자동으로 감지하고 마스킹하는 CrewAI AMP 기능입니다. 이를 통해 신용카드 번호, 주민등록번호, 이메일 주소, 이름과 같은 민감한 데이터가 CrewAI AMP 트레이스에 노출되지 않도록 보장합니다. 또한 조직별 데이터를 보호하기 위해 커스텀 인식기를 생성할 수 있습니다.
<Info>
PII 삭제는 Enterprise 플랜에서 사용 가능합니다.
배포 버전은 1.8.0 이상이어야 합니다.
</Info>
<Frame>
![PII 삭제 개요](/images/enterprise/pii_mask_recognizer_trace_example.png)
</Frame>
## PII 삭제가 중요한 이유
프로덕션 환경에서 AI 에이전트를 실행할 때, 민감한 정보가 종종 크루를 통해 흐릅니다:
- CRM 통합의 고객 데이터
- 결제 처리업체의 금융 정보
- 양식 제출의 개인 정보
- 내부 직원 데이터
적절한 삭제 없이는 이 데이터가 트레이스에 나타나, GDPR, HIPAA, PCI-DSS와 같은 규정 준수가 어려워집니다. PII 삭제는 트레이스에 저장되기 전에 민감한 데이터를 자동으로 마스킹하여 이 문제를 해결합니다.
## 작동 방식
1. **감지** - 알려진 PII 패턴에 대해 트레이스 이벤트 데이터를 스캔
2. **분류** - 민감한 데이터 유형 식별 (신용카드, SSN, 이메일 등)
3. **마스킹/삭제** - 구성에 따라 민감한 데이터를 마스킹된 값으로 대체
```
원본: "john.doe@company.com으로 연락하거나 555-123-4567로 전화하세요"
삭제됨: "<EMAIL_ADDRESS>로 연락하거나 <PHONE_NUMBER>로 전화하세요"
```
## PII 삭제 활성화
<Info>
이 기능을 사용하려면 Enterprise 플랜이어야 하며 배포 버전이 1.8.0 이상이어야 합니다.
</Info>
<Steps>
<Step title="크루 설정으로 이동">
CrewAI AMP 대시보드에서 배포된 크루를 선택하고 배포/자동화 중 하나로 이동한 다음 **Settings** → **PII Protection**으로 이동합니다.
</Step>
<Step title="PII 보호 활성화">
**PII Redaction for Traces**를 토글하여 활성화합니다. 이렇게 하면 트레이스 데이터의 자동 스캔 및 삭제가 활성화됩니다.
<Info>
각 배포에 대해 PII 삭제를 수동으로 활성화해야 합니다.
</Info>
<Frame>
![PII 삭제 활성화](/images/enterprise/pii_mask_recognizer_enable.png)
</Frame>
</Step>
<Step title="엔티티 유형 구성">
감지하고 삭제할 PII 유형을 선택합니다. 각 엔티티는 개별적으로 활성화하거나 비활성화할 수 있습니다.
<Frame>
![엔티티 구성](/images/enterprise/pii_mask_recognizer_supported_entities.png)
</Frame>
</Step>
<Step title="저장">
구성을 저장합니다. PII 삭제는 이후 모든 크루 실행에서 활성화되며, 재배포가 필요하지 않습니다.
</Step>
</Steps>
## 지원되는 엔티티 유형
CrewAI는 카테고리별로 구성된 다음 PII 엔티티 유형을 지원합니다.
### 글로벌 엔티티
| 엔티티 | 설명 | 예시 |
|--------|------|------|
| `CREDIT_CARD` | 신용/직불 카드 번호 | "4111-1111-1111-1111" |
| `CRYPTO` | 암호화폐 지갑 주소 | "bc1qxy2kgd..." |
| `DATE_TIME` | 날짜 및 시간 | "2024년 1월 15일" |
| `EMAIL_ADDRESS` | 이메일 주소 | "john@example.com" |
| `IBAN_CODE` | 국제 은행 계좌 번호 | "DE89 3704 0044 0532 0130 00" |
| `IP_ADDRESS` | IPv4 및 IPv6 주소 | "192.168.1.1" |
| `LOCATION` | 지리적 위치 | "뉴욕시" |
| `MEDICAL_LICENSE` | 의료 면허 번호 | "MD12345" |
| `NRP` | 국적, 종교 또는 정치 그룹 | - |
| `PERSON` | 개인 이름 | "홍길동" |
| `PHONE_NUMBER` | 다양한 형식의 전화번호 | "+82 (10) 1234-5678" |
| `URL` | 웹 URL | "https://example.com" |
### 미국 특정 엔티티
| 엔티티 | 설명 | 예시 |
|--------|------|------|
| `US_BANK_NUMBER` | 미국 은행 계좌 번호 | "1234567890" |
| `US_DRIVER_LICENSE` | 미국 운전면허 번호 | "D1234567" |
| `US_ITIN` | 개인 납세자 번호 | "900-70-0000" |
| `US_PASSPORT` | 미국 여권 번호 | "123456789" |
| `US_SSN` | 사회보장번호 | "123-45-6789" |
## 삭제 작업
활성화된 각 엔티티에 대해 데이터가 삭제되는 방식을 구성할 수 있습니다:
| 작업 | 설명 | 출력 예시 |
|------|------|----------|
| `mask` | 엔티티 유형 레이블로 대체 | `<CREDIT_CARD>` |
| `redact` | 텍스트를 완전히 제거 | *(비어있음)* |
## 커스텀 인식기
기본 제공 엔티티 외에도 조직별 PII 패턴을 감지하기 위한 **커스텀 인식기**를 생성할 수 있습니다.
<Frame>
![커스텀 인식기](/images/enterprise/pii_mask_recognizer.png)
</Frame>
### 인식기 유형
커스텀 인식기에는 두 가지 옵션이 있습니다:
| 유형 | 적합한 용도 | 사용 사례 예시 |
|------|------------|---------------|
| **패턴 기반 (Regex)** | 예측 가능한 형식의 구조화된 데이터 | 급여 금액, 직원 ID, 프로젝트 코드 |
| **거부 목록** | 정확한 문자열 매칭 | 회사명, 내부 코드명, 특정 용어 |
### 커스텀 인식기 생성
<Steps>
<Step title="커스텀 인식기로 이동">
조직 **Settings** → **Organization** → **Add Recognizer**로 이동합니다.
</Step>
<Step title="인식기 구성">
<Frame>
![인식기 구성](/images/enterprise/pii_mask_recognizer_create.png)
</Frame>
다음 필드를 구성합니다:
- **Name**: 인식기의 설명적 이름
- **Entity Type**: 삭제된 출력에 나타날 엔티티 레이블 (예: `EMPLOYEE_ID`, `SALARY`)
- **Type**: Regex 패턴 또는 거부 목록 중 선택
- **Pattern/Values**: 매칭할 Regex 패턴 또는 문자열 목록
- **Confidence Threshold**: 삭제를 트리거하는 데 필요한 최소 점수 (0.0-1.0). 높은 값 (예: 0.8)은 거짓 양성을 줄이지만 일부 매치를 놓칠 수 있습니다. 낮은 값 (예: 0.5)은 더 많은 매치를 잡지만 과도하게 삭제할 수 있습니다. 기본값은 0.8입니다.
- **Context Words** (선택사항): 근처에서 발견될 때 감지 신뢰도를 높이는 단어
</Step>
<Step title="저장">
인식기를 저장합니다. 배포에서 활성화할 수 있게 됩니다.
</Step>
</Steps>
### 엔티티 유형 이해하기
**Entity Type**은 매칭된 콘텐츠가 삭제된 트레이스에 어떻게 나타나는지 결정합니다:
```
Entity Type: SALARY
Pattern: salary:\s*\$\s*\d+
입력: "직원 급여: $50,000"
출력: "직원 <SALARY>"
```
### 컨텍스트 단어 사용
컨텍스트 단어는 매칭된 패턴 근처에 특정 용어가 나타날 때 신뢰도를 높여 정확도를 향상시킵니다:
```
Context Words: "project", "code", "internal"
Entity Type: PROJECT_CODE
Pattern: PRJ-\d{4}
```
"project" 또는 "code"가 "PRJ-1234" 근처에 나타나면, 인식기는 그것이 진정한 매치라는 확신이 높아져 거짓 양성을 줄입니다.
## 삭제된 트레이스 보기
PII 삭제가 활성화되면, 트레이스에서 민감한 데이터 대신 삭제된 값이 표시됩니다:
```
Task Output: "고객 <PERSON>이 주문 #12345를 했습니다.
연락처 이메일: <EMAIL_ADDRESS>, 전화: <PHONE_NUMBER>.
<CREDIT_CARD>로 끝나는 카드로 결제가 처리되었습니다."
```
삭제된 값은 꺾쇠 괄호와 엔티티 유형 레이블 (예: `<EMAIL_ADDRESS>`)로 명확하게 표시되어, 어떤 데이터가 보호되었는지 쉽게 이해할 수 있으면서도 크루 동작을 디버그하고 모니터링할 수 있습니다.
## 모범 사례
### 성능 고려사항
<Steps>
<Step title="필요한 엔티티만 활성화">
활성화된 각 엔티티는 처리 오버헤드를 추가합니다. 데이터와 관련된 엔티티만 활성화하세요.
</Step>
<Step title="구체적인 패턴 사용">
커스텀 인식기의 경우 거짓 양성을 줄이고 성능을 향상시키기 위해 구체적인 패턴을 사용하세요. Regex 패턴은 급여, 직원 ID, 프로젝트 코드 등 특정 패턴을 식별할 때 가장 적합합니다. 거부 목록 인식기는 회사명, 내부 코드명 등 정확한 문자열을 식별할 때 가장 적합합니다.
</Step>
<Step title="컨텍스트 단어 활용">
컨텍스트 단어는 주변 텍스트가 매칭될 때만 감지를 트리거하여 정확도를 향상시킵니다.
</Step>
</Steps>
## 문제 해결
<Accordion title="PII가 삭제되지 않음">
**가능한 원인:**
- 구성에서 엔티티 유형이 활성화되지 않음
- 패턴이 데이터 형식과 매치되지 않음
- 커스텀 인식기에 구문 오류가 있음
**해결책:**
- Settings → Security에서 엔티티가 활성화되어 있는지 확인
- 샘플 데이터로 regex 패턴 테스트
- 구성 오류에 대한 로그 확인
</Accordion>
<Accordion title="너무 많은 데이터가 삭제됨">
**가능한 원인:**
- 너무 광범위한 엔티티 유형이 활성화됨 (예: `DATE_TIME`이 모든 곳의 날짜를 잡음)
- 커스텀 인식기 패턴이 너무 일반적임
**해결책:**
- 거짓 양성을 유발하는 엔티티 비활성화
- 커스텀 패턴을 더 구체적으로 만들기
- 정확도 향상을 위해 컨텍스트 단어 추가
</Accordion>
<Accordion title="성능 문제">
**가능한 원인:**
- 너무 많은 엔티티가 활성화됨
- NLP 기반 엔티티 (`PERSON`, `LOCATION`, `NRP`)는 머신러닝 모델을 사용하므로 계산 비용이 높음
**해결책:**
- 실제로 필요한 엔티티만 활성화
- 가능한 경우 패턴 기반 대안 고려
- 대시보드에서 트레이스 처리 시간 모니터링
</Accordion>
---
## 실제 예시: 급여 패턴 매칭
이 예시는 트레이스에서 급여 정보를 감지하고 마스킹하는 커스텀 인식기를 생성하는 방법을 보여줍니다.
### 사용 사례
크루가 다음과 같은 형식의 급여 정보가 포함된 직원 또는 재무 데이터를 처리합니다:
- `salary: $50,000`
- `salary: $125,000.00`
- `salary:$1,500.50`
민감한 보상 데이터를 보호하기 위해 이러한 값을 자동으로 마스킹하려고 합니다.
### 구성
<Frame>
![급여 인식기 구성](/images/enterprise/pii_mask_custom_recognizer_salary.png)
</Frame>
| 필드 | 값 |
|------|-----|
| **Name** | `SALARY` |
| **Entity Type** | `SALARY` |
| **Type** | Regex Pattern |
| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
| **Action** | Mask |
| **Confidence Threshold** | `0.8` |
| **Context Words** | `salary, compensation, pay, wage, income` |
### Regex 패턴 분석
| 패턴 구성요소 | 의미 |
|--------------|------|
| `salary:` | 리터럴 텍스트 "salary:" 매치 |
| `\s*` | 0개 이상의 공백 문자 매치 |
| `\$` | 달러 기호 매치 (이스케이프) |
| `\s*` | $ 뒤의 0개 이상의 공백 문자 매치 |
| `\d{1,3}` | 1-3자리 숫자 매치 (예: "1", "50", "125") |
| `(,\d{3})*` | 쉼표로 구분된 천 단위 매치 (예: ",000", ",500,000") |
| `(\.\d{2})?` | 선택적으로 센트 매치 (예: ".00", ".50") |
### 결과 예시
```
원본: "직원 기록에 salary: $125,000.00 연봉이 표시됩니다"
삭제됨: "직원 기록에 <SALARY> 연봉이 표시됩니다"
원본: "기본 salary:$50,000에 보너스 가능성"
삭제됨: "기본 <SALARY>에 보너스 가능성"
```
<Tip>
"salary", "compensation", "pay", "wage", "income"과 같은 컨텍스트 단어를 추가하면 이러한 용어가 매칭된 패턴 근처에 나타날 때 감지 신뢰도가 높아져 거짓 양성을 줄입니다.
</Tip>
### 배포에서 인식기 활성화
<Warning>
조직 수준에서 커스텀 인식기를 생성해도 배포에 자동으로 활성화되지 않습니다. 적용하려는 모든 배포에 대해 각 인식기를 수동으로 활성화해야 합니다.
</Warning>
커스텀 인식기를 생성한 후, 각 배포에서 활성화합니다:
<Steps>
<Step title="배포로 이동">
배포/자동화로 이동하여 **Settings** → **PII Protection**을 엽니다.
</Step>
<Step title="커스텀 인식기 선택">
**Mask Recognizers** 아래에서 조직에서 정의한 인식기를 볼 수 있습니다. 활성화하려는 인식기 옆의 체크박스를 선택합니다.
<Frame>
![커스텀 인식기 활성화](/images/enterprise/pii_mask_recognizers_options.png)
</Frame>
</Step>
<Step title="구성 저장">
변경 사항을 저장합니다. 인식기는 이 배포의 모든 후속 실행에서 활성화됩니다.
</Step>
</Steps>
<Info>
커스텀 인식기가 필요한 각 배포에서 이 프로세스를 반복합니다. 이를 통해 다양한 환경 (예: 개발 vs. 프로덕션)에서 어떤 인식기가 활성화되는지 세밀하게 제어할 수 있습니다.
</Info>

260
docs/edge/ko/enterprise/features/rbac.mdx Normal file
View File

@@ -0,0 +1,260 @@
---
title: "역할 기반 접근 제어 (RBAC)"
description: "역할, 범위, 세분화된 권한으로 crews, 도구, 데이터 접근을 제어합니다."
icon: "shield"
mode: "wide"
---
## 개요
CrewAI AMP의 RBAC는 두 가지 계층을 통해 안전하고 확장 가능한 접근 관리를 제공합니다:
1. **기능 권한** — 플랫폼 전반에서 각 역할이 수행할 수 있는 작업을 제어합니다 (관리, 읽기 또는 접근 불가)
2. **엔티티 수준 권한** — 개별 자동화, 환경 변수, LLM 연결, Git 저장소에 대한 세분화된 접근 제어
<Frame>
<img src="/images/enterprise/users_and_roles.png" alt="CrewAI AMP RBAC 개요" />
</Frame>
## 사용자와 역할
CrewAI 워크스페이스의 각 구성원에게는 역할이 할당되며, 이를 통해 다양한 기능에 대한 접근 범위가 결정됩니다.
가능한 작업:
- 사전 정의된 역할 사용 (Owner, Member)
- 특정 권한에 맞춘 커스텀 역할 생성
- 설정 패널에서 언제든지 역할 할당
설정 위치: Settings → Roles
<Steps>
<Step title="Roles 설정 열기">
CrewAI AMP에서 <b>Settings → Roles</b>로 이동합니다.
</Step>
<Step title="역할 유형 선택">
사전 정의된 역할(<b>Owner</b>, <b>Member</b>)을 사용하거나{" "}
<b>Create role</b>을 클릭하여 커스텀 역할을 만듭니다.
</Step>
<Step title="멤버에 할당">
사용자를 선택하고 역할을 할당합니다. 언제든지 변경할 수 있습니다.
</Step>
</Steps>
### 사전 정의된 역할
| 역할 | 설명 |
| :--------- | :------------------------------------------------------------------- |
| **Owner** | 모든 기능 및 설정에 대한 전체 접근 권한. 제한할 수 없습니다. |
| **Member** | 대부분의 기능에 대한 읽기 접근, 환경 변수, LLM 연결, Studio 프로젝트에 대한 관리 접근. 조직 설정이나 기본 설정은 수정할 수 없습니다. |
### 구성 요약
| 영역 | 설정 위치 | 옵션 |
| :------------ | :--------------------------------- | :-------------------------------- |
| 사용자 & 역할 | Settings → Roles | 사전 정의: Owner, Member; 커스텀 역할 |
| 자동화 가시성 | Automation → Settings → Visibility | Private; 사용자/역할 화이트리스트 |
---
## 기능 권한 매트릭스
각 역할에는 기능 영역별 권한 수준이 있습니다. 세 가지 수준은 다음과 같습니다:
- **Manage** — 전체 읽기/쓰기 접근 (생성, 편집, 삭제)
- **Read** — 읽기 전용 접근
- **No access** — 기능이 숨겨지거나 접근 불가
| 기능 | Owner | Member (기본값) | 사용 가능한 수준 | 설명 |
| :-------------------------- | :------ | :--------------- | :------------------------- | :------------------------------------------------------------- |
| `usage_dashboards` | Manage | Read | Manage / Read / No access | 사용 메트릭 및 분석 보기 |
| `crews_dashboards` | Manage | Read | Manage / Read / No access | 배포 대시보드 보기, 자동화 세부 정보 접근 |
| `invitations` | Manage | Read | Manage / Read / No access | 조직에 새 멤버 초대 |
| `training_ui` | Manage | Read | Manage / Read / No access | 훈련/파인튜닝 인터페이스 접근 |
| `tools` | Manage | Read | Manage / Read / No access | 도구 생성 및 관리 |
| `agents` | Manage | Read | Manage / Read / No access | 에이전트 생성 및 관리 |
| `environment_variables` | Manage | Manage | Manage / No access | 환경 변수 생성 및 관리 |
| `llm_connections` | Manage | Manage | Manage / No access | LLM 제공자 연결 구성 |
| `default_settings` | Manage | No access | Manage / No access | 조직 전체 기본 설정 수정 |
| `organization_settings` | Manage | No access | Manage / No access | 결제, 플랜 및 조직 구성 관리 |
| `studio_projects` | Manage | Manage | Manage / No access | Studio에서 프로젝트 생성 및 편집 |
<Tip>
커스텀 역할을 만들 때 대부분의 기능은 **Manage**, **Read** 또는 **No access**로 설정할 수 있습니다. 그러나 `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, `studio_projects`는 **Manage** 또는 **No access**만 지원합니다 — 이 기능들에는 읽기 전용 옵션이 없습니다.
</Tip>
---
## GitHub 또는 Zip에서 배포
가장 흔한 RBAC 질문 중 하나: _"팀원이 배포하려면 어떤 권한이 필요한가요?"_
### GitHub에서 배포
GitHub 저장소에서 자동화를 배포하려면 사용자에게 다음이 필요합니다:
1. **`crews_dashboards`**: 최소 `Read` — 배포가 생성되는 자동화 대시보드에 접근하는 데 필요
2. **Git 저장소 접근** (Git 저장소에 대한 엔티티 수준 RBAC가 활성화된 경우): 사용자의 역할에 엔티티 수준 권한을 통해 특정 Git 저장소에 대한 접근이 부여되어야 함
3. **`studio_projects`: `Manage`** — 배포 전에 Studio에서 crew를 빌드하는 경우
### Zip에서 배포
Zip 파일 업로드로 자동화를 배포하려면 사용자에게 다음이 필요합니다:
1. **`crews_dashboards`**: 최소 `Read` — 자동화 대시보드에 접근하는 데 필요
2. **Zip 배포 활성화**: 조직이 조직 설정에서 Zip 배포를 비활성화하지 않아야 함
### 빠른 참조: 배포에 필요한 최소 권한
| 작업 | 필요한 기능 권한 | 추가 요구사항 |
| :------------------- | :----------------------------------- | :----------------------------------------------- |
| GitHub에서 배포 | `crews_dashboards: Read` | Git 저장소 엔티티 접근 (Git RBAC 활성화 시) |
| Zip에서 배포 | `crews_dashboards: Read` | 조직 수준에서 Zip 배포가 활성화되어야 함 |
| Studio에서 빌드 | `studio_projects: Manage` | — |
| LLM 키 구성 | `llm_connections: Manage` | — |
| 환경 변수 설정 | `environment_variables: Manage` | 엔티티 수준 접근 (엔티티 RBAC 활성화 시) |
---
## 자동화 수준 접근 제어 (엔티티 권한)
조직 전체 역할 외에도, CrewAI는 개별 리소스에 대한 접근을 제한하는 세분화된 엔티티 수준 권한을 지원합니다.
### 자동화 가시성
자동화는 사용자 또는 역할별로 접근을 제한하는 가시성 설정을 지원합니다. 다음과 같은 경우에 유용합니다:
- 민감하거나 실험적인 자동화를 비공개로 유지
- 대규모 팀이나 외부 협업자의 가시성 관리
- 격리된 컨텍스트에서 자동화 테스트
배포를 비공개로 구성할 수 있으며, 이 경우 화이트리스트에 포함된 사용자와 역할만 상호작용할 수 있습니다.
설정 위치: Automation → Settings → Visibility 탭
<Steps>
<Step title="Visibility 탭 열기">
<b>Automation → Settings → Visibility</b>로 이동합니다.
</Step>
<Step title="가시성 설정">
접근을 제한하려면 <b>Private</b>를 선택합니다. 조직 Owner는 항상
접근 권한을 유지합니다.
</Step>
<Step title="접근 허용 대상 추가">
보기, 실행, 로그/메트릭/설정 접근이 허용된 특정 사용자와 역할을
추가합니다.
</Step>
<Step title="저장 및 확인">
변경 사항을 저장한 후, 화이트리스트에 없는 사용자가 자동화를 보거나 실행할 수
없는지 확인합니다.
</Step>
</Steps>
### Private 가시성: 접근 결과
| 동작 | Owner | 화이트리스트 사용자/역할 | 비포함 |
| :--------------------- | :---- | :----------------------- | :----- |
| 자동화 보기 | ✓ | ✓ | ✗ |
| 자동화/API 실행 | ✓ | ✓ | ✗ |
| 로그/메트릭/설정 접근 | ✓ | ✓ | ✗ |
<Tip>
조직 Owner는 항상 접근 권한이 있습니다. Private 모드에서는 화이트리스트에 포함된
사용자/역할만 보기, 실행, 로그/메트릭/설정에 접근할 수 있습니다.
</Tip>
<Frame>
<img src="/images/enterprise/visibility.png" alt="CrewAI AMP 자동화 가시성 설정" />
</Frame>
### 배포 권한 유형
특정 자동화에 엔티티 수준 접근을 부여할 때 다음 권한 유형을 할당할 수 있습니다:
| 권한 | 허용 범위 |
| :------------------- | :-------------------------------------------------- |
| `run` | 자동화 실행 및 API 사용 |
| `traces` | 실행 트레이스 및 로그 보기 |
| `manage_settings` | 자동화 편집, 재배포, 롤백 또는 삭제 |
| `human_in_the_loop` | HITL(human-in-the-loop) 요청에 응답 |
| `full_access` | 위의 모든 권한 |
### 기타 리소스에 대한 엔티티 수준 RBAC
엔티티 수준 RBAC가 활성화되면 다음 리소스에 대한 접근도 사용자 또는 역할별로 제어할 수 있습니다:
| 리소스 | 제어 방식 | 설명 |
| :----------------- | :---------------------------------- | :------------------------------------------------------------ |
| 환경 변수 | 엔티티 RBAC 기능 플래그 | 특정 환경 변수를 보거나 관리할 수 있는 역할/사용자 제한 |
| LLM 연결 | 엔티티 RBAC 기능 플래그 | 특정 LLM 제공자 구성에 대한 접근 제한 |
| Git 저장소 | Git 저장소 RBAC 조직 설정 | 특정 연결된 저장소에 접근할 수 있는 역할/사용자 제한 |
---
## 일반적인 역할 패턴
CrewAI는 Owner와 Member 역할을 기본 제공하지만, 대부분의 팀은 커스텀 역할을 만들어 활용합니다. 일반적인 패턴은 다음과 같습니다:
### Developer 역할
자동화를 빌드하고 배포하지만 조직 설정을 관리하지 않는 팀원을 위한 역할입니다.
| 기능 | 권한 |
| :-------------------------- | :---------- |
| `usage_dashboards` | Read |
| `crews_dashboards` | Manage |
| `invitations` | Read |
| `training_ui` | Read |
| `tools` | Manage |
| `agents` | Manage |
| `environment_variables` | Manage |
| `llm_connections` | Manage |
| `default_settings` | No access |
| `organization_settings` | No access |
| `studio_projects` | Manage |
### Viewer / Stakeholder 역할
자동화를 모니터링하고 결과를 확인해야 하는 비기술 이해관계자를 위한 역할입니다.
| 기능 | 권한 |
| :-------------------------- | :---------- |
| `usage_dashboards` | Read |
| `crews_dashboards` | Read |
| `invitations` | No access |
| `training_ui` | Read |
| `tools` | Read |
| `agents` | Read |
| `environment_variables` | No access |
| `llm_connections` | No access |
| `default_settings` | No access |
| `organization_settings` | No access |
| `studio_projects` | No access |
### Ops / Platform Admin 역할
인프라 설정을 관리하지만 에이전트를 빌드하지 않을 수 있는 플랫폼 운영자를 위한 역할입니다.
| 기능 | 권한 |
| :-------------------------- | :---------- |
| `usage_dashboards` | Manage |
| `crews_dashboards` | Manage |
| `invitations` | Manage |
| `training_ui` | Read |
| `tools` | Read |
| `agents` | Read |
| `environment_variables` | Manage |
| `llm_connections` | Manage |
| `default_settings` | Manage |
| `organization_settings` | Read |
| `studio_projects` | No access |
---
<Card
title="도움이 필요하신가요?"
icon="headset"
href="mailto:support@crewai.com"
>
RBAC 관련 질문은 지원팀에 문의해 주세요.
</Card>

321
docs/edge/ko/enterprise/features/secrets-manager/aws-workload-identity.mdx Normal file
View File

@@ -0,0 +1,321 @@
---
title: AWS Workload Identity (OIDC Federation)
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity를 통해 AWS Secrets Manager를 구성합니다
sidebarTitle: Workload Identity 사용
icon: "id-badge"
---
## 개요
이 가이드는 **Workload Identity Federation**을 사용하여 AWS Secrets Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, STS를 통해 이를 AWS 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 AWS 액세스 키를 어디에도 저장하지 않습니다.
<Note>
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하고 로테이션 전파에 신경 쓰지 않는다면, 더 간단한 [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) 가이드를 참조하세요.
</Note>
### 런타임 동작 방식
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
2. 워커가 JWT를 제시하여 아래에서 설정한 IAM 역할에 대해 `sts:AssumeRoleWithWebIdentity`를 호출합니다.
3. AWS STS가 CrewAI Platform의 공개 OIDC 발급자에 대해 JWT를 검증한 다음(따라서 플랫폼 설치가 AWS에서 접근 가능해야 함), 단기 AWS 자격 증명을 반환합니다.
4. 워커가 해당 자격 증명을 사용하여 `secretsmanager:GetSecretValue`를 호출합니다.
5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
- IAM OIDC 공급자, IAM 역할, IAM 정책을 생성할 권한이 있는 AWS 계정.
- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`).
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
- **CrewAI 조직 UUID.** CrewAI Platform의 조직 설정 페이지에서 찾을 수 있습니다 — 3단계의 신뢰 정책이 IAM 역할을 이 특정 조직에 바인딩합니다.
- **CrewAI Platform 설치가 AWS에서 HTTPS를 통해 접근 가능해야 합니다.** AWS STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지(또는 AWS가 VPC 피어링/동등한 방법을 통해 네트워크에 도달할 수 있는지) 확인하세요.
</Note>
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 해당 문서의 `issuer` 필드는 AWS가 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다.
브라우저에서 URL을 엽니다(`<your-platform-host>`를 실제 호스트 이름으로 교체, 예: `app.crewai.com`):
```
https://<your-platform-host>/.well-known/openid-configuration
```
다음을 포함하는 JSON이 보일 것입니다:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
<Tip>
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
</Tip>
## 2단계 — CrewAI Platform을 IAM OIDC ID 공급자로 등록
[IAM → Identity providers 콘솔](https://console.aws.amazon.com/iam/home#/identity_providers)을 열고 **Add provider**를 클릭합니다.
- **Provider type:** OpenID Connect.
- **Provider URL:** 1단계의 `issuer` 값(예: `https://app.crewai.com`).
- **Audience:** `sts.amazonaws.com`
**Add provider**를 클릭합니다.
또는 CLI를 통해:
```bash
aws iam create-open-id-connect-provider \
--url "https://<your-platform-host>" \
--client-id-list "sts.amazonaws.com" \
--thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
```
출력에서 **OpenIDConnectProviderArn**(또는 콘솔에서 공급자의 ARN)을 복사합니다. 3단계에서 사용합니다.
<Note>
AWS는 실제로 STS WebIdentity 호출의 thumbprint를 검증하지 않습니다 — 검증 시점에 항상 JWKS를 다시 가져옵니다 — 그러나 API에서 해당 필드가 존재해야 합니다.
</Note>
{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */}
{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */}
## 3단계 — IAM 역할 생성
`trust-policy.json`으로 저장하고, `<YOUR_ACCOUNT_ID>`, `<your-platform-host>`(발급자 호스트로 `https://` 또는 `http://` **없음**, 예: `app.crewai.com`), `<YOUR_CREWAI_ORG_UUID>`(사전 준비 사항에서)를 교체합니다:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"<your-platform-host>:aud": "sts.amazonaws.com",
"<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
}
}
}
]
}
```
역할을 생성합니다:
```bash
aws iam create-role \
--role-name crewai-secrets-reader \
--assume-role-policy-document file://trust-policy.json
```
출력에서 **Role Arn**을 복사합니다 — 이것이 `aws_role_arn`입니다. 6단계에서 CrewAI Platform에 붙여 넣습니다.
<Tip>
두 조건은 신뢰를 정확하게 범위 지정합니다: `aud`는 AWS STS audience를 가진 토큰으로만 가정을 제한하고, `sub`는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다. CrewAI Platform은 항상 AWS workload identity 토큰에 두 클레임을 모두 설정합니다.
</Tip>
{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */}
## 4단계 — Secrets Manager + KMS 액세스용 IAM 정책 생성 및 연결
`secrets-policy.json`으로 저장하고 자리 표시자를 계정 ID, 리전, 시크릿 이름 접두사, 그리고 해당 시크릿을 암호화하는 KMS 키 ARN으로 교체합니다:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerListForUI",
"Effect": "Allow",
"Action": "secretsmanager:ListSecrets",
"Resource": "*"
},
{
"Sid": "SecretsManagerRead",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
},
{
"Sid": "KMSDecrypt",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
}
]
}
```
`SecretsManagerListForUI`는 환경 변수 폼의 **Secret Name 자동 완성**과 자격 증명의 **Test Connection** 버튼을 지원합니다. `secretsmanager:ListSecrets`는 `Resource: "*"`만 허용합니다 — IAM 계층에서 계정 범위로 제한됩니다.
CLI(인라인 정책, 가장 간단함) 또는 콘솔 UI를 사용하여 역할에 정책을 연결합니다. 많은 역할에서 동일한 권한을 재사용하는 환경의 경우 재사용 가능한 명명된 정책을 위해 **Managed policy** 탭을 사용하세요.
<Tabs>
<Tab title="인라인 정책 (CLI)">
```bash
aws iam put-role-policy \
--role-name crewai-secrets-reader \
--policy-name SecretsManagerRead \
--policy-document file://secrets-policy.json
```
이는 정책을 **인라인**으로 역할에 연결합니다. 인라인 정책은 역할에 연결되어 있으며 다른 역할에서 재사용할 수 없습니다.
</Tab>
<Tab title="관리형 정책 (CLI, 재사용 가능)">
```bash
POLICY_ARN=$(aws iam create-policy \
--policy-name CrewAISecretsReader \
--policy-document file://secrets-policy.json \
--query 'Policy.Arn' --output text)
aws iam attach-role-policy \
--role-name crewai-secrets-reader \
--policy-arn "$POLICY_ARN"
```
관리형 정책은 여러 역할에 연결할 수 있는 독립형 IAM 리소스입니다.
</Tab>
<Tab title="콘솔 (UI)">
1. [IAM → Roles 콘솔](https://console.aws.amazon.com/iam/home#/roles)을 열고 **crewai-secrets-reader**를 선택합니다.
2. **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다.
3. **JSON** 편집기로 전환하고 `secrets-policy.json`의 내용을 붙여 넣습니다.
4. **Next**를 클릭하고 정책 이름(예: `SecretsManagerRead`)을 지정한 다음 **Create policy**를 클릭합니다.
대신 재사용 가능한 관리형 정책을 만들려면 **IAM → Policies → Create policy**를 사용한 다음, 역할의 **Permissions** 탭에서 역할에 연결합니다.
{/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */}
</Tab>
</Tabs>
## 5단계 — AWS에 최소 하나의 시크릿 생성
테스트할 시크릿이 아직 없다면 지금 하나 만드세요:
```bash
aws secretsmanager create-secret \
--region <REGION> \
--name crewai-test-keyword \
--secret-string "hello from aws"
```
또는 [AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**을 통해 만듭니다.
{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */}
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */}
{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */}
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `aws-prod`).
- **Cloud Provider:** `AWS`.
- **AWS Role ARN:** 3단계의 **Role Arn**.
- **AWS Region:** 시크릿이 위치한 리전(예: `us-east-1`).
- (선택) AWS 기반 시크릿 자격 증명을 생성할 때 이 WI 구성을 기본으로 선택하려면 **Set as default for AWS**를 체크합니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */}
{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */}
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `aws-prod-wi`).
- **Provider:** `AWS Secrets Manager`.
- **Authentication Method:** `Workload Identity`(정적 키 / AssumeRole 대신).
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다(예: `aws-prod`).
- (선택) **Set as default credential for this provider**를 체크합니다.
Workload Identity 아래에서는 폼이 **AWS Region**만 요청합니다 — 정적 자격 증명 필드(Access Key ID, Secret Access Key, Role ARN, External ID)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. 역할 ARN은 연결된 WI 구성에서 가져옵니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */}
## 8단계 — 연결 테스트
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, `sts:AssumeRoleWithWebIdentity`를 통해 AWS STS와 교환한 다음, 결과로 받은 자격 증명이 가정된 역할에 대해 `sts:GetCallerIdentity`를 호출할 수 있는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
성공적인 Test Connection은 신뢰 정책, OIDC 공급자 등록, audience 조건이 모두 올바르게 연결되었음을 증명합니다. 시크릿별 IAM이 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿 ARN에 대한 `secretsmanager:GetSecretValue`는 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
## 9단계 — 환경 변수에서 시크릿 참조
이제 다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
WI 기반과 정적 키 기반 환경 변수의 유일한 차이는 시크릿이 **언제** 읽히는지입니다:
- **WI 기반:** 모든 자동화 kickoff에서 시크릿 값을 새로 읽습니다.
- **정적 키 기반:** 배포 시점에 시크릿 값을 읽고 배포 이미지에 박힙니다.
## 10단계 — 로테이션 확인
배포가 실행 중인 상태에서 AWS의 시크릿을 로테이션합니다:
```bash
aws secretsmanager update-secret \
--region <REGION> \
--secret-id crewai-test-keyword \
--secret-string "rotated value"
```
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
로그에서 확인하려면(워커에 액세스할 수 있는 경우) 다음을 찾으세요:
```
Workload identity config '<id>' (aws): N secret(s) resolved
```
이 줄은 모든 kickoff에 나타나며 AWS에 대한 새로운 `GetSecretValue` 호출을 의미합니다.
## 문제 해결
| 증상 | 가능한 원인 |
|---|---|
| Test Connection이 핸드셰이크 오류로 실패함 | `sts:AssumeRoleWithWebIdentity` 호출이 거부되었습니다. 신뢰 정책의 federated principal ARN이 `oidc-provider/<your-platform-host>`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 참조하는지, audience 조건이 정확히 `sts.amazonaws.com`인지, `sub` 조건이 CrewAI 조직 UUID와 일치하는지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 AWS에서 접근 가능한지 확인하세요. |
| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS가 CrewAI Platform 호스트에 도달하여 JWKS를 가져올 수 없습니다. 호스트가 AWS에서 인터넷에 접근 가능한지, OIDC 디스커버리 URL이 200을 반환하는지, JWKS 엔드포인트가 접근 가능한지 확인하세요. |
| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | 신뢰 정책 불일치. 3단계를 다시 확인하세요: federated principal ARN은 `oidc-provider/<your-platform-host>`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 포함해야 하고, audience 조건은 정확히 `sts.amazonaws.com`이어야 하며, `sub` 조건은 `organization:<YOUR_CREWAI_ORG_UUID>`와 같아야 합니다. |
| Secret Name 자동 완성에 `AccessDenied: secretsmanager:ListSecrets` 표시 | 역할에 `Resource: "*"`를 가진 `secretsmanager:ListSecrets`가 없습니다. 4단계의 `SecretsManagerListForUI` 문을 추가하세요. |
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 리소스 범위 IAM이 없습니다. 해당 시크릿의 ARN과 KMS 키에 대한 역할의 `secretsmanager:GetSecretValue` 및 `kms:Decrypt` 권한을 감사하세요. |
| `RegionDisabledException` / 시크릿을 찾을 수 없음 | Workload Identity Config의 리전이 시크릿이 위치한 곳과 일치하지 않습니다. 6단계를 다시 확인하세요. |
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
### 참고 링크
- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html)
- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
## 다음 단계
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
- 다중 클라우드의 경우 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요.

295
docs/edge/ko/enterprise/features/secrets-manager/aws.mdx Normal file
View File

@@ -0,0 +1,295 @@
---
title: AWS Secrets Manager (정적 자격 증명)
description: 정적 액세스 키 또는 AssumeRole을 사용하여 AWS Secrets Manager를 CrewAI Platform의 시크릿 공급자로 구성합니다
sidebarTitle: 정적 자격 증명 사용
icon: "key"
---
## 개요
이 가이드는 **정적 자격 증명**(액세스 키, 선택적으로 AssumeRole 포함)을 사용하여 AWS Secrets Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 AWS 계정에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
<Note>
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원하면(재배포 없음), [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)을 참조하세요.
</Note>
<Note>
이 가이드는 AWS 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
</Note>
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- IAM 사용자, 고객 관리형 정책, 그리고 (선택적으로) IAM 역할을 생성할 수 있는 권한이 있는 AWS 계정.
- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`).
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
</Note>
## 인증 방법 선택
CrewAI Platform은 AWS Secrets Manager에 인증하는 두 가지 방법을 지원합니다. 시작하기 전에 하나를 선택하세요 — 아래 단계는 선택한 방법에 따라 다릅니다.
| 방법 | 사용 시기 | 트레이드오프 |
|---|---|---|
| **정적 액세스 키** | 시작 단계, 단일 계정 배포 | 가장 간단한 설정; 액세스 키를 수동으로 로테이션해야 함 |
| **AssumeRole** | 교차 계정, 프로덕션 강화 | 단기 자격 증명; External ID 지원; 추가 IAM 역할 필요 |
이 가이드의 나머지 부분은 단계 3-5에서 탭을 사용하므로 선택한 경로에 맞는 단계를 따를 수 있습니다.
## 1단계 — IAM 사용자 생성
[IAM 콘솔](https://console.aws.amazon.com/iam/)을 열고 **Users**로 이동한 다음 **Create user**를 클릭합니다.
- 권장 이름: `crewai-secrets-reader`.
- **Provide user access to the AWS Management Console**은 선택하지 마세요 — 이 주체는 사람이 아닌 CrewAI Platform이 프로그래밍 방식으로 사용합니다.
- **Next**를 클릭합니다.
**Set permissions** 페이지에서 기본 선택을 유지합니다. 정책은 3단계에서 연결합니다.
**Next**를 클릭하고 검토한 다음 **Create user**를 클릭합니다.
자세한 내용은 AWS 문서를 참조하세요: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */}
## 2단계 — IAM 정책 생성
CrewAI Platform은 AWS Secrets Manager에 대한 읽기 전용 액세스와 KMS를 통해 시크릿을 복호화할 수 있는 권한이 필요합니다. 다음 JSON으로 고객 관리형 정책을 생성하세요.
IAM 콘솔에서 **Policies**로 이동한 다음 **Create policy**를 클릭합니다.
**JSON** 탭을 선택하고 내용을 다음으로 바꿉니다:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerRead",
"Effect": "Allow",
"Action": [
"secretsmanager:ListSecrets",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": "*"
},
{
"Sid": "KMSDecrypt",
"Effect": "Allow",
"Action": [
"kms:DescribeKey",
"kms:Decrypt"
],
"Resource": "*"
}
]
}
```
**Next**를 클릭한 다음 **Review and create** 페이지에서:
- **Policy name:** `CrewAISecretsManagerRead`
- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform`
**Create policy**를 클릭합니다.
<Tip>
위 정책은 간소화를 위해 `Resource`에 `*`를 부여합니다. 프로덕션에서는 `Resource`를 CrewAI Platform이 액세스해야 하는 특정 시크릿의 ARN으로 좁히고, `kms:Decrypt`를 해당 시크릿을 암호화하는 특정 KMS 키 ARN으로 좁히세요. [AWS의 최소 권한 지침](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)을 참조하세요.
</Tip>
{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */}
{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */}
## 3단계 — 정책 연결
<Tabs>
<Tab title="정적 액세스 키">
1. IAM 콘솔에서 **Users**로 이동하여 1단계에서 만든 사용자를 클릭합니다.
2. **Permissions** 탭에서 **Add permissions** → **Attach policies directly**를 클릭합니다.
3. `CrewAISecretsManagerRead`를 검색하고 선택한 다음 **Next**를 클릭합니다.
4. **Add permissions**를 클릭합니다.
{/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */}
</Tab>
<Tab title="AssumeRole">
AssumeRole의 경우 정책은 (사용자가 아닌) 별도의 IAM **역할**에 연결됩니다. 1단계의 사용자는 해당 역할에 대해 `sts:AssumeRole`을 호출할 권한만 필요합니다.
**역할 생성:**
1. IAM 콘솔에서 **Roles**로 이동하여 **Create role**을 클릭합니다.
2. **Trusted entity type:** AWS account. **This account**를 선택합니다(또는 교차 계정 설정의 경우 **Another AWS account**를 선택하고 1단계 IAM 사용자를 호스팅하는 AWS 계정 ID를 입력합니다).
3. (권장) **Require external ID**를 체크하고 직접 생성한 값을 입력합니다 — 이는 5단계에서 CrewAI Platform에 붙여 넣을 공유 시크릿입니다.
4. **Next**를 클릭합니다.
5. `CrewAISecretsManagerRead` 정책을 연결합니다.
6. **Next**를 클릭하고 역할 이름을 `CrewAISecretsManagerRole`로 지정한 다음 **Create role**을 클릭합니다.
**IAM 사용자가 역할을 맡을 수 있도록 허용:**
1. 방금 만든 역할을 열고 **ARN**을 복사합니다.
2. IAM 콘솔에서 **Users**로 이동하여 1단계 사용자를 클릭한 다음 **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다.
3. **JSON** 탭에서 다음을 붙여 넣습니다(`ROLE_ARN_FROM_ABOVE`를 교체):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "ROLE_ARN_FROM_ABOVE"
}
]
}
```
4. 정책 이름을 `CrewAIAssumeSecretsRole`로 지정하고 **Create policy**를 클릭합니다.
{/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */}
{/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */}
</Tab>
</Tabs>
## 4단계 — 자격 증명 가져오기
<Tabs>
<Tab title="정적 액세스 키">
1. IAM 콘솔에서 1단계 사용자를 엽니다.
2. **Security credentials** 탭을 클릭합니다.
3. **Access keys** 아래에서 **Create access key**를 클릭합니다.
4. 사용 사례로 **Application running outside AWS**(또는 **Other**)를 선택합니다. **Next**를 클릭합니다.
5. (선택) 설명 태그를 추가합니다. **Create access key**를 클릭합니다.
6. **Show**를 클릭하여 시크릿 액세스 키를 표시한 다음 **Access key ID**와 **Secret access key**를 모두 복사하거나 **Download .csv file**을 클릭합니다.
<Warning>
시크릿 액세스 키는 한 번만 표시됩니다. 복사하지 않고 이 페이지를 닫으면 키를 삭제하고 새 키를 만들어야 합니다.
</Warning>
자세한 내용은 AWS 문서를 참조하세요: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
{/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */}
{/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */}
</Tab>
<Tab title="AssumeRole">
AssumeRole을 사용하더라도 CrewAI Platform은 여전히 IAM 사용자에 대한 액세스 키가 필요합니다 — `sts:AssumeRole` 호출을 수행하기 위한 호출 신원으로 해당 키를 사용합니다.
1. 위의 **정적 액세스 키** 탭에서 설명한 대로 사용자에 대한 액세스 키를 생성합니다.
2. 3단계에서 만든 역할을 열고 다음을 복사합니다:
- **Role ARN** (역할 요약에서).
- 구성한 **External ID** (있는 경우) — 3단계에서 직접 설정했으므로 가지고 있는지 확인하세요.
{/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */}
</Tab>
</Tabs>
## 5단계 — CrewAI Platform에 자격 증명 추가
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */}
<Tabs>
<Tab title="정적 액세스 키">
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `aws-prod`).
- **Provider:** `AWS Secrets Manager`.
- **Region:** 시크릿이 위치한 AWS 리전(예: `us-east-1`). 읽으려는 시크릿의 리전과 일치해야 합니다.
- **Access Key ID:** 4단계의 값.
- **Secret Access Key:** 4단계의 값.
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 AWS 시크릿을 참조하는 환경 변수에서 사용됩니다.
**Role ARN**과 **External ID**는 비워둡니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */}
</Tab>
<Tab title="AssumeRole">
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `aws-prod-assumerole`).
- **Provider:** `AWS Secrets Manager`.
- **Region:** 시크릿이 위치한 AWS 리전.
- **Access Key ID:** 4단계의 IAM 사용자 액세스 키(STS 호출에 사용).
- **Secret Access Key:** 4단계의 IAM 사용자 시크릿 액세스 키.
- **Role ARN:** 4단계에서 복사한 Role ARN.
- **External ID:** 역할의 신뢰 정책에 설정한 External ID(없으면 생략).
- (선택) **Set as default credential for this provider**를 체크합니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */}
</Tab>
</Tabs>
<Note>
**두 모드의 런타임 동작:**
- **정적 액세스 키**만 사용하는 경우, CrewAI Platform은 제공된 키를 사용하여 AWS Secrets Manager를 직접 호출합니다.
- **Role ARN**이 설정된 경우, CrewAI Platform은 먼저 제공된 액세스 키(구성된 경우 External ID 포함)로 `sts:AssumeRole`을 호출한 다음, STS가 반환한 단기 자격 증명을 사용하여 시크릿을 읽습니다.
</Note>
{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */}
## 6단계 — AWS에 최소 하나의 시크릿 생성
AWS Secrets Manager에 시크릿이 아직 없다면, 7단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
[AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/)에서 **Store a new secret**을 클릭합니다.
- **Secret type:** **Other type of secret**을 선택합니다.
- **Key/value pairs** — 다음 중 하나:
- 하나 이상의 키/값 쌍 입력(구조화된 시크릿에 권장), 또는
- 단일 문자열 값을 위해 **Plaintext** 탭 사용.
- **Encryption key:** 특정 KMS 키 요구 사항이 없으면 `aws/secretsmanager`(AWS 관리형 키)를 사용합니다.
**Next**를 클릭한 다음 입력합니다:
- **Secret name:** 고유한 이름(예: `crewai/openai-api-key`).
- **Description (optional):** 시크릿 용도에 대한 간단한 메모.
로테이션 및 검토 단계를 통해 **Next**를 클릭한 다음 **Store**를 클릭합니다.
<Note>
**JSON 키 참조 구문.** 여러 키/값 쌍(JSON 객체)이 있는 시크릿을 저장하는 경우, CrewAI Platform은 환경 변수 참조에서 `secret-name#json_key` 구문을 사용하여 특정 필드를 추출할 수 있습니다. 예를 들어, `{"username": "...", "password": "..."}`가 있는 `database-credentials`라는 시크릿은 `database-credentials#password`로 참조할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
</Note>
자세한 내용은 AWS 문서를 참조하세요: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */}
{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */}
## 7단계 — 연결 테스트
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
성공 토스트는 CrewAI Platform이 AWS에 인증하고 계정의 시크릿을 읽을 수 있음을 확인합니다.
{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */}
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
| 증상 | 가능한 원인 |
|---|---|
| `secretsmanager:ListSecrets`에서 `AccessDenied` | 정책이 연결되지 않았거나 잘못된 사용자입니다. 3단계를 다시 확인하세요. |
| `kms:Decrypt`에서 `AccessDenied` | `KMSDecrypt` 문이 누락되었거나, 시크릿이 `Resource: "*"`로 다루지 않는 고객 관리형 KMS 키를 사용합니다. |
| `InvalidClientTokenId` / `SignatureDoesNotMatch` | 잘못된 액세스 키 ID 또는 시크릿 액세스 키입니다. 4단계와 5단계를 다시 확인하세요. |
| `RegionDisabledException` / 시크릿을 찾을 수 없음 | 자격 증명의 **Region**이 시크릿이 실제로 위치한 곳과 일치하지 않습니다. |
| `sts:AssumeRole`에서 `AccessDenied` (AssumeRole만 해당) | IAM 사용자에 인라인 `sts:AssumeRole` 정책이 없거나, 역할의 신뢰 정책이 이 주체를 허용하지 않거나, External ID가 일치하지 않습니다. |
| IAM 사용자 생성 직후 테스트는 통과하지만 다음 번에는 실패함 | IAM 자격 증명이 전역적으로 전파되는 데 1-2분 정도 걸릴 수 있습니다. 다시 시도하세요. |
## 다음 단계
이제 AWS가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
- CrewAI Platform 환경 변수에서 AWS 시크릿을 참조합니다.
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다.

275
docs/edge/ko/enterprise/features/secrets-manager/azure-workload-identity.mdx Normal file
View File

@@ -0,0 +1,275 @@
---
title: Azure Workload Identity Federation
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Microsoft Entra Workload Identity Federation을 통해 Azure Key Vault를 구성합니다
sidebarTitle: Workload Identity 사용
icon: "id-badge"
---
## 개요
이 가이드는 **Microsoft Entra Workload Identity Federation**을 사용하여 Azure Key Vault를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Microsoft identity platform을 통해 이를 Entra 액세스 토큰과 교환하여 시크릿을 읽습니다 — 클라이언트 시크릿을 어디에도 저장하지 않습니다.
<Note>
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [Azure Key Vault — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) 가이드를 참조하세요.
</Note>
### 런타임 동작 방식
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
2. 워커가 `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token`에서 JWT를 `client_assertion`(`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`)으로 Microsoft Entra에 제시하며, JWT의 발급자 + 주체와 일치하는 **Federated Identity Credential**을 가진 App Registration을 참조합니다.
3. Entra가 플랫폼의 OIDC 디스커버리 문서와 JWKS에 대해 JWT를 검증한 다음, `https://vault.azure.net/.default`로 범위가 지정된 단기 액세스 토큰을 반환합니다.
4. 워커가 Azure Key Vault를 호출하여 시크릿을 읽습니다.
5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
- 관리할 수 있는 Azure 구독과 Microsoft Entra 테넌트.
- App Registration을 생성하고 Federated Identity Credential을 추가할 테넌트 권한.
- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님).
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
- **CrewAI Platform 설치가 Microsoft Entra에서 HTTPS를 통해 접근 가능해야 합니다.** Entra가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요.
</Note>
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Microsoft Entra가 신뢰할 수 있는 federation 발급자로 등록할 URL입니다.
브라우저에서 URL을 엽니다:
```
https://<your-platform-host>/.well-known/openid-configuration
```
다음을 포함하는 JSON이 보일 것입니다:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
<Tip>
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
</Tip>
## 2단계 — App Registration 생성
[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다.
- **Name:** `crewai-secrets-reader`
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
- **Redirect URI**는 비워둡니다.
**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 6단계에서 사용합니다.
{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */}
## 3단계 — Federated Identity Credential 추가
Federated Identity Credential은 Microsoft Entra에 다음을 알려줍니다: *이 발급자가 발급한 JWT를 신뢰하라, 이 주체로, 이 App Registration에 대한 client assertion으로 제시될 때.*
App Registration에서 **Certificates & secrets** → **Federated credentials** → **Add credential**로 이동합니다.
- **Federated credential scenario:** `Other issuer`.
- **Issuer:** 1단계의 CrewAI Platform 발급자 URL(예: `https://<your-platform-host>`).
- **Subject identifier:** `organization:<YOUR_CREWAI_ORG_UUID>` — 정확히 JWT의 `sub` 클레임 값. CrewAI Platform의 조직 설정에서 조직 UUID를 찾으세요. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다.
- **Name:** 설명적인 레이블(예: `crewai-org-prod`).
- **Audience:** `api://AzureADTokenExchange`. 이는 Microsoft Entra가 federated 자격 증명에 요구하는 고정 audience이며 CrewAI Platform이 JWT의 `aud` 클레임에 설정하는 값입니다.
**Add**를 클릭합니다.
<Tip>
**조직별 격리.** 주체 식별자(`organization:<UUID>`)는 federated 자격 증명을 특정 CrewAI 조직의 토큰으로 제한합니다. 여러 CrewAI 조직이 하나의 App Registration을 공유해야 하는 경우, 조직당 하나의 Federated Identity Credential을 추가하세요(각각 조직의 UUID 사용).
</Tip>
자세한 내용은 Microsoft 문서를 참조하세요: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust).
{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:<uuid>", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */}
## 4단계 — App Registration에 Key Vault 액세스 부여
대상 볼트에서 App Registration에 **Key Vault Secrets User**를 부여합니다 — 정적 자격 증명 경로에서 사용할 것과 동일한 역할입니다. 볼트 전체(더 간단함) 또는 시크릿별(최소 권한)을 사용하세요.
<Tabs>
<Tab title="볼트 전체 (더 간단함)">
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
```
볼트 전체 범위는 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**이 의존하는 `secrets/list` 권한을 부여합니다. 자동 완성이 작동하길 원한다면 이 탭을 선택하세요.
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */}
</Tab>
<Tab title="시크릿별 (최소 권한)">
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
```
시크릿별 바인딩은 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**을 비활성화합니다(자동 완성은 볼트 범위에서만 가능한 `secrets/list`가 필요합니다). 대신 전체 시크릿 이름을 입력하세요.
{/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */}
</Tab>
<Tab title="포털 (UI)">
**볼트 전체** 할당:
1. Azure 포털에서 Key Vault를 엽니다.
2. **Access control (IAM)** → **Add** → **Add role assignment**를 클릭합니다.
3. 역할 **Key Vault Secrets User**를 선택하고 → **Next**를 클릭합니다.
4. **Select members**를 클릭하고 App Registration `crewai-secrets-reader`를 검색한 다음 **Select**를 클릭합니다.
5. **Review + assign**을 클릭합니다.
**시크릿별** 할당의 경우 동일한 흐름을 사용하지만 **Objects** → **Secrets** → 시크릿 선택 → 자체 **Access control (IAM)** 패널에서 시작합니다. 시크릿별 바인딩은 자동 완성을 비활성화합니다(위의 시크릿별 탭 참조).
</Tab>
</Tabs>
## 5단계 — Key Vault에 최소 하나의 시크릿 생성
테스트할 시크릿이 아직 없다면 Azure CLI를 통해 하나 만듭니다:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "sk-your-actual-key"
```
또는 Azure 포털을 통해:
1. Key Vault를 열고 **Objects** → **Secrets**로 이동합니다.
2. **Generate/Import**를 클릭합니다.
3. **Upload options:** `Manual`. **Name:** 시크릿 이름(예: `openai-api-key`). **Secret value:** 값을 붙여 넣습니다.
4. **Create**를 클릭합니다.
<Note>
**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다.
</Note>
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `azure-prod`).
- **Cloud Provider:** `Azure`.
- **Tenant ID:** 2단계의 Microsoft Entra **Directory (tenant) ID**.
- **Client ID:** 2단계의 App Registration **Application (client) ID**.
- (선택) Azure 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Set as default for Azure**를 체크합니다.
**Audience**는 `api://AzureADTokenExchange`로 고정되어 있습니다 — Microsoft Entra는 federated 자격 증명에 대해 이 정확한 audience를 요구하므로 폼에 Audience 필드가 표시되지 않습니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */}
{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */}
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `azure-prod-wi`).
- **Provider:** `Azure Key Vault`.
- **Authentication Method:** `Workload Identity`.
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다.
- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`).
- (선택) **Set as default credential for this provider**를 체크합니다.
Workload Identity 아래에서는 폼이 **Key Vault URL**만 요청합니다 — 정적 자격 증명 필드(Tenant ID, Client ID, Client Secret)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. tenant + client는 연결된 WI 구성에서 가져옵니다.
**Create**를 클릭합니다.
<Tip>
**하나의 App Registration, 여러 볼트.** Key Vault URL은 WI 구성이 아닌 자격 증명에 있습니다. 따라서 하나의 App Registration(과 하나의 WI 구성)이 여러 Key Vault를 서비스할 수 있습니다 — 동일한 WI 구성에 연결된 볼트당 하나의 Secret Provider Credential을 만드세요.
</Tip>
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */}
## 8단계 — 연결 테스트
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, federated `client_assertion`으로 Microsoft Entra에 제시한 다음, Entra가 볼트 범위 액세스 토큰을 반환하는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
성공적인 Test Connection은 Federated Identity Credential의 발급자, 주체, audience가 모두 일치하고 App Registration이 접근 가능함을 증명합니다. 시크릿별 Key Vault RBAC가 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿에 대한 `getSecret`은 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
## 9단계 — 환경 변수에서 시크릿 참조
다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
## 10단계 — 로테이션 확인
배포가 실행 중인 상태에서 Key Vault의 시크릿을 로테이션합니다:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "rotated value"
```
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
워커 로그에서 확인하려면 다음을 찾으세요:
```
Workload identity config '<id>' (azure): N secret(s) resolved
```
이 줄은 모든 kickoff에 나타나며 Azure Key Vault에 대한 새로운 `getSecret` 호출을 의미합니다.
엔드 투 엔드 fingerprint 기반 검증은 [로테이션 엔드 투 엔드 검증](/ko/enterprise/features/secrets-manager/verify-rotation)을 참조하세요.
## 문제 해결
| 증상 | 가능한 원인 |
|---|---|
| Test Connection이 핸드셰이크 오류로 실패함 | federated `client_assertion`이 Microsoft Entra에 의해 거부되었습니다. Federated Identity Credential의 **Issuer**가 플랫폼의 `issuer` 값과 정확히 일치하는지, **Subject**가 `organization:<your-org-uuid>`(JWT의 `sub` 클레임과 일치)인지, **Audience**가 `api://AzureADTokenExchange`인지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 Entra에서 접근 가능한지 확인하세요. |
| `AADSTS70021: No matching federated identity record found for presented assertion` | Federated Identity Credential의 **Issuer** + **Subject** + **Audience**가 모두 JWT와 정확히 일치하지 않습니다. 3단계를 다시 확인하세요: 주체는 `organization:<your-org-uuid>`(JWT의 `sub` 클레임과 일치)여야 하고, audience는 `api://AzureADTokenExchange`여야 합니다. |
| `AADSTS700024: Client assertion is not within its valid time range` | CrewAI Platform 호스트의 시계가 실제 시간과 크게 다릅니다. 호스트의 NTP를 확인하세요. |
| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra가 JWT의 서명을 확인할 수 없습니다. `https://<your-platform-host>/oauth2/jwks`가 공용 인터넷에서 접근 가능하고 유효한 JWKS를 제공하는지 확인하세요. |
| Secret Name 자동 완성에 `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` 표시 | App Registration의 **Key Vault Secrets User** 역할이 단일 시크릿으로 범위 지정되어 있습니다. `list` 데이터 플레인 액션이 허용되도록 볼트 범위에서 역할을 부여하세요. 4단계를 참조하세요. |
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 시크릿별 Key Vault RBAC가 없습니다. 해당 특정 시크릿에 대한 **Key Vault Secrets User**를 감사하거나(또는 역할 할당을 볼트 범위로 확장). |
| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 4단계의 역할을 다시 부여하세요. |
| `azure_vault_url is required for Azure secret resolution` (워커 로그) | Secret Provider Credential에 **Key Vault URL**이 없습니다. 7단계를 다시 확인하세요. |
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
### 참고 링크
- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
## 다음 단계
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
- 다중 클라우드의 경우 AWS 동등 설정은 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)에, GCP 동등 설정은 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에 있습니다.
## 스크린샷 참조
위의 자리 표시자는 다음에 매핑됩니다:
- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼.
- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, **Other issuer**, 플랫폼 발급자 URL, 주체 `organization:<uuid>`, audience `api://AzureADTokenExchange`.
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**와 App Registration이 선택됨.
- `04-per-secret-rbac.png` — 동일한 폼이지만 단일 시크릿의 IAM 범위에서(대체 최소 권한 경로).
- `05-amp-add-wi-config-azure.png` — Cloud Provider = Azure, Tenant ID, Client ID가 채워진 CrewAI Platform "Add Workload Identity Config" 폼.
- `06-amp-wi-list-with-azure.png` — 생성 후 Workload Identity 목록 페이지, AWS, GCP 및 새 Azure 구성 행 표시.
- `07-amp-add-credential-azure-wi.png` — Provider = Azure Key Vault, Auth = Workload Identity, WI 구성 선택, Key Vault URL이 채워진 "Add Secret Provider Credential" 폼.

196
docs/edge/ko/enterprise/features/secrets-manager/azure.mdx Normal file
View File

@@ -0,0 +1,196 @@
---
title: Azure Key Vault
description: Azure Key Vault를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다
sidebarTitle: 정적 자격 증명 사용
icon: "key"
---
## 개요
이 가이드는 **클라이언트 시크릿이 있는 Microsoft Entra App Registration**을 사용하여 Azure Key Vault를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Azure Key Vault에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
<Note>
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 참조하세요.
</Note>
<Note>
이 가이드는 Azure 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
</Note>
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- Microsoft Entra에서 App Registration을 생성하고 Key Vault 리소스에 역할 할당을 부여할 권한이 있는 Azure 구독.
- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님). 볼트가 여전히 액세스 정책을 사용하는 경우, 볼트의 **Access configuration** 블레이드에서 RBAC로 전환하세요.
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
</Note>
## 1단계 — App Registration 생성
App Registration은 CrewAI Platform이 인증할 Microsoft Entra 측 ID입니다.
[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다.
- **Name:** `crewai-secrets-reader`
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
- **Redirect URI**는 비워둡니다.
**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 4단계에서 둘 다 CrewAI Platform에 붙여 넣습니다.
자세한 내용은 Microsoft 문서를 참조하세요: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */}
## 2단계 — 클라이언트 시크릿 생성
App Registration에서 **Certificates & secrets** → **Client secrets** → **New client secret**으로 이동합니다.
- **Description:** `crewai-platform`
- **Expires:** 로테이션 정책과 일치하는 기간을 선택합니다(Microsoft은 이를 24개월로 제한).
**Add**를 클릭합니다. **Value** 열을 즉시 복사하세요 — 페이지를 떠난 후에는 다시 표시할 수 없습니다.
<Warning>
클라이언트 시크릿은 장기 정적 자격 증명입니다. 값을 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 만료 전에 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 사용하세요.
</Warning>
{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */}
## 3단계 — App Registration에 Key Vault 액세스 부여
CrewAI Platform은 Key Vault의 시크릿에 대한 읽기 액세스가 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **볼트 전체** 또는 최소 권한을 위한 **시크릿별**.
<Tabs>
<Tab title="볼트 전체 (더 간단함)">
[Key Vault 콘솔](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults)에서 대상 볼트를 열고 **Access control (IAM)** → **Add** → **Add role assignment**로 이동합니다.
- **Role:** **Key Vault Secrets User**
- **Assign access to:** User, group, or service principal
- **Members:** App Registration(`crewai-secrets-reader`)을 검색하고 선택합니다.
**Review + assign**을 클릭합니다.
또는 Azure CLI를 통해:
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
```
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */}
</Tab>
<Tab title="시크릿별 (최소 권한)">
개별 시크릿 수준에서 역할을 부여합니다. CrewAI Platform이 액세스해야 하는 각 시크릿에 대해 반복합니다:
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
```
{/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */}
</Tab>
</Tabs>
<Tip>
**Key Vault Secrets User** 역할은 시크릿 값 읽기를 허용하지만 볼트의 모든 시크릿을 나열하는 것은 허용하지 않습니다. CrewAI Platform의 시크릿 이름 자동 완성도 `list`를 호출합니다 — 해당 권한은 볼트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 대신 전체 시크릿 이름을 입력하세요.
</Tip>
## 4단계 — CrewAI Platform에 자격 증명 추가
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `azure-prod`).
- **Provider:** `Azure Key Vault`.
- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`).
- **Tenant ID:** 1단계의 Microsoft Entra **Directory (tenant) ID**.
- **Client ID:** 1단계의 App Registration **Application (client) ID**.
- **Client Secret:** 2단계에서 복사한 **Value**.
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 Azure 시크릿을 참조하는 환경 변수에서 사용됩니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */}
## 5단계 — Azure Key Vault에 최소 하나의 시크릿 생성
Key Vault에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
Key Vault 콘솔에서 **Objects** → **Secrets** → **Generate/Import**로 이동합니다.
- **Upload options:** `Manual`
- **Name:** 예: `openai-api-key`
- **Secret value:** 시크릿 값을 붙여 넣습니다
- 나머지는 기본값으로 둡니다.
**Create**를 클릭합니다.
또는 Azure CLI를 통해:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "sk-your-actual-key"
```
<Note>
**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다.
</Note>
<Note>
**JSON 키 참조 구문.** Key Vault는 시크릿 값을 불투명한 문자열로 취급합니다. 시크릿 값이 JSON 객체인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
</Note>
자세한 내용은 Microsoft 문서를 참조하세요: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */}
## 6단계 — 연결 테스트
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
성공 토스트는 CrewAI Platform이 Microsoft Entra에 인증하고 볼트의 시크릿을 읽을 수 있음을 확인합니다.
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */}
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
| 증상 | 가능한 원인 |
|---|---|
| `AADSTS7000215: Invalid client secret provided` | 붙여 넣은 **Client Secret**이 잘못되었거나 만료되었습니다. 시크릿을 다시 생성하고(2단계) 자격 증명을 업데이트하세요. |
| `AADSTS700016: Application not found in the directory` | **Tenant ID** 또는 **Client ID**가 App Registration과 일치하지 않습니다. 4단계를 다시 확인하세요. |
| `Forbidden — caller does not have permission` | App Registration에 볼트(또는 시크릿별) **Key Vault Secrets User** 역할이 없습니다. 3단계를 다시 확인하세요. |
| `Vault not found` / DNS 오류 | **Key Vault URL**이 잘못되었거나, 볼트에 공용 액세스를 차단하는 프라이빗 엔드포인트가 있습니다. 호스트가 `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`에 응답하는지 확인하세요. |
| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 3단계의 역할을 다시 부여하세요. |
## 다음 단계
이제 Azure Key Vault가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
- CrewAI Platform 환경 변수에서 Azure 시크릿을 참조합니다.
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)으로 전환하세요 — 동일한 볼트, 로테이션할 클라이언트 시크릿 없음, kickoff마다 시크릿을 가져옵니다.
## 스크린샷 참조
위의 자리 표시자는 다음에 매핑됩니다:
- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼.
- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, 새로 생성된 시크릿 행이 표시됨(마스킹되기 전 Value 열 강조).
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**가 선택되고 App Registration이 멤버로 선택됨.
- `04-per-secret-rbac.png` — 동일한 패널이지만 단일 시크릿 리소스로 범위 지정됨(대체 최소 권한 경로).
- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" 폼: Provider = Azure Key Vault, 다섯 필드 모두 채워짐.
- `06-create-secret.png` — `openai-api-key`와 붙여 넣은 값이 있는 Azure Key Vault "Create a secret" 패널.
- `07-test-connection-success.png` — 자격 증명에서 **Test Connection**을 클릭한 후의 CrewAI Platform 성공 토스트 / 행 상태.

273
docs/edge/ko/enterprise/features/secrets-manager/gcp-workload-identity.mdx Normal file
View File

@@ -0,0 +1,273 @@
---
title: GCP Workload Identity Federation
description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity Federation을 통해 Google Cloud Secret Manager를 구성합니다
sidebarTitle: Workload Identity 사용
icon: "id-badge"
---
## 개요
이 가이드는 **Workload Identity Federation**을 사용하여 Google Cloud Secret Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Security Token Service를 통해 이를 Google Cloud 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 서비스 계정 키를 어디에도 저장하지 않습니다.
<Note>
**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) 가이드를 참조하세요.
</Note>
### 런타임 동작 방식
1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다.
2. 워커가 아래에서 설정한 Workload Identity Pool Provider를 참조하여 [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest)를 통해 JWT를 federated Google 자격 증명과 교환합니다.
3. 워커가 federated 자격 증명을 직접 사용하여 시크릿을 읽기 위해 `secretmanager.googleapis.com:accessSecretVersion`을 호출합니다(federated 주체가 `roles/secretmanager.secretAccessor`를 보유함 — 4단계 참조).
4. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다.
OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다.
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다.
- **Secret Manager API**, **Security Token Service API**, **IAM Credentials API**가 활성화된 Google Cloud 프로젝트. 콘솔에서 또는 다음을 통해 활성화하세요:
```bash
gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \
--project=<YOUR_PROJECT_ID>
```
- Workload Identity Pool, IAM 역할, 서비스 계정, (필요한 경우) 시크릿을 생성할 프로젝트 권한.
- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
- **CrewAI Platform 설치가 Google Cloud에서 HTTPS를 통해 접근 가능해야 합니다.** GCP STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요.
</Note>
## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기
CrewAI Platform 설치는 `https://<your-platform-host>/.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Google이 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다.
브라우저에서 URL을 엽니다:
```
https://<your-platform-host>/.well-known/openid-configuration
```
다음을 포함하는 JSON이 보일 것입니다:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다.
<Tip>
URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요.
</Tip>
## 2단계 — Workload Identity Pool 생성
Workload Identity Pool은 신뢰할 수 있는 외부 ID를 위한 Google Cloud 측 컨테이너입니다. 이 풀 내부에 CrewAI Platform을 공급자로 등록합니다.
```bash
gcloud iam workload-identity-pools create crewai-pool \
--project=<YOUR_PROJECT_ID> \
--location=global \
--display-name="CrewAI Platform"
```
또는 [Workload Identity Pools 콘솔](https://console.cloud.google.com/iam-admin/workload-identity-pools)에서 **Create Pool**을 클릭합니다.
{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */}
## 3단계 — CrewAI Platform을 풀에 OIDC 공급자로 추가
```bash
gcloud iam workload-identity-pools providers create-oidc crewai-provider \
--project=<YOUR_PROJECT_ID> \
--location=global \
--workload-identity-pool=crewai-pool \
--display-name="CrewAI Platform OIDC" \
--issuer-uri="https://<your-platform-host>" \
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
--attribute-condition="assertion.organization_id != ''"
```
`--attribute-mapping`은 JWT 클레임을 Google 속성으로 매핑하는 방법을 Google에 알려줍니다:
- `google.subject`는 주체 식별자입니다 — JWT의 `sub` 클레임에 매핑하며, CrewAI Platform은 이를 `organization:<uuid>`로 설정합니다.
- `attribute.organization`은 사용자 정의 속성입니다 — JWT의 `organization_id` 클레임에 매핑하여 나중에 IAM 바인딩에서 참조할 수 있습니다.
`--attribute-condition`은 `organization_id` 클레임이 없는 토큰을 거부하는 심층 방어 검사입니다.
**Provider 리소스 이름**을 가져옵니다(audience 및 IAM 바인딩에 필요):
```bash
gcloud iam workload-identity-pools providers describe crewai-provider \
--project=<YOUR_PROJECT_ID> \
--location=global \
--workload-identity-pool=crewai-pool \
--format="value(name)"
```
출력은 다음과 같습니다:
```
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider
```
이것이 6단계에서 CrewAI Platform의 **Workload Identity Provider** 값입니다. CrewAI Platform은 토큰을 발급할 때 OIDC audience를 `//iam.googleapis.com/<this-resource-name>`으로 자동으로 계산합니다.
{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */}
## 4단계 — Federated 주체에 Secret Manager 액세스 부여
프로젝트 범위에서 두 Secret Manager 역할을 모두 federated 주체에 바인딩합니다 — 한 역할은 환경 변수 폼의 Secret Name 자동 완성을 활성화하고, 다른 역할은 자동화 kickoff 시점에 시크릿 값을 읽을 수 있게 합니다. 기능이 처음부터 끝까지 작동하려면 두 역할 모두 필요합니다.
```bash
PRINCIPAL_SET="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/attribute.organization/<YOUR_CREWAI_ORG_UUID>"
# Secret Name 자동 완성에 필요 (secretmanager.secrets.list 호출)
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.viewer"
# kickoff 시점에 시크릿 값을 읽는 데 필요
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.secretAccessor"
```
`<PROJECT_NUMBER>`를 숫자 프로젝트 번호(`gcloud projects describe <YOUR_PROJECT_ID> --format='value(projectNumber)'`)로, `<YOUR_CREWAI_ORG_UUID>`를 시크릿을 읽을 수 있도록 허용할 CrewAI Platform 조직의 UUID로 교체합니다. 조직 UUID는 플랫폼 UI의 조직 설정 페이지나 API를 통해 찾을 수 있습니다. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다.
또는 Google Cloud 콘솔을 통해:
1. 프로젝트의 **IAM & Admin** → **IAM**을 엽니다.
2. **GRANT ACCESS**를 클릭합니다.
3. **New principals:** 전체 `principalSet://...attribute.organization/<YOUR_CREWAI_ORG_UUID>` 문자열을 붙여 넣습니다.
4. 역할 **Secret Manager Viewer** (`roles/secretmanager.viewer`)를 할당합니다.
5. **SAVE**를 클릭합니다.
6. **GRANT ACCESS**를 다시 클릭하고 **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) 역할로 반복합니다.
<Tip>
**조직별 격리.** `principalSet://...attribute.organization/<UUID>` 패턴은 특정 조직의 토큰에 대한 액세스를 제한합니다. 하나의 Google Cloud 프로젝트를 여러 CrewAI 조직이 공유하는 경우, 각 조직에 대해 올바른 UUID로 두 바인딩을 모두 반복하거나 — 격리가 필요하지 않으면 덜 제한적인 attribute condition을 사용하세요.
</Tip>
<Tip>
**시크릿별로 `secretAccessor` 범위 지정 (선택 사항).** `roles/secretmanager.secretAccessor`를 프로젝트 전체로 부여하고 싶지 않으면, 위의 두 번째 바인딩을 생략하고 대신 시크릿별로 바인딩합니다:
```bash
gcloud secrets add-iam-policy-binding <SECRET_NAME> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.secretAccessor" \
--project=<YOUR_PROJECT_ID>
```
어느 쪽이든 `roles/secretmanager.viewer`는 프로젝트 범위로 유지하세요 — `secretmanager.secrets.list`(자동 완성이 의존)는 시크릿별로 부여할 수 없습니다.
</Tip>
## 5단계 — GCP에 최소 하나의 시크릿 생성
테스트할 시크릿이 아직 없다면 `gcloud` CLI를 통해 하나 만듭니다:
```bash
echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \
--data-file=- \
--project=<YOUR_PROJECT_ID> \
--replication-policy=automatic
```
또는 [Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)을 통해:
1. GCP 프로젝트에서 **Secret Manager**를 엽니다.
2. **+ CREATE SECRET**을 클릭합니다.
3. **Name:** `crewai-test-keyword`. **Secret value:** 값을 붙여 넣습니다.
4. **CREATE SECRET**을 클릭합니다.
## 6단계 — CrewAI Platform에 Workload Identity 구성 추가
CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다.
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `gcp-prod`).
- **Cloud Provider:** `GCP`.
- **Workload Identity Provider:** 3단계의 provider 리소스 이름(예: `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`).
- (선택) GCP 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Default Configuration**을 토글합니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */}
{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */}
## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가
**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `gcp-prod-wi`).
- **Provider:** `Google Cloud Secret Manager`.
- **Authentication Method:** `Workload Identity`.
- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다.
- **Project ID:** GCP 프로젝트 ID(시크릿을 소유한 동일한 프로젝트).
- (선택) **Set as default credential for this provider**를 체크합니다.
Workload Identity 아래에서는 폼이 **Project ID**만 요청합니다 — **Service Account JSON** 필드는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. federated ID는 연결된 WI 구성에서 가져옵니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */}
## 8단계 — 연결 테스트
자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, Security Token Service를 통해 federated Google 액세스 토큰과 교환합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다.
성공적인 Test Connection은 Workload Identity Pool, OIDC 공급자, attribute mapping, attribute condition이 모두 올바르게 연결되었음을 증명합니다. Secret Manager IAM이 올바르다는 것을 증명하지는 **않습니다** — `secretmanager.secrets.list`와 `secretmanager.versions.access`는 Secret Name 자동 완성이 로드되거나 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요.
## 9단계 — 환경 변수에서 시크릿 참조
다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
## 10단계 — 로테이션 확인
배포가 실행 중인 상태에서 새 버전을 추가하여 GCP의 시크릿을 로테이션합니다(Secret Manager는 기본적으로 항상 최신 활성화 버전을 읽음):
```bash
echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \
--data-file=- \
--project=<YOUR_PROJECT_ID>
```
새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음.
워커 로그에서 확인하려면 다음을 찾으세요:
```
Workload identity config '<id>' (gcp): N secret(s) resolved
```
이 줄은 모든 kickoff에 나타나며 GCP에 대한 새로운 `accessSecretVersion` 호출을 의미합니다.
## 문제 해결
| 증상 | 가능한 원인 |
|---|---|
| Test Connection이 핸드셰이크 오류로 실패함 | STS 토큰 교환이 거부되었습니다. Workload Identity Pool이 존재하는지, OIDC provider의 발급자가 플랫폼의 `issuer` 값과 일치하는지, attribute condition이 JWT의 클레임을 수락하는지 확인하세요. 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 GCP에서 접근 가능한지 확인하세요. |
| `Could not refresh access token: invalid_target` | audience 클레임이 Workload Identity Provider의 예상 audience와 일치하지 않습니다. CrewAI Platform이 audience를 자동으로 설정합니다. 사용자 정의한 경우 `//iam.googleapis.com/<provider-resource-name>`과 일치하는지 확인하세요. |
| `Failed to fetch JWKS from issuer` | GCP STS가 CrewAI Platform 호스트에 도달할 수 없습니다. 호스트가 인터넷에서 접근 가능하고 `/.well-known/openid-configuration`이 200을 반환하는지 확인하세요. |
| `Attribute condition rejected token` | OIDC provider의 attribute condition(3단계)이 `organization_id`를 요구합니다. CrewAI Platform은 항상 이 클레임을 설정하므로 보통 잘못 구성된 풀/공급자를 의미합니다. provider의 attribute condition을 다시 확인하세요. |
| Secret Name 자동 완성에 `PERMISSION_DENIED: secretmanager.secrets.list` 표시 | federated 주체에 프로젝트 범위의 `roles/secretmanager.viewer`가 없습니다. `secretmanager.secrets.list` 권한은 프로젝트 범위에서만 가능하며 시크릿별로 부여할 수 없습니다. 4단계를 참조하세요. |
| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 `secretmanager.versions.access`가 없습니다. `roles/secretmanager.secretAccessor`(프로젝트 범위 또는 4단계에서 그렇게 범위 지정한 경우 시크릿별)를 감사하세요. |
| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. |
### 참고 링크
- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation)
- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control)
## 다음 단계
- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage)
- 다중 클라우드의 경우 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요.

189
docs/edge/ko/enterprise/features/secrets-manager/gcp.mdx Normal file
View File

@@ -0,0 +1,189 @@
---
title: Google Cloud Secret Manager
description: Google Cloud Secret Manager를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다
sidebarTitle: 정적 자격 증명 사용
icon: "key"
---
## 개요
이 가이드는 **서비스 계정 자격 증명**을 사용하여 Google Cloud Secret Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Google Cloud 프로젝트에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다.
<Note>
이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 참조하세요.
</Note>
<Note>
이 가이드는 GCP 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요.
</Note>
## 사전 준비 사항
<Note>
시작하기 전에 다음을 준비하세요:
- **Secret Manager API**가 활성화된 Google Cloud 프로젝트. [APIs & Services 콘솔](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com)에서 또는 `gcloud`를 통해 활성화하세요:
```bash
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
```
- 서비스 계정 생성, IAM 역할 부여, (필요한 경우) 시크릿 생성에 대한 프로젝트 권한.
- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
</Note>
## 1단계 — 서비스 계정 생성
서비스 계정은 CrewAI Platform이 인증할 GCP 측 ID입니다.
[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 **Create Service Account**를 클릭합니다.
- **Service account name:** `crewai-secrets-reader`
- **Service account ID:** 이름에서 자동으로 채워짐(예: `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`)
- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform"
**Create and Continue**를 클릭합니다. 이 화면에서 선택적 권한 부여는 건너뜁니다 — 역할은 2단계에서 연결합니다. **Done**을 클릭합니다.
자세한 내용은 GCP 문서를 참조하세요: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */}
## 2단계 — Secret Manager 액세스 부여
CrewAI Platform은 프로젝트의 시크릿을 나열하고 읽을 수 있는 권한이 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **프로젝트 전체** 또는 최소 권한을 위한 **시크릿별**.
<Tabs>
<Tab title="프로젝트 전체 (더 간단함)">
[IAM 콘솔](https://console.cloud.google.com/iam-admin/iam)에서 **Grant Access**를 클릭하고:
- **New principals:** 1단계 서비스 계정의 이메일.
- **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
**Save**를 클릭합니다.
또는 `gcloud`를 통해:
```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
```
{/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */}
</Tab>
<Tab title="시크릿별 (최소 권한)">
CrewAI Platform이 액세스해야 하는 특정 시크릿에만 역할을 부여합니다. 각 시크릿에 대해 반복합니다:
```bash
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor" \
--project=YOUR_PROJECT_ID
```
또는 콘솔에서: [Secret Manager](https://console.cloud.google.com/security/secret-manager)에서 각 시크릿을 열고, 오른쪽 패널의 **Permissions**를 클릭한 다음 서비스 계정에 **Secret Manager Secret Accessor**를 부여합니다.
{/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */}
</Tab>
</Tabs>
<Tip>
`roles/secretmanager.secretAccessor` 역할은 시크릿 값에 대한 읽기 전용 액세스를 부여합니다. CrewAI Platform은 또한 환경 변수 폼의 자동 완성 경험을 위해 `secretmanager.secrets.list`를 호출합니다 — 해당 권한은 프로젝트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 전체 시크릿 이름을 입력해야 합니다.
</Tip>
## 3단계 — 서비스 계정 키 생성
[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 1단계의 서비스 계정을 엽니다.
- **Keys** 탭을 클릭합니다.
- **Add Key** → **Create new key**를 클릭합니다.
- **Key type:** JSON.
- **Create**를 클릭합니다. 브라우저가 JSON 파일을 다운로드합니다 — 안전하게 보관하세요. 다시 다운로드할 수 없습니다.
또는 `gcloud`를 통해:
```bash
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
--iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
```
<Warning>
서비스 계정 키는 장기 정적 자격 증명입니다. 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 정기적으로 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 사용하세요.
</Warning>
{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */}
## 4단계 — CrewAI Platform에 자격 증명 추가
CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
폼을 작성합니다:
- **Name:** 설명적인 이름(예: `gcp-prod`).
- **Provider:** `Google Cloud Secret Manager`.
- **Project ID:** GCP 프로젝트 ID(예: `my-crewai-prod`).
- **Service Account JSON:** 3단계에서 다운로드한 JSON 파일의 전체 내용을 붙여 넣습니다.
- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 GCP 시크릿을 참조하는 환경 변수에서 사용됩니다.
**Create**를 클릭합니다.
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */}
## 5단계 — GCP에 최소 하나의 시크릿 생성
GCP Secret Manager에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요.
[Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)에서 **Create secret**을 클릭합니다.
- **Name:** 고유한 이름(예: `openai-api-key`).
- **Secret value:** 원시 값을 붙여 넣거나 파일을 업로드합니다.
- 특정 요구 사항이 없으면 로테이션, 복제 및 기타 설정을 기본값으로 둡니다.
**Create secret**을 클릭합니다.
또는 `gcloud`를 통해:
```bash
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
--data-file=- \
--project=YOUR_PROJECT_ID \
--replication-policy=automatic
```
<Note>
**JSON 키 참조 구문.** GCP Secret Manager는 시크릿 값을 불투명한 blob으로 취급합니다. 시크릿 값이 JSON 문자열인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
</Note>
자세한 내용은 GCP 문서를 참조하세요: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart).
{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */}
## 6단계 — 연결 테스트
CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다.
성공 토스트는 CrewAI Platform이 GCP에 인증하고 프로젝트의 시크릿을 읽을 수 있음을 확인합니다.
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */}
테스트가 실패하면 가장 일반적인 원인을 확인하세요:
| 증상 | 가능한 원인 |
|---|---|
| 시크릿 나열 시 `PERMISSION_DENIED` | 서비스 계정에 `roles/secretmanager.secretAccessor`가 없거나, 시크릿별로 범위를 지정했습니다(`list`가 부여되지 않음). 2단계를 다시 확인하세요. |
| `secretmanager.secrets.access`에서 `PERMISSION_DENIED` | 위와 동일하지만 특정 시크릿에 대한 것입니다. 해당 시크릿에 서비스 계정이 accessor 역할을 갖고 있는지 확인하세요. |
| `unauthorized_client` / `invalid_grant` | 붙여 넣은 서비스 계정 JSON이 유효하지 않거나, 만료되었거나, 삭제된 서비스 계정용입니다. 키를 다시 만들고(3단계) 다시 붙여 넣으세요. |
| `Project ID does not match` | CrewAI Platform의 Project ID 필드가 서비스 계정/시크릿을 소유한 프로젝트와 일치하지 않습니다. 4단계를 다시 확인하세요. |
| `API not enabled` | 프로젝트에 Secret Manager API가 활성화되어 있지 않습니다. 사전 준비 사항을 참조하세요. |
## 다음 단계
이제 GCP가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요:
- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다.
- CrewAI Platform 환경 변수에서 GCP 시크릿을 참조합니다.
재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다.

96
docs/edge/ko/enterprise/features/secrets-manager/overview.mdx Normal file
View File

@@ -0,0 +1,96 @@
---
title: Secrets Manager 개요
description: 외부 시크릿 저장소를 CrewAI Platform에 연결하고 환경 변수에서 관리되는 시크릿을 참조합니다
sidebarTitle: 개요
icon: "book-open"
---
## 개요
Secrets Manager 기능은 조직에서 외부 시크릿 저장소(AWS Secrets Manager, Google Cloud Secret Manager 또는 Azure Key Vault)를 연결하고, 자동화(Automation) 및 Crew의 환경 변수에서 해당 시크릿을 직접 참조할 수 있게 해줍니다. 플랫폼에 평문 값을 붙여 넣는 대신, 각 공급자별로 자격 증명 한 세트만 저장하고 시크릿을 이름으로 참조합니다.
이를 통해 얻는 이점은 다음과 같습니다:
- **중앙 집중식 저장** — CrewAI Platform 설정을 편집하는 대신 공급자에서 시크릿을 관리합니다. CrewAI Platform은 시크릿 값의 평문 사본을 보관하지 않습니다.
- **노출 감소** — 민감한 값이 CrewAI Platform 설정에 평문으로 존재하지 않습니다.
- **클라우드 네이티브 감사 가능성** — 공급자의 감사 로그에 모든 시크릿 읽기 작업이 기록됩니다.
<Note>
Secrets Manager(정적 자격 증명 및 Workload Identity 경로 모두)는 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 필요합니다.
</Note>
## 두 가지 경로: 정적 자격 증명 vs Workload Identity
CrewAI Platform을 클라우드의 시크릿 저장소에 연결하는 방법은 두 가지가 있습니다. **로테이션 동작 방식에서 큰 차이가 있으므로**, 시크릿이 얼마나 자주 로테이션되는지와 보안 정책의 엄격함에 따라 선택하세요.
| 항목 | 정적 자격 증명 | Workload Identity (OIDC Federation) |
|---|---|---|
| **인증** | 장기 액세스 키 / 서비스 계정 JSON을 CrewAI Platform에 저장 | 워커 프로세스마다 발급되는 단기 토큰; 어디에도 정적 자격 증명을 저장하지 않음 |
| **로테이션 전파** | 배포 시점에 해석되어 **배포 컨테이너 이미지에 박힘** — 로테이션된 값을 반영하려면 재배포 필요 | **자동화 실행 시점**에 해석됨 — 로테이션된 값이 재배포 없이 다음 kickoff에 전파됨 |
| **설정 노력** | 더 적음 — 키 붙여 넣기 / 서비스 계정 JSON 업로드 | 더 많음 — CrewAI Platform을 클라우드에 OIDC 공급자로 등록하고 신뢰 정책 구성 |
| **적합한 용도** | 시작 단계, 드물게 로테이션되는 시크릿, 단일 계정 배포 | 프로덕션, 자주 로테이션되는 시크릿, 장기 자격 증명을 금지하는 규정 준수 환경 |
<Note>
**두 경로 모두 환경 변수에서 시크릿을 참조하는 동일한 UI 흐름을 사용합니다**([Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage) 참조). 차이점은 전적으로 플랫폼이 클라우드에 어떻게 인증하고 언제 시크릿 값을 읽는지에 있습니다.
</Note>
### 설정 가이드 선택
| 공급자 | 정적 자격 증명 | Workload Identity |
|---|---|---|
| AWS Secrets Manager | [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/ko/enterprise/features/secrets-manager/aws-workload-identity) |
| Google Cloud Secret Manager | [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) |
| Azure Key Vault | [Azure — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity) |
<Note>
Secrets Manager 및 Workload Identity UI는 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다.
</Note>
## 동작 방식
Secrets Manager 설정은 클라우드 공급자와 CrewAI Platform 양쪽 모두에서 작업하는 3단계 흐름입니다:
1. **관리자가 공급자 자격 증명을 구성합니다.** 이는 클라우드 측 작업이며 — 선택한 경로(정적 자격 증명 또는 Workload Identity)에 따라 작업이 다릅니다. 공급자별 가이드에서 처음부터 끝까지 다룹니다.
2. **관리자(또는 권한이 부여된 멤버)가 환경 변수에서 시크릿을 참조합니다.** Environment Variables 페이지에서 공급자 자격 증명을 선택하고 시크릿 이름을 선택합니다. [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요.
3. **자동화가 런타임에 해석된 값을 받습니다.** Crew 또는 자동화가 실행될 때, CrewAI Platform이 공급자에서 시크릿을 가져와 환경 변수 값으로 주입합니다. Workload Identity의 경우 이 가져오기는 매 kickoff마다 수행됩니다(로테이션 인식). 정적 자격 증명의 경우 이 가져오기는 배포 시점에 수행되고 값이 배포 이미지에 박힙니다.
## 가시성 및 범위
<Note>
WI 기반 환경 변수는 평문 환경 변수와 동일한 할당 모델을 따릅니다: 자동화는 명시적으로 할당된 WI 기반 변수만 해석합니다. 해당 자동화의 Environment Variables 페이지에서 WI 기반 변수를 자동화에 할당하세요; 조직 수준 또는 Studio 프로젝트에 정의된 변수는 할당하기 전까지 kickoff에서 해석되지 않습니다.
</Note>
<Note>
시크릿 가져오기 단계는 매 kickoff마다 실행되지만, 배포에 WI 기반 환경 변수가 할당되어 있을 때만 실제로 작업을 수행합니다. 할당된 변수 각각에 대해, 런타임은 매 crew, flow, training, test, 또는 checkpoint-restore kickoff마다 클라우드 공급자에서 값을 해석하여 프로세스 환경에 기록합니다. 할당된 변수가 없으면 이 단계는 no-op입니다. 그렇지 않은 경우, 비용은 할당된 변수 수에 비례합니다: kickoff당 약간의 추가 지연 시간과 변수당 하나의 클라우드 측 audit log 항목.
</Note>
<Warning>
Workload Identity *구성* 수준에서는 오늘날에도 여전히 조직 전체에 적용됩니다. 조직 내 모든 자동화는 조직이 등록한 모든 Workload Identity 구성을 기반으로 부트스트랩되며, 오늘날에는 특정 Workload Identity 구성을 특정 자동화에 바인딩할 수 없습니다. 자동화별 Workload Identity 범위 지정은 로드맵에 있습니다. 그때까지는 조직 내 모든 자동화가 사용해도 되는 Workload Identity 구성만 등록하세요.
</Warning>
## 권한
Secrets Manager 접근을 제어하는 두 가지 CrewAI Platform 기능:
- `secret_providers` — 공급자 자격 증명을 보거나 관리할 수 있는 사람을 제어합니다.
- `environment_variables` — 시크릿을 참조하는 환경 변수를 포함하여 환경 변수를 생성하고 편집할 수 있는 사람을 제어합니다.
세 번째 기능은 Workload Identity 설정을 제어합니다:
- `workload_identity_configs` — Workload Identity 구성을 보거나 관리할 수 있는 사람을 제어합니다. Workload Identity 경로를 사용하는 경우에만 필요합니다.
소유자(Owner)는 항상 전체 접근 권한을 가집니다. 멤버는 기본적으로 `secret_providers` 또는 `workload_identity_configs`에 대한 접근 권한을 **받지 않으며**, 사용자 정의 역할을 통해 권한을 명시적으로 부여받아야 합니다. 전체 매트릭스와 단계별 지침은 [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요.
## 다음 단계
원하는 경로를 선택하세요:
- **정적 자격 증명** (더 간단함, 로테이션 시 재배포 필요):
- [AWS Secrets Manager 구성](/ko/enterprise/features/secrets-manager/aws)
- [Google Cloud Secret Manager 구성](/ko/enterprise/features/secrets-manager/gcp)
- [Azure Key Vault 구성](/ko/enterprise/features/secrets-manager/azure)
- **Workload Identity** (로테이션 인식, 재배포 불필요):
- [AWS Workload Identity 구성](/ko/enterprise/features/secrets-manager/aws-workload-identity)
- [GCP Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/gcp-workload-identity)
- [Azure Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/azure-workload-identity)
- 그리고: [환경 변수에서 시크릿을 사용하고 권한 관리하기](/ko/enterprise/features/secrets-manager/usage)

137
docs/edge/ko/enterprise/features/secrets-manager/usage.mdx Normal file
View File

@@ -0,0 +1,137 @@
---
title: Secrets Manager 사용하기
description: CrewAI Platform에서 권한을 관리하고 환경 변수에서 관리되는 시크릿을 참조합니다
sidebarTitle: 사용 및 권한
icon: "list-check"
---
## 개요
이 가이드는 공급자 중립적입니다. 사용자(또는 다른 관리자)가 이미 최소 하나의 Secret Provider Credential을 구성했다고 가정합니다. 원하는 경로에 따라 설정 가이드를 선택하세요:
- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp)
- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity)
이 가이드를 사용하여 다음을 수행하세요:
- 조직 멤버에게 적절한 권한을 부여합니다.
- 자동화의 환경 변수에서 시크릿을 참조합니다.
- 런타임에서 모든 것이 올바르게 해석되는지 확인합니다.
## 권한 (RBAC)
Secrets Manager를 사용할 때 관련된 세 가지 CrewAI Platform 기능:
- `secret_providers` — **Secret Provider Credentials** 페이지에 대한 접근을 제어합니다.
- `workload_identity_configs` — **Workload Identity** 페이지에 대한 접근을 제어합니다(WI 경로를 사용하는 경우에만 관련됨).
- `environment_variables` — 환경 변수를 생성하거나 편집할 수 있는 사람을 제어합니다.
각 기능에는 두 가지 작업 수준이 있습니다: `read`와 `manage`. `manage`를 부여하면 자동으로 `read`를 포함합니다.
### 부여할 권한
| 목표 | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|---|---|---|---|
| 환경 변수에서 기존 정적 자격 증명 사용 (공급자 편집 불가) | `read` | — | `manage` |
| 정적 자격 증명 생성, 편집 또는 삭제 | `manage` | — | `manage` |
| 환경 변수에서 기존 Workload Identity 기반 자격 증명 사용 | `read` | — | `manage` |
| Workload Identity 구성(및 이를 참조하는 자격 증명) 생성, 편집 또는 삭제 | `manage` | `manage` | `manage` |
<Note>
**소유자(Owner)**는 모든 기능에 대해 자동으로 전체 접근 권한을 가집니다. 기본 **멤버(Member)** 역할은 의도적으로 `secret_providers` 및 `workload_identity_configs`를 제외합니다 — 관리자는 사용자 정의 역할을 통해 멤버에게 명시적으로 옵트인해야 합니다.
</Note>
### 할당 방법
1. CrewAI Platform에서 **Settings** → **Roles**로 이동합니다. 이 페이지에서 새 역할을 생성하고, 각 역할의 권한을 편집하며, 조직의 기존 멤버에게 역할을 할당할 수 있습니다.
{/* 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. **Create Role**을 클릭하여 새 역할을 만들거나, 기존 역할을 열어 권한을 편집합니다.
3. 역할의 권한 편집기에서 위 표에 따라 관련 기능을 토글합니다:
- `secret_providers`: 이 역할이 기존 자격 증명만 사용하면 되는 경우 **read**를 선택하고, 자격 증명을 생성, 편집, 삭제할 수도 있어야 하면 **manage**를 선택합니다.
- `environment_variables`: 역할이 시크릿을 참조하는 환경 변수를 생성할 수 있도록 **manage**를 선택합니다.
{/* 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. 역할을 저장합니다.
5. 동일한 Roles 페이지(또는 조직 Members 목록)에서 해당 멤버에게 역할을 할당합니다.
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
## 환경 변수에서 시크릿 참조하기
공급자 자격 증명이 존재하고 역할에 적절한 권한이 있으면, 모든 환경 변수에서 관리되는 시크릿을 참조할 수 있습니다.
CrewAI Platform에서 **Environment Variables**로 이동하여 **Add Environment Variables**를 클릭합니다.
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
폼을 작성합니다:
- **Key** — 환경 변수의 이름입니다. 문자나 밑줄로 시작해야 하며, 문자, 숫자, 밑줄만 포함해야 합니다. 관례적으로 대문자로 작성합니다(예: `OPENAI_API_KEY`).
- **Value Source** — 값의 출처를 선택합니다:
- **Direct Value** — 직접 입력하는 평문 값입니다. 공급자를 사용하고 싶지 않을 때 사용합니다.
- **Use AWS default** (또는 공급자에 해당하는 항목) — 해당 공급자 유형에서 기본값으로 표시된 자격 증명을 사용합니다.
- **특정 명명된 자격 증명** — 이름으로 자격 증명을 선택합니다. 동일한 공급자에 대해 여러 자격 증명(예: `aws-prod`와 `aws-staging`)이 있고 하나를 명시적으로 선택하려는 경우에 사용합니다.
{/* 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** — 공급자의 시크릿 이름입니다. 자격 증명이 선택되면 이 필드에서 자동 완성을 제공합니다: 입력을 시작하면 CrewAI Platform이 일치하는 시크릿 이름을 공급자에 쿼리합니다.
구조화된(JSON) 시크릿에서 단일 필드를 추출하려면 `secret-name#json_key` 구문을 사용합니다. 예를 들어, `{"username": "...", "password": "..."}` 값을 가진 시크릿 `database-credentials`가 있다면, `database-credentials#password`로 참조하여 비밀번호만 주입할 수 있습니다.
{/* 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>
**Azure Key Vault 참고:** Azure 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 `Secret Name` 필드의 밑줄을 자동으로 하이픈으로 변환합니다(예: `db_password`는 `db-password`로 전송됨).
</Note>
**Create**를 클릭하여 변수를 저장합니다.
{/* 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>
기존 환경 변수를 편집할 때 **Value** 필드를 비워두면 현재 값이 유지됩니다. 이는 의도된 동작이며 — 값을 다시 입력하지 않고도 다른 필드(시크릿 이름이나 자격 증명 등)를 변경할 수 있게 해줍니다.
</Tip>
## 작동 여부 검증
엔드 투 엔드 검증 방법:
1. 다른 환경 변수와 동일한 방식으로 자동화, Crew 또는 배포에서 환경 변수를 참조합니다.
2. 자동화를 배포합니다.
3. 실행을 트리거하고 성공적으로 완료되는지 확인합니다.
### 로테이션 동작은 자격 증명 경로에 따라 다릅니다
| 자격 증명 경로 | 시크릿이 읽히는 시점 | 로테이션 시 필요한 작업 |
|---|---|---|
| **정적 자격 증명** (AWS 액세스 키, GCP 서비스 계정 JSON) | **배포 시점** — 값이 배포 이미지에 박힘 | 시크릿 로테이션 후 자동화 재배포 |
| **Workload Identity** (OIDC federation, AWS 또는 GCP) | **모든 자동화 kickoff 시점** — 값을 클라우드에서 새로 가져옴 | 없음 — 로테이션 후 다음 kickoff에서 새 값이 보임 |
<Note>
**로테이션 인식 시크릿이 필요한 경우**(로테이션 시 재배포 없이), Workload Identity 경로를 사용하세요: [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity). 트레이드오프는 초기 설정 노력이 더 많지만(CrewAI Platform을 클라우드에 OIDC 공급자로 등록), 장기적으로는 운영이 더 단순해진다는 점입니다.
</Note>
배포 또는 실행이 시크릿 관련 오류로 실패하면 가장 일반적인 원인을 확인하세요:
| 증상 | 가능한 원인 |
|---|---|
| `no credential found` | 환경 변수가 공급자를 참조하지만 특정 자격 증명이 선택되지 않았고, 해당 공급자 유형에 대한 기본 자격 증명이 설정되어 있지 않습니다. 변수에서 자격 증명을 명시적으로 선택하거나, **Secret Provider Credentials** 페이지에서 자격 증명을 기본값으로 표시하세요. |
| `secret not found` | **Secret Name**의 오타, 또는 자격 증명이 가리키는 공급자 계정/리전에 시크릿이 존재하지 않습니다. 둘 다 다시 확인하세요. |
| 로테이션 후에도 자동화가 이전 값으로 실행됨 (정적 자격 증명 경로) | 이전 값이 배포 컨테이너 이미지에 박혀 있습니다. 로테이션된 값을 가져오려면 자동화를 재배포하세요. 이를 완전히 피하려면 자격 증명을 Workload Identity 경로로 전환하세요. |
| 로테이션 후에도 자동화가 이전 값으로 실행됨 (Workload Identity 경로) | 환경 변수가 WI 기반 자격 증명을 참조하는지 확인하세요(정적 키가 아님). WI를 사용하면 로테이션 후 다음 kickoff에서 새 값이 보여야 합니다. 그렇지 않으면 시크릿이 실제로 클라우드에서 업데이트되었는지 확인하세요(예: `aws secretsmanager get-secret-value`). |
| `JSON key not found` | `secret-name#json_key`를 사용할 때 기본 시크릿은 해당 키를 포함하는 유효한 JSON 객체여야 합니다. 공급자에서 직접 시크릿을 읽어 확인하세요. |
## 다음 단계
- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview)
- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp)
- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity)

261
docs/edge/ko/enterprise/features/secrets-manager/verify-rotation.mdx Normal file
View File

@@ -0,0 +1,261 @@
---
title: 로테이션 확인
description: 클라우드 공급자에서 로테이션된 시크릿이 재배포 없이 실행 중인 배포에 전파됨을 증명하는 자체 포함된 예제 Crew입니다.
sidebarTitle: 로테이션 확인
icon: "arrows-rotate"
---
## 개요
이 가이드는 **클라우드 공급자에서 로테이션된 시크릿이 바로 다음 자동화 kickoff에서 적용됨**을 검증하는 방법을 보여줍니다 — 재배포 없음, 워커 재시작 없음. Workload Identity 기반 자격 증명([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity))을 구성한 경우에만 관련됩니다. 정적 자격 증명 배포는 로테이션 후 재배포가 필요합니다. 여기에서는 확인할 것이 없습니다.
아래 레시피는 하나의 도구, 하나의 에이전트, 하나의 작업으로 구성된 작은 자체 포함된 Crew를 사용합니다. Crew 프롬프트는 시크릿 값을 절대 참조하지 않으며 — 대신 도구가 `os.environ`에서 이를 읽고 본 것의 SHA-256 fingerprint를 보고합니다. 클라우드 공급자에서 시크릿을 로테이션하고, 다시 kickoff하면 fingerprint가 변경됩니다.
<Note>
원시 값이 아닌 fingerprint를 사용하는 이유? 원시 시크릿을 LLM 출력과 트레이스 로그에 넣는 것은 유출 벡터입니다. fingerprint는 실제 값을 관찰 가능한 곳에 쓰지 않고도 "값이 변경되었다"는 것을 확인하기에 충분합니다.
</Note>
## 사전 준비 사항
이 검증을 실행하기 전에:
- WI 기반 Secret Provider Credential이 구성되어 있어야 합니다([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity)).
- `Secret = true`, 키 `API_KEY`(또는 원하는 이름 — 아래 도구를 일치시키도록 조정)로 클라우드 공급자의 시크릿을 참조하는 배포의 환경 변수.
- 클라우드 공급자에서 시크릿 값을 업데이트할 방법(CLI 액세스 또는 클라우드 콘솔).
- HTTP를 통해 배포를 kickoff할 방법(curl, Postman, 또는 CrewAI Platform의 **Run** 탭).
## 1단계 — 검증 Crew 스캐폴딩
이 예제는 `crew.py`를 통해 Python 도구를 연결하므로 클래식 crew 프로젝트를 만듭니다:
```bash
crewai create crew rotation_verifier --classic --skip_provider
cd rotation_verifier
```
## 2단계 — Credential Echo 도구 추가
`src/rotation_verifier/tools/custom_tool.py`를 시크릿 기반 환경 변수를 읽고 fingerprint를 반환하는 도구로 교체합니다:
```python src/rotation_verifier/tools/credential_echo_tool.py
"""Tool that verifies a runtime-injected secret without leaking the value.
Reads the secret-backed env var (populated by the workload-identity
secrets manager at kickoff time) and returns a stable fingerprint. Never
echo raw credential values into LLM output or logs in production code —
the fingerprint alone is sufficient to confirm rotation worked.
"""
from __future__ import annotations
import hashlib
import os
from crewai.tools import BaseTool
# Match the deployment environment variable's `key` field.
ENV_VAR_NAME = "API_KEY"
class CredentialEchoTool(BaseTool):
name: str = "credential_echo"
description: str = (
"Read the API credential from the worker's environment and return a "
"fingerprint summary. Use this exactly once when asked to verify the "
"current credential. Takes no arguments."
)
def _run(self) -> str:
value = os.environ.get(ENV_VAR_NAME)
if not value:
return (
f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-"
"identity secret fetch did not run, or the deployment is "
"missing the secret-backed env var."
)
fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12]
return f"Authenticated. credential.fingerprint=sha256:{fingerprint}"
```
## 3단계 — 기본 에이전트 및 작업 구성 교체
Crew에는 하나의 에이전트와 하나의 작업이 있습니다 — 둘 다 시크릿 값을 **절대** 언급하지 않는 설명을 가지므로, 작업 키가 로테이션 전반에 걸쳐 안정적으로 유지됩니다.
```yaml src/rotation_verifier/config/agents.yaml
credential_checker:
role: >
Credential Verifier
goal: >
Confirm that the workload-identity-backed secret reached this worker
process and report a fingerprint of the current value.
backstory: >
You are a no-nonsense reliability engineer responsible for verifying
that secrets fetched at runtime via workload identity are present
and fresh. You always use the credential_echo tool exactly once and
report the result verbatim — you never make up values.
```
```yaml src/rotation_verifier/config/tasks.yaml
verify_credential_task:
description: >
Use the credential_echo tool to read the runtime-injected credential
and produce a one-line confirmation. The current year is {current_year}
(use it only in the timestamp; do not transform the credential output).
expected_output: >
A single line in the form:
"[{current_year}] <credential_echo tool's exact output>"
agent: credential_checker
```
## 4단계 — Crew 클래스 연결
```python src/rotation_verifier/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool
@CrewBase
class RotationVerifierCrew():
"""Single-task crew that verifies a workload-identity-backed secret
was successfully fetched at runtime.
Rotate the underlying secret in the cloud provider, kickoff again, and
the credential fingerprint in the agent's report changes — without any
re-deploy, worker restart, or input change. The crew prompt itself
never references the secret value.
"""
agents: list[BaseAgent]
tasks: list[Task]
@agent
def credential_checker(self) -> Agent:
return Agent(
config=self.agents_config["credential_checker"],
tools=[CredentialEchoTool()],
verbose=True,
)
@task
def verify_credential_task(self) -> Task:
return Task(config=self.tasks_config["verify_credential_task"])
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
## 5단계 — 배포 및 시크릿 환경 변수 구성
다른 Crew와 마찬가지로 이 Crew를 CrewAI Platform에 배포합니다. 그런 다음 배포의 **Environment Variables** 페이지에서:
- **Key:** `API_KEY` (도구의 `ENV_VAR_NAME`과 일치해야 함)
- **Value Source:** [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에서 설정한 WI 기반 자격 증명
- **Secret Name:** 클라우드 공급자의 Secret Manager에 있는 시크릿 이름
{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */}
## 6단계 — 첫 번째 Kickoff 실행
`<DEPLOYMENT_AUTH_TOKEN>`과 `<DEPLOYMENT_HOST>`를 배포의 **Run** 탭에 있는 값으로 교체합니다.
```bash
curl -m 60 \
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
-H "Content-Type: application/json" \
-X POST https://<DEPLOYMENT_HOST>/kickoff \
-d '{"inputs":{"current_year":"2026"}}'
```
kickoff가 완료되면(몇 초), 에이전트의 출력을 확인합니다. 다음과 같이 표시됩니다:
```
[2026] Authenticated. credential.fingerprint=sha256:004421b993c9
```
fingerprint를 기록합니다. 그 해시는 클라우드 공급자에 현재 있는 어떤 시크릿 값과 고유하게 연결되어 있습니다.
## 7단계 — 클라우드 공급자에서 시크릿 로테이션
<Tabs>
<Tab title="AWS">
```bash
aws secretsmanager update-secret \
--region <REGION> \
--secret-id <SECRET_NAME> \
--secret-string "rotated value"
```
</Tab>
<Tab title="GCP">
새 버전을 추가합니다(Secret Manager는 항상 `latest`를 읽음):
```bash
echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
--data-file=- \
--project=<YOUR_PROJECT_ID>
```
</Tab>
<Tab title="Azure">
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name <SECRET_NAME> \
--value "rotated value"
```
</Tab>
</Tabs>
## 8단계 — 두 번째 Kickoff 실행 및 비교
```bash
curl -m 60 \
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
-H "Content-Type: application/json" \
-X POST https://<DEPLOYMENT_HOST>/kickoff \
-d '{"inputs":{"current_year":"2026"}}'
```
이제 에이전트의 출력은 **다른 fingerprint**를 보여줍니다:
```
[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72
```
이는 재배포, 워커 재시작 또는 기타 운영자 작업 없이 실행 중인 배포에서 로테이션이 적용되었음을 증명합니다.
## 이것이 검증하는 것 — 그리고 검증하지 않는 것
**검증하는 것:**
- CrewAI Platform에서 WI OIDC 토큰 발급이 작동합니다.
- 클라우드 측 신뢰(AWS의 IAM OIDC 공급자, GCP의 Workload Identity Pool, Azure의 Federated Identity Credential)가 토큰을 수락합니다.
- 클라우드 측 ID(IAM Role / GCP 서비스 계정 / Entra App Registration)가 시크릿을 읽을 수 있는 액세스 권한을 가집니다.
- 시크릿 값이 kickoff 시점에 워커 프로세스의 `os.environ`에 도달합니다.
- 후속 로테이션이 다음 kickoff에 전파됩니다.
**검증하지 않는 것:**
- 실제 프로덕션 Crew가 로테이션을 우아하게 처리하는지 — 예를 들어, 시작 시 환경 변수를 한 번만 읽는 장기 실행 작업은 작업이 끝날 때까지 이전 값을 계속 사용합니다. 적절히 계획하세요: 모듈 임포트 시가 아닌 사용 시점에 시크릿을 읽으세요.
## 왜 프롬프트에서 직접 시크릿을 참조하지 않나요?
더 간단해 보이는 데모는 시크릿 값을 작업 설명에 직접 넣고(예: "`{api_key}`에 대해 조사") 프롬프트를 검사하는 것입니다. **그렇게 하지 마세요.** 두 가지 이유:
1. **LLM 호출 트레이스와 공급자 측 로그에 시크릿이 유출됩니다.** 트레이스 액세스가 있는 모든 사람이 읽을 수 있습니다.
2. **모든 kickoff에서 작업 설명이 변경됩니다.** CrewAI Platform은 설명의 MD5 해시로 작업을 식별합니다. 로테이션되는 값은 kickoff마다 해시가 변경되어 배포 시간 → 런타임 작업 매핑이 깨집니다. 증상: 작업 레코드가 무한정 `pending_run`으로 표시되거나 다중 작업 Crew의 일부 작업만 등록됩니다.
이 가이드의 도구 기반 패턴은 두 문제를 모두 회피합니다: 프롬프트는 정적이고, 도구가 런타임에 환경 변수를 읽으며, 값의 fingerprint만 LLM에 도달합니다.
## 다음 단계
- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview)
- 검증되면 검증 Crew를 삭제합니다. 실제 Crew는 동일한 패턴을 따라야 합니다: 시크릿은 도구 내부의 `os.environ`을 통해 액세스되며, 절대 프롬프트에 치환되지 않습니다.

248
docs/edge/ko/enterprise/features/tools-and-integrations.mdx Normal file
View File

@@ -0,0 +1,248 @@
---
title: "도구 & 통합"
description: "외부 앱을 연결하고 에이전트가 사용할 내부 도구를 관리하세요."
icon: "wrench"
mode: "wide"
---
## 개요
도구 & 통합은 서드파티 애플리케이션을 연결하고 에이전트가 런타임에 사용할 내부 도구를 관리하는 중앙 허브입니다.
<Frame>![도구 & 통합 개요](/images/enterprise/crew_connectors.png)</Frame>
## 살펴보기
<Tabs>
<Tab title="통합" icon="plug">
## 에이전트 앱 (통합)
Gmail, Google Drive, HubSpot, Slack 등 OAuth 기반 서비스에 연결하여 에이전트 액션을 활성화하세요.
{" "}
<Steps>
<Step title="연결">
원하는 앱에서 <b>Connect</b>를 클릭하고 OAuth를 완료합니다.
</Step>
<Step title="구성">
필요에 따라 스코프, 트리거, 사용 가능한 액션을 조정합니다.
</Step>
<Step title="에이전트에서 사용">
연결된 서비스는 에이전트 도구로 사용 가능합니다.
</Step>
</Steps>
{" "}
<Frame>![앱 그리드](/images/enterprise/agent-apps.png)</Frame>
### 계정 연결하기
1. <Link href="https://app.crewai.com/crewai_plus/connectors">
Integrations
</Link>
로 이동
2. 원하는 서비스에서 <b>Connect</b> 클릭
3. OAuth 플로우 완료 및 스코프 승인
4. <Link href="https://app.crewai.com/crewai_plus/settings/integrations">
통합 설정
</Link>
에서 Enterprise Token 복사
{" "}
<Frame>
![Enterprise Token](/images/enterprise/enterprise_action_auth_token.png)
</Frame>
### 통합 도구 설치
로컬에서 통합을 사용하려면 최신 `crewai-tools` 패키지를 설치하세요.
```bash
uv add crewai-tools
```
### 환경 변수 설정
{" "}
<Note>
`Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로
`CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다.
</Note>
```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```
또는 `.env` 파일에 추가하세요:
```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```
### 사용 예시
{" "}
<Tip>
새로운 간소화된 접근 방식을 사용하여 엔터프라이즈 앱을 통합하세요. Agent
구성에서 앱과 해당 액션을 직접 지정하기만 하면 됩니다.
</Tip>
```python
from crewai import Agent, Task, Crew
# Gmail 기능을 가진 에이전트 생성
email_agent = Agent(
role="이메일 매니저",
goal="이메일 커뮤니케이션 관리",
backstory="이메일 관리에 특화된 AI 어시스턴트",
apps=['gmail', 'gmail/send_email'] # 정식 이름 'gmail' 사용
)
email_task = Task(
description="프로젝트 업데이트에 대한 후속 이메일 작성 및 전송",
agent=email_agent,
expected_output="이메일 전송 성공 확인"
)
crew = Crew(agents=[email_agent], tasks=[email_task])
crew.kickoff()
```
### 도구 필터링
```python
from crewai import Agent, Task, Crew
# 특정 Gmail 액션만 사용하는 에이전트 생성
gmail_agent = Agent(
role="Gmail 매니저",
goal="Gmail 커뮤니케이션 및 알림 관리",
backstory="Gmail 커뮤니케이션 조율 AI 어시스턴트",
apps=['gmail/fetch_emails'] # 정식 이름과 특정 액션 사용
)
notification_task = Task(
description="john@example.com에서 온 이메일 찾기",
agent=gmail_agent,
expected_output="john@example.com의 이메일을 찾았다는 확인"
)
crew = Crew(agents=[gmail_agent], tasks=[notification_task])
```
배포된 크루에서는 각 통합의 서비스 설정 페이지에서 사용 가능한 액션을 지정할 수 있습니다.
{" "}
<Frame>
![액션 필터링](/images/enterprise/filtering_enterprise_action_tools.png)
</Frame>
### 범위 지정 배포 (다중 사용자 조직)
각 통합을 특정 사용자로 범위 지정할 수 있습니다 (예: 특정 사용자의 Gmail 계정 사용).
{" "}
<Tip>팀/사용자별 데이터 접근을 분리해야 할 때 유용합니다.</Tip>
`user_bearer_token`을 사용해 요청 사용자로 인증을 범위 지정합니다. 사용자가 로그인하지 않은 경우 연결된 통합을 사용하지 않으며, 그렇지 않으면 배포에 설정된 기본 토큰을 사용합니다.
{" "}
<Frame>![사용자 토큰](/images/enterprise/user_bearer_token.png)</Frame>
{" "}
<div id="catalog"></div>
### 카탈로그
#### 커뮤니케이션 & 협업
- Gmail — 이메일 및 초안 관리
- Slack — 워크스페이스 알림 및 경보
- Microsoft — Office 365 및 Teams 통합
#### 프로젝트 관리
- Jira — 이슈 추적 및 프로젝트 관리
- ClickUp — 작업 및 생산성 관리
- Asana — 팀 작업 조율
- Notion — 페이지 및 데이터베이스 관리
- Linear — 버그/프로젝트 추적
- GitHub — 리포지토리 및 이슈 관리
#### CRM
- Salesforce — 계정 및 기회 관리
- HubSpot — 파이프라인/연락처 관리
- Zendesk — 고객 지원 티켓 관리
#### 비즈니스 & 금융
- Stripe — 결제 처리 및 고객 관리
- Shopify — 전자상거래 및 상품 관리
#### 생산성 & 스토리지
- Google Sheets — 스프레드시트 동기화
- Google Calendar — 일정/이벤트 관리
- Box — 파일 스토리지
…더 많은 통합이 추가될 예정입니다!
</Tab>
<Tab title="내부 도구" icon="toolbox">
## 내부 도구
로컬에서 도구를 만들고, CrewAI AMP 도구 저장소에 게시한 후, 에이전트에서 사용하세요.
{" "}
<Tip>
아래 명령을 실행하기 전에 CrewAI AMP 계정에 로그인하세요: ```bash crewai login```
</Tip>
{" "}
<Frame>![내부 도구](/images/enterprise/tools-integrations-internal.png)</Frame>
{" "}
<Steps>
<Step title="생성">
로컬에서 새 도구 생성 ```bash crewai tool create your-tool ```
</Step>
<Step title="게시">도구 저장소에 게시 ```bash crewai tool publish ```</Step>
<Step title="설치">
도구 저장소에서 설치 ```bash crewai tool install your-tool ```
</Step>
</Steps>
관리:
- 이름 및 설명
- 가시성 (비공개 / 공개)
- 필요한 환경 변수
- 버전 이력 및 다운로드
- 팀/역할 접근 권한
{" "}
<Frame>![도구 설정](/images/enterprise/tool-configs.png)</Frame>
</Tab>
</Tabs>
## 관련 문서
<CardGroup cols={2}>
<Card
title="도구 저장소"
href="/ko/enterprise/guides/tool-repository"
icon="toolbox"
>
크루 기능을 확장할 수 있도록 도구를 게시하고 설치하세요.
</Card>
<Card
title="Webhook 자동화"
href="/ko/enterprise/guides/webhook-automation"
icon="bolt"
>
워크플로를 자동화하고 외부 플랫폼/서비스와 통합하세요.
</Card>
</CardGroup>

142
docs/edge/ko/enterprise/features/traces.mdx Normal file
View File

@@ -0,0 +1,142 @@
---
title: 트레이스
description: "Traces를 사용하여 내 크루 모니터링하기"
icon: "timeline"
mode: "wide"
---
## 개요
Trace는 crew 실행에 대한 포괄적인 가시성을 제공하여 성능 모니터링, 문제 디버깅, AI agent workflow 최적화에 도움을 줍니다.
## Traces란 무엇인가요?
CrewAI AOP의 Traces는 crew의 작동 과정을 처음 입력에서 최종 출력까지 모든 측면에서 포착하는 상세 실행 기록입니다. Traces에는 다음 내용이 기록됩니다:
- Agent의 생각 및 추론
- 작업 실행 세부 정보
- 도구 사용 및 출력
- 토큰 소모 메트릭
- 실행 시간
- 비용 추정치
<Frame>![Traces Overview](/images/enterprise/traces-overview.png)</Frame>
## 트레이스(Traces) 접근하기
<Steps>
<Step title="트레이스 탭으로 이동">
CrewAI AMP 대시보드에 들어가면, **트레이스**를 클릭하여 모든 실행 기록을 볼 수 있습니다.
</Step>
<Step title="실행 선택하기">
모든 crew 실행 목록이 날짜별로 정렬되어 표시됩니다. 상세 트레이스를 보려면 원하는 실행을 클릭하세요.
</Step>
</Steps>
## 트레이스 인터페이스 이해하기
트레이스 인터페이스는 여러 섹션으로 나뉘어 있으며, 각 섹션은 crew의 실행에 대한 다양한 인사이트를 제공합니다.
### 1. 실행 요약
상단 섹션에서는 실행에 대한 고수준 메트릭을 표시합니다:
- **총 토큰**: 모든 작업에서 소모된 토큰 수
- **프롬프트 토큰**: LLM에 프롬프트로 사용된 토큰
- **컴플리션 토큰**: LLM 응답에서 생성된 토큰
- **요청 수**: 수행된 API 호출 수
- **실행 시간**: crew 런의 전체 소요 시간
- **예상 비용**: 토큰 사용량을 기반으로 한 대략적인 비용
<Frame>![Execution Summary](/images/enterprise/trace-summary.png)</Frame>
### 2. Tasks & Agents
이 섹션에서는 crew 실행에 포함된 모든 task와 agent를 보여줍니다:
- task 이름 및 agent 할당
- 각 task에 사용된 agent 및 LLM
- 상태 (완료/실패)
- task의 개별 실행 시간
<Frame>![Task List](/images/enterprise/trace-tasks.png)</Frame>
### 3. 최종 결과
모든 작업이 완료된 후 crew가 생성한 최종 결과를 표시합니다.
<Frame>![최종 결과](/images/enterprise/final-output.png)</Frame>
### 4. 실행 타임라인
각 작업이 시작되고 종료된 시점을 시각적으로 표현하여 병목 현상이나 병렬 실행 패턴을 파악하는 데 도움이 됩니다.
<Frame>![실행 타임라인](/images/enterprise/trace-timeline.png)</Frame>
### 5. 상세 작업 보기
타임라인이나 작업 목록에서 특정 작업을 클릭하면 다음을 볼 수 있습니다:
<Frame>![상세 작업 보기](/images/enterprise/trace-detailed-task.png)</Frame>
- **작업 키**: 작업의 고유 식별자
- **작업 ID**: 시스템 내의 기술적 식별자
- **상태**: 현재 상태 (완료/진행 중/실패)
- **에이전트**: 해당 작업을 수행한 에이전트
- **LLM**: 이 작업에 사용된 언어 모델
- **시작/종료 시간**: 작업이 시작되고 완료된 시간
- **실행 시간**: 이 특정 작업의 소요 시간
- **작업 설명**: 에이전트에게 지시된 작업 내용
- **예상 출력**: 요청된 출력 형식
- **입력**: 이전 작업에서 이 작업에 제공된 입력값
- **출력**: 에이전트가 실제로 생성한 결과
## 디버깅을 위한 트레이스 사용
트레이스는 crew 문제 해결에 매우 유용합니다:
<Steps>
<Step title="실패 지점 식별">
crew 실행이 예상한 결과를 내지 못할 때, 트레이스를 확인하여 어디에서 문제가 발생했는지 찾으세요. 다음을 확인하세요:
- 실패한 작업
- 에이전트의 예상 밖 결정
- 도구 사용 오류
- 잘못 해석된 지침
<Frame>
![Failure Points](/images/enterprise/failure.png)
</Frame>
</Step>
<Step title="성능 최적화">
실행 메트릭을 사용하여 성능 병목 현상을 파악하세요:
- 예상보다 오래 걸린 작업
- 과도한 토큰 사용
- 중복된 도구 작업
- 불필요한 API 호출
</Step>
<Step title="비용 효율성 향상">
토큰 사용량 및 비용 추정치를 분석해 crew의 효율성을 최적화하세요:
- 더 간단한 작업에는 더 작은 모델을 사용 고려
- 프롬프트를 더 간결하게 다듬기
- 자주 액세스하는 정보 캐싱
- 중복 작업을 최소화하도록 작업 구조화하기
</Step>
</Steps>
<Card
title="도움이 필요하신가요?"
icon="headset"
href="mailto:support@crewai.com"
>
트레이스 분석이나 기타 CrewAI 엔터프라이즈 기능에 대한 지원이 필요하시면 저희
지원팀에 문의하세요.
</Card>

82
docs/edge/ko/enterprise/features/webhook-streaming.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
title: 웹훅 스트리밍
description: "웹훅 스트리밍을 사용하여 이벤트를 웹훅으로 스트리밍하기"
icon: "webhook"
mode: "wide"
---
## 개요
Enterprise Event Streaming을 사용하면 CrewAI AOP에 배포된 crew 및 flow에 대한 실시간 웹훅 업데이트(예: 모델 호출, 도구 사용, flow 단계)를 받을 수 있습니다.
## 사용법
Kickoff API를 사용할 때, 요청에 `webhooks` 객체를 포함시키세요. 예를 들면 아래와 같습니다:
```json
{
"inputs": {"foo": "bar"},
"webhooks": {
"events": ["crew_kickoff_started", "llm_call_started"],
"url": "https://your.endpoint/webhook",
"realtime": false,
"authentication": {
"strategy": "bearer",
"token": "my-secret-token"
}
}
}
```
`realtime`이 `true`로 설정되면, 각 이벤트가 개별적으로 그리고 즉시 전달되지만 crew/flow 성능에 영향을 미칠 수 있습니다.
## Webhook 형식
각 webhook은 이벤트 목록을 전송합니다:
```json
{
"events": [
{
"id": "event-id",
"execution_id": "crew-run-id",
"timestamp": "2025-02-16T10:58:44.965Z",
"type": "llm_call_started",
"data": {
"model": "gpt-4",
"messages": [
{"role": "system", "content": "You are an assistant."},
{"role": "user", "content": "Summarize this article."}
]
}
}
]
}
```
`data` 객체의 구조는 이벤트 타입에 따라 다릅니다. 자세한 내용은 GitHub의 [이벤트 목록](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)을 참조하세요.
요청이 HTTP를 통해 전송되므로, 이벤트의 순서가 보장되지 않습니다. 순서가 필요하다면 `timestamp` 필드를 사용하세요.
## 지원되는 이벤트
CrewAI는 Enterprise Event Streaming에서 시스템 이벤트와 사용자 지정 이벤트 둘 다를 지원합니다. 이러한 이벤트는 crew 및 flow 실행 중에 구성한 웹훅 엔드포인트로 전송됩니다.
- `crew_kickoff_started`
- `crew_step_started`
- `crew_step_completed`
- `crew_execution_completed`
- `llm_call_started`
- `llm_call_completed`
- `tool_usage_started`
- `tool_usage_completed`
- `crew_test_failed`
- *...그리고 기타 여러 가지*
이벤트 이름은 내부 이벤트 버스와 일치합니다. 전체 목록은 [GitHub 소스](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)에서 확인할 수 있습니다.
사용자 지정 이벤트도 직접 발생시킬 수 있으며, 시스템 이벤트와 함께 웹훅 스트림을 통해 전달됩니다.
<Card title="도움이 필요하신가요?" icon="headset" href="mailto:support@crewai.com">
웹훅 통합 또는 문제 해결에 대한 지원이 필요하다면 저희 지원팀에 문의해 주세요.
</Card>