Terraform을 사용하여 배포를 실행하도록 컨테이너 이미지 구성

아티클
06/07/2024

이 문서에서는 ADE(Azure Deployment Environments)에 환경 정의를 배포하기 위해 사용자 지정 Terraform 컨테이너 이미지를 빌드하는 방법을 알아봅니다. Terraform IaC(코드 제공 인프라) 프레임워크를 사용하여 인프라를 프로비전하기 위해 사용자 지정 이미지를 구성하는 방법을 알아봅니다.

환경 정의는 최소한 두 개의 파일, 즉 main.tf와 같은 템플릿 파일과 environment.yaml이라는 매니페스트 파일로 구성됩니다. 컨테이너를 사용하여 Terraform을 사용하는 환경 정의를 배포합니다.

ADE 확장성 모델을 사용하면 환경 정의에서 사용할 사용자 지정 컨테이너 이미지를 만들 수 있습니다. 확장성 모델을 사용하면 고유한 사용자 지정 컨테이너 이미지를 만들고 DockerHub와 같은 컨테이너 레지스트리에 저장할 수 있습니다. 그런 다음 환경 정의에서 이러한 이미지를 참조하여 환경을 배포할 수 있습니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
Azure 구독에 설정된 Azure Deployment Environments입니다.
- ADE를 설정하려면 빠른 시작: Azure Deployment Environments 구성을 따릅니다.

사용자 지정 Terraform 컨테이너 이미지 만들기

사용자 지정 컨테이너 이미지를 만들면 요구 사항에 맞게 배포를 사용자 지정할 수 있습니다.

이미지 사용자 지정을 완료한 후에는 이미지를 빌드하고 컨테이너 레지스트리에 푸시해야 합니다.

Docker를 사용하여 컨테이너 이미지 만들기 및 사용자 지정

이 예에서는 ADE 배포를 활용하고 ADE 빌드 이미지 중 하나를 기반으로 이미지를 기반으로 ADE CLI에 액세스하기 위해 Docker 이미지를 빌드하는 방법을 알아봅니다.

ADE CLI는 ADE 기본 이미지를 사용하여 사용자 지정 이미지를 빌드할 수 있는 도구입니다. ADE CLI를 사용하여 워크플로에 맞게 배포 및 삭제를 사용자 지정할 수 있습니다. ADE CLI는 샘플 이미지에 사전 설치되어 있습니다. ADE CLI에 대해 자세히 알아보려면 CLI 사용자 지정 실행기 이미지 참조를 확인합니다.

ADE용으로 구성된 이미지를 만들려면 다음 단계를 따릅니다.

ADE에서 제작한 샘플 이미지 또는 FROM 문을 사용하여 선택한 이미지를 기반으로 합니다.
RUN 문을 사용하여 이미지에 필요한 패키지를 설치합니다.
Dockerfile과 같은 레벨에 스크립트 폴더를 만들고, 그 안에 deploy.sh 및 delete.sh 파일을 저장한 다음, 생성한 컨테이너 내에서 해당 스크립트를 검색하고 실행할 수 있는지 확인합니다. 배포가 ADE 핵심 이미지를 사용하여 작동하려면 이 단계가 필요합니다.

FROM 문을 사용하여 샘플 컨테이너 이미지를 선택합니다.

Microsoft 아티팩트 레지스트리에서 호스트되는 샘플 이미지를 가리키는 새 이미지에 대해 만들어진 DockerFile 내에 FROM 문을 포함합니다.

다음은 샘플 코어 이미지를 참조하는 FROM 문의 예입니다.

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

이 문은 가장 최근에 게시된 핵심 이미지를 끌어와 사용자 지정 이미지의 기반으로 만듭니다.

Dockerfile에 Terraform 설치

배포 및 삭제 스크립트에서 사용할 수 있도록 Terraform CLI를 실행 가능한 위치에 설치할 수 있습니다.

다음은 Terraform CLI 버전 1.7.5를 설치하는 프로세스의 예입니다.

RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
RUN unzip terraform.zip && rm terraform.zip
RUN mv terraform /usr/bin/terraform

팁

Hashicorp 릴리스에서 기본 버전의 Terraform CLI에 대한 다운로드 URL을 가져올 수 있습니다.

ADE 샘플 이미지는 Azure CLI 이미지를 기반으로 하며 ADE CLI 및 JQ 패키지가 미리 설치되어 있습니다. Azure CLI 및 JQ 패키지에 대해 자세히 알아볼 수 있습니다.

이미지 내에 필요한 패키지를 더 설치하려면 RUN 문을 사용합니다.

작업 셸 스크립트 실행

샘플 이미지 내에서는 작업 이름을 기준으로 작업이 결정되고 실행됩니다. 현재 지원되는 두 가지 작업 이름은 deploy 및 delete입니다.

