전송 에이전트 관리

Storage Transfer Service 에이전트는 Docker 컨테이너 내에서 실행되는 애플리케이션으로, 파일 시스템이나 또는 S3 호환 스토리지와 관련된 전송을 위해 Storage Transfer Service와 조율됩니다.

전송이 파일 시스템이나 S3 호환 스토리지와 관련되지 않으면 에이전트를 설정할 필요가 없습니다.

Amazon S3에서 전송할 때는 에이전트가 필요 없습니다. S3 호환 스토리지는 S3 API를 사용하지만 Amazon에서 직접 호스팅하지 않는 스토리지 시스템을 나타냅니다.

이 문서에서는 서버에서 전송 에이전트를 관리하는 방법을 설명합니다.

개요

• 에이전트 프로세스는 동적입니다. 전송을 실행하는 동안 에이전트를 추가하여 성능을 향상할 수 있습니다. 새로 시작된 에이전트는 할당된 에이전트 풀에 참여하여 기존 전송에서 작업을 수행합니다. 이를 통해 실행 중인 에이전트 수를 조정하거나 전송 성능에 맞춰 전송 수요를 변경할 수 있습니다.

• 에이전트 프로세스는 내결함성 집단입니다. 한 에이전트의 실행이 중지되면 나머지 에이전트는 계속 작동합니다. 모든 에이전트가 중지되면 에이전트를 다시 시작할 때 에이전트가 중지된 곳에서 전송이 다시 시작됩니다. 이렇게 하면 에이전트 모니터링, 전송 재시도, 복구 로직 구현을 피할 수 있습니다. Google Kubernetes Engine과 에이전트를 조정하여 전송 다운타임 없이 에이전트 풀을 패치, 이전, 동적 확장할 수 있습니다.

  예를 들어 두 에이전트가 실행되는 동안 두 개의 전송을 제출합니다. 머신 재부팅 또는 운영체제 패치로 인해 에이전트 중 하나가 중지되면 나머지 에이전트는 계속 작동합니다. 두 전송은 계속 실행 중이지만 단일 에이전트에서 데이터를 이동하므로 속도가 느립니다. 나머지 에이전트도 중지될 경우 실행 중인 에이전트가 없으므로 모든 전송이 중지됩니다. 에이전트 프로세스를 다시 시작하면 중단된 지점부터 전송이 다시 시작됩니다.

• 에이전트 프로세스는 풀에 속합니다. 전체적으로 데이터를 병렬로 이동합니다. 따라서 풀에 있는 모든 에이전트는 전송하려는 모든 데이터 소스에 대해 동일한 액세스 권한을 가지고 있어야 합니다.

  예를 들어 특정 파일 시스템에서 데이터를 전송하려면 에이전트 풀에서 에이전트를 호스팅하는 모든 머신에 파일 시스템을 마운트해야 합니다. 풀의 일부 에이전트는 데이터 소스에 연결할 수 있지만 다른 에이전트는 연결할 수 없는 경우 해당 데이터 소스에서 전송할 수 없습니다.

시작하기 전에

전송을 구성하기 전에 사용자 및 서비스 계정에 대한 액세스를 구성했는지 확인하세요.

gcloud 명령어를 사용하려는 경우 gcloud CLI를 설치합니다.

전송 에이전트 설치 및 실행

중요: 전송 작업을 만들 수 있는 사용자는 에이전트가 액세스할 수 있는 모든 파일 시스템 디렉터리에서 데이터를 검색하고 다운로드할 수 있습니다. 에이전트가 루트로 실행되고 전체 파일 시스템에 대한 액세스 권한이 부여되면 악의적인 행위자가 호스트를 인계받을 수 있습니다. 필요한 에이전트로만 에이전트 액세스를 제한하는 것이 좋습니다.

에이전트 풀별로 최소 3개의 에이전트를 설치하는 것이 좋습니다(별도의 머신에 설치하는 것이 이상적임). 실행할 에이전트 수 결정에 대한 자세한 내용은 전송 에이전트 성능 극대화를 참조하세요.

