Bicep 매개 변수를 사용하여 환경 간의 차이점 처리

  • 7분

Bicep 매개 변수에 대한 정보를 이미 배웠습니다. Bicep 파일 배포 간에 변경될 수 있는 값을 지정하는 데 도움이 됩니다.

매개 변수는 일반적으로 환경 간의 차이점을 지원하는 데 사용됩니다. 예를 들어 비프로덕션 환경에서 저렴한 Azure 리소스 SKU를 배포하려는 경우가 있습니다. 프로덕션 환경에서는 더 나은 실적을 가진 SKU를 배포하려고 합니다. 각 환경에서 리소스에 대해 다른 이름을 사용하는 것이 좋습니다.

Bicep 파일을 배포하는 경우 각 매개 변수에 대한 값을 제공합니다. 워크플로에서 각 매개 변수의 값을 지정하는 방법과 각 환경에 대해 별도의 값을 지정하는 방법에 대한 여러 가지 옵션이 있습니다. 이 단원에서는 배포 워크플로에서 Bicep 매개 변수 값을 지정하기 위한 접근 방식에 관해 알아봅니다.

매개 변수 파일

매개 변수 파일은 각 환경에 사용할 매개 변수 값을 나열하는 JSON 형식의 파일입니다. 배포를 제출할 때 Azure Resource Manager에 매개 변수 파일을 제출합니다.

다음은 매개 변수 파일의 예시입니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "reviewApiUrl": {
      "value": "https://sandbox.contoso.com/reviews"
    }
  }
}

Bicep 파일을 함께 Git 리포지토리에 매개 변수 파일을 커밋할 수 있습니다. 그런 다음, 배포를 실행하는 워크플로 템플릿에서 매개 변수 파일을 참조할 수 있습니다.

매개 변수 파일에 대해 일관된 환경 이름 지정 전략을 설정하는 것이 좋습니다. 예를 들어 매개 변수 파일의 이름을 매개 변수의 이름을 ‘parameters.환경_이름.json’(예: parameters.Production.json)으로 지정할 수 있습니다. 그런 다음, 워크플로 템플릿 입력을 사용하여 입력 값에 따라 올바른 매개 변수 파일을 자동으로 선택할 수 있습니다.

on:
  workflow_call:
    inputs:
      environmentType:
        required: true
        type: string
      # ...

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # ...
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json

매개 변수 파일을 사용하는 경우 워크플로 YAML 파일은 배포 스테이지에 개별적으로 전달해야 하는 매개 변수 목록을 포함할 필요가 없습니다. 이는 매개 변수 수가 많은 경우에 특히 유용합니다.

매개 변수 파일은 단일 JSON 파일에서 매개 변수 값을 함께 유지합니다. 매개 변수 파일은 Git 리포지토리의 일부 이기도 하므로 다른 모든 코드와 동일한 방식으로 버전 관리를 수행할 수 있습니다.

중요

보안 값에는 매개 변수 파일을 사용할 수 없습니다. 매개 변수 파일의 암호 값을 보호할 수 있는 방법은 없으며 Git 리포지토리에 암호를 커밋하지 말아야 합니다.

워크플로 변수

GitHub Actions를 사용하면 환경 간에 다를 수 있는 값에 유용한 ‘워크플로 변수’를 저장할 수 있습니다. 한 번만 정의한 다음, 워크플로 전체에서 다시 사용하려는 값에도 유용합니다.

YAML 파일에 정의된 변수

변수를 정의하고 YAML 파일 내에서 해당 값을 설정할 수 있습니다. 이는 동일한 값을 여러 번 재사용해야 하는 경우에 유용합니다. 전체 워크플로, 작업 또는 단일 단계에 대한 변수를 정의할 수 있습니다.

env:
  MyVariable1: value1

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyVariable2: value2
    steps:
    - run: echo Hello world!
      env:
        MyVariable3: value3

웹 인터페이스에 정의된 비밀

Bicep 매개 변수 파일과 마찬가지로 YAML 파일은 비밀에 적합하지 않습니다. 대신 GitHub 웹 인터페이스를 사용하여 비밀을 정의할 수 있습니다. 변수 값은 언제든지 변경할 수 있으며, 워크플로는 다음에 실행될 때 업데이트된 값을 읽습니다. GitHub Actions는 워크플로 로그에서 비밀 값을 숨기려고 합니다. 즉, Bicep 파일이 @secure() 데코레이터를 통해 매개 변수로 허용하는 값을 저장할 수 있습니다.

