키트 세트 구성하기

키트 세트 구성하기 (Compose a kit set)

팀이 하나의 키트로 실행할 수 있도록 도구와 버전을 묶어 주는 키트 세트를 만드는 방법을 알아볼게요.

출처: 문서

본문

키트 세트(kit set)는 팀이 선택한 도구와 버전을 담은 키트 하나를 실행할 수 있게 해줘요. 포함할 키트를 나열하고, 결합된 환경에 필요한 설정을 추가하고, 결과물을 배포하면 돼요. 세트는 설정 명령을 실행하거나 에이전트 지침을 제공하거나 어떤 모델을 쓸지 같은 선택지를 제시할 수도 있어요.

키트 조합을 공유하고 그 설정을 한곳에서 관리하고 싶을 때 세트를 사용하세요. 구성 요소는 팀이 배포한 키트일 수도, 다른 배포자의 키트일 수도 있어요. 세트를 배포하려면 Docker Buildx와 푸시 가능한 레지스트리 네임스페이스가 필요해요.

참고 (Note): 이 기능은 Early Access 상태예요.

구성 요소 고르기

세트에는 워크로드 하나와 임의 개수의 mixin을 담을 수 있어요. 이들이 함께 완전한 샌드박스 환경을 제공해요. mixin만으로 세트를 만들어서, 사용자가 --kit으로 워크로드에 추가할 도구와 설정을 공유할 수도 있어요.

함께 동작하는 v3 키트를 고르세요. 예를 들어 에이전트 워크로드에 linter mixin과 팀 설정을 추가하는 mixin을 결합할 수 있어요. 직접 만든 도구를 패키징하려면 도구 믹스인 만들기 문서를 보세요.

세트를 구성하기 전에 sbx run과 --kit으로 워크로드와 mixin을 함께 시험해 볼 수 있어요. Mixins 추가하기 문서를 보세요. 한 키트가 다른 키트에 의존하면 Docker Sandboxes는 의존성을 먼저 적용해요. --kit 플래그나 세트 항목의 순서를 바꿔도 그 순서는 바뀌지 않아요.

세트 descriptor 작성하기

세트 descriptor는 kind: set을 쓰고 kits: 아래에 구성 요소를 나열해요. 예를 들어 이 descriptor는 Docker의 Codex 워크로드와 mixin을 결합해요:

# syntax=docker/sandbox-kit:3
schemaVersion: "3"
kind: set
displayName: Codex with tools
version: "1.0.0"

kits:
  - ref: docker.io/docker/sbx-kit-codex:0.155.1
  - ref: <MIXIN_REFERENCE>

<MIXIN_REFERENCE>를 배포된 v3 mixin의 전체 이미지 참조로 바꾸세요. 다른 에이전트나 환경을 쓰려면 다른 워크로드 참조를 고르세요. 구성 요소들이 각자 네트워크 규칙과 자격 증명 요청을 제공하므로 세트가 그것을 반복할 필요는 없어요.

세트는 kits: 목록에서 소프트웨어와 파일을 가져와요. Dockerfile, dockerfile: 필드, build: 블록은 없어요. 더 많은 소프트웨어나 정적 파일을 포함하려면 그것을 워크로드나 mixin으로 패키징하고, 그 키트를 배포한 뒤 목록에 추가하세요.

모든 ref는 배포된 레지스트리 참조여야 해요. 로컬 경로와 Git URL은 로컬 소스에서 빌드하더라도 구성 요소로 받아들여지지 않아요.

세트에 런타임 접근 추가하기

구성 요소가 요청하는 서비스 외에, 결합된 환경이 추가 서비스에 접근하도록 할 수도 있어요. 예를 들어 에이전트가 내부 레지스트리에서 패키지를 내려받게 하려면 이 네트워크 capability를 세트 descriptor에 추가하세요:

capabilities:
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow:
          - packages.company.example:443