에이전트 ID 프리픽스에 개인 식별 정보(PII) 또는 보안 데이터와 같은 민감한 정보를 포함하지 마세요. 리소스 이름은 다른 Google Cloud 리소스의 이름으로 전파될 수 있으며 프로젝트 외부의 Google 내부 시스템에 노출될 수 있습니다.

전송 에이전트를 설치하고 실행하려면 다음 안내를 따르세요.

2023년 4월 12일: S3 호환 스토리지에서 전송하는 데 사용되는 에이전트는 서비스 계정 키로 인증해야 합니다. 서비스 계정 키 파일의 경로를 지정하려면 --creds-file 플래그를 사용합니다. 서비스 계정을 사용하지 못하면 전송이 중단됩니다. 작업이 진행 중으로 표시되지만 데이터가 전송되지 않습니다.

이 알림은 문제가 해결되면 삭제됩니다.

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 run

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

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

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

기본 사용자 인증 정보

Docker 컨테이너에서 gcloud 기본 사용자 인증 정보로 인증하도록 하려면 다음 명령어를 실행해 애플리케이션 기본 사용자 인증 정보가 있는 파일을 포함한 Docker 볼륨을 만드세요.

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

그런 후 다음 명령어를 사용하여 에이전트를 설치하고 --volumes-from 플래그를 사용하여 gcloud-config 사용자 인증 정보 볼륨을 마운트합니다.

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

서비스 계정 인증

서비스 계정 사용자 인증 정보를 사용하여 전송 에이전트 docker run을 설치하고 실행하려면 --creds-file 플래그를 사용하여 JSON 형식의 서비스 계정 키 경로를 지정합니다.

경로에는 /transfer_root 문자열이 프리픽스로 추가되어야 합니다.

서비스 계정 키에 대한 자세한 내용은 서비스 계정 키 생성 및 관리를 참조하세요.

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.

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

에이전트 연결 확인

에이전트가 연결되었는지 확인하려면 다음 단계를 따르세요.

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

   에이전트 풀로 이동

   에이전트 풀이 연결된 에이전트 수와 함께 표시됩니다.

2. 연결된 에이전트에 대한 세부정보를 보려면 에이전트 풀을 선택하세요.

에이전트 생성 후 10분 내에 새 에이전트가 에이전트 풀 페이지에 표시되지 않으면 에이전트가 연결되지 않음을 참조하세요.

에이전트 활동 모니터링

Cloud Monitoring 알림을 사용하여 에이전트 활동을 모니터링할 수 있습니다.

project, agent_pool, agent_id 측정기준과 함께 Monitoring을 사용할 수 있습니다.

이 모니터링 데이터를 사용하여 전송과 관련된 잠재적인 문제를 알리도록 알림을 설정할 수 있습니다. 이렇게 하려면 다음 Google Cloud 측정항목 중 하나에 대한 알림을 만드세요.

측정항목 이름	설명 내용	추천 용도
storagetransfer.googleapis.com/agent/transferred_bytes_count	특정 에이전트가 특정 시점에 서비스를 제공하는 모든 작업 사이에서 데이터가 이동하는 속도를 측정합니다.	성능 하락 알림
storagetransfer.googleapis.com/agent/connected	Google Cloud가 최근 하트비트 메시지를 수신한 각 에이전트에 대해 True인 부울입니다.	실패한 에이전트 알림 합리적인 성능에 필요하다고 판단되는 여러 에이전트에 미달 에이전트 머신 문제 알림

에이전트 중지

에이전트를 중지하려면 에이전트의 Docker 컨테이너 ID에서 docker stop을 실행합니다. ID를 찾고 에이전트를 중지하려면 다음 안내를 따르세요.

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

   에이전트 풀로 이동

2. 중지할 에이전트가 포함된 에이전트 풀을 선택합니다.

3. 목록에서 에이전트를 선택합니다. 필터 필드를 사용하여 프리픽스, 에이전트 상태, 에이전트 연령 등을 검색합니다.

4. 에이전트 중지를 클릭합니다. 특정 컨테이너 ID가 표시된 docker stop 명령어가 표시됩니다.

5. 에이전트가 실행 중인 머신에서 명령어를 실행합니다. docker stop 명령어가 성공하면 컨테이너 ID가 반환됩니다.

