전송 에이전트 관리

Google Cloud 콘솔

1. Google Cloud 콘솔에서 에이전트 풀 페이지로 이동합니다.

   에이전트 풀로 이동

2. 새 에이전트를 추가할 에이전트 풀을 선택합니다.

3. 에이전트 설치를 클릭합니다.

4. 안내를 따라 에이전트를 설치 및 실행합니다.

   에이전트의 명령줄 옵션에 대한 자세한 내용은 에이전트 명령줄 옵션을 참조하세요.

gcloud CLI

gcloud CLI를 사용하여 하나 이상의 에이전트를 설치하려면 gcloud transfer agents install을 실행합니다.

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

이 도구는 에이전트를 설치하는 데 필요한 단계를 안내합니다. 이 명령어는 POOL_NAME으로 지정된 풀 이름에 매핑된 NUM_AGENTS 에이전트를 머신에 설치하고 gcloud 사용자 인증 정보를 사용하여 에이전트를 인증합니다. 풀 이름은 있어야 하며, 그렇지 않은 경우 오류가 반환됩니다.

--mount-directories 플래그는 선택사항이지만 적극 권장됩니다. 값은 에이전트 액세스 권한을 부여할 파일 시스템의 쉼표로 구분된 디렉터리 목록입니다. 이 플래그를 생략하면 전체 파일 시스템이 에이전트 컨테이너에 마운트됩니다. 자세한 내용은 gcloud 참조를 읽어보세요.

S3 호환 소스

S3 호환 소스에 사용하도록 에이전트를 설치할 때는 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY의 값과 같은 환경 변수로 AWS 사용자 인증 정보를 제공하거나 시스템 구성 파일에 저장된 기본 사용자 인증 정보를 제공해야 합니다.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

서비스 계정 키 사용

서비스 계정 키를 사용하여 에이전트를 만들려면 --creds-file 옵션을 사용합니다.

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

추가 정보

선택적인 플래그의 전체 목록을 보려면 gcloud transfer agents install --help를 실행하거나 gcloud transfer 참조를 읽으세요.

Docker

Docker를 사용하여 에이전트를 설치하기 전에 안내에 따라 Docker를 설치합니다.

docker run 명령어는 에이전트 하나를 설치합니다. 풀의 에이전트 수를 늘리려면 이 명령어를 필요한 횟수만큼 다시 실행합니다.

에이전트를 설치할 때 gcloud 기본 사용자 인증 정보나 서비스 계정을 사용하여 인증할 수 있습니다.

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

옵션 및 플래그

위 예시의 변수를 다음 정보로 바꿉니다.

• HOST_DIRECTORY는 복사하려는 호스트 머신의 디렉터리입니다. -v 플래그를 두 개 이상 사용하여 복사할 디렉터리를 추가 지정할 수 있습니다.
• CONTAINER_DIRECTORY는 에이전트 컨테이너 내에서 매핑된 디렉터리입니다. HOST_DIRECTORY와 같아야 합니다.
• PROJECT_ID는 전송을 호스팅하는 프로젝트 ID입니다.
• POOL_NAME은 이 에이전트를 설치할 에이전트 풀의 이름입니다. 이 플래그를 생략하면 에이전트가 프로젝트의 transfer_service_default 풀에 설치됩니다.

docker run 명령어는 추가 플래그를 지원합니다.

• --enable-mount-directory는 전체 파일 시스템을 컨테이너의 /transfer_root 디렉터리 아래에 마운트합니다. --enable-mount-directory가 지정되면 -v 플래그를 사용하는 디렉터리 제한사항이 적용되지 않습니다.

• --creds-file=CREDENTIAL_FILE은 JSON 형식의 서비스 계정 사용자 인증 정보 파일로 경로를 지정합니다. --enable_mount_directory를 사용하지 않는 경우에는 다음을 수행해야 합니다.

  1. -v 플래그를 사용하여 사용자 인증 정보 파일을 마운트합니다.
  2. --creds-file 경로에 /transfer_root를 프리픽스로 추가합니다.

  예를 들면 다음과 같습니다.

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3은 이 에이전트가 S3 호환 스토리지의 전송에 사용되도록 지정합니다. 이 옵션으로 설치된 에이전트는 POSIX 파일 시스템의 전송에 사용할 수 없습니다.

• 전송이 AWS S3 또는 S3 호환 스토리지에서 온 경우 환경 변수를 사용하여 액세스 키 ID와 보안 비밀키를 전달합니다.

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY는 네트워크에서 전달 프록시를 지정합니다. PROXY 값은 프록시 서버의 HTTP URL 및 포트입니다. TLS 암호화에서 이중 래핑 요청이 발생하지 않도록 HTTPS URL이 아닌 HTTP URL을 지정해야 합니다. 이중 래핑 요청은 프록시 서버가 유효한 아웃바운드 요청을 보내지 못하게 합니다.

• --agent-id-prefix=ID_PREFIX는 Google Cloud 콘솔에서 에이전트 또는 머신을 식별하는 데 유용하도록 에이전트 ID 앞에 추가되는 선택적 프리픽스를 지정합니다. 프리픽스가 사용되면 에이전트 ID 형식은 prefix + hostname + Docker container ID로 지정됩니다.

• --log-dir=LOGS_DIRECTORY는 에이전트에서 로그를 쓰는 디렉터리를 수정합니다. 기본 디렉터리는 /tmp/입니다.

  --enable_mount_directory를 지정하지 않았으면 이 경로에 /transfer_root를 프리픽스로 추가해야 합니다. 예를 들면 /transfer_root/logs입니다.