경고

기본적으로 GitHub Actions는 워크플로 로그에서 비밀 변수 값을 난독 처리하지만, 사용자도 모범 사례를 따라야 합니다. 워크플로 단계에서 비밀 값에 액세스할 수 있습니다. 워크플로에 비밀을 안전하게 처리하지 않는 단계가 포함된 경우 워크플로 로그에 비밀 값이 표시될 가능성이 있습니다. 항상 워크플로 정의 파일의 변경 내용을 신중하게 검토하여 비밀이 잘못 처리되지 않는지 확인해야 합니다.

비밀을 만들 때 GitHub를 사용하면 전체 Git 리포지토리 또는 특정 환경으로 범위를 지정할지 여부를 선택할 수 있습니다. 환경 범위 비밀은 사용자 환경에서 구성하는 보호 규칙을 준수하므로 필요한 검토자 규칙을 구성하는 경우 지정된 GitHub 사용자가 해당 환경에 배포하도록 파이프라인을 승인할 때까지 워크플로에서 비밀 값에 액세스할 수 없습니다.

환경 범위 비밀은 유용할 수 있지만 Azure Resource Manager의 실행 전 유효성 검사 또는 가상 작업을 사용하는 경우 쉽게 작동하지 않습니다. 이러한 작업은 Azure와 통신해야 합니다. 즉, 워크로드 ID가 필요합니다. 일반적으로 실행 전 유효성 검사 또는 가상 작업이 완료된 ‘후’ 배포 승인을 제공하려고 하므로, 배포할 변경 내용에 대해 높은 수준의 신뢰도를 가집니다. 따라서 환경 범위 비밀을 사용하는 경우 사용자 검토 프로세스가 워크플로에서 너무 일찍 발생합니다.

이러한 이유로 이 모듈의 연습에서는 환경 범위 비밀을 사용하지 않습니다. 대신 환경 이름을 포함하는 예측 가능한 이름으로 리포지토리 범위 비밀을 만듭니다. 이렇게 하면 워크플로가 각 환경에 사용할 올바른 비밀을 식별할 수 있습니다. 고유한 워크플로에서 리포지토리 범위 비밀, 환경 범위 비밀 또는 두 비밀을 함께 사용하도록 선택할 수 있습니다.

참고

또한 비밀 범위를 GitHub 조직으로 지정할 수 있습니다. 이 모듈의 범위는 아니지만 자세한 내용은 요약에서 링크를 통해 제공됩니다.

워크플로에서 변수 사용

워크플로의 변수 값에 액세스하는 방법은 변수 형식에 따라 달라집니다.

유형 Syntax
동일한 파일에 정의된 변수 ${{ env.VARIABLE_NAME }}
호출된 워크플로에 대한 입력 ${{ inputs.INPUT_NAME }}
비밀 ${{ secrets.SECRET_NAME }}

예를 들어, Bicep 배포를 실행하는 경우 비밀을 사용하여 사용할 Azure 워크로드 ID를 지정하고, 호출된 워크플로 입력을 사용하여 리소스 그룹 이름을 지정하고, 변수를 사용하여 매개 변수 값을 지정할 수 있습니다.

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyParameter: value-of-parameter
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: myParameter=${{ env.MyParameter }}

가장 좋은 방법은 무엇인가요?

Bicep 파일이 배포에 필요로 하는 매개 변수를 처리하는 여러 가지 방법을 알아보았습니다. 어떤 방식을 사용할 지 이해하는 것이 좋습니다.

불필요한 매개 변수 방지

매개 변수를 통해 Bicep 파일을 재사용할 수 있지만 너무 많은 매개 변수를 쉽게 정의할 수 있습니다. Bicep 파일을 배포하는 경우 모든 매개 변수에 값을 제공해야 합니다. 여러 환경에 대한 복잡한 배포에서는 많은 개별 매개 변수 값을 관리하기가 어렵습니다.

