Forge 시크릿 사용하기

Forge Secret Manager를 사용하면 서버리스 용량에서 실행되는 샌드박스 안에서 API 토큰과 기타 사용자 인증 정보를 사용할 수 있습니다. 애플리케이션이 Sandboxes API에 시크릿 이름을 전달하면, API는 샌드박스를 생성할 때 Forge 팀에서 해당 값을 조회해 환경 변수로 주입합니다.

시작하기 전에

Forge 시크릿 주입을 사용하려면 Forge API 키로 인증된 샌드박스가 필요합니다. 이 기능은 서버리스 샌드박스에서 사용할 수 있지만, 자체 CoreWeave Kubernetes Service(CKS) 클러스터의 샌드박스에서는 사용할 수 없습니다. CKS 배치에는 CoreWeave API 액세스 토큰이 사용됩니다. 이 토큰을 별도의 Forge API 키와 함께 사용하여 CKS 샌드박스의 시크릿을 가져올 수는 없습니다.

샌드박스 배치	샌드박스 사용자 인증 정보	Forge 시크릿 주입
서버리스	Forge API 키	지원됨. `wandb` 저장소를 사용하세요.
서버리스	CoreWeave API 액세스 토큰	지원되지 않음.
자체 CKS 클러스터	CoreWeave API 액세스 토큰	지원되지 않음. `FORGE_API_KEY`를 추가해도 활성화되지 않습니다.

예시를 따라 하려면 다음이 필요합니다.

서버리스 샌드박스 액세스 권한이 있는 Forge SaaS(Software as a Service) 계정
Forge 팀의 Secret Manager에 저장된 HF_TOKEN이라는 시크릿. 이 시크릿이 없으면 Forge Admin에게 시크릿 추가를 요청하세요.
해당 팀에 액세스할 수 있는 Forge API 키

샌드박스를 생성하는 프로세스의 환경에 FORGE_API_KEY를 설정하세요. [FORGE-API-KEY]는 본인의 Forge API 키로 바꾸세요.

export FORGE_API_KEY="[FORGE-API-KEY]"

FORGE_TEAM을 설정하지 않으면 예시에서는 API 키의 기본 팀을 사용합니다. 시크릿이 다른 팀에 속해 있다면 FORGE_TEAM을 해당 팀으로 설정하세요. [FORGE-TEAM]을 팀 이름으로 바꾸세요.

export FORGE_TEAM="[FORGE-TEAM]"

예시에서는 이러한 변수를 클라이언트에 명시적으로 전달합니다. SDK는 FORGE_API_KEY나 FORGE_TEAM을 자동으로 감지하지 않습니다. 사용하는 언어에 맞는 클라이언트를 설치하세요.

Python
TypeScript

Python 3.11 이상을 사용하고, 필요하면 uv를 설치하세요. Python 환경에 클라이언트를 설치하세요.

uv pip install 'cwsandbox>=1.14.2'

Node.js 22 이상을 사용하세요. TypeScript 클라이언트와 예시 실행에 필요한 tsx를 설치하세요.

npm install @coreweave/cwsandbox
npm install --save-dev tsx

실행할 TypeScript 예시를 secrets.mts로 저장한 다음 npx tsx secrets.mts를 실행하세요.

시크릿 주입

Python에서는 store="wandb"를, TypeScript에서는 store: "wandb"를 사용하세요. 이 저장소는 인증된 Forge 팀의 시크릿을 해석합니다. 이 플로우에서는 조직 시크릿 저장소를 등록할 필요가 없습니다. 다음 예시는 HF_TOKEN을 주입한 뒤, 값을 출력하지 않고 존재 여부만 확인합니다. 샌드박스에서 환경 변수 이름은 기본적으로 시크릿 이름과 같습니다.

Python
TypeScript

AuthHeaders를 통해 Forge API 키와 팀(선택 사항)을 전달하세요:

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  resources={"cpu": "1", "memory": "1Gi"},
  secrets=[Secret(store="wandb", name="HF_TOKEN")],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

