Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

조정 파이프라인 배포

이 페이지에서는 오케스트레이션 파이프라인의 배포 환경 구성을 만드는 프로세스를 설명합니다.

배포 환경 정보

프로젝트에는 하나 이상의 배포 환경이 있을 수 있습니다. 각 배포 환경의 구성은 이 환경에 속하는 파이프라인과 리소스가 배포되는 방식을 정의합니다. 예를 들어 개발용 배포 환경과 프로덕션용 환경을 별도로 둘 수 있습니다. 이러한 배포 환경에는 별도의 파이프라인 세트가 있을 수 있으며 서로 다른 러너 환경에서 실행될 수 있습니다.

각 배포 환경에는 러너 환경이 있어야 합니다. Managed Airflow는 파이프라인이 배포된 후 실행하는 오케스트레이션 엔진입니다. 미리보기에서는 배포 환경에 할당한 Managed Airflow 환경만 지원되는 러너 환경입니다.

배포 환경의 아티팩트 버킷을 지정할 수 있습니다. 이 버킷에는 파이프라인이 실행하는 버전이 지정된 파이프라인 애셋과 아티팩트 버킷에 출력되는 일부 작업의 결과가 저장됩니다.

파이프라인 번들 정보

오케스트레이션 파이프라인은 파이프라인 번들에 배포됩니다. 파이프라인 번들에는 공통 배포 주기를 공유하는 하나 이상의 파이프라인과 파이프라인 애셋이 포함됩니다.

각 번들에는 여러 버전이 있을 수 있습니다.

번들을 배포하면 특정 버전의 번들 패키지에 있는 모든 파이프라인과 함께 제공되는 스크립트가 함께 배포됩니다.
번들의 현재 버전은 하나 (최신 버전으로 배포된 버전)이며 이전 코드 버전으로 트리거된 개별 파이프라인 실행은 중단 없이 계속 실행됩니다.
현재 버전과 다른 버전에서는 파이프라인을 수동으로 트리거할 수 없습니다.
번들에서 파이프라인이 삭제되고 새 버전의 번들이 배포되면 파이프라인이 새 버전에서 실행되지 않지만 이전에 활성 상태로 실행 중인 실행은 계속됩니다.

시작하기 전에

이미 러너 환경을 만들었는지 확인합니다.

파이프라인 번들 스캐폴딩 초기화

오케스트레이션 파이프라인은 저장소에서 오케스트레이션 파이프라인의 스캐폴딩을 초기화하는 gcloud CLI 명령어를 제공합니다.

스캐폴딩에는 다음이 포함됩니다.

orchestration-pipeline.yaml: 일정이 포함되어 있지만 정의된 작업이 없는 파이프라인 정의의 예입니다.
deployment.yaml: 파이프라인이 배포되는 방식을 정의하는 파이프라인 배포 구성의 예입니다. 러너 환경, 아티팩트 버킷, 파이프라인 작업에서 사용하는 기타 리소스의 구성이 포함됩니다.
.github/workflows/validate.yaml: main 브랜치에 대한 pull 요청이 생성될 때 파이프라인을 검증하는 GitHub 작업의 예입니다.
.github/workflows/deploy.yaml: GitHub 저장소의 main 브랜치에 변경사항을 병합할 때 파이프라인을 배포하는 GitHub 작업의 예입니다.

조정 파이프라인을 초기화하려면 다음 단계를 따르세요.