예시 도메인을 레지스트리의 호스트로 바꾸세요. 이 규칙은 샌드박스의 정책이 허용하는 한 접근을 허용해요. 레지스트리가 인증도 요구한다면 자격 증명 요청을 추가하세요. 키트가 선언한 서비스 문서를 보세요.

도구가 필요로 하는 접근은 그 도구의 키트에 두어, 다른 워크로드에서 쓸 때도 접근 규칙이 따라가게 하세요. 결합된 환경이 공유하는 설정(예: 팀 패키지 레지스트리 접근)은 세트에 두세요. 세트에 설정 명령, 생성되는 설정 파일, 지침, argument도 추가할 수 있어요.

세트 빌드하고 배포하기

배포하기 전에 구성 요소 사이의 파일 충돌을 확인하세요.

세트는 그 descriptor를 Docker Buildx에 넘겨 빌드·배포해요. codex-tools/codex-tools.yaml 위치의 descriptor 기준으로:

$ docker login
$ docker buildx build ./codex-tools -f ./codex-tools/codex-tools.yaml \
    -t docker.io/<NAMESPACE>/codex-tools:1.0.0 --push

경로를 세트의 소스 디렉터리와 descriptor로, <NAMESPACE>를 푸시 가능한 Docker Hub 네임스페이스로 바꾸세요.

빌드는 나열된 키트를 가져와 그 선언된 요구사항을 확인하고, 파일과 설정을 결합해요. 의존성이 빠졌거나, 두 키트가 provides에서 같은 기능을 선언하거나, 둘 이상의 키트가 워크로드면 빌드가 실패해요.

워크로드를 포함한 세트는 kind: workload로 배포돼요. mixin만 담은 세트는 kind: mixin으로 배포돼요. 팀은 결과물을 다른 워크로드나 mixin처럼 쓸 수 있어요. 배포된 키트는 각 구성 요소의 정확한 이미지 digest를 kits:에 기록해요. kind: set을 쓰는 건 소스 descriptor뿐이에요.

세트 실행하기

워크로드를 담은 배포된 세트는 개별 워크로드처럼 sbx run에 이미지 참조를 넘겨 실행해요:

$ sbx run <SET_REFERENCE> --name my-project

샌드박스에는 세트에 패키징된 워크로드와 모든 mixin이 들어 있어요. 그 mixin들을 --kit으로 별도 나열할 필요는 없어요.

mixin만 담은 세트는 --kit으로 워크로드에 추가하세요:

$ sbx run <WORKLOAD_REFERENCE> --kit <SET_REFERENCE> --name my-project

인증은 세트 안의 키트에 달려 있어요. 필요한 자격 증명은 그 문서에서 확인하고, 호스트에 저장하고, 프롬프트가 뜨면 접근을 승인하세요. 인증 옵션과 무인(unattended) 실행 준비는 자격 증명 구성 문서를 보세요.

에이전트의 기본 이미지나 실행 명령을 제어하려면 에이전트 워크로드 빌드하기 문서를 보세요.

구성 요소 argument 구성하기

어떤 키트를 포함할지 바꾸지 않고도 팀이 설정을 바꿀 수 있게 하고 싶을 때가 있어요. 예를 들어 linter가 파일을 검사할지 수정할지를 고르게 하면서, linter 버전은 선택한 것으로 유지하고 싶을 수 있어요.

세트는 사용자가 바꿀 수 있는 구성 요소 argument를 통제해요. argument의 값을 세트 배포 시점에 고정할 수도 있고, 세트의 argument로 노출해서 사용자가 샌드박스를 만들 때 선택하게 할 수도 있어요.

descriptor에서 argument 정의를 바꾼 뒤 세트를 다시 빌드·배포하세요.

argument 값 고정하기

보통 샌드박스를 만들 때 사용자가 설정하는 mode argument가 있는 linter 키트가 있다고 가정해 봅시다. 그것을 check 값으로 고정해 세트에 추가하세요:

kits:
  - ref: docker.io/my-org/linter-kit:1.0.0
    args:
      mode: check

이 발췌는 세트를 배포할 때 linter의 mode를 check로 고정해요. linter의 이미지 참조와 argument 이름을 쓰세요. 세트의 다른 구성 요소는 각자 argument 값을 가질 수 있어요.

사용자가 값 고르게 하기

사용자가 샌드박스를 만들 때 mode를 고르게 하려면 세트에 argument를 정의하고 그 값을 linter에 넘기세요:

args:
  lint_mode:
    default: check
    enum: [check, fix]

kits:
  - ref: docker.io/my-org/linter-kit:1.0.0
    args:
      mode: ${{ kit.args.lint_mode }}

이 예시는 linter가 mode를 같은 기본값과 허용값으로 정의한다고 가정해요. 세트는 그 제약을 지켜야 해요. 그러면 사용자는 배포된 세트를 실행할 때 --kit-arg lint_mode=fix를 넘길 수 있어요. 세트에 정의된 argument만 바꿀 수 있고, 구성 요소의 다른 argument는 바꿀 수 없어요. argument 규칙은 Set merge rules 문서를 보세요.

빌드 argument 바꾸기

설치할 도구 버전처럼 구성 요소를 빌드하는 데 쓰이는 argument는 그 배포된 이미지에 고정돼 있어요. 그것을 바꾸려면 구성 요소를 다시 빌드·배포하고, 세트의 참조를 갱신하세요.

구성 검토하고 갱신하기

파일 충돌 확인하기

세트를 공유하기 전에 구성 요소가 함께 동작하는지 확인하세요. 각 구성 요소의 파일에 별도 경로를 주세요. 두 구성 요소가 같은 경로를 포함하면 뒤쪽 이미지 레이어의 파일이 앞쪽 것을 대체해요. 빌드는 레이어를 키트 의존성 순서로 정렬하므로 kits:를 재정렬해도 어떤 파일이 이기는지 선택되지 않아요. 빌드된 이미지를 검사해 의도치 않은 대체가 없는지 확인하세요. --kit으로 키트를 결합할 때는 샌드박스를 만들 때 충돌하는 파일을 Docker Sandboxes가 거절해요.

결합된 설정 확인하기

세트는 각 구성 요소의 네트워크 규칙과 에이전트 지침을 포함해요. Lifecycle hooks는 의존성 순서로 실행되지만, startup hooks는 에이전트와 나란히 실행돼요. 에이전트가 그 hooks가 끝나기 전에 시작될 수도 있어요.

샌드박스 생성 중에 끝나야 하는 설정에는 install hooks를 쓰세요. 모든 에이전트 실행 전에 끝나야 하는 설정에는 워크로드의 entrypoint를 쓰세요.

워크로드가 지침 파일 이름을 골라요. 세트에 agent-context capability로 지침을 추가한다면 파일 이름은 빼세요.

구성 요소 갱신하기

구성 요소의 참조를 바꾸고, 세트를 다시 빌드하고, 다른 버전을 배포하세요. 새 샌드박스를 만들어 갱신된 세트를 시험해 보세요. 기존 샌드박스는 생성될 때의 키트 구성을 유지해요.

배포된 세트는 빌드 당시의 파일과 설정을 유지하므로, 나중에 구성 요소의 태그가 다른 이미지를 가리켜도 영향받지 않아요. 다시 빌드할 때 같은 이미지를 쓰려면 소스의 각 ref 옆에 digest를 추가하세요.

서명과 멀티 플랫폼 빌드는 키트 빌드 및 배포하기 문서를 보세요.

더 알아보기 (Learn more)

도구 믹스인 만들기, Mixins 추가하기, 키트가 선언한 서비스, 자격 증명 구성, Set merge rules, 에이전트 워크로드 빌드하기, 키트 빌드 및 배포하기 문서를 참고하세요.