중지되면 에이전트가 에이전트 풀 목록에 연결 해제됨으로 표시됩니다.

에이전트 삭제

특정 에이전트를 삭제하려면 머신에서 실행 중인 에이전트를 나열합니다.

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

그런 다음 에이전트 ID를 transfer agents delete에 전달합니다.

gcloud transfer agents delete --ids=id1,id2,…

머신에서 실행 중인 모든 에이전트를 삭제하려면 --all 플래그 또는 --uninstall 플래그를 사용합니다. 두 플래그 모두 머신의 모든 에이전트를 삭제합니다. --uninstall 플래그는 에이전트 Docker 이미지를 추가로 제거합니다.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

파일 시스템 전송 세부정보

증분 전송

Storage Transfer Service는 소스 및 대상에 있는 데이터를 연산하여 모든 전송을 시작하여 마지막 전송 이후 새로운 소스 파일, 업데이트 또는 삭제된 소스 파일을 확인합니다. 이를 통해 머신에서 전송하는 데이터의 양을 줄이고, 대역폭을 효율적으로 사용하며, 전송 시간을 단축시킵니다.

파일이 변경되었는지 감지하기 위해 gsutil rsync와 유사한 알고리즘을 사용합니다. 소스 파일의 최종 수정 시간과 크기를 확인하고 파일을 마지막으로 복사한 시점의 최종 수정 시간과 크기를 비교합니다. 새 파일이나 변경된 파일이 감지되면 전체 파일이 대상에 복사됩니다. 파일 최신 상태에 대한 자세한 내용은 데이터 일관성 세부정보를 참조하세요.

기본적으로 Google은 소스에서 삭제된 파일을 감지하지만 조치를 취하지 않습니다. 만들기 또는 수정 시 소스에도 없는 대상 파일 삭제 동기화 옵션을 선택하면 전송 시 대상에서 해당 객체가 삭제됩니다.

소스에도 없는 대상 파일 삭제 동기화 옵션을 선택하면 소스에서 실수로 삭제된 파일도 대상에서 삭제됩니다. 이 옵션을 사용할 경우 실수로 인한 데이터 손실을 방지하려면 대상 버킷에서 객체 버전 관리를 사용 설정하는 것이 좋습니다. 그러면 실수로 인해 파일이 삭제되어도 Cloud Storage의 객체를 이전 버전으로 복원할 수 있습니다.

데이터 일관성 세부정보

성공적인 전송 작업은 작업의 전체 실행 시간 동안 존재하고 수정되지 않은 모든 소스 파일을 전송합니다. 전송 중에 생성, 업데이트 또는 삭제된 소스 파일의 경우 대상 데이터 세트에 변경사항이 반영 또는 반영되지 않을 수 있습니다.

Storage Transfer Service는 파일의 마지막 수정 시간과 크기를 사용하여 변경사항이 있는지 확인합니다. 마지막 수정 시간 또는 크기를 변경하지 않고 파일이 업데이트된 경우 delete-objects-from-source 옵션을 사용 설정하면 이러한 변경사항에서 데이터가 손실될 수 있습니다.

delete-objects-from-source 기능을 사용할 때는 데이터 손실 방지를 위해 전송 기간 동안 소스에 대한 쓰기를 고정하는 것이 좋습니다.

소스에 대한 쓰기를 고정하려면 다음 중 하나를 수행합니다.

• 전송하려는 디렉터리를 클론한 후 클론된 디렉터리를 전송 소스로 사용합니다.
• 소스 디렉터리에 쓰기를 수행하는 애플리케이션을 중지합니다.

전송 중에 발생한 변경사항을 반영해야 하면 전송을 다시 실행하거나 작업이 실행되는 동안 소스 파일 시스템을 읽기 전용으로 설정하면 됩니다.

Cloud Storage에는 디렉터리 개념이 없으므로 빈 소스 디렉터리가 전송되지 않습니다.

중요: 소스 데이터를 삭제하기 전에 전송이 성공했는지 확인하는 것이 좋습니다. 이 서비스에는 Cloud Storage에서 데이터를 복원할 수 있는 기능이 없습니다.