저장소 또는 프로젝트 디렉터리로 이동합니다. 이 명령어는 명령어를 실행한 디렉터리에 새 파일을 만듭니다.
다음 gcloud CLI 명령어를 실행합니다.
```
gcloud beta orchestration-pipelines init PIPELINE_NAME \
  --environment DEPLOYMENT_ENVIRONMENT \
  --composer-environment RUNNER_ENVIRONMENT \
  --artifacts-bucket ARTIFACTS_BUCKET_NAME \
  --project PROJECT_ID \
  --region REGION \
  --service-account SERVICE_ACCOUNT
```
다음을 바꿉니다.
- PIPELINE_NAME: 초기 파이프라인의 이름입니다.
- DEPLOYMENT_ENVIRONMENT: 초기 배포 환경의 이름입니다.
- RUNNER_ENVIRONMENT: 러너 환경의 이름입니다.
- ARTIFACTS_BUCKET_NAME: 파이프라인 작업 아티팩트를 저장하는 데 사용되는 Cloud Storage 버킷입니다(gs:// 접두사 제외).
- PROJECT_ID: 러너 환경이 있는 Google Cloud 프로젝트의 프로젝트 ID입니다.
- REGION: 러너 환경이 있는 리전입니다.
- SERVICE_ACCOUNT: 변수로 사전 설정될 서비스 계정입니다. 이 값을 러너 환경의 서비스 계정으로 설정합니다. 파이프라인 정의 및 리소스 프로필에서 이 변수를 사용할 수 있습니다. 예를 들어 가장 체인을 사용하는 작업에서 impersonationChain 매개변수의 값으로 사용됩니다.
  
  환경 세부정보를 확인하여 러너 환경의 서비스 계정을 확인할 수 있습니다. gcloud CLI에서 환경 서비스 계정은 nodeConfig.serviceAccount 키에 제공됩니다.
  
  중요: 이 매개변수는 변수의 값을 지정합니다. 러너 환경은 생성 시 지정한 원래 서비스 계정으로 계속 실행됩니다. 변수 값을 다른 서비스 계정으로 변경하더라도 러너 환경의 서비스 계정을 사용하여 모든 파이프라인 작업을 실행합니다.
예:
```
gcloud beta orchestration-pipelines init example-pipeline \
  --environment development \
  --composer-environment production-runner-us-central1 \
  --artifacts-bucket production-artifacts \
  --project example-production-project \
  --region us-central1 \
  --service-account example-account@example-project.iam.gserviceaccount.com
```

러너 환경 구성 추가

러너 환경은 배포 환경의 composer_environment 키에 지정됩니다. 여러 배포 환경을 사용하는 경우 각 환경에 별도의 러너 환경을 지정할 수 있습니다.

composer_environment 키의 러너 환경 이름은 개발 환경 구성의 project 및 region 키와 함께 파이프라인이 배포되는 러너 환경을 지정합니다.

다음 예에서는 example-development-project 프로젝트의 us-central1 리전에 있는 example-runner-environment이라는 이름의 러너 환경을 추가하는 방법을 보여줍니다.

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "example-runner-environment"
    ...

러너 환경 구성 조정

다른 Managed Service for Apache Airflow 환경과 마찬가지로 러너 환경을 구성할 수 있습니다.

예를 들어 러너 환경에서 파이프라인의 Python 스크립트를 로컬로 실행하기 위해 Python 종속 항목을 설치합니다.
환경을 확장하여 리소스를 늘리거나 줄이거나 러너 환경에서 Airflow 작업자를 확장하는 방식을 변경합니다.
Airflow 구성 옵션을 재정의하여 Airflow를 구성합니다.

파이프라인 애셋 추가 및 작업 구성

작업과 파이프라인 애셋을 포함하도록 파이프라인의 정의 파일을 수정합니다.

코드 예시와 작업 매개변수 설명은 오케스트레이션 파이프라인 DSL 참조를 참고하세요.
자세한 안내 예시는 Google Cloud 데이터 에이전트 키트 확장 프로그램 문서의 데이터 엔지니어링 파이프라인 빌드를 참고하세요.

Hello World 작업 예시

다음은 최소한의 파이프라인 작업의 예입니다. 이를 사용하여 배포 환경의 구성을 테스트할 수 있습니다.

스캐폴딩 파이프라인에 다음 작업을 추가하고 actions: []를 대체합니다.

actions:
  - python:
      name: "hello_world_script_run"
      executionTimeout: "30m"
      mainFilePath: "scripts/hello_world.py"
      pythonCallable: "main"
      engine:
        local: {}

저장소에 scripts라는 새 하위 디렉터리를 만들고 다음 파일을 /scripts/hello_world.py로 저장합니다.
```
def main():
  print("Hello, World!")
```

파이프라인 검증

유효성 검사 명령어는 파이프라인 정의 파일의 구문과 유형 정확성을 확인하고 배포 구성 및 파이프라인 정의 파일 모두에서Google Cloud 프로젝트 및 Managed Service for Apache Airflow 환경과 같은 리소스에 대한 시맨틱 검사도 실행합니다.

기본적으로 원격 러너 환경에 도달하는 것을 비롯한 모든 배포 환경의 전체 유효성 검사가 실행됩니다. 다음 매개변수를 사용하여 배포 구성의 특정 부분을 검증할 수 있습니다.

--mode: 원격 러너 환경에 도달하지 않도록 syntax-only로 설정합니다. 기본값은 full입니다.
--environment: 특정 환경만 검증합니다.
--pipeline-paths: 검증할 파이프라인 정의 파일의 경로 목록으로 쉼표로 구분되어 있습니다.
--substitutions 및 --substitutions-file: 검증 중에 배포 구성 매개변수를 대체합니다.

로컬 파이프라인 버전을 배포하기 전에 빠른 확인으로 이 명령어를 실행하고 CI/CD 워크플로의 일부로 GitHub 작업으로 실행할 수 있습니다.

저장소에서 다음 명령어를 실행하여 파이프라인의 유효성을 검사합니다.

gcloud beta orchestration-pipelines validate

파이프라인 번들 배포

이 섹션에서는 파이프라인을 배포하는 다양한 방법을 설명합니다.

오케스트레이션 파이프라인은 파이프라인 번들을 배포하는 두 가지 방법을 지원합니다. 이러한 접근 방식은 개발 및 출시 워크플로의 다양한 단계에서 함께 작동하도록 설계되었습니다.

로컬 번들 버전 배포: 파이프라인 애셋, 파이프라인 정의, 배포 구성의 현재 버전을 배포합니다. 새 번들 ID는 작업공간 이름과 번들 내 파일의 md5를 기반으로 자동 생성됩니다.

이 배포 유형은 개발 목적으로 사용됩니다. 또한 파이프라인을 스테이징 러너 환경에 배포하는 별도의 배포 구성을 만드는 것이 좋습니다.
커밋된 변경사항 배포: 파이프라인 애셋, 파이프라인 정의, 배포 구성에 변경사항을 커밋한 후 러너 환경에 새 버전의 파이프라인 번들을 배포할 수 있습니다. 새 번들의 ID가 저장소의 Git 커밋 SHA에 연결됩니다.

이 배포 유형은 CI/CD의 일부로 실행되도록 설계되었습니다(예: GitHub 작업을 통해). 로컬 Git 저장소에서 커밋된 변경사항을 배포할 수도 있습니다.

오케스트레이션 파이프라인은 파이프라인 정의 및 배포 구성 파일에서 매개변수를 대체하는 여러 방법을 지원하며, 이는 로컬 개발과 GitHub 작업에서 실행되는 명령어 모두에 파이프라인을 배포할 때 유용할 수 있습니다. 예를 들어 gcloud CLI 명령어에서 --substitutions 인수를 사용하거나 환경 변수를 설정하거나 GitHub 보안 비밀에서 값을 가져와 매개변수를 대체할 수 있습니다.

배포 명령어 실행

로컬

로컬 번들 버전을 배포하려면 --local 인수를 사용합니다.

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT \
  --local

다음을 바꿉니다.

DEPLOYMENT_ENVIRONMENT: 파이프라인의 배포 환경입니다.

예:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local

출력 예시에는 파이프라인 번들 이름과 버전, 배포 상태가 포함됩니다.

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

커밋됨

변경사항을 배포하려면 변경사항이 저장소에 커밋되어 있어야 합니다. gcloud CLI에서 다음 명령어를 실행합니다.

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

다음을 바꿉니다.

DEPLOYMENT_ENVIRONMENT: 파이프라인의 배포 환경입니다.

예:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment

출력 예시에는 파이프라인 번들 이름과 버전, 배포 상태가 포함됩니다.

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

GitHub Action

파이프라인 스캐폴딩에는 GitHub 작업을 통해 파이프라인을 배포하고 검증하는 데 도움이 되는 두 가지 GitHub 작업 예시가 있습니다. 이러한 파일을 GitHub에 업로드하면 저장소가 이러한 작업으로 구성됩니다. 더 복잡한 GitHub 작업을 구성하는 방법에 관한 자세한 내용은 GitHub 문서의 GitHub Actions로 배포를 참고하세요.

예시 GitHub 작업을 사용하려면 다음 단계를 따르세요.

GitHub 작업에서 gcloud CLI 명령어를 실행할 별도의 서비스 계정을 만듭니다.
이 서비스 계정에 배포 및 유효성 검사 명령어를 실행할 수 있는 역할을 할당합니다.

중요: 이 용도로는 Google 계정을 사용할 수 없습니다. 러너 환경의 서비스 계정은 이 작업에 너무 광범위한 권한이 있으므로 사용하지 마세요.
이 서비스 계정의 서비스 계정 키를 만듭니다.
GitHub 저장소에 GCP_SA_KEY 보안 비밀을 추가하고 값을 생성된 서비스 계정 키로 설정합니다. 보안 비밀 추가에 관한 자세한 내용은 GitHub Actions에서 보안 비밀 사용을 참고하세요.

배포 구성

이 섹션에서는 배포 환경에 적용할 수 있는 추가 구성을 제공합니다.

다른 파이프라인 추가 또는 삭제

기존 배포 환경에 다른 파이프라인을 추가하려면 다음 단계를 따르세요.

파이프라인 정의 파일과 파이프라인 애셋을 저장소에 추가합니다.
배포 구성에서 새 파이프라인 정의 파일을 가리키는 값이 포함된 새 source 키를 추가합니다.

예:

environments:
  dev:

    ...

    pipelines:
      - source: example-pipeline.yaml
      - source: another-pipeline.yaml

파이프라인을 삭제하려면 다음 단계를 따르세요.

배포 구성에서 파이프라인의 source 키를 삭제합니다.
파이프라인 정의 파일과 파이프라인 애셋을 저장소에서 삭제합니다.
새 버전의 파이프라인을 배포합니다. 파이프라인이 새 번들 버전에 표시되지 않습니다.

다른 배포 환경 추가

다른 배포 환경을 추가하려면 다음 단계를 따르세요.

배포 구성에서 environments 매핑에 새 키를 추가합니다.
배포 구성과 파이프라인 정의가 각 환경에 속한 Google Cloud리소스를 구분해야 하는 파이프라인 작업을 실행하기 위해 변수와 배포 구성 변수를 사용하는지 확인합니다.

예:

environments:

  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    ...
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
    ...

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    ...
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"

변수, 보안 비밀, 대체

배포 구성에서 변수를 정의한 후 파이프라인 정의 및 리소스 프로필에서 사용할 수 있습니다.

맞춤 변수 추가

배포 구성의 variables 키에 자체 변수를 추가할 수 있습니다.

배포 구성 환경에서 variables 키를 추가합니다.
변수 이름과 값의 매핑을 추가합니다.
변수의 이름을 이중 중괄호({{ example_variable }})로 묶어 파이프라인 정의 및 리소스 프로필에서 변수의 값을 가져옵니다.

다음 예시에서는 두 배포 환경에서 동일한 변수를 설정합니다.

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    artifact_storage:
      bucket: "development-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
      network_uri: projects/example-development-project/global/networks/default

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    artifact_storage:
      bucket: "production-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"
      network_uri: projects/example-production-project/global/networks/vpc-main

다음은 이러한 변수를 읽는 Managed Service for Apache Spark 리소스 프로필입니다. 파이프라인 정의 파일(example-pipeline.yaml)의 작업은 동일한 리소스 프로필을 사용할 수 있으며 프로덕션 환경과 개발 환경 간에 조정할 필요가 없습니다.

profileId: serverless-standard
type: dataproc.session
definition:
  environmentConfig:
    execution_config:
      service_account: "{{ service_account }}"
      network_uri: "{{ network_uri }}"

배포 구성 매개변수에 액세스

배포 구성의 일부 매개변수는 변수로도 사용할 수 있습니다.

project
region
composer_environment
COMMIT_SHA: Git 저장소의 현재 커밋 SHA입니다. 예를 들어 로컬 파이프라인 번들 버전을 배포할 때 이 변수의 값을 대체하여 사용할 수 있습니다. 이렇게 하면 커밋 SHA 값에 종속된 작업이 올바른 파일 콘텐츠에서 계속 작동합니다.

다음 예에서 파이프라인 정의는 배포 구성 매개변수 project 및 region에 따라 파이프라인 작업의 기본값을 설정합니다.

pipelineId: example-pipeline
description: Example pipeline
runner: 'airflow'
owner: 'data-eng-team'
modelVersion: '1.0'
defaults:
  projectId: {{ project }}
  location: {{ region }}
  executionConfig:
    retries: 1

GitHub Action 보안 비밀 액세스

파이프라인 정의 및 배포 구성 파일에서 GitHub 보안 비밀을 사용할 수 있습니다. GitHub 작업을 통해 파이프라인이 배포되면 이러한 보안 비밀의 값이 파이프라인 정의와 배포 구성 모두에 전달됩니다.

배포 중에 액세스할 수 있는 보안 비밀을 만들려면 다음 단계를 따르세요.

GitHub에서 DEPLOY_VAR_ 접두사가 있는 보안 비밀을 추가합니다. 예: DEPLOY_VAR_API_KEY

시크릿 생성에 관한 자세한 내용은 GitHub 문서의 GitHub Actions에서 시크릿 사용을 참고하세요.
GitHub 워크플로에 동일한 환경 변수를 추가합니다. GitHub 보안 비밀에서 이 변수의 값을 읽습니다.

예:
```
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_VAR_API_KEY: ${{ secrets.API_KEY }}

    steps:

    ...
```
워크플로에 환경 변수를 추가하는 방법에 대한 자세한 내용은 GitHub 문서의 변수에 정보 저장을 참고하세요.
파이프라인 정의 파일 및 배포 구성에서 변수 이름 (DEPLOY_VAR_ 접두사 제외)을 사용합니다. 예를 들면 {{ API_KEY }}입니다.
(선택사항) GitHub 보안 비밀을 사용하는 파이프라인의 로컬 버전을 배포하려면 명령줄 매개변수를 통해 또는 배포 명령어를 실행하는 환경에서 정의하여 보안 비밀의 DEPLOY_VAR_* 환경 변수를 대체하면 됩니다.

명령줄 매개변수를 통해 변수 대체

gcloud CLI 배포 명령어는 --substitutions 인수를 지원하며, 이를 사용하여 파이프라인 정의 및 배포 구성의 변수를 재정의하거나 설정할 수 있습니다.

명령줄 매개변수를 통해 변수를 대체하려면 명령줄에 변수 목록과 값을 제공합니다.

예:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions=VARIABLE_NAME_1=value_1,VARIABLE_NAME_2=value_2

또는 대체 항목을 YAML 파일에 저장하고 --substitutions-file 인수에서 지정할 수 있습니다.

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions-file=substitutions.yaml

대체 파일에서 변수 매핑을 제공합니다.

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

파이프라인 정의 파일과 배포 구성에서 변수 이름을 사용할 수 있습니다. 예: {{ VARIABLE_NAME_1 }}

환경 변수를 통해 변수 제공 및 대체

파이프라인 정의와 배포 구성은 DEPLOY_VAR_ 접두사가 있는 환경 변수를 사용할 수 있습니다.

환경 변수를 설정합니다.

export DEPLOY_VAR_VARIABLE_NAME_1=value_1

파이프라인 정의 파일 및 배포 구성에서 변수 이름 (DEPLOY_VAR_ 접두사 제외)을 사용할 수 있습니다. 예를 들면 {{ VARIABLE_NAME_1 }}입니다.

다음 단계

파이프라인 관리 및 파이프라인 실행 기록 및 상태 확인