Azure 개발자 CLI 환경 변수 작업

Azure 개발자 CLI(azd)는 환경 변수를 사용하여 배포 환경에 대한 구성 설정을 저장하고 관리합니다. 이러한 변수는 애플리케이션이 Azure에서 프로비전, 배포 및 실행되는 방법을 제어합니다. 이 문서에서는 환경 변수가 환경 내에서 azd 작동하는 방식을 설명하고 이를 효과적으로 관리하는 방법에 대한 지침을 제공합니다.

환경 변수 이해

Azure 개발자 CLI의 컨텍스트에서 환경 변수는 개발, 테스트 또는 prod와 같은 명명된 특정 환경에 연결된 키-값 쌍입니다. 각 azd 환경은 고유한 환경 변수 집합을 유지 관리하므로 여러 배포 대상에 대해 서로 다른 설정을 구성할 수 있습니다.

환경 변수는 azd 폴더의 .env 환경 폴더 내 파일에 저장됩니다 .azure . 다음을 입력하는 역할을 합니다.

애플리케이션 배포 워크플로
Azure 서비스 및 연결에 대한 구성
Bicep 및 Terraform을 통한 인프라 프로비저닝

운영 체제 수준에서 존재하는 기존 환경 변수와 달리 환경 azd 변수는 프로젝트 내의 특정 환경으로 범위가 지정되어 서로 다른 배포 대상 간에 격리를 제공합니다.

환경 변수는 다음을 사용할 azd때 몇 가지 주요 이점을 제공합니다.

환경 격리: 개발, 테스트 및 프로덕션에 대한 구성을 별개와 구분하여 유지합니다.
구성 일관성: 모든 팀 구성원이 특정 환경에 대해 동일한 설정을 사용하는지 확인합니다.
코드로서의 인프라: 하드 코딩된 값 대신 변수를 통해 인프라 매개 변수화를 정의합니다.
배포 자동화: CI/CD 파이프라인이 동일한 코드베이스와 다른 구성을 사용하여 다른 환경에 배포되도록 설정합니다.
간소화된 관리: 중앙 위치에서 환경의 모든 서비스에서 설정을 쉽게 업데이트합니다.

각 azd 환경에는 고유한 변수 집합이 있으므로 동일한 애플리케이션 코드 및 인프라 템플릿을 사용하는 동안 환경별 구성을 허용합니다.

환경 변수 및 .env 파일

환경 변수는 azd 프로젝트의 환경별 디렉터리 내의 파일에 저장 .env 됩니다. 다음을 사용하여 azd env new <name>환경을 만들면 디렉터리 구조가 만들어집니다.

.azure/
├── <environment-name>/
│   ├── .env                   # Environment variables for this environment

파일은 .env 각 줄이 키-값 쌍을 나타내는 표준 형식을 사용합니다.

KEY1=value1
KEY2=value2

팁 (조언)

환경에 대한 자세한 내용은 azd 문서를 참조하세요.

같은 azd upazd 명령을 실행하면 선택 환경의 .env 파일에서 변수가 자동으로 로드됩니다.

이러한 변수는 다음과 같은 영향을 줍니다.

인프라 프로비전: 리소스를 만드는 위치와 방법을 좋아 AZURE_LOCATION 하고 AZURE_SUBSCRIPTION_ID 결정하는 변수입니다.
배포: 서비스 엔드포인트와 같은 변수는 애플리케이션이 Azure 서비스에 연결하는 방법을 제어합니다.
애플리케이션 구성: 변수를 애플리케이션 구성에 전달하여 동작을 제어할 수 있습니다.
리소스 명명: 리소스 명명 패턴에 영향을 주는 변수와 같은 AZURE_RESOURCE_GROUP 변수입니다.

또한 파일 .env 은 인프라 템플릿에서 출력을 캡처하고 azd나중에 사용할 수 있도록 저장하는 등의 azd initazd provision작업 중에 자동으로 azd deploy 업데이트됩니다.

환경 변수 설정

시나리오에 따라 다른 메서드를 사용하여 환경 변수를 설정할 azd 수 있습니다.

CLI 명령 사용

환경 변수를 설정하는 권장 방법은 유효한 값을 확인하는 검사를 포함하는 명령을 사용하는 azd env set 것입니다.

azd env set <key> <value>

예를 들어 애플리케이션에 대한 구성 값을 설정하려면 다음을 수행합니다.

azd env set API_TIMEOUT 5000

이 명령은 현재 선택한 환경의 파일에서 .env 변수를 추가하거나 업데이트합니다. 플래그를 사용하여 특정 환경을 대상으로 지정할 수도 있습니다.--environment

azd env set API_TIMEOUT 5000 --environment prod

환경 변수가 올바르게 설정되었는지 확인하려면 다음을 수행합니다.

azd env get-value API_TIMEOUT

Bicep의 출력

강력한 기능은 azd Bicep 인프라 템플릿에서 출력 매개 변수를 환경 변수로 자동으로 캡처하는 기능입니다. 예를 들어 파일에서 main.bicep 출력 매개 변수를 정의하는 경우:

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

실행 azd provision후 이 출력은 환경의 .env 파일에 자동으로 저장됩니다.

API_ENDPOINT=https://api-dev-123456.azurewebsites.net

이 방법을 사용하면 애플리케이션이 항상 다음과 같은 최신 리소스 정보에 액세스할 수 있습니다.

서비스 엔드포인트 및 URL
리소스 이름 및 식별자

환경 변수 가져오기 및 사용

설정되면 여러 컨텍스트에서 환경 변수에 액세스할 수 있습니다.

CLI 명령

현재 환경에 대한 모든 환경 변수를 보려면 다음을 수행합니다.

azd env get-values

특정 변수의 값을 보려면 다음을 수행합니다.

azd env get-value API_ENDPOINT

컴퓨터에서 읽을 수 있는 출력의 경우(스크립트에 유용):

azd env get-values --output json

인프라 파일에서 환경 변수 사용

환경 변수를 사용하여 인프라 템플릿을 사용자 지정할 수 있습니다. 이는 현재 환경에 따라 리소스를 명명, 태그 지정 또는 구성하는 데 유용합니다. azd 또한 태그를 사용하여 배포 및 기타 작업을 위해 Azure에서 리소스를 찾습니다.

다음과 같은 일반적인 흐름을 고려합니다.

azd init 중에azd는 프롬프트에 대한 사용자의 응답에 따라 이러한 환경 변수를 설정합니다.
```
AZURE_ENV_NAME=myapp-dev
AZURE_LOCATION=eastus2
```

폴더에서 main.parameters.json 해당 변수를 참조합니다 infra . azd 프로비전하는 동안 값을 대체하고 확인된 매개 변수를 Bicep에 전달합니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "value": "${AZURE_ENV_NAME}"
    },
    "location": {
      "value": "${AZURE_LOCATION}"
    }
  }
}

Bicep 템플릿에서 일치하는 매개 변수를 정의합니다.

@description('Name of the environment used to derive resource names and tags.')
param name string

@minLength(1)
@description('Primary Azure region for all resources.')
param location string

azd 에서는 이러한 Bicep 매개 변수를 대체된 값 main.parameters.json과 함께 제공합니다.

리소스 이름 지정 및 태그에 대한 매개 변수를 사용하여 나중에 리소스가 속한 환경을 식별합니다.

var resourceToken = toLower(uniqueString(resourceGroup().id, name, location))

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'st${resourceToken}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  tags: {
    Environment: name
    Project: 'myproject'
  }
}

이 패턴은 템플릿을 유연하게 유지하고, 코드 변경 없이 환경별 사용자 지정을 사용하도록 설정하고, 리소스 거버넌스(명명, 태그 지정 및 검색)를 향상시킵니다.

비고

azd 또한 배포 단계 중에 태그 지정을 사용하여 Azure 리소스를 찾습니다.

후크

azd 환경 변수는 파일에 정의된 후크 및 사용자 지정 스크립트에서 azure.yaml 자동으로 미리 로드되고 사용할 수 있습니다. 다음 구문을 사용하여 환경 변수에 액세스할 수 있습니다.

배쉬
PowerShell

# Use the variables in your script
echo "API endpoint: $API_ENDPOINT"
echo "Deploying to: $AZURE_LOCATION"

# Use the variables in your script
Write-Host "API endpoint: $API_ENDPOINT"
Write-Host "Deploying to: $AZURE_LOCATION"

파일에서 azure.yaml 후크를 정의하여 수명 주기의 특정 지점에서 이러한 스크립트를 azd 실행할 수 있습니다.

hooks:
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/load-env-vars.ps1
      interactive: false
    posix:
      shell: sh
      run: ./scripts/load-env-vars.sh
      interactive: false

팁 (조언)

후크 사용에 대한 자세한 내용은 후크 문서를 사용하여 워크플로 사용자 지정을 참조하세요.

변수 제거 또는 업데이트

사용자 환경에서 변수를 제거하려면 다음을 수행합니다.

azd env unset VARIABLE_NAME

기존 변수를 업데이트하려면 다음을 수행합니다.

azd env set VARIABLE_NAME "new-value"

Azure 리소스의 현재 상태에서 로컬 환경 변수를 새로 고치려면 다음을 수행합니다.

azd env refresh

환경 새로 고침은 다음과 같은 경우에 유용합니다.

로컬 .env 파일이 인프라의 최신 출력(예: 연결 문자열, 엔드포인트 등)을 반영하는지 확인하려고 합니다.
팀 동료가 환경을 업데이트한 후 환경 변수를 동기화해야 합니다.

AZD 및 OS 환경 변수

azd 환경 변수 및 운영 체제 환경 변수는 다양한 용도로 사용할 수 있으며 다음과 같은 다양한 방식으로 작동합니다.

개념	Azure 개발자 명령줄 인터페이스 (CLI)	운영 체제
위치	파일에 저장됨 `.azure/<env-name>/.env`	운영 체제 환경에서 설정
Scope	프로젝트 내의 특정 명명된 환경으로 범위 지정	사용자 세션 또는 시스템에 대한 전역
Management	명령을 사용하여 `azd env` 관리	OS 관련 명령(`export`등 `set`)을 사용하여 관리
Access	명령에 의해 `azd` 자동으로 로드됨	일반적으로 스크립트 또는 애플리케이션에서 명시적으로 로드됩니다.
Target	Azure 리소스 및 배포에 연결	범용 시스템 구성
수명 주기	터미널 세션 간에 유지	설정 방법에 따라 일시적이거나 영구적일 수 있습니다.

azd 는 OS 환경 변수를 자동으로 읽거나 쓰지 않습니다. 그러나 사용자 지정 스크립트를 사용하여 두 유형의 변수와 상호 작용할 수 있습니다.

환경 변수 및 OS 환경 변수를 읽 azd 습니다.

배쉬
PowerShell

# Access OS environment variable
echo "OS variable: $PATH"

# Access azd environment variable
echo "AZD variable: $(azd env get-value MY_VARIABLE)"

# Access OS environment variable
Write-Host "OS variable: $env:PATH"

# Access azd environment variable
Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"

OS 또는 프레임워크 환경 변수에 환경 변수를 씁 azd 니다.

배쉬
PowerShell

# Load all azd environment variables into the current shell session
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

# Load all azd environment variables into the current PowerShell session
foreach ($line in (& azd env get-values)) {
    if ($line -match "([^=]+)=(.*)") {
        $key = $matches[1]
        $value = $matches[2] -replace '^"|"$'
        $env:$key = $value
    }
}

표준 환경 변수

azd 모든 환경에서 몇 가지 일반적인 환경 변수를 설정하고 사용합니다.

Variable	설명	Example	설정 시
`AZURE_ENV_NAME`	현재 환경의 이름	`dev`	환경이 만들어지는 경우
`AZURE_LOCATION`	리소스가 배포되는 Azure 지역	`eastus`	첫 번째 프로비전 중
`AZURE_SUBSCRIPTION_ID`	사용된 Azure 구독의 ID	`00000000-0000-0000-0000-000000000000`	첫 번째 프로비전 중
`AZURE_RESOURCE_GROUP`	리소스 그룹의 이름	`rg-myapp-dev`	프로비전 중
`AZURE_PRINCIPAL_ID`	실행 중인 사용자/서비스 주체 ID	`00000000-0000-0000-0000-000000000000`	프로비전 중
`AZURE_PRINCIPAL_TYPE`	환경의 보안 주체 유형입니다.	`1a2b3c`	프로비전 중
`AZURE_TENANT_ID`	사용된 Azure 테넌트 ID입니다.	`00000000-0000-0000-0000-000000000000`	프로비전 중

비밀 및 중요한 데이터 고려 사항

환경 변수는 구성에 편리하지만 중요한 데이터에 대해 특별한 처리가 필요합니다.

.env 파일에 비밀을 저장하지 마세요.

.env 파일은 일반적으로 일반 텍스트로 저장되며 쉽게 다음을 수행할 수 있습니다.

실수로 소스 제어에 커밋됨
적절한 보호 없이 공유 또는 복사
프로젝트 파일에 액세스할 수 있는 모든 사용자가 볼 수 있습니다.
로그 또는 오류 보고서에 포함됨

경고

Azure 개발자 CLI .env 파일에 비밀을 저장하지 않습니다. 이러한 파일을 쉽게 공유하거나 무단 위치로 복사하거나 소스 제어에 체크 인할 수 있습니다. 보호되거나 비밀 없는 솔루션에는 Azure Key Vault 또는 AZURE RBAC(역할 기반 액세스 제어)와 같은 서비스를 사용합니다.

비밀 처리에 대한 대안

중요한 데이터의 경우 다음과 같은 보다 안전한 방법을 고려합니다.

Azure Key Vault 참조: Azure Key Vault에 비밀을 저장하고 파일에서 참조합니다 .env .
```
azd env set-secret <secret-value>
```
이 명령은 Key Vault 비밀을 만들고 실제 값이 아닌 파일에 참조 .env 를 저장합니다.
관리 ID: 연결 문자열 또는 액세스 키 대신 관리 ID를 사용하도록 Azure 서비스를 구성합니다.
환경별 보안: 개발 환경보다 프로덕션 환경에 더 엄격한 보안 제어를 적용합니다.
Just-In-Time 비밀: 영구 비밀을 저장하는 대신 배포 중에 수명이 짧은 자격 증명을 생성합니다.

다음 단계

후크를 사용하여 Azure 개발자 CLI 워크플로 사용자 지정 Azure Developer CLI의 환경 작업

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-08-16