가능한 경우 매개 변수를 선택 사항으로 만들고 대부분의 환경에 적용되는 기본값을 사용하는 것이 좋습니다. 그러면 워크플로가 매개 변수에 대한 값을 전달할 필요가 없도록 할 수 있습니다.

또한 리소스가 다른 리소스에 연결해야 하는 경우 매개 변수가 Bicep에서 사용되는 경우가 많습니다. 예를 들어 스토리지 계정에 연결해야 하는 웹 사이트가 있는 경우 스토리지 계정 이름 및 액세스 키를 제공해야 합니다. 키는 보안 값입니다. 그러나 이러한 리소스 조합을 배포할 때는 다음과 같은 다른 방식을 고려해 보십시오.

  • 웹 사이트의 관리 ID를 사용하여 스토리지 계정에 액세스합니다. 관리 ID를 만드는 경우 Azure는 자격 증명을 자동으로 생성하고 관리합니다. 이 방법은 연결 설정을 간소화합니다. 또한 암호를 전혀 처리할 필요가 없으므로 가장 안전한 옵션입니다.
  • 스토리지 계정과 웹 사이트를 동일한 Bicep 템플릿에 함께 배포합니다. Bicep 모듈을 사용하여 웹 사이트와 스토리지 리소스를 함께 유지합니다. 그런 다음 매개 변수로 전달하는 대신 Bicep 코드 내에서 스토리지 계정 이름 및 키에 대한 값을 자동으로 조회할 수 있습니다.
  • 스토리지 계정의 세부 정보를 키 자격 증명 모음에 암호로 추가합니다. 그러면 웹 사이트 코드는 자격 증명 모음에서 직접 액세스 키를 로드합니다. 이 접근 방식을 사용하면 워크플로에서 키를 관리할 필요가 없습니다.

작은 매개 변수 세트에 워크플로 변수 사용

Bicep 파일에 적은 수의 매개 변수만 사용하는 경우 YAML 파일에서 변수를 정의하는 것이 좋습니다.

많은 매개 변수에 매개 변수 파일 사용

Bicep 파일에 대한 매개 변수가 많은 경우 매개 변수 파일을 사용하여 각 환경에 대해 비보안 값을 함께 유지하는 것이 좋습니다. 그러면 값을 변경해야 할 때마다 매개 변수 파일을 업데이트하고 변경 내용을 커밋할 수 있습니다.

이 접근 방식은 모든 매개 변수에 대한 값을 명시적으로 설정할 필요가 없으므로 워크플로 단계를 더 간단하게 유지합니다.

안전하게 암호 저장

암호를 저장하고 처리하는 데 적절한 프로세스를 사용합니다. GitHub 비밀을 사용하여 GitHub 리포지토리에 비밀을 저장하거나 Key Vault를 사용하여 Azure에 비밀을 저장합니다.

보안 매개 변수의 경우 각 매개 변수를 배포 단계에 명시적으로 전달해야 합니다.

GitHub는 실수로 커밋된 비밀을 리포지토리에서 자동으로 검사할 수 있으므로 알림을 받을 수 있습니다. 알림을 받으면 비밀을 제거하고 회전할 수 있습니다. 이 기능에 관한 자세한 내용은 요약에서 링크를 통해 제공됩니다.

방식 조합

매개 변수를 처리하는 여러 방식을 조합하는 것이 일반적입니다. 예를 들어 대다수 매개 변수 값을 매개 변수 파일에 저장한 다음, 비밀을 사용하여 보안 값을 설정할 수 있습니다. 다음 예제에서는 이러한 조합을 보여줍니다.

on:
  workflow_dispatch:
    inputs:
      environmentType:
        required: true
        type: string
      resourceGroupName:
        required: true
        type: string
    secrets:
      AZURE_CLIENT_ID:
        required: true
      AZURE_TENANT_ID:
        required: true
      AZURE_SUBSCRIPTION_ID:
        required: true
      MySecureParameter:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: >
          ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json
          mySecureParameter=${{ secrets.MySecureParameter }}

팁

이 예제를 마치면 > 문자를 사용하여 parameters 값이 YAML 여러 줄 문자열로 제공됩니다. 이렇게 하면 YAML 파일을 더 쉽게 읽을 수 있습니다. 한 줄에 전체 값을 포함하는 것과 같습니다.