Forge 진입점에서 클라이언트를 임포트하세요. runnerIds를 생략하면 클라이언트는 서버리스 배치를 사용합니다:

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
    secrets: [{ store: "wandb", name: "HF_TOKEN" }],
  },
);

console.log(result.stdout);

두 예시 모두 Secret is available을 출력하고, 오퍼레이션이 종료되면 샌드박스를 중지합니다. 샌드박스 내부에서 실행되는 코드는 HF_TOKEN에서 값을 읽을 수 있습니다. secrets에는 시크릿 값이 아닌 이름을 전달하세요. 값은 서버가 해석합니다. 값을 출력하거나 로그에 기록하지 마십시오.

시크릿 참조 필드

Python Secret 또는 TypeScript secrets 항목에서 이 필드를 사용하세요:

Python 필드	TypeScript 필드	Required	설명
`store`	`store`	Yes	시크릿 저장소 이름. Forge Secret Manager의 경우 `wandb`를 사용하세요.
`name`	`name`	Yes	선택한 Forge 팀의 Secret Manager에 있는 시크릿의 이름.
`field`	`field`	No	값이 JSON 객체인 시크릿에서 선택할 최상위 키. 전체 시크릿 값을 주입하려면 생략하세요.
`env_var`	`envVar`	No	값을 받는 환경 변수. 기본값은 `name`입니다.

맞춤형 환경 변수 이름 사용

시크릿을 받을 환경 변수를 선택하려면 Python에서 env_var를, TypeScript에서 envVar를 설정하세요. 다음 예시는 HF_TOKEN 시크릿을 HUGGINGFACE_TOKEN으로 노출합니다:

Python
TypeScript

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  secrets=[Secret(
    store="wandb",
    name="HF_TOKEN",
    env_var="HUGGINGFACE_TOKEN",
  )],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HUGGINGFACE_TOKEN'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    secrets: [{
      store: "wandb",
      name: "HF_TOKEN",
      envVar: "HUGGINGFACE_TOKEN",
    }],
  },
);

console.log(result.stdout);

두 예시 모두 HUGGINGFACE_TOKEN이 존재하는지 확인한 후 Secret is available을 출력합니다.

구조화된 시크릿에서 필드 선택

JSON 객체에서 하나의 값을 주입하려면 field를 해당 최상위 키로 설정하세요. 중첩된 경로는 지원되지 않습니다. JSON 문자열의 경우, 주입된 값에는 JSON 따옴표가 없습니다. 이 예제에서는 값이 {"password":"[DB-PASSWORD]"}와 같은 JSON 객체인 DB_CREDENTIALS라는 팀 시크릿을 추가하세요. 시크릿을 저장하기 전에 [DB-PASSWORD]를 비밀번호로 교체하세요. 예시에서는 password 필드를 DB_PASSWORD에 주입합니다:

Python
TypeScript

import os
from cwsandbox import AuthHeaders, Sandbox, Secret

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

with Sandbox.run(
  auth=forge_auth,
  placement_mode="serverless",
  container_image="python:3.11",
  secrets=[Secret(
    store="wandb",
    name="DB_CREDENTIALS",
    field="password",
    env_var="DB_PASSWORD",
  )],
) as sandbox:
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
  ]).result()
  print(result.stdout)

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('DB_PASSWORD'); print('Secret is available')",
  ]),
  {
    containerImage: "python:3.11",
    secrets: [{
      store: "wandb",
      name: "DB_CREDENTIALS",
      field: "password",
      envVar: "DB_PASSWORD",
    }],
  },
);

console.log(result.stdout);

두 예시 모두 비밀번호를 출력하지 않고 Secret is available을 출력합니다. 시크릿이 JSON 객체가 아니거나, 키가 존재하지 않거나, 값이 null이면 필드 선택이 실패합니다.

시크릿 참조 재사용

Python 세션의 경우, 공유 시크릿 참조를 SandboxDefaults에 넣으세요. TypeScript의 경우, 샌드박스를 생성할 때 secrets 배열을 재사용하세요:

Python
TypeScript

import os
from cwsandbox import AuthHeaders, SandboxDefaults, Secret, Session