• --max-physical-mem=MAX_MEMORY: 에이전트는 기본적으로 최대 8GiB 시스템 메모리를 사용합니다. 기본값이 사용자 환경에 맞지 않으면 다음 형식으로 관련 최대 메모리 사용량을 지정할 수 있습니다.

  max-physical-mem 값	최대 메모리 설정
  6g	6GB
  6gb	6GB
  6GiB	6GB

Podman

Podman을 사용하여 에이전트를 설치하기 전에 Podman을 설치합니다.

sudo apt-get update
sudo apt-get -y install podman

에이전트를 설치할 때 gcloud 기본 사용자 인증 정보나 서비스 계정을 사용하여 인증할 수 있습니다.

  gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io
  sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
  sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth application-default login
  ```

Then use the following command to install an agent, using the
`--volumes-from` flag to mount the `gcloud-config` credentials volume.
The command installs one agent. To increase the number of agents in your
pool, re-run this command as many times as required.

```sh
  sudo podman run \
    --ulimit memlock=64000000 \
    -d \
    --rm \
    --volumes-from gcloud-config \
    -v HOST_DIRECTORY:CONTAINER_DIRECTORY \
    gcr.io/cloud-ingest/tsop-agent:latest \
    --project-id=PROJECT_ID \
    --hostname=$(hostname) \
    --agent-pool=POOL_NAME
  ```

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

옵션 및 플래그

위 예시의 변수를 다음 정보로 바꿉니다.

• HOST_DIRECTORY는 복사하려는 호스트 머신의 디렉터리입니다. -v 플래그를 두 개 이상 사용하여 복사할 디렉터리를 추가 지정할 수 있습니다.
• CONTAINER_DIRECTORY는 에이전트 컨테이너 내에서 매핑된 디렉터리입니다. HOST_DIRECTORY와 같아야 합니다.
• PROJECT_ID는 전송을 호스팅하는 프로젝트 ID입니다.
• POOL_NAME은 이 에이전트를 설치할 에이전트 풀의 이름입니다. 이 플래그를 생략하면 에이전트가 프로젝트의 transfer_service_default 풀에 설치됩니다.

podman run 명령어는 추가 플래그를 지원합니다.

• --enable-mount-directory는 전체 파일 시스템을 컨테이너의 /transfer_root 디렉터리 아래에 마운트합니다. --enable-mount-directory가 지정되면 -v 플래그를 사용하는 디렉터리 제한사항이 적용되지 않습니다.

• --creds-file=CREDENTIAL_FILE은 JSON 형식의 서비스 계정 사용자 인증 정보 파일로 경로를 지정합니다. --enable_mount_directory를 사용하지 않는 경우에는 다음을 수행해야 합니다.

  1. -v 플래그를 사용하여 사용자 인증 정보 파일을 마운트합니다.
  2. --creds-file 경로에 /transfer_root를 프리픽스로 추가합니다.

  예를 들면 다음과 같습니다.

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3은 이 에이전트가 S3 호환 스토리지의 전송에 사용되도록 지정합니다. 이 옵션으로 설치된 에이전트는 POSIX 파일 시스템의 전송에 사용할 수 없습니다.

• 전송이 AWS S3 또는 S3 호환 스토리지에서 온 경우 환경 변수를 사용하여 액세스 키 ID와 보안 비밀키를 전달합니다.

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY는 네트워크에서 전달 프록시를 지정합니다. PROXY 값은 프록시 서버의 HTTP URL 및 포트입니다. TLS 암호화에서 이중 래핑 요청이 발생하지 않도록 HTTPS URL이 아닌 HTTP URL을 지정해야 합니다. 이중 래핑 요청은 프록시 서버가 유효한 아웃바운드 요청을 보내지 못하게 합니다.

• --agent-id-prefix=ID_PREFIX는 Google Cloud 콘솔에서 에이전트 또는 머신을 식별하는 데 유용하도록 에이전트 ID 앞에 추가되는 선택적 프리픽스를 지정합니다. 프리픽스가 사용되면 에이전트 ID 형식은 prefix + hostname + OCI container ID로 지정됩니다.

• --log-dir=LOGS_DIRECTORY는 에이전트에서 로그를 쓰는 디렉터리를 수정합니다. 기본 디렉터리는 /tmp/입니다.

  --enable_mount_directory를 지정하지 않았으면 이 경로에 /transfer_root를 프리픽스로 추가해야 합니다. 예를 들면 /transfer_root/logs입니다.

• --max-physical-mem=MAX_MEMORY: 에이전트는 기본적으로 최대 8GiB 시스템 메모리를 사용합니다. 기본값이 사용자 환경에 맞지 않으면 다음 형식으로 관련 최대 메모리 사용량을 지정할 수 있습니다.

  max-physical-mem 값	최대 메모리 설정
  6g	6GB
  6gb	6GB
  6GiB	6GB

문제 해결

SELinux 구성에서 컨테이너에 마운트된 볼륨 콘텐츠에 라벨을 배치해야 하는 경우 볼륨에 :Z 플래그를 추가합니다.

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

라벨이 없으면 보안 시스템으로 인해 컨테이너 내에서 실행되는 프로세스가 콘텐츠를 사용하지 못할 수 있습니다. 기본적으로 Podman은 OS에서 설정한 라벨을 변경하지 않습니다.