Azure 개발자 CLI 템플릿 파일 탐색 및 편집

Azure 개발자 CLI(azd) 템플릿은 프로젝트를 프로비전하고 배포할 수 있는 azd 구성 및 인프라 자산이 있는 표준 리포지토리입니다. 새 템플릿을 빌드하든 기존 템플릿에서 시작하든 프로젝트가 발전함에 따라 파일을 검토하고 유지 관리하는 책임을 맡게 됩니다.

이 문서에서는 기본 템플릿 파일을 검사하고 편집하는 방법을 설명합니다. 전체 구조에 대한 개념 설명은 Azure 개발자 CLI 템플릿을 참조하세요.

이 문서에서는 실제 프로젝트에서 각 파일이 수행하는 작업을 볼 수 있도록 hello-azd 템플릿을 표준화된 예제로 사용합니다. 사용자 고유의 앱에 대해 생성하는 템플릿에는 동일한 개념이 적용됩니다. 따라가려면 빈 디렉터리에서 템플릿을 초기화합니다.

azd init --template hello-azd

템플릿은 hello-azd 컨테이너화된 C# 앱을 배포하여 Azure Container Apps Bicep 통해 지원되는 Azure 리소스를 프로비전합니다. 다음과 같은 폴더 구조를 사용합니다. 여기서 각 기본 자산은 이 문서의 섹션에 매핑됩니다.

.
├── azure.yaml                # Project configuration (Explore azure.yaml)
├── infra/                    # Infrastructure as code (Infrastructure files)
│   ├── main.bicep            # Deployment entry point
│   ├── main.parameters.json  # Parameter values that azd supplies
│   ├── abbreviations.json    # Resource name abbreviations
│   ├── app/                  # Application-specific modules
│   └── core/                 # Reusable resource modules
├── src/                      # Application source code (Source code)
│   └── Dockerfile            # Container image build for the app
├── .azure/                   # Environment configuration
└── README.md

정확한 구조는 프로젝트에 따라 다르며 azure.yaml 사용하는 경로를 식별합니다 azd . 다음 섹션에서는 각 자산을 편집하는 방법을 설명합니다.

상당한 변경을 하기 전에 잘 알려진 버전의 템플릿을 커밋하거나 저장합니다. 포함된 자격 증명, 불필요한 리소스, 과도한 권한, 네트워크 노출, 서비스 계층 및 환경별 값에 대한 모든 변경 내용을 검토합니다.

`azure.yaml` 탐색

이 파일은 azure.yaml 프로젝트를 정의하고 인프라를 프로비전하고, 애플리케이션 코드를 패키지하고, 각 서비스를 배포하는 방법을 알려줍니다 azd . 서비스, 인프라 설정, 후크, 워크플로 및 기타 프로젝트 동작을 정의할 수 있습니다.

템플릿은 hello-azd 다음과 같은 aca단일 서비스를 정의합니다.

name: azd-starter
metadata:
  template: hello-azd-dotnet
services:
  aca:
    project: ./src
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

각 속성은 azd 서비스를 처리하는 방법을 알려줍니다.

aca 는 서비스 이름입니다. azd는 서비스를 호스트하는 Azure 리소스와 일치하도록 사용합니다. 자세한 내용은 서비스 검색 구성을 참조하세요.
project: ./src 는 패키지 및 배포하는 azd 애플리케이션 소스 코드를 가리킵니다.
language: csharp 는 애플리케이션 언어를 식별합니다.
host: containerapp는 Azure Container Apps 서비스를 배포하도록 지시합니다azd.
docker는 src 디렉터리의 Dockerfile로부터 컨테이너 이미지를 빌드합니다.
remoteBuild는 azd ACR(Azure Container Registry)을 사용하여 컨테이너 이미지를 빌드하도록 지시합니다.

서비스 정의 추가

services에서 배포해야 하는 각 추가 애플리케이션에 대해 azd 아래에 항목을 추가합니다. 서비스 정의는 원본 디렉터리, 언어 및 Azure 호스팅 대상을 지정합니다. 예를 들어 새 API 프로젝트를 설명하려면 다음을 수행합니다.

services:
  api:
    project: ./src/api
    language: csharp
    host: appservice

애플리케이션 코드를 이동할 때 해당 project 경로를 업데이트합니다. 호스팅 아키텍처를 변경하는 경우 서비스 정의와 호스트를 프로비전하는 인프라를 모두 업데이트합니다.

사용 가능한 모든 속성 및 지원되는 값은 스키마를azure.yaml 참조하세요.

소스 코드

애플리케이션 원본은 선택 사항입니다. 배포 가능한 애플리케이션이 있는 템플릿은 디렉터리 아래에 src 소스 코드를 구성하는 경우가 많지만 특정 폴더 이름 또는 레이아웃을 사용할 필요는 없습니다. project에 있는 각 서비스의 azure.yaml 속성은 해당 서비스의 소스 코드가 있는 위치를 azd에 알려줍니다.

