즉석에서 프로젝트를 거버넌스 폴리시에 할당하기

즉석에서 프로젝트를 거버넌스 폴리시에 할당하기 (Assign Projects to Governance Policies on the Fly)

CI/CD 파이프라인에서 바로 각 프로젝트를 올바른 거버넌스 폴리시에 등록해, 수동 UI 단계 없이 모든 배포가 게이팅되게 하는 방법을 설명하는 문서예요. 이 문서에서는 Admin SDK 구성, 대상 폴리시 찾기, 프로젝트 할당, 그리고 등록 검증을 다뤄요.

출처: 문서

본문

개요 (Overview)

이 가이드는 규모에 맞춰 AI 거버넌스를 운영하는 팀 — 보통 고객별 또는 에이전트별로 Confident AI 프로젝트 하나를 쓰는 팀 — 이 모든 프로젝트를 자동으로, 아무도 플랫폼 UI를 클릭하지 않고 거버넌스 폴리시에 등록해야 하는 경우를 위한 문서예요.

이는 에이전트용 프로젝트 즉석 프로비저닝을 직접 이어받아요. 파이프라인이 프로젝트를 만들면, 다음 단계는 그 프로젝트를 배포를 게이팅하는 거버넌스 폴리시에 등록하는 거예요. 거버넌스 폴리시는 조직 범위(명명된 컨트롤 묶음)이고, 각 프로젝트는 최대 하나의 폴리시에 속해요.

이 가이드에서 여러분은:

하나의 조직 API 키로 Admin SDK를 구성해요.
이름으로 대상 거버넌스 폴리시를 찾아요.
파이프라인의 일부로 코드에서 프로젝트를 폴리시에 할당해요.
프로젝트의 폴리시를 다시 읽어 등록을 검증해요.

구축하기 (Build It)

Admin SDK 설치

거버넌스 폴리시는 confidentai Admin SDK로 관리돼요.

Python

pip install confidentai

TypeScript

npm install confidentai

Admin SDK 구성

시작 전에 조직 API 키가 필요해요. 여기서 가져오세요.

CONFIDENT_ORG_API_KEY에 조직 API 키를 설정해요. Admin SDK는 클라이언트를 만들 때 기본적으로 이 변수를 읽어요.

export CONFIDENT_ORG_API_KEY="confident_us_org_..."

Python

from confidentai import ConfidentAI

confident_ai = ConfidentAI()

TypeScript

import { ConfidentAI } from "confidentai";

const confidentAI = new ConfidentAI();

대상 폴리시 찾기

거버넌스 폴리시는 플랫폼 UI에서 만들거나 create_governance_policy로 만들 수 있고, 컨트롤은 UI에서 구성돼요. 코드에서는 목록을 나열하고 보통 이름으로 배포를 게이팅할 폴리시를 골라요.

Python

from confidentai import ConfidentAI

confident_ai = ConfidentAI()

def find_policy_id(policy_name: str) -> str:
    policies = confident_ai.organization.list_governance_policies()
    for policy in policies.governance_policies:
        if policy.name == policy_name:
            return policy.id
    raise ValueError(f"No governance policy named {policy_name!r}")

TypeScript

import { ConfidentAI } from "confidentai";

const confidentAI = new ConfidentAI();

async function findPolicyId(policyName: string): Promise<string> {
  const policies = await confidentAI.organization.listGovernancePolicies();
  const policy = policies.governancePolicies.find((p) => p.name === policyName);
  if (!policy) {
    throw new Error(`No governance policy named ${policyName}`);
  }
  return policy.id;
}

목록의 각 폴리시는 controls와 projectsCount를 포함해요. 폴리시에 이미 등록된 프로젝트를 페이지네이션하려면 organization.list_governance_policy_projects(policy_id)(TypeScript: organization.listGovernancePolicyProjects(policyId))를 사용해요.

프로젝트 할당

프로젝트를 폴리시에 할당해요. 할당은 덧셈적이고 부분적이에요. 존재하는 모든 프로젝트는 등록되어 assignedProjectIds로 반환되고(다른 폴리시에 있는 건 이동), 폴리시의 다른 프로젝트는 건드리지 않아요. 조직에 존재하지 않는 id는 호출을 실패시키는 대신 notFoundProjectIds로 돌아와요. 그래서 오래된 id 하나가 배치 전체를 망치지 않아요. 이미 등록된 프로젝트를 다시 할당해도 카운트되므로, 파이프라인 실행마다 안전하게 실행할 수 있어요.

Python

from confidentai import ConfidentAI

confident_ai = ConfidentAI()

# find_policy_id() is defined above

def enroll_project(project_id: str, policy_name: str = "Production Gate") -> list[str]:
    policy_id = find_policy_id(policy_name)
    result = confident_ai.organization.assign_projects_to_governance_policy(
        policy_id, [project_id]
    )
    return result.assigned_project_ids

TypeScript

import { ConfidentAI } from "confidentai";

const confidentAI = new ConfidentAI();

// findPolicyId() is defined above

async function enrollProject(
  projectId: string,
  policyName = "Production Gate",
): Promise<string[]> {
  const policyId = await findPolicyId(policyName);
  const result =
    await confidentAI.organization.assignProjectsToGovernancePolicy(policyId, [
      projectId,
    ]);
  return result.assignedProjectIds;
}

폴리시에서 프로젝트를 제거하려면(예: 고객 프로비저닝 해제 시) 같은 방식으로 unassign_projects_from_governance_policy(policy_id, project_ids)(TypeScript: unassignProjectsFromGovernancePolicy)를 사용해요. unassignedProjectIds와 skippedProjectIds를 반환해요.

등록 검증

프로젝트를 다시 읽어 등록됐는지 확인해요. projects.list()(및 project(id).get())가 반환하는 모든 프로젝트는 governancePolicy를 포함해요. 등록되면 { id, name }, 아니면 null이에요.

Python

from confidentai import ConfidentAI

confident_ai = ConfidentAI()

project = confident_ai.project("project-uuid-1").get()
print(project.governance_policy)  # ProjectGovernancePolicy(id="...", name="Production Gate")

TypeScript

import { ConfidentAI } from "confidentai";

const confidentAI = new ConfidentAI();

const project = await confidentAI.project("project-uuid-1").get();
console.log(project.governancePolicy); // { id: "...", name: "Production Gate" }

완료됐어요! 이제 파이프라인이 단일 조직 API 키로 각 프로젝트를 올바른 거버넌스 폴리시에 등록해요.

CI에서 배포 게이팅

위의 모든 것은 플랫폼 팀의 몫이에요 — 프로비저닝의 일부로 각 프로젝트를 올바른 폴리시에 한 번 등록하는 것. 이후부터 프로젝트를 소유한 제품 팀은 deepeval CLI로 자체 배포를 게이팅해요. 조직 API 키는 필요 없고, 그 프로젝트의 프로젝트 API 키(CONFIDENT_API_KEY)만 필요해요.

Python

export CONFIDENT_API_KEY="confident_us_proj_..."
deepeval gate

TypeScript

export CONFIDENT_API_KEY="confident_us_proj_..."
npx deepeval gate

deepeval gate는 프로젝트 폴리시의 모든 컨트롤을 평가하고, 폴리시가 통과할 때만 코드 0으로 종료해요. Low 중요도보다 높은 컨트롤 중 하나라도 실패하면 0이 아닌 코드로 종료되고 배포가 멈춰요. 전체 레퍼런스는 CI/CD에서 배포 게이트 걸기를 참고해요.

즉석에서 프로젝트를 거버넌스 폴리시에 할당하기