Dataproc 커스텀 이미지 만들기

사전 설치된 패키지가 포함된 커스텀 이미지로 Dataproc 클러스터를 만들 수 있습니다. 이 페이지에서는 커스텀 이미지를 만들고 Dataproc 클러스터에 설치하는 방법을 설명합니다.

사용 고려사항 및 제한사항

  • 커스텀 이미지 전체 기간: 클러스터에 최신 서비스 업데이트 및 버그 수정이 적용되도록 보장하기 위해 커스텀 이미지를 사용한 클러스터 만들기는 커스텀 이미지 생성일로부터 365일까지로 제한됩니다. 커스텀 이미지로 만든 기존 클러스터는 무한대로 실행될 수 있습니다.

    특정 커스텀 이미지를 사용하여 365일 이상 클러스터를 만들려면 자동화를 사용해야 할 수 있습니다. 자세한 내용은 만료된 커스텀 이미지를 사용하여 클러스터 만들기를 참조하세요.

  • Linux만 해당: 이 문서의 안내는 Linux 운영체제에만 적용됩니다. 다른 운영체제는 향후 출시되는 Dataproc 버전에서 지원될 예정입니다.

  • 지원되는 기본 이미지: 커스텀 이미지 빌드는 Dataproc 기본 이미지에서 시작해야 합니다. Debian, Rocky Linux, Ubuntu 기본 이미지가 지원됩니다.

    • 기본 이미지 가용성: Dataproc 출시 노트에 발표된 새 이미지는 발표일로부터 1주일 동안 커스텀 이미지의 기본으로 사용될 수 없습니다.

  • 선택적 구성요소 사용:

    커스텀 이미지에 사용된 기본 이미지와 관계없이 클러스터를 만들 때 선택적 구성요소를 나열하거나 선택해야 합니다.

    예시: Google Cloud CLI 클러스터 생성 명령어:

    gcloud dataproc clusters create CLUSTER_NAME
    --image=CUSTOM_IMAGE_URI  \
    --optional-components=COMPONENT_NAME \
    ... other flags

    클러스터를 만들 때 구성요소 이름을 지정하지 않으면 구성요소(커스텀 OS 패키지 및 구성 포함)가 삭제됩니다.

  • 호스팅된 커스텀 이미지 사용: 다른 프로젝트에서 호스팅되는 커스텀 이미지를 사용하는 경우 프로젝트의 Dataproc 서비스 에이전트 서비스 계정에 호스트 프로젝트의 이미지에 대한 compute.images.get 권한이 있어야 합니다. 호스팅된 이미지에 대한 roles/compute.imageUser 역할을 프로젝트의 Dataproc 서비스 에이전트 서비스 계정에 부여하여 이 권한을 부여할 수 있습니다. 조직 내에서 커스텀 이미지 공유를 참조하세요.

  • 보안 부트 MOK(머신 소유자 키) 보안 비밀 사용: Dataproc 커스텀 이미지로 부안 부트를 사용 설정하려면 다음을 수행합니다.

    1. Secret Manager API(secretmanager.googleapis.com)를 사용 설정합니다. Dataproc에서 Secret Manager 서비스를 사용하여 키 쌍을 생성하고 관리합니다.

    2. 커스텀 이미지를 생성할 때 generate_custom_image.py 명령어에 --service-account="SERVICE_ACCOUNT" 플래그를 추가합니다. 참고: 서비스 계정에 프로젝트에 대한 Secret Manager 뷰어 역할(roles/secretmanager.viewer)과 공개 및 비공개 보안 비밀에 대한 Secret Manager 접근자 역할(roles/secretmanager.secretAccessor)을 부여해야 합니다.

      예시를 포함한 자세한 내용은 README.md 및 GitHub의 GoogleCloudDataproc/custom-images 저장소 examples/secure-boot 디렉터리 내에 있는 기타 파일을 참조하세요.

      보안 부트 중지: 기본적으로 Dataproc 커스텀 이미지 스크립트는 Dataproc 클러스터에서 실행될 때 Secret Manager를 사용하여 키 쌍을 생성하고 관리합니다. 커스텀 이미지에서 secure-boot를 사용하지 않으려면 커스텀 이미지를 생성할 때 generate_custom_image.py 명령어에 --trusted-cert=""(플래그 값이 비어 있음)를 포함합니다.

시작하기 전에

커스텀 이미지를 생성하기 전에 프로젝트를 설정해야 합니다.