이 구조를 활용하도록 사용자 지정 이미지를 설정하려면 Dockerfile 수준에서 scripts라는 폴더를 지정하고 deploy.sh 및 delete.sh라는 두 파일을 지정합니다. 배포 셸 스크립트는 환경이 만들어지거나 다시 배포될 때 실행되고, 삭제 셸 스크립트는 환경이 삭제될 때 실행됩니다. ARM-Bicep용 Runner-Images 폴더 이미지 아래 리포지토리에서 셸 스크립트의 예를 볼 수 있습니다.

이러한 셸 스크립트가 실행 가능하도록 하려면 Dockerfile에 다음 줄을 추가합니다.

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

Terraform CLI를 사용하기 위한 작업 셸 스크립트 작성

Terraform을 통해 인프라를 배포하는 세 단계는 다음과 같습니다.

terraform init - Terraform CLI를 초기화하여 작업 디렉터리 내에서 작업을 수행합니다.
terraform plan - 수신되는 Terraform 인프라 파일과 변수, 기존 상태 파일을 기반으로 계획을 개발하고 .tf 파일에 지정된 인프라를 만들거나 업데이트하는 데 필요한 단계를 개발합니다.
terraform apply - Azure에서 새 인프라를 만들거나 기존 인프라를 업데이트하는 계획을 적용합니다.

코어 이미지의 진입점 동안 기존 상태 파일은 컨테이너와 환경 변수 $ADE_STORAGE에 저장된 디렉터리로 끌어옵니다. 또한 현재 환경에 대해 설정된 모든 매개 변수는 변수 $ADE_OPERATION_PARAMETERS에 저장됩니다. 기존 상태 파일에 액세스하고 .tfvars.json 파일 내에서 변수를 설정하려면 다음 명령을 실행합니다.

EnvironmentState="$ADE_STORAGE/environment.tfstate"
EnvironmentPlan="/environment.tfplan"
EnvironmentVars="/environment.tfvars.json"

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

또한 ADE 권한을 활용하여 구독 내에 인프라를 배포하려면 Terraform AzureRM 공급자를 사용하여 인프라를 프로비전할 때 스크립트에서 MSI(관리되는 서비스 ID)를 사용해야 합니다. 배포를 완료하기 위해 특정 역할과 같은 특별 권한이 배포에 필요한 경우 해당 권한을 환경 배포에 사용되는 프로젝트 환경 유형의 ID에 할당합니다. ADE는 코어 이미지의 진입점 내에서 클라이언트, 테넌트 및 구독 ID와 같은 관련 환경 변수를 설정하므로 다음 명령을 실행하여 공급자가 ADE MSI를 사용하는지 확인합니다.

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

환경 매개 변수에 지정되지 않은 템플릿 내에서 참조할 다른 변수가 있는 경우 접두사 TF_VAR을 사용하여 환경 변수를 설정합니다. 제공된 ADE 환경 변수 목록은 Azure 배포 환경 CLI 변수 참조로 제공됩니다. 이러한 명령의 예는 다음과 같습니다.

export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE

이제 이전에 나열된 단계를 실행하여 Terraform CLI를 초기화하고, 인프라 프로비전 계획을 생성하고, 배포 스크립트 중에 계획을 적용할 수 있습니다.

terraform init
terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

삭제 스크립트 중에 다음 예와 같이 계획 생성에 destroy 플래그를 추가하여 기존 리소스를 삭제할 수 있습니다.

terraform init
terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

마지막으로, Azure CLI를 통해 환경에 액세스할 때 배포 출력을 업로드하고 액세스할 수 있도록 하려면 출력 개체를 Terraform에서 JQ 패키지를 통해 ADE 지정 형식으로 변환합니다. 다음 예와 같이 값을 $ADE_OUTPUTS 환경 변수로 설정합니다.

tfOutputs=$(terraform output -state=$EnvironmentState -json)
# Convert Terraform output format to ADE format.
tfOutputs=$(jq 'walk(if type == "object" then 
            if .type == "bool" then .type = "boolean" 
            elif .type == "list" then .type = "array" 
            elif .type == "map" then .type = "object" 
            elif .type == "set" then .type = "array" 
            elif (.type | type) == "array" then 
                if .type[0] == "tuple" then .type = "array" 
                elif .type[0] == "object" then .type = "object" 
                elif .type[0] == "set" then .type = "array" 
                else . 
                end 
            else . 
            end 
        else . 
        end)' <<< "$tfOutputs")

echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS

ADE에서 사용자 지정 이미지에 액세스할 수 있도록 설정

ADE에서 사용할 수 있도록 하려면 Docker 이미지를 빌드하고 컨테이너 레지스트리에 푸시해야 합니다. Docker CLI를 사용하거나 ADE에서 제공하는 스크립트를 사용하여 이미지를 빌드할 수 있습니다.

각 방식에 대해 자세히 알아보려면 해당 탭을 선택합니다.

Docker CLI를 사용하여 이미지 빌드
스크립트를 사용하여 컨테이너 이미지 빌드

