> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Launch 에이전트 설정
> Docker 및 Kaniko 빌더와 컨테이너 레지스트리 설정을 포함해 W&B Launch의 고급 에이전트 옵션을 구성합니다.
# 고급 에이전트 설정
이 가이드는 다양한 환경에서 컨테이너 이미지를 빌드하고, 해당 이미지를 클라우드 컨테이너 레지스트리에 푸시하며, 빌드 프로세스를 사용자 지정할 수 있도록 W\&B Launch 에이전트를 설정하는 방법을 설명합니다. 이미지 빌드가 필요한 launch 작업을 실행해야 하며, 에이전트가 해당 이미지를 어디에서 어떤 방식으로 생성할지 제어하려는 경우 이 가이드를 사용하세요. 이 페이지는 Launch 에이전트를 배포하고 관리하는 관리자 및 운영자를 위한 문서입니다.
빌드는 git 및 코드 artifact 작업에만 필요합니다. Image jobs에는 빌드가 필요하지 않습니다.
작업 유형에 대한 자세한 내용은 [Launch 작업 만들기](/ko/platform/launch/create-launch-job/)를 참조하세요.
## 빌더
Launch 에이전트는 컨테이너 이미지를 생성하는 두 가지 빌더를 지원합니다. 에이전트가 실행되는 환경에 맞는 빌더를 선택하세요.
Launch 에이전트는 [Docker](https://docs.docker.com/) 또는 [Kaniko](https://github.com/GoogleContainerTools/kaniko)를 사용해 이미지를 빌드할 수 있습니다.
* Kaniko: Kubernetes에서 빌드를 권한 있는 컨테이너로 실행하지 않고 컨테이너 이미지를 빌드합니다.
* Docker: 로컬에서 `docker build` 명령을 실행해 컨테이너 이미지를 빌드합니다.
Launch 에이전트 설정의 `builder.type` 키로 빌더 유형을 제어합니다. 이 값을 `docker`, `kaniko`, 또는 빌드를 비활성화하는 `noop`로 설정하세요. 기본적으로 에이전트 Helm chart는 `builder.type`을 `noop`로 설정합니다. 에이전트는 빌드 프로세스를 구성하기 위해 `builder` 섹션의 추가 키를 사용합니다.
에이전트 설정에서 빌더를 지정하지 않았고 사용 가능한 `docker` CLI가 있으면 에이전트는 기본적으로 Docker를 사용합니다. Docker를 사용할 수 없으면 에이전트는 기본적으로 `noop`를 사용합니다.
Kubernetes cluster에서 이미지를 빌드할 때는 Kaniko를 사용하세요. 그 외의 경우에는 Docker를 사용하세요.
## 컨테이너 레지스트리로 푸시하기
빌드한 이미지를 컴퓨팅 대상에서 실행하려면, 에이전트가 대상이 pull할 수 있는 컨테이너 레지스트리로 이미지를 푸시해야 합니다. 다음 섹션에서는 에이전트가 이미지를 어떻게 태그하고 업로드하는지 설명합니다.
Launch 에이전트는 빌드한 모든 이미지에 고유한 소스 해시 태그를 붙입니다. 에이전트는 `builder.destination` 키에 지정된 레지스트리로 이미지를 푸시합니다.
예를 들어 `builder.destination` 키가 `my-registry.example.com/my-repository`로 설정되어 있으면, 에이전트는 이미지에 `my-registry.example.com/my-repository:[SOURCE-HASH]` 태그를 붙여 푸시합니다. 레지스트리에 이미지가 이미 있으면 빌드는 건너뜁니다.
### 에이전트 설정
에이전트는 YAML 파일에서 설정을 읽어옵니다. 이 파일을 어디에 제공할지는 에이전트를 실행하는 방식에 따라 달라집니다.
Helm chart로 에이전트를 배포하는 경우 `values.yaml` 파일의 `agentConfig` 키에 에이전트 설정을 지정하세요.
`wandb launch-agent`로 직접 에이전트를 실행하는 경우 `--config` 플래그에 YAML 파일 경로를 지정해 에이전트 설정을 제공하세요. 기본적으로 에이전트는 `~/.config/wandb/launch-config.yaml`에서 설정을 로드합니다.
Launch 에이전트 설정(`launch-config.yaml`)에서는 `environment` 키와 `registry` 키에 각각 대상 리소스 환경의 이름과 컨테이너 레지스트리를 지정하세요.
다음 탭에서는 환경과 레지스트리에 따라 Launch 에이전트를 설정하는 방법을 보여줍니다.
AWS 환경 설정에는 `region` 키가 필요합니다. `region`은 에이전트가 실행되는 AWS 리전으로 설정하세요.
```yaml title="launch-config.yaml" theme={null}
environment:
type: aws
region: [AWS-REGION]
builder:
type: [BUILDER-TYPE]
# 에이전트가 이미지를 저장하는 ECR 저장소의 URI입니다.
# 환경에서 설정한 리전과 일치하는지
# 확인하세요.
destination: [ACCOUNT-ID].ecr.[AWS-REGION].amazonaws.com/[REPOSITORY-NAME]
# Kaniko를 사용하는 경우 에이전트가
# 빌드 컨텍스트를 저장할 S3 버킷을 지정하세요.
build-context-store: s3://[BUCKET-NAME]/[PATH]
```
에이전트는 `boto3`를 사용해 기본 AWS 자격 증명을 로드합니다. 기본 AWS 자격 증명을 설정하는 방법에 대한 자세한 내용은 [boto3 문서](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) 를 참조하세요.
Google Cloud 환경에는 `region` 및 `project` 키가 필요합니다. `region`은 에이전트가 실행되는 리전으로 설정하세요. `project`는 에이전트가 실행되는 Google Cloud 프로젝트로 설정하세요. 에이전트는 Python의 `google.auth.default()`를 사용해 기본 자격 증명을 로드합니다.
```yaml title="launch-config.yaml" theme={null}
environment:
type: gcp
region: [GCP-REGION]
project: [GCP-PROJECT-ID]
builder:
type: [BUILDER-TYPE]
# 에이전트가 이미지를 저장하는 Artifact Registry 저장소와 이미지 이름의
# URI입니다. 리전과 프로젝트가
# 환경에서 설정한 값과 일치하는지 확인하세요.
uri: [REGION]-docker.pkg.dev/[PROJECT-ID]/[REPOSITORY-NAME]/[IMAGE-NAME]
# Kaniko를 사용하는 경우 에이전트가
# 빌드 컨텍스트를 저장할 GCS 버킷을 지정하세요.
build-context-store: gs://[BUCKET-NAME]/[PATH]
```
에이전트가 사용할 수 있도록 기본 Google Cloud 자격 증명을 설정하는 방법에 대한 자세한 내용은 [`google-auth` 문서](https://google-auth.readthedocs.io/en/latest/reference/google.auth.html#google.auth.default) 를 참조하세요.
Azure 환경에는 추가 키가 필요하지 않습니다. 에이전트가 시작되면 `azure.identity.DefaultAzureCredential()`를 사용해 기본 Azure 자격 증명을 로드합니다.
```yaml title="launch-config.yaml" theme={null}
environment:
type: azure
builder:
type: [BUILDER-TYPE]
# 에이전트가 이미지를 저장하는 Azure Container Registry 저장소의 URI입니다.
destination: https://[REGISTRY-NAME].azurecr.io/[REPOSITORY-NAME]
# Kaniko를 사용하는 경우 에이전트가
# 빌드 컨텍스트를 저장할 Azure Blob Storage 컨테이너를 지정하세요.
build-context-store: https://[STORAGE-ACCOUNT-NAME].blob.core.windows.net/[CONTAINER-NAME]
```
기본 Azure 자격 증명을 설정하는 방법에 대한 자세한 내용은 [`azure-identity` 문서](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python) 를 참조하세요.
## 에이전트 권한
에이전트는 컨테이너 레지스트리에 이미지를 푸시할 권한이 있어야 하며, Kaniko를 사용하는 경우 클라우드 저장소의 빌드 컨텍스트를 읽고 쓸 권한도 있어야 합니다. 에이전트에 필요한 권한은 사용 사례에 따라 다릅니다.
### 클라우드 레지스트리 권한
에이전트가 저장소를 생성하고 이미지 레이어를 업로드하며 태그가 지정된 이미지를 푸시하려면 레지스트리 권한이 필요합니다. 다음은 Launch 에이전트가 클라우드 레지스트리와 상호작용하는 데 필요한 권한입니다.
```yaml theme={null}
{
'Version': '2012-10-17',
'Statement':
[
{
'Effect': 'Allow',
'Action':
[
'ecr:CreateRepository',
'ecr:UploadLayerPart',
'ecr:PutImage',
'ecr:CompleteLayerUpload',
'ecr:InitiateLayerUpload',
'ecr:DescribeRepositories',
'ecr:DescribeImages',
'ecr:BatchCheckLayerAvailability',
'ecr:BatchDeleteImage',
],
'Resource': 'arn:aws:ecr:[REGION]:[ACCOUNT-ID]:repository/[REPOSITORY]',
},
{
'Effect': 'Allow',
'Action': 'ecr:GetAuthorizationToken',
'Resource': '*',
},
],
}
```
```js theme={null}
artifactregistry.dockerimages.list;
artifactregistry.repositories.downloadArtifacts;
artifactregistry.repositories.list;
artifactregistry.repositories.uploadArtifacts;
```
Kaniko 빌더를 사용하는 경우 [`AcrPush` 역할](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/containers#acrpush)을 추가하세요.
### Kaniko용 저장소 권한
에이전트가 Kaniko 빌더를 사용하는 경우, Launch 에이전트에 클라우드 저장소로 푸시할 권한이 있어야 합니다. Kaniko는 빌드 작업을 실행하는 파드 외부의 컨텍스트 저장소를 사용합니다.
AWS에서는 Kaniko 빌더의 컨텍스트 저장소로 Amazon S3를 사용하세요. 다음 정책을 사용해 에이전트에 S3 버킷에 대한 액세스 권한을 부여하세요.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ListObjectsInBucket",
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::[BUCKET-NAME]"]
},
{
"Sid": "AllObjectActions",
"Effect": "Allow",
"Action": "s3:*Object",
"Resource": ["arn:aws:s3:::[BUCKET-NAME]/*"]
}
]
}
```
Google Cloud에서는 빌드 컨텍스트를 GCS에 업로드하려면 에이전트에 다음 IAM 권한이 필요합니다.
```js theme={null}
storage.buckets.get;
storage.objects.create;
storage.objects.delete;
storage.objects.get;
```
빌드 컨텍스트를 Azure Blob Storage에 업로드하려면 에이전트에 [Storage Blob Data Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#storage-blob-data-contributor) 역할이 필요합니다.
## Kaniko 빌드 맞춤 설정
빌드 파드의 캐싱 동작이나 환경 변수와 같은 기본값을 재정의하려면 Kaniko가 실행하는 Kubernetes 작업을 맞춤 설정하세요. Kaniko 작업에서 사용할 Kubernetes 작업 사양을 에이전트 설정의 `builder.kaniko-config` 키에 지정합니다. 예:
```yaml title="launch-config.yaml" theme={null}
builder:
type: kaniko
build-context-store: [MY-BUILD-CONTEXT-STORE]
destination: [MY-IMAGE-DESTINATION]
build-job-name: wandb-image-build
kaniko-config:
spec:
template:
spec:
containers:
- args:
- "--cache=false" # 인수는 "키=값" 형식이어야 합니다
env:
- name: "MY_ENV_VAR"
value: "my-env-var-value"
```
## CoreWeave에 Launch 에이전트 배포
워크로드가 GPU 가속 인프라의 이점을 활용할 수 있다면 Launch 에이전트를 CoreWeave Cloud에 배포할 수 있습니다. CoreWeave는 GPU 가속 워크로드를 위해 구축된 클라우드 인프라입니다.
CoreWeave에 Launch 에이전트를 배포하는 방법에 대한 자세한 내용은 [CoreWeave 문서](https://docs.coreweave.com/partners/weights-and-biases#integration)를 참조하세요.
CoreWeave 인프라에 Launch 에이전트를 배포하려면 [CoreWeave 계정](https://cloud.coreweave.com/login)을 만들어야 합니다.