프로젝트 설정

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  7. gcloud CLI를 초기화하려면 다음 명령어를 실행합니다. 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  13. gcloud CLI를 초기화하려면 다음 명령어를 실행합니다. 

    gcloud init
  14. Python 3.11+를 설치합니다.
  15. 커스텀 패키지 또는 업데이트 구성을 설치하는 맞춤설정 스크립트를 준비합니다. 예를 들면 다음과 같습니다. 
      #! /usr/bin/bash
  apt-get -y update
  apt-get install python-dev
  apt-get install python-pip
  pip install numpy

    16. 프로젝트에 Cloud Storage 버킷 만들기

    1. In the Google Cloud console, go to the Cloud Storage Buckets page.

      Go to Buckets

    2. Click Create.
    3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
      1. In the Get started section, do the following:
        • Enter a globally unique name that meets the bucket naming requirements.
        • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
      2. In the Choose where to store your data section, do the following:
        1. Select a Location type.
        2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
        3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

          Set up cross-bucket replication

          1. In the Bucket menu, select a bucket.

          2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
      3. In the Choose how to store your data section, do the following:
        1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
        2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      5. In the Choose how to protect object data section, do the following:
        • Select any of the options under Data protection that you want to set for your bucket.
          • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
          • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
          • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
            • To enable Object Retention Lock, click the Enable object retention checkbox.
            • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
        • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
    4. Click Create.

    커스텀 이미지 생성

    Python 프로그램인 generate_custom_image.py를 사용하여 Dataproc 커스텀 이미지를 만듭니다.

    기능 소개

    generate_custom_image.py 프로그램은 지정된 Dataproc 기본 이미지를 사용하여 임시 Compute Engine VM 인스턴스를 시작한 후 VM 인스턴스 내에서 맞춤설정 스크립트를 실행하여 커스텀 패키지를 설치하거나 구성을 업데이트합니다. 맞춤설정 스크립트가 완료되면 VM 인스턴스를 종료하고 VM 인스턴스 디스크에서 Dataproc 커스텀 이미지를 만듭니다. 커스텀 이미지가 생성되면 임시 VM이 삭제됩니다. 커스텀 이미지가 저장되며 Dataproc 클러스터를 만드는 데 사용할 수 있습니다.

    generate_custom_image.py 프로그램은 gcloud CLI를 사용하여 Compute Engine에서 다단계 워크플로를 실행합니다.

    코드 실행

    GitHub(Dataproc 커스텀 이미지)에서 파일을 포크하거나 클론합니다.

    그런 다음 generate_custom_image.py 스크립트를 실행하여 Dataproc에서 커스텀 이미지를 생성하고 저장하도록 합니다.

    python3 generate_custom_image.py \
    --image-name=CUSTOM_IMAGE_NAME \
    [--family=CUSTOM_IMAGE_FAMILY_NAME] \
    --dataproc-version=IMAGE_VERSION \
    --customization-script=LOCAL_PATH \
    --zone=ZONE \
    --gcs-bucket=gs://BUCKET_NAME \
    [--no-smoke-test]

    필수 플래그

    • --image-name: 커스텀 이미지의 출력 이름입니다.

    • --dataproc-version: 커스텀 이미지에서 사용할 Dataproc 이미지 버전입니다. 버전을 x.y.z-os 또는 x.y.z-rc-os 형식으로 지정합니다(예: '2.0.69-debian10').

    • --customization-script: 커스텀 패키지를 설치하거나 다른 맞춤설정을 수행하기 위해 도구가 실행될 스크립트에 대한 로컬 경로입니다. 이 스크립트는 커스텀 이미지를 만드는 데 사용되는 임시 VM에서만 Linux 시작 스크립트로 실행됩니다. 커스텀 이미지를 사용하여 클러스터를 만들 때 수행할 다른 초기화 작업에 다른 초기화 스크립트를 지정할 수 있습니다.

      프로젝트 간 이미지: 커스텀 이미지가 여러 프로젝트에서 클러스터를 만드는 데 사용되는 경우 이미지 내에 저장된 gcloud 또는 gsutil 명령어 캐시로 인해 오류가 발생할 수 있습니다. 맞춤설정 스크립트에 다음 명령어를 포함하여 캐시된 사용자 인증 정보를 삭제하면 이 문제를 방지할 수 있습니다.

      rm -r /root/.gsutil /root/.config/gcloud

    • --zone: 커스텀 이미지를 만드는 데 사용할 임시 VM을 만드는 generate_custom_image.py의 Compute Engine 영역입니다.

    • --gcs-bucket: gs://BUCKET_NAME 형식의 URI로, Cloud Storage 버킷을 가리킵니다. generate_custom_image.py는 이 버킷에 로그 파일을 작성합니다.

    선택적 플래그

    • --family: 커스텀 이미지의 이미지 계열입니다. 이미지 계열은 유사한 이미지를 함께 그룹화하는 데 사용되며, 클러스터를 생성할 때 해당 계열의 최신 이미지에 대한 포인터로 사용할 수 있습니다. 예를 들면 custom-2-2-debian12입니다.
    • --no-smoke-test: 새로 빌드한 커스텀 이미지의 스모크 테스트를 사용 중지하는 선택적 플래그입니다. 스모크 테스트는 새로 빌드된 이미지로 Dataproc 테스트 클러스터를 만들고 작은 작업을 실행한 다음 테스트가 끝날 때 클러스터를 삭제합니다. 스모크 테스트는 기본적으로 실행되어 새로 빌드된 커스텀 이미지가 기능적인 Dataproc 클러스터를 만들 수 있는지 확인합니다. --no-smoke-test 플래그를 사용하여 이 단계를 중지하면 커스텀 이미지 빌드 프로세스가 빨라지지만 사용하지 않는 것이 좋습니다.
    • --subnet: 커스텀 Dataproc 이미지를 빌드하는 VM을 만드는 데 사용할 서브네트워크입니다. 프로젝트가 공유 VPC에 포함된 경우 전체 서브네트워크 URL을 projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET 형식으로 지정해야 합니다.

    • --optional-components: 이 플래그는 기본 이미지 버전 2.3 이상을 사용하는 경우에만 사용할 수 있습니다. SOLR, RANGER, TRINO, DOCKER, FLINK, HIVE_WEBHCAT, ZEPPELIN, HUDI, ICEBERG, PIG(PIG는 이미지 버전 2.3 이상에서 선택적 구성요소로 사용 가능)와 같은 이미지에 설치할 선택적 구성요소 목록입니다.

      예시: Google Cloud CLI 클러스터 생성 명령어:

      gcloud dataproc clusters create CLUSTER_NAME
    --image=CUSTOM_IMAGE_URI  \
    --optional-components=COMPONENT_NAME \
    ... other flags

    사용 가능한 선택적 플래그 목록은 GitHub의 선택적 인수를 참조하세요.

    generate_custom_image.py가 성공하면 커스텀 이미지의 imageURI가 터미널 창 출력에 표시됩니다(전체 imageUri는 아래에 굵게 표시됨).

    ...