forge_auth = AuthHeaders(
    headers={
        "x-wandb-api-key": os.environ["FORGE_API_KEY"],
        **({"x-entity-id": os.environ["FORGE_TEAM"]} if os.environ.get("FORGE_TEAM") else {}),
    },
    strategy="wandb_api_key",
)

defaults = SandboxDefaults(
  auth=forge_auth,
  placement_mode="serverless",
  secrets=(Secret(store="wandb", name="HF_TOKEN"),),
)

with Session(defaults) as session:
  sandbox = session.sandbox()
  result = sandbox.exec([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]).result()
  print(result.stdout)

Python 클라이언트는 세션 기본값을 샌드박스별 secrets와 병합하고 정확한 중복을 무시합니다. 서로 다른 레퍼런스가 동일한 환경 변수를 대상으로 하는 경우, 클라이언트는 샌드박스를 생성하기 전에 ValueError를 발생시킵니다. Python 유형 시그니처는 시크릿 참조를 참조하세요.

import { createSandboxClient } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClient({
  apiKey: process.env.FORGE_API_KEY,
  entity: process.env.FORGE_TEAM,
});
const secrets = [{ store: "wandb", name: "HF_TOKEN" }];

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run([
    "python", "-c",
    "import os; assert os.environ.get('HF_TOKEN'); print('Secret is available')",
  ]),
  { containerImage: "python:3.11", secrets },
);

console.log(result.stdout);

시크릿 주입 문제 해결

시크릿 참조로 샌드박스를 시작하지 못하면 오류 메시지를 통해 인증, 선택한 팀, 배치를 확인하세요.

오류 메시지	확인할 사항
`secret store "wandb" not found`	클라이언트에서 CoreWeave 인증을 선택했는지 확인하세요. 서버리스 배치의 경우 예시와 같이 Python에서는 `AuthHeaders`를 통해, TypeScript에서는 `@coreweave/cwsandbox/wandb`의 `createSandboxClient`를 통해 Forge 사용자 인증 정보를 전달하세요. `FORGE_API_KEY`만 설정해도 CoreWeave 인증을 사용하는 클라이언트가 Forge 인증으로 전환되지는 않습니다. 저장소를 등록할 필요는 없습니다.
`one or more W&B secrets not found`	시크릿 이름과 선택한 Forge 팀을 확인하세요. 시크릿이 API 키의 기본 entity가 아닌 다른 팀에 속해 있다면 `FORGE_TEAM`을 설정하고, Forge 계정으로 해당 시크릿에 액세스할 수 있는지 확인하세요.
`entity not found`	`FORGE_TEAM`에 오타가 없는지 확인하고, 팀이 존재하며 Forge 계정으로 해당 팀에 액세스할 수 있는지 확인하세요.
`no eligible runner is available on this replica right now; retry shortly`	Forge 인증으로 CKS 러너를 선택했다면 지원되지 않는 조합입니다. 재시도해도 사용할 수 없습니다. 시크릿 주입에는 서버리스 배치와 Forge 인증을 사용하세요. 서버리스 요청에서 이 오류는 러너를 일시적으로 사용할 수 없음을 나타낼 수 있습니다.

CoreWeave API 액세스 토큰과 Forge API 키를 모두 설정한 경우에도 CKS 배치에서는 Forge 시크릿 주입을 사용할 수 없습니다.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

Forge 시크릿 사용하기

시작하기 전에

시크릿 주입

시크릿 참조 필드

맞춤형 환경 변수 이름 사용

구조화된 시크릿에서 필드 선택

시크릿 참조 재사용

시크릿 주입 문제 해결

​시작하기 전에

​시크릿 주입

​시크릿 참조 필드

​맞춤형 환경 변수 이름 사용

​구조화된 시크릿에서 필드 선택

​시크릿 참조 재사용

​시크릿 주입 문제 해결

시작하기 전에

시크릿 주입

시크릿 참조 필드

맞춤형 환경 변수 이름 사용

구조화된 시크릿에서 필드 선택

시크릿 참조 재사용

시크릿 주입 문제 해결