> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> API 토큰과 자격 증명을 암호화된 조직 단위 Secret으로 저장하고, 배치 잡 실행 시 환경 변수로 주입해요.

<strong>Secret</strong>은 API 토큰, 비밀번호, 데이터베이스 연결 문자열 같은 민감한 정보를 안전하게 보관하는, 암호화된 조직 단위 자격 증명이에요. 평문을 명령어, 이미지 설정, 저장소 파일에 그대로 두지 말고 Secret으로 등록해 두면, VESSL Cloud가 런타임에 환경 변수로 컨테이너에 주입해요. 값은 사용자 컴퓨터에서 암호화된 뒤 전송되고, 요청 본문이나 접근 로그에 평문으로 남지 않으며, 암호문 형태로만 저장돼요.

<Note>
  조직에 속한 누구나 Secret을 조회하고 새로 만들 수 있고, 배치 잡을 만들 때 이름으로 참조해서 사용할 수 있어요. Secret을 수정하거나 삭제하려면 <strong>Organization admin</strong> 권한이 필요해요. [Secret 관리](/ko/admin/secrets/overview)를 참고하세요.
</Note>

<Info>
  VESSL Cloud는 <strong>SOC 2 Type II</strong> 보안 attestation을 완료했어요. 전체 보고서와 보안 운영 현황은 [trust.vessl.ai](https://trust.vessl.ai)에서 확인할 수 있어요.
</Info>

<div>
  <Frame>
    <img src="https://mintcdn.com/dora/ak9sJWQAzmPhmU9G/images/secrets-list-member.png?fit=max&auto=format&n=ak9sJWQAzmPhmU9G&q=85&s=febf9374a7119a42faf3efa6bcca9ceb" alt="Secret 페이지: Secret Name, Key, 마스킹된 Value, Slug, 마지막 편집자, 편집 시각이 들어있는 표와 New Secret 버튼" width="3360" height="2040" data-path="images/secrets-list-member.png" />
  </Frame>

  <small>예시: 멤버가 보는 Secrets 페이지 — 행에 수정과 삭제 메뉴가 없어요</small>
</div>

## 자주 쓰는 예시

| 환경 변수               | 용도               |
| ------------------- | ---------------- |
| `HF_TOKEN`          | Hugging Face     |
| `OPENAI_API_KEY`    | OpenAI           |
| `ANTHROPIC_API_KEY` | Anthropic        |
| `WANDB_API_KEY`     | Weights & Biases |
| `GITHUB_TOKEN`      | GitHub           |
| `DATABASE_URL`      | 데이터베이스 연결 문자열    |

## 동작 방식

* <strong>전송 전에 암호화돼요</strong>: Secret을 만들 때 값이 사용자 컴퓨터에서 조직 공개 키로 봉인(sealed-box)돼서, 평문이 요청 본문이나 접근 로그에 남지 않아요. VESSL Cloud는 저장할 때 master key로 다시 암호화해서 암호문만 보관해요.
* <strong>제출 시점에 주입돼요</strong>: 워크로드를 제출하면 VESSL Cloud가 서버에서 값을 복호화해 Kubernetes Secret으로 컨테이너에 전달하고, 컨테이너가 시작될 때 환경 변수로 주입돼요.
* <strong>값은 다시 볼 수 없어요</strong>: Secret을 저장하고 나면 VESSL Cloud는 값을 멤버든 admin이든 누구에게도 다시 보여주지 않아요. 목록과 상세 화면에는 메타데이터만 보여요. 값을 바꾸려면 admin이 새 값으로 덮어써야 해요(rotation). 이전 값은 다시 가져올 수 없어요.
* <strong>조직 단위로 공유돼요</strong>: 한 조직 안의 모든 팀이 같은 Secret을 공유해요. 조직 내 어떤 배치 잡에서든 이름으로 참조할 수 있어요.
* <strong>생성은 누구나, 변경은 관리자만 할 수 있어요</strong>: 조직에 속한 누구나 Secret을 조회하고 새로 만들 수 있어요. [수정과 삭제](/ko/admin/secrets/overview)는 <strong>Organization admin</strong>만 할 수 있고, 멤버가 만든 Secret도 마찬가지예요. 멤버 화면의 Secret 목록에는 수정과 삭제 메뉴가 보이지 않아요.

## Secret 만들기

Secret은 세 가지 핵심 필드를 가져요.

| 항목                           | 설명                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| <strong>Secret name</strong> | Secret을 식별하는 이름이에요. 조직 안에서 중복될 수 없어요.                                                      |
| <strong>Key</strong>         | 워크로드에 주입할 때 기본으로 쓰이는 환경 변수 이름이에요. `^[A-Za-z_][A-Za-z0-9_]*$` 형식(영문, 숫자, 밑줄, 최대 256자)을 따라요. |
| <strong>Value</strong>       | 실제 자격 증명 값이에요. 등록 전에 사용자 컴퓨터에서 암호화돼요.                                                      |

<strong>Secret name</strong>과 <strong>Key</strong>는 같게(`HF_TOKEN`/`HF_TOKEN`) 두면 직관적이에요. 같은 환경 변수가 필요하지만 환경별로 다른 Secret을 쓰고 싶을 때(예: `hf-prod`와 `hf-staging`, 둘 다 키는 `HF_TOKEN`)는 이름만 다르게 두면 돼요.

### GUI

1. 사이드바에서 <strong>Settings</strong>를 선택해요.
2. <strong>Account</strong> 메뉴에서 <strong>Secrets</strong>를 선택해요.
3. <strong>New Secret</strong>을 클릭해요.
4. <strong>Secret name</strong>, <strong>Key</strong>, <strong>Value</strong>를 입력해요.
5. <strong>Create</strong>를 눌러 등록해요.

<div>
  <Frame>
    <img src="https://mintcdn.com/dora/ak9sJWQAzmPhmU9G/images/secrets-create-modal.png?fit=max&auto=format&n=ak9sJWQAzmPhmU9G&q=85&s=d7766e70b71f4677914bacdfe9acce85" alt="Create new Secret 모달: Secret name, Key, Value 입력란과 Cancel, Create 버튼" width="3840" height="2488" data-path="images/secrets-create-modal.png" />
  </Frame>

  <small>예시: Secret 생성 모달</small>
</div>

### CLI

```bash theme={null}
# 대화형 프롬프트로 입력(터미널일 때 마스킹 처리)
vesslctl secret create HF_TOKEN HF_TOKEN

# 환경 변수에서 값 읽기
vesslctl secret create HF_TOKEN HF_TOKEN --from-env LOCAL_HF_TOKEN

# 표준 입력에서 값 읽기
echo "$HF_TOKEN" | vesslctl secret create HF_TOKEN HF_TOKEN --from-stdin

# 설명 추가
vesslctl secret create HF_TOKEN HF_TOKEN -d "Hugging Face 토큰(프로덕션)"
```

평문 값이 명령줄에 노출되지 않아요. `--from-env`나 `--from-stdin`을 쓰면 셸 히스토리에도 남지 않아요.

## Job에서 Secret 사용하기

### GUI

Job 생성 화면의 <strong>Environment variables</strong> 섹션에서 <strong>Secrets</strong> 드롭다운으로 사용할 Secret을 선택해요. <strong>Add secret</strong>을 눌러 여러 개를 한 번에 연결할 수 있어요. 같은 환경 변수 키를 일반 Variable과 Secret에 동시에 쓰면 일반 Variable 값이 우선해요.

<div>
  <Frame>
    <img src="https://mintcdn.com/dora/JNAR1GfyPwQhmXIo/images/secrets-job-injection.png?fit=max&auto=format&n=JNAR1GfyPwQhmXIo&q=85&s=f7ffb28b79020408308f5d8798c64de5" alt="Job 생성 폼의 Environment variables 섹션: Secrets 드롭다운, Add secret 버튼, 일반 Variable 키-값 입력 표" width="701" height="380" data-path="images/secrets-job-injection.png" />
  </Frame>

  <small>예시: Job 생성 폼에서 Secret 연결</small>
</div>

### CLI

Job을 만들 때 `--secret`으로 하나 이상의 Secret을 주입해요.

```bash theme={null}
# HF_TOKEN 환경 변수로 주입(같은 이름의 Secret을 참조)
vesslctl job create ... --secret HF_TOKEN

# OPENAI_API_KEY 환경 변수로 주입(openai-prod라는 이름의 Secret을 참조)
vesslctl job create ... --secret OPENAI_API_KEY=openai-prod

# 여러 개 동시에 주입
vesslctl job create ... --secret HF_TOKEN --secret OPENAI_API_KEY
```

* `--secret NAME`은 Secret을 같은 이름의 환경 변수로 주입해요.
* `--secret KEY=NAME`은 `KEY`라는 환경 변수로 주입하고, `NAME`이라는 Secret을 참조해요.
* 같은 환경 변수 키를 `--env`와 `--secret`에서 둘 다 지정할 수는 없어요. CLI가 명령을 거부하니 키마다 한쪽 플래그만 사용하세요.

<Note>
  Workspace는 아직 Secret 주입을 지원하지 않아요. 현재 Job에서만 사용할 수 있고, Workspace 지원은 후속 릴리스로 예정돼 있어요.
</Note>

## Secret 목록 보기

```bash theme={null}
# 활성 Secret 목록
vesslctl secret list

# 소프트 삭제된 Secret까지 포함
vesslctl secret list --include-deleted
```

Secret 수정과 삭제는 admin 전용이에요. [Secret 관리](/ko/admin/secrets/overview)를 참고하세요.

## FAQ

<AccordionGroup>
  <Accordion title="Secret은 누가 관리할 수 있나요?">
    조직에 속한 누구나 Secret을 조회하고 새로 만들 수 있어요. 수정과 삭제는 직접 만든 Secret이라도 <strong>Organization admin</strong>만 할 수 있어서, 멤버 화면의 Secret 목록에는 수정과 삭제 메뉴가 보이지 않아요. 배치 잡을 만들 때 이름으로 참조하는 데는 admin 권한이 필요 없어요. (저장된 값은 멤버든 admin이든 누구도 다시 볼 수 없어요. 멤버만의 제약이 아니에요.)
  </Accordion>

  <Accordion title="VESSL Cloud는 Secret 값을 어떻게 보호하나요?">
    값은 사용자 컴퓨터에서 조직 공개 키로 봉인(sealed-box)된 뒤 전송돼서, 평문이 요청 본문이나 접근 로그에 남지 않아요. VESSL Cloud는 암호문만 저장하고(저장할 때 master key로 다시 암호화), 워크로드에 주입하기 위해서만 Job을 제출할 때 서버에서 복호화해요. 접근은 [SOC 2 Type II](https://trust.vessl.ai) 통제를 따라요.
  </Accordion>

  <Accordion title="왜 Secret name과 Key를 따로 두나요?">
    <strong>Secret name</strong>은 조직 안에서 Secret을 식별하는 이름(중복 불가)이고, <strong>Key</strong>는 워크로드에 주입할 때 기본으로 쓰이는 환경 변수 이름이에요. 단순하게 쓰려면 둘을 같게 두면 되고, 같은 환경 변수가 필요하지만 환경별로 다른 Secret을 쓰고 싶을 때(예: `hf-prod`와 `hf-staging`, 둘 다 키는 `HF_TOKEN`)는 이름을 따로 둘 수 있어요.
  </Accordion>

  <Accordion title="같은 환경 변수 키를 --env와 --secret에 동시에 쓰면 어떻게 되나요?">
    CLI에서는 에러가 나요. `vesslctl job create`는 같은 키가 두 플래그에 모두 있으면 명령을 거부하니, 키마다 한쪽만 사용하세요. GUI에서는 둘을 같이 쓸 수 있는데, 같은 키라면 일반 Variable 값이 우선하고 Secret 참조는 무시돼요.
  </Accordion>

  <Accordion title="이미 돌고 있는 워크로드가 갱신된 값을 받나요?">
    아니요. Secret은 컨테이너가 시작될 때 주입돼요. 새 값을 적용하려면 워크로드를 재시작해야 해요.
  </Accordion>
</AccordionGroup>