managedCluster:
    clusterName: verify-image-20180614213641-8308a4cd
    config:
      gceClusterConfig:
        zoneUri: ZONE
      masterConfig:
        imageUri: https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

INFO:__main__:Successfully built Dataproc custom image: CUSTOM_IMAGE_NAME
INFO:__main__:

#####################################################################
  WARNING: DATAPROC CUSTOM IMAGE 'CUSTOM_IMAGE_NAME'
           WILL EXPIRE ON 2018-07-14 21:35:44.133000.
#####################################################################

    커스텀 이미지 버전 라벨(고급 사용)

    Dataproc의 표준 커스텀 이미지 도구를 사용할 때 이 도구는 생성된 커스텀 이미지에 goog-dataproc-version 라벨을 설정합니다. 이 라벨은 이미지에서 소프트웨어를 관리하기 위해 Dataproc에 사용되는 특성 기능 및 프로토콜을 반영합니다.

    고급 사용: 자체 프로세스를 수행하여 커스텀 Dataproc 이미지를 만드는 경우 다음과 같이 커스텀 이미지에 goog-dataproc-version 라벨을 수동으로 추가해야 합니다.

    1. 커스텀 이미지 만들기를 위해 사용되는 기본 Dataproc 이미지에서 goog-dataproc-version 라벨을 추출합니다.

      gcloud compute images describe ${BASE_DATAPROC_IMAGE} \
    --project cloud-dataproc \
    --format="value(labels.goog-dataproc-version)"

    2. 커스텀 이미지에 라벨을 설정합니다.

      gcloud compute images add-labels IMAGE_NAME --labels=[KEY=VALUE,...]

    커스텀 이미지 사용

    Dataproc 클러스터를 만들 때 커스텀 이미지를 지정합니다. 커스텀 이미지는 Cloud Compute 이미지에 저장되어 생성일로부터 365일 동안 Dataproc 클러스터를 만드는 데 사용할 수 있습니다. 365일 만료일이 지난 후 커스텀 이미지를 사용하려면 만료된 커스텀 이미지를 사용하여 클러스터 만들기를 참조하세요.

    커스텀 이미지 URI

    커스텀 이미지의 imageUri를 클러스터 생성 작업에 전달합니다. 이 URI는 다음 세 가지 방법 중 하나로 지정할 수 있습니다.

    1. 전체 URI:
      https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/`gs://`BUCKET_NAME`
    2. 부분 URI: projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
    3. 닉네임: CUSTOM_IMAGE_NAME

    커스텀 이미지는 계열 URI에서 지정할 수 있으며 항상 이미지 계열에서 가장 최근의 이미지를 선택합니다.

    1. 전체 URI:
      https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME/var>
    2. 부분 URI: projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME

    커스텀 이미지 URI 찾기

    Google Cloud CLI

    다음 명령어를 실행하여 커스텀 이미지 이름을 나열합니다.

    gcloud compute images list

    커스텀 이미지의 URI(selfLink)를 나열하려면 커스텀 이미지 이름을 다음 명령어에 전달합니다.

    gcloud compute images describe custom-image-name

    출력 스니펫:

    ...
name: CUSTOM_IMAGE_NAME
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

    콘솔

    1. Google Cloud 콘솔에서 Compute Engine→이미지 페이지를 열고 이미지 이름을 클릭합니다. filter images 필드에 쿼리를 삽입하여 표시되는 이미지의 수를 제한할 수 있습니다.
    2. 이미지 세부정보 페이지가 열립니다. 동등한 REST를 클릭합니다.
    3. REST 응답은 이미지 URI인 selfLink를 포함하여 이미지에 대한 추가 정보를 나열합니다. 
      {
  ...
  "name": "my-custom-image",
  "selfLink": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME",
  "sourceDisk": ...,
  ...
}

    커스텀 이미지로 클러스터 만들기

    gcloud CLI, Dataproc API 또는Google Cloud 콘솔을 사용하여 클러스터를 만듭니다.

    gcloud CLI

    --image 플래그와 함께 dataproc clusters create 명령어를 사용하여 커스텀 이미지로 Dataproc 클러스터를 만듭니다.

    예시: 
    gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM_IMAGE_URI \
    --region=REGION \
    ... other flags

    REST API

    cluster.create API 요청에 포함된 masterConfig, workerConfig, secondaryWorkerConfig(해당되는 경우) 객체의 InstanceGroupConfig.imageUri 필드에 커스텀 이미지 URI를 지정하여 커스텀 이미지로 클러스터를 만듭니다.

    예시: 커스텀 이미지로 표준 Dataproc 클러스터(마스터 1개, 워커 노드 2개)를 만드는 REST 요청입니다. 

    POST /v1/projects/PROJECT_ID/regions/REGION/clusters/
{
  "clusterName": "CLUSTER_NAME",
  "config": {
    "masterConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    },
    "workerConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    }
  }
}

    콘솔

    1. Dataproc 클러스터 만들기 페이지를 엽니다. 클러스터 설정 패널이 선택되었습니다.
    2. 버전 관리 섹션에서 변경을 클릭합니다. 커스텀 이미지 탭을 선택하고 Dataproc 클러스터에 사용할 커스텀 이미지를 선택한 후 선택을 클릭합니다. 선택한 커스텀 이미지를 통해 클러스터의 VM이 프로비저닝됩니다.

    커스텀 이미지로 Dataproc 클러스터 속성 재정의

    커스텀 이미지를 사용하면 클러스터 생성 중에 설정된 클러스터 속성을 덮어쓸 수 있습니다. 커스텀 이미지로 클러스터를 만들고 클러스터 생성 작업에서 커스텀 이미지에서 설정한 값과 다른 값으로 속성을 설정하는 경우에는 커스텀 이미지에서 설정한 속성 값이 우선 적용됩니다.

    커스텀 이미지로 클러스터 속성을 설정하려면 다음 안내를 따르세요.

    1. 커스텀 이미지 맞춤설정 스크립트에서 /etc/google-dataproc에 dataproc.custom.properties 파일을 만든 다음 파일에 클러스터 속성 값을 설정합니다.

      • 샘플 dataproc.custom.properties 파일:
      dataproc.conscrypt.provider.enable=VALUE
dataproc.logging.stackdriver.enable=VALUE
      • 맞춤설정 스크립트 파일 생성 스니펫을 샘플링하여 클러스터 속성 2개를 재정의합니다.
      cat <<EOF >/etc/google-dataproc/dataproc.custom.properties
dataproc.conscrypt.provider.enable=true
dataproc.logging.stackdriver.enable=false
EOF

    만료된 커스텀 이미지를 사용하여 클러스터 만들기

    기본적으로 커스텀 이미지는 이미지 생성일로부터 365일 후에 만료됩니다. 다음 단계를 완료하여 만료된 커스텀 이미지를 사용하는 클러스터를 만들 수 있습니다.

    1. 만료된 커스텀 이미지나 10일 이내에 만료될 커스텀 이미지를 사용하여 Dataproc 클러스터를 만듭니다.

      gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --region=REGION \
    ... other flags

    2. gcloud CLI가 클러스터 dataproc:dataproc.custom.image.expiration.token 속성 이름 및 토큰 값을 포함하는 오류 메시지를 실행합니다.

    dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE

    TOKEN_VALUE 문자열을 클립보드에 복사합니다.

    1. gcloud CLI를 사용하여 Dataproc 클러스터를 다시 만들고 복사한 TOKEN_VALUE를 클러스터 속성으로 추가합니다.

      gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --properties=dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE \
    --region=REGION \
    ... other flags

    커스텀 이미지로 클러스터 만들기가 성공합니다.