레지스트리에 푸시할 이미지를 빌드하기 전에 컴퓨터에 Docker 엔진이 설치되어 있는지 확인합니다. 그런 다음 Dockerfile 디렉터리로 이동하여 다음 명령을 실행합니다.

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

예를 들어, customImage라는 레지스트리 내의 리포지토리에 이미지를 저장하고 1.0.0 태그 버전으로 업로드하려면 다음을 실행합니다.

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

Docker 이미지를 레지스트리에 푸시

사용자 지정 이미지를 사용하려면 익명 이미지 끌어오기가 사용하도록 설정된 공개적으로 액세스 가능한 이미지 레지스트리를 설정해야 합니다. 이러한 방식으로 Azure Deployment Environments는 사용자 지정 이미지에 액세스하여 컨테이너에서 실행할 수 있습니다.

Azure Container Registry는 컨테이너 이미지 및 유사한 아티팩트를 저장하는 Azure 제공 사항입니다.

Azure CLI, Azure Portal, PowerShell 명령 등을 통해 수행할 수 있는 레지스트리를 만들려면 빠른 시작 중 하나를 따릅니다.

익명 이미지 풀을 사용하도록 설정하도록 레지스트리를 설정하려면 Azure CLI에서 다음 명령을 실행합니다.

az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true

이미지를 레지스트리에 푸시할 준비가 되면 다음 명령을 실행합니다.

docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}

Microsoft는 시작하는 데 도움이 되는 빠른 시작 스크립트를 제공합니다. 스크립트는 이미지를 빌드하고 리포지토리 ade 및 태그 latest 아래의 지정된 ACR(Azure Container Registry)에 푸시합니다.

스크립트를 사용하려면 다음을 수행해야 합니다.

ADE 확장성 모델을 지원하도록 Dockerfile 및 스크립트 폴더를 만듭니다.
사용자 지정 이미지에 대한 레지스트리 이름 및 디렉터리를 제공합니다.
Azure CLI 및 Docker Desktop을 설치하고 PATH 변수에 있도록 합니다.
지정된 레지스트리에 푸시할 수 있는 권한이 있습니다.

여기에서 스크립트를 볼 수 있습니다.

PowerShell에서 다음 명령을 사용하여 스크립트를 호출할 수 있습니다.

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

또한 특정 리포지토리 및 태그 이름으로 푸시하려는 경우 다음을 실행할 수 있습니다.

.\quickstart-image.build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

이미지를 환경 정의에 연결

배포에서 사용자 지정 이미지를 사용하기 위해 환경 정의를 작성할 때 매니페스트 파일(environment.yaml 또는 manifest.yaml)에서 runner 속성을 편집합니다.

runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"

액세스 작업 로그 및 오류 세부 정보

ADE는 실패한 배포에 대한 오류 세부 정보를 컨테이너 내의 $ADE_ERROR_LOG 파일에 저장합니다.

실패한 배포 문제를 해결하려면

개발자 포털에 로그인합니다.
배포에 실패한 환경을 식별하고 세부 정보 보기를 선택합니다.
오류 세부 정보 섹션에서 오류 세부 정보를 검토합니다.

또한 Azure CLI를 사용하면 다음 명령을 사용하여 환경의 오류 세부 정보를 볼 수 있습니다.

az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}

환경 배포 또는 삭제에 대한 작업 로그를 보려면 Azure CLI를 사용하여 환경에 대한 최신 작업을 검색한 다음 해당 작업 ID에 대한 로그를 봅니다.

# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}

다음을 통해 공유

Terraform을 사용하여 배포를 실행하도록 컨테이너 이미지 구성

필수 조건

사용자 지정 Terraform 컨테이너 이미지 만들기

Docker를 사용하여 컨테이너 이미지 만들기 및 사용자 지정

FROM 문을 사용하여 샘플 컨테이너 이미지를 선택합니다.

Dockerfile에 Terraform 설치

작업 셸 스크립트 실행

Terraform CLI를 사용하기 위한 작업 셸 스크립트 작성

ADE에서 사용자 지정 이미지에 액세스할 수 있도록 설정

Docker 이미지를 레지스트리에 푸시

이미지를 환경 정의에 연결

액세스 작업 로그 및 오류 세부 정보

피드백

피드백

추가 리소스

다음을 통해 공유

Terraform을 사용하여 배포를 실행하도록 컨테이너 이미지 구성

필수 조건

사용자 지정 Terraform 컨테이너 이미지 만들기

Docker를 사용하여 컨테이너 이미지 만들기 및 사용자 지정

FROM 문을 사용하여 샘플 컨테이너 이미지를 선택합니다.

Dockerfile에 Terraform 설치

작업 셸 스크립트 실행

Terraform CLI를 사용하기 위한 작업 셸 스크립트 작성

ADE에서 사용자 지정 이미지에 액세스할 수 있도록 설정

Docker 이미지를 레지스트리에 푸시

이미지를 환경 정의에 연결

액세스 작업 로그 및 오류 세부 정보

관련 콘텐츠

피드백

피드백

추가 리소스