hello-azd에서는 src 서비스가 project: ./src를 설정하므로 azd가 aca 디렉터리의 C# 앱을 패키징하고 이를 Azure Container Apps에 배포합니다. 서비스가 azd 구성도 설정하므로, docker은 배포 전에 src 디렉터리의 Dockerfile에서 컨테이너 이미지를 빌드합니다.

azd는 지원되는 Azure 호스트에서 Node.js, Python, .NET, Java 및 Go를 지원합니다. 템플릿은 컨테이너를 배포할 수도 있습니다. 현재 언어, 프레임워크 및 호스트 조합은 지원되는 언어 및 환경을 참조하세요.

모든 애플리케이션 리포지토리에서와 마찬가지로 소스 코드를 편집합니다. 서비스를 추가하거나 원본 디렉터리를 이동하는 경우 해당 서비스 정의를 업데이트합니다 azure.yaml . 애플리케이션에 새 Azure 리소스가 필요한 경우 인프라를 업데이트하고 구성을 통해 필요한 엔드포인트 또는 리소스 이름을 애플리케이션에 전달합니다.

서비스 원본 디렉터리 변경

예를 들어, src/app에서 hello-azd(으)로 src 앱을 이동하는 경우, aca 서비스의 project 값을 업데이트합니다:

services:
  aca:
    project: ./src/app
    language: csharp
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

인프라 파일

디렉터리에는 infra 템플릿에 대한 Azure 리소스를 정의하는 Bicep 또는 Terraform 파일이 포함되어 있습니다. infra 디렉터리에서 hello-azdBicep 사용하며 다음과 같은 주요 자산을 포함합니다.

main.bicep 는 리소스를 프로비전하기 위해 실행되는 표준 배포 진입점 azd 입니다.
main.parameters.json 에 대한 main.bicep매개 변수 값을 제공합니다.
app 에는 애플리케이션과 관련된 모듈이 포함되어 있습니다.
core 에는 스토리지 및 호스팅과 같은 일반적인 리소스에 재사용 가능한 모듈이 포함되어 있습니다.

`azd up` 중 `main.bicep` 실행 방식

azd up를 실행하면 프로비전 단계에서 infra/main.bicep를 배포합니다. main.bicep 에서 hello-azd구독 범위를 대상으로 하고, 리소스 그룹을 만든 다음, 모듈을 호출하여 앱에 필요한 리소스를 프로비전합니다.

targetScope = 'subscription'

// Create a storage account
module storage './core/storage/storage-account.bicep' = {
  name: 'storage'
  scope: rg
  params: {
    name: !empty(storageAccountName) ? storageAccountName : '${abbrs.storageStorageAccounts}${resourceToken}'
    location: location
    tags: tags
    allowSharedKeyAccess: false
    containers: [ { name: 'attachments' } ]
    tables: [ { name: 'tickets' } ]
  }
}

// Container app for the 'aca' service
module web 'app/app.bicep' = {
  name: serviceName
  scope: rg
  params: {
    // ...
    serviceName: serviceName
  }
}

이 파일은 main.bicep 사용자가 할당한 관리 ID, Azure Storage 계정, Azure Container Apps 환경 및 레지스트리 및 서비스를 호스트하는 컨테이너 앱을 프로비전합니다aca. 또한 관리 ID가 스토리지에 액세스할 수 있도록 하는 역할을 할당합니다. 모듈은 읽을 수 있도록 main.bicep 각 리소스를 자체 파일에 유지합니다.

`main.bicep`에 리소스 추가

단순 또는 일회성 리소스에 infra/main.bicep 대한 리소스 선언을 직접 추가합니다. 리소스를 재사용하는 경우, 리소스에 여러 개의 관련 리소스가 필요한 경우 또는 main.bicep의 가독성을 유지하려는 경우에는 리소스를 별도의 Bicep 모듈로 분리합니다. 마찬가지로 hello-azd, 많은 템플릿은 아래 infra/core의 재사용 가능한 모듈을 그룹화합니다.

일반적인 Azure 리소스의 경우 모듈을 처음부터 작성하는 대신 Azure 확인된 모듈을 사용하는 것이 좋습니다. 확인된 모듈은 Microsoft 유지 관리되고, 보안 및 안정성 모범 사례를 따르고, 템플릿에서 유지 관리하는 인프라 코드의 양을 줄입니다.

hello-azd에 새 리소스를 추가하는 전체 안내는 템플릿 확장을 참조하세요.

main.parameters.json 파일은 azd에서 유지 관리하는 값을 Bicep 매개 변수에 매핑합니다. 템플릿은 hello-azd 다음 매개 변수를 사용합니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "principalType": { "value": "${AZURE_PRINCIPAL_TYPE=User}" }
  }
}

각 항목은 환경 이름, 위치, 배포를 실행하는 보안 주체 등 azd가 환경에서 유지하는 값에 Bicep 매개 변수를 바인딩합니다. 환경 이름, 위치 또는 생성하는 리소스 이름과 같이 환경 또는 배포에 따라 달라지는 값에 azd 사용합니다main.parameters.json. 환경 간에 변경되지 않는 안정적인 값을 매개 변수 기본값 또는 리터럴로 유지합니다 main.bicep. 이 방법은 각 배포에 대해 편집하지 않고도 환경에서 동일한 Bicep 재사용할 수 있게 유지합니다.

인프라를 추가하거나 편집하는 경우:

리소스 구성 환경을 독립적으로 유지합니다. 구독 ID, 리소스 이름, 위치 또는 자격 증명을 포함하는 대신 매개 변수 및 azd 환경 값을 사용합니다.
중요한 값에 보안 출력을 사용하고 비밀을 일반 텍스트 배포 출력으로 노출하지 마세요.
관리 ID에 최소 권한 역할 할당을 적용합니다.
azure.yaml의 서비스 정의가 대상 리소스와 일치하도록 유지합니다.
서비스 계층, 크기 조정 제한, 중복성 및 보존 설정이 비용에 미치는 영향을 검토합니다.

Bicep 언어 및 모듈 지침은 Bicep 설명서를 참조하세요. Terraform 기반 템플릿의 경우 Azure Developer CLI에서 Terraform 사용을 참조하세요.

서비스 검색 설정

기본적으로 azd는 azure.yaml의 서비스 이름과 azd-service-name 태그가 일치하는 리소스를 찾아 서비스용 Azure 리소스를 검색합니다. 서비스의 이름을 바꾸는 경우 해당 리소스 태그를 업데이트하거나 리소스 이름을 명시적으로 구성합니다 azure.yaml.

예를 들어 서비스 이름에서 hello-azdaca 컨테이너 앱 리소스의 azd-service-name 태그와 일치합니다. 서비스 정의는 azure.yaml 이름을 설정합니다.

services:
  aca:
    project: ./src
    language: csharp
    host: containerapp

infra/app/app.bicep의 컨테이너 앱 모듈은 일치하는 태그를 적용합니다:

tags: union(tags, { 'azd-service-name': serviceName })

비표준 인프라 경로 구성

azure.yaml의 infra 섹션은 인프라 공급자와 진입점을 식별합니다. 이러한 값은 기본 Bicep 레이아웃을 사용하는 경우 선택 사항이지만 선언하면 표준이 아닌 레이아웃을 더 쉽게 이해할 수 있습니다.

infra:
  provider: bicep
  path: infra
  module: main

환경 구성

.azure 디렉터리에는 azd에서 생성하는 로컬 환경 상태 및 값(예: 선택한 구독, 위치, 리소스 이름, 배포 출력)이 포함됩니다. 이 디렉터리를 재사용 가능한 템플릿 자산이 아닌 로컬 상태로 처리합니다. 비밀 또는 환경별 값을 포함하는 환경 파일을 커밋하지 마세요.

인프라 출력 추가

Bicep을 배포하기 위해 azd provision를 실행하면 인프라 진입 지점의 출력을 azd 환경 값으로 가져옵니다. 애플리케이션 서비스 또는 후크에 필요한 리소스 엔드포인트, 리소스 이름 및 관리 ID 클라이언트 ID에 대한 출력을 추가합니다. 예를 들어 hello-azd 다음에서 main.bicep컨테이너 레지스트리 및 관리 ID 세부 정보를 출력합니다.

output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerAppsEnv.outputs.registryLoginServer
output AZURE_CONTAINER_REGISTRY_NAME string = containerAppsEnv.outputs.registryName
output AZURE_USER_ASSIGNED_IDENTITY_NAME string = identity.outputs.name

관리 ID 또는 Key Vault 참조가 대신 액세스를 제공할 수 있는 경우 비밀을 출력하지 마세요. 프로비저닝한 후 실행 azd env get-values하여 캡처된 값을 검사합니다.

자세한 내용은 환경 변수 관리를 참조하세요.

변경 내용 테스트

실행 azd up 하여 인프라를 프로비전하고 애플리케이션 서비스를 배포합니다.

azd up

템플릿을 공유하려는 경우 클린 디렉터리에서 초기화하고 새 환경으로 배포합니다. 이 테스트는 템플릿의 일부가 아닌 로컬 파일, 캐시된 값 또는 환경별 가정을 식별하는 데 도움이 됩니다.

도움말 요청

버그를 제출하거나, 도움말을 요청하거나, Azure 개발자 CLI에 대한 새 기능을 제안하는 방법에 대한 자세한 내용은 troubleshooting and support 페이지를 방문하세요.

피드백

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

Last updated on 2026-09-16