Azure Container Apps에서 Functions 호스트 키 스토리지 구성

함수 액세스 키 는 Functions 런타임이 HTTP 트리거 엔드포인트를 보호하는 데 사용하는 인증 토큰입니다. 호출자가 HTTP 함수를 호출할 때 키는 ?code= 쿼리 매개 변수나 x-functions-key 헤더로 포함됩니다. 런타임은 키의 유효성을 검사하고 요청에 권한을 부여하거나 거부합니다.

액세스 키는 앱 수준 비밀과 동일하지 않습니다. 액세스 키는 함수를 호출할 수 있는 사용자를 보호하는 반면, 앱 수준 비밀 은 함수가 연결하는 항목을 보호합니다.

액세스 키를 사용하는 경우

시나리오	액세스 키가 적합한 이유
타사 웹후크	GitHub, Stripe 또는 Twilio와 같은 공급자는 URL 및 비밀을 통해 함수를 호출합니다. 액세스 키는 예상되는 `?code=` 패턴에 직접 삽입됩니다.
서비스 대 서비스 호출	백 엔드 서비스 A는 HTTP를 통해 함수 B를 호출합니다. 공유 키는 내부 전용 호출에 Microsoft Entra 앱 등록을 설정하는 것보다 간단합니다.
Event Grid 구독	Event Grid는 플랫폼이 자동으로 관리하는 시스템 키를 사용하여 함수 엔드포인트의 유효성을 검사하고 호출합니다.
개발/테스트 인증	개발하는 동안 전체 OAuth/OIDC를 구성하지 않고 기본 인증이 필요합니다. 액세스 키는 ID 구성이 없는 낮은 마찰 인증 게이트를 제공합니다.
마이그레이션 호환성	기존 Azure Functions 앱은 이미 액세스 키를 사용하고 있습니다. Container Apps로 마이그레이션할 때 호출자를 중단하지 않도록 동일한 키 기반 인증이 필요합니다.

메모

사용자 연결 API, 제로 트러스트 워크로드 또는 사용자별 권한 부여 시나리오의 경우 액세스 키 대신 Microsoft Entra ID/OAuth 2.0을 사용합니다. 액세스 키는 ID 수준 감사 내역이 없는 공유 비밀입니다.

필수 조건

활성 구독이 있는 Azure 계정. 무료로 계정을 만듭니다.
Azure CLI 버전 2.40.0 이상.
Container Apps의 기존 Azure Functions 앱이나 앱을 만들 수 있는 권한.

액세스 키 유형

Functions 런타임은 다음 네 가지 유형의 키를 관리합니다.

키 유형	Scope	Purpose
마스터 키 (`_master`)	전체 함수 앱	모든 함수 및 `/admin/*` 관리 엔드포인트에 대한 관리자 수준 액세스 취소할 수 없으며 회전만 가능합니다.
호스트 키 (`default` + 사용자 지정)	전체 함수 앱	앱에서 HTTP 트리거 함수에 대한 호출에 권한을 부여합니다.
함수 키 (`default` + 사용자 지정)	단일 함수	하나의 특정 함수에 대한 호출에 권한을 부여합니다. 호스트 키보다 더 세분화된 컨트롤을 제공합니다.
시스템 키	확장 끝점	Event Grid 웹후크 구독 및 Durable Functions 같은 플랫폼 확장에서 사용됩니다. 자동으로 관리됩니다.

스토리지 백 엔드 선택

런타임이 AzureWebJobsSecretStorageType 액세스 키를 유지하는 위치를 제어하도록 환경 변수를 설정합니다. Azure Container Apps 3개의 프로덕션 등급 백 엔드를 지원합니다.

백엔드	설정값	키 자동 생성	외부 종속성	적합한 대상
Container Apps 비밀 저장소	`containerapps`	아니요 - 컨테이너 앱 시크릿으로 키를 프로비전합니다.	None	대부분의 워크로드(권장)
Azure Key Vault	`keyvault`	아니요 - 수동으로 트리거 생성	Key Vault 인스턴스	중앙 집중식 거버넌스, 규정 준수 감사
Azure Blob Storage	`blob`	예	스토리지 계정	레거시 앱 또는 기존 `AzureWebJobsStorage` 계정

백엔드 관련 고려사항을 명심하세요:

런타임이 컨테이너 앱의 비밀 저장소를 자동으로 선택하지 않습니다. 만약 인식되지 않은 값으로 설정 AzureWebJobsSecretStorageType 하지 않으면, Functions 호스트가 사용할 수 있을 때 AzureWebJobsStorage Blob Storage를 사용합니다.
AzureWebJobsStorage 스토리지 상태 확인과 스토리지 관련 기능에 맞게 계속 설정하세요.
AzureWebJobsSecretStorageType을/를 files로 설정하지 마세요. 컨테이너 앱 파일 시스템은 일시적이기 때문에, 앱이 0으로 확장되거나 재시작되거나 새 버전을 배포할 때 이 백엔드에 저장된 키가 손실됩니다.

비밀 이름 패턴

저장된 키에 대한 명명 규칙은 스토리지 백 엔드에 따라 달라집니다.

Container Apps 비밀 저장소는 다른 규칙을 사용합니다. Functions 호스트는 볼륨 탑재 파일 /run/secrets/functions-keys/의 키를 읽습니다. 각 파일은 점으로 구분된 이름(예: host.master)을 사용하지만 Container Apps 비밀 이름은 소문자 영숫자 및 대시만 허용합니다. 비밀 볼륨을 마운트할 때는 Functions 호스트가 예상하는 점 표기된 파일 이름으로 path 필드를 명시적으로 설정해야 합니다(예: secretRef: host-master → path: host.master). 플랫폼은 자동 이름 변환을 수행하지 않습니다.

키 유형	Container Apps 비밀 이름(대시)	볼륨 마운트 `path` (점)
마스터 키	`host-master`	`host.master`
기본 호스트 키	`host-function-default`	`host.function.default`
사용자 지정 호스트 키	`host-function-<name>`	`host.function.<name>`
특정 함수의 기본 함수 키	`functions-<functionname>-default`	`functions.<functionName>.default`
특정 함수에 대한 사용자 지정 함수 키	`functions-<functionname>-<keyname>`	`functions.<functionName>.<keyName>`
시스템 키	`host-systemkey-<extension>`	`host.systemKey.<extension>`

Key Vault 백 엔드는 이중 대시(--) 규칙을 사용하여 각 키를 개별 Key Vault 비밀로 저장합니다.

키 유형	비밀 이름 패턴	Example
마스터 키	`host--masterKey--master`	`host--masterKey--master`
함수 키(기본값)	`host--functionKey--default`	`host--functionKey--default`
함수 키(사용자 지정)	`host--functionKey--<name>`	`host--functionKey--MyApiClient`
시스템 키	`host--systemKey--<extension>`	`host--systemKey--eventgrid_extension`
함수별 키	`function--<functionName>--<keyName>`	`function--myhttpfunc--default`

Blob Storage 백 엔드는 키를 azure-webjobs-secrets Blob 컨테이너에 JSON 파일로 저장합니다. 모든 호스트 수준 키(마스터, 함수 키 및 시스템 키)는 단일 host.json Blob에 함께 저장됩니다. 함수별 키는 각 함수의 이름을 따서 명명된 별도의 Blob에 저장됩니다.

Blob 경로	목차
`<SITE_SLOT_NAME>/host.json`	`masterKey`, `functionKeys`, 및 `systemKeys`를 포함하는 JSON 파일
`<SITE_SLOT_NAME>/<FUNCTION_NAME>.json`	특정 함수에 대한 키가 포함된 JSON 파일

Tip

문제를 해결할 때 백 엔드 저장소에서 이러한 패턴을 검색하여 키가 올바르게 구성되었는지 확인합니다.

Container Apps 비밀 저장소 구성

Container Apps 비밀 저장소가 권장되는 백 엔드입니다. 키는 Container Apps 플랫폼 내에 유지되며 외부 스토리지 또는 Key Vault 필요하지 않습니다. Azure Resource Manager 활동 로그는 비밀 및 환경 변수에 대한 변경 내용을 추적합니다.

이 백엔드를 사용하면 Functions 호스트는 /run/secrets/functions-keys/에 볼륨 마운트된 파일에서 키를 읽습니다. 호스트는 키를 자동으로 생성하지 않습니다. 각 키를 Container Apps 비밀로 만들어야 하며 플랫폼은 호스트가 읽을 파일로 탑재합니다.

Important

Container Apps 비밀 저장소는 호스트의 관점에서 읽기 전용입니다. 호스트는 탑재된 키 파일을 읽지만 절대로 기록하지 않습니다. 필요한 키가 누락된 경우 호스트가 자동으로 키를 생성하지 않습니다.

Azure 포털에서 Functions 컨테이너 앱으로 이동합니다.
설정에서 환경 변수를 선택합니다.
추가를 선택하고 다음 값을 입력합니다.

재산 가치

이름 AzureWebJobsSecretStorageType

값 containerapps
저장을 선택한 다음 적용을 선택하여 변경 내용을 확인합니다.

재산	가치
이름	`AzureWebJobsSecretStorageType`
값	`containerapps`

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=containerapps"

2단계: 액세스 키 비밀 생성 및 저장

키 값을 생성하고 Container Apps 비밀로 저장합니다. 최소한 마스터 키 와 기본 호스트 키가 필요합니다.

포트알
Azure CLI

Functions 컨테이너 앱의 설정에서 비밀을 선택합니다.
추가를 선택하고 다음 값을 입력합니다.

재산 가치

이름 host-master

Type Container Apps 시크릿

값 임의로 생성된 키 값입니다.
추가를 선택합니다.
임의로 생성된 다른 값을 사용하여 host-function-default 반복합니다.
함수별 키를 추가하려면, functions-<functionname>-default라는 이름의 비밀(모두 소문자)을 추가하세요.

재산	가치
이름	`host-master`
Type	Container Apps 시크릿
값	임의로 생성된 키 값입니다.

# Generate random key values
MASTER_KEY=$(openssl rand -hex 32)
HOST_DEFAULT_KEY=$(openssl rand -hex 32)

# Store as Container Apps secrets
az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-master=$MASTER_KEY" "host-function-default=$HOST_DEFAULT_KEY"

함수별 키(예: 명명된 MyHttpFunc함수의 경우)를 추가하려면 다음을 실행합니다.

FUNC_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "functions-myhttpfunc-default=$FUNC_KEY"

메모

Container Apps 비밀 이름은 소문자 영숫자 및 대시만 허용합니다. 볼륨 구성의 path 필드를 Functions 호스트에서 예상하는 점선 파일 이름(예 secretRef: host-master : → path: host.master)으로 명시적으로 설정해야 합니다. 명시적인 path이 없으면 디스크의 파일은 하이픈이 포함된 이름 그대로 유지되며, Functions 호스트는 해당 키를 찾지 못합니다.

3단계: 볼륨 마운트 구성

비밀을 /run/secrets/functions-keys/에 파일로 탑재합니다.

포트알
Azure CLI

Functions 컨테이너 앱의 애플리케이션에서 수정 버전 및 복제본을 선택합니다.
새 수정 버전 만들기를 선택합니다.
크기 조정 및 볼륨 탭의볼륨에서 추가를 선택합니다.
다음 값을 입력합니다.

재산 가치

볼륨 유형 비밀

이름 functions-keys
각 비밀에 대해 경로 필드를 Functions 호스트가 예상하는 점이 있는 파일 이름으로 설정합니다. 예를 들어, host-master을 host.master 경로로 설정하고, host-function-default을 host.function.default 경로로 설정합니다.
추가를 선택합니다.
컨테이너 탭에서 컨테이너를 선택한 다음 편집을 선택합니다.
볼륨 탑재 탭을 선택하고 추가를 선택합니다.
다음 값을 입력합니다.

재산 가치

볼륨 이름 functions-keys

탑재 경로 /run/secrets/functions-keys
저장을 선택한 다음 만들기를 선택하여 새 수정 버전을 배포합니다.

재산	가치
볼륨 유형	비밀
이름	`functions-keys`

재산	가치
볼륨 이름	`functions-keys`
탑재 경로	`/run/secrets/functions-keys`

앱의 YAML을 내보내고 볼륨 및 볼륨 탑재를 추가한 다음 적용합니다.

# Export current config
az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --output yaml > app.yaml

적절한 섹션에 볼륨 및 볼륨 마운트를 추가하기 위해 app.yaml를 편집합니다.

properties:
  template:
    volumes:
      - name: functions-keys
        storageType: Secret
        secrets:
          - secretRef: host-master
            path: host.master
          - secretRef: host-function-default
            path: host.function.default
    containers:
      - name: <CONTAINER_NAME>
        volumeMounts:
          - volumeName: functions-keys
            mountPath: /run/secrets/functions-keys

업데이트된 구성을 적용합니다.

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --yaml app.yaml

4단계: 확인

앱이 다시 시작되면 키가 작동하는지 확인합니다.

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

앱 로그에서 Resolved secret storage provider ContainerAppsSecretsRepository 메시지를 확인하여 호스트가 Container Apps 비밀 저장소를 사용 중인지 확인할 수도 있습니다.

키 회전

키를 회전하려면 Container Apps 비밀을 업데이트하고 앱을 다시 시작합니다.

NEW_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-function-default=$NEW_KEY"

az containerapp revision restart \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --revision "<REVISION_NAME>"

메모

모든 복제본은 탑재된 동일한 비밀을 공유합니다. 다시 시작한 후 모든 복제본은 업데이트된 키 값을 선택합니다.

Key Vault 또는 Blob Storage를 저장소로 설정하세요

Key Vault 구성
Blob Storage 구성

Key Vault 백 엔드는 액세스 키를 Key Vault 비밀로 저장하여 엔터프라이즈급 감사 및 액세스 제어를 제공합니다.

Key Vault 만듭니다(없는 경우).

az keyvault create \
  --name "<KEYVAULT_NAME>" \
  --resource-group "<RESOURCE_GROUP>" \
  --location "<LOCATION>"

컨테이너 앱에서 관리 ID를 사용하도록 설정합니다(아직 사용하도록 설정되지 않은 경우).

az containerapp identity assign \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --system-assigned

Key Vault 비밀 책임자 역할을 관리 ID에 부여합니다. 런타임은 키를 만들고 관리하기 위해 읽기 및 쓰기 액세스 권한이 필요합니다.

PRINCIPAL_ID=$(az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --query identity.principalId \
  --output tsv)

KEYVAULT_ID=$(az keyvault show \
  --name "<KEYVAULT_NAME>" \
  --query id \
  --output tsv)

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee "$PRINCIPAL_ID" \
  --scope "$KEYVAULT_ID"

스토리지 유형 및 Key Vault URI를 설정합니다.

시스템 할당 ID의 경우:

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars \
    "AzureWebJobsSecretStorageType=keyvault" \
    "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net"

사용자 할당 ID의 경우 클라이언트 ID도 설정합니다.

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars \
    "AzureWebJobsSecretStorageType=keyvault" \
    "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net" \
    "AzureWebJobsSecretStorageKeyVaultClientId=<USER_ASSIGNED_IDENTITY_CLIENT_ID>"

키를 나열하여 키 만들기를 트리거합니다.

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

Blob Storage 백 엔드를 사용하면 런타임에서 액세스 키를 자동으로 생성하고 관리할 수 있습니다. 스토리지 계정이 AzureWebJobsStorage 이미 있고 중앙 집중식 거버넌스가 필요하지 않은 경우 이 옵션을 사용합니다.

컨테이너 앱에서 관리 ID를 사용하도록 설정합니다(아직 사용하도록 설정되지 않은 경우).

az containerapp identity assign \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --system-assigned

스토리지 계정의 Storage Blob 데이터 기여자 역할을 관리 ID에 부여합니다.

PRINCIPAL_ID=$(az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --query identity.principalId \
  --output tsv)

STORAGE_ID=$(az storage account show \
  --name "<STORAGE_ACCOUNT_NAME>" \
  --resource-group "<RESOURCE_GROUP>" \
  --query id \
  --output tsv)

az role assignment create \
  --role "Storage Blob Data Contributor" \
  --assignee "$PRINCIPAL_ID" \
  --scope "$STORAGE_ID"

스토리지 유형을 설정합니다.

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=blob"

런타임은 다음 콜드 시작 시 키를 자동으로 생성합니다. 확인:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

액세스 키 관리

백 엔드에 관계없이 다음 명령을 사용하여 액세스 키를 나열, 만들기 및 삭제합니다.

메모

이러한 키 관리 작업을 수행하기 위해 최소 하나의 복제본을 계속 실행하세요.

모든 호스트 키 목록:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

마스터 키 목록:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type masterKey

사용자 지정 호스트 키를 생성하거나 덮어쓰기:

az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

특정 키를 보여주세요:

az containerapp function keys show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "<KEY_NAME>" \
  --key-type hostKey

호스트 키를 삭제하기:

az containerapp function keys delete \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-type hostKey

액세스 키를 사용하여 함수 호출

키를 쿼리 매개 변수 또는 요청 헤더로 전달합니다.

# Query parameter
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>?code=<HOST_KEY>"

# Header
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>" \
  -H "x-functions-key: <HOST_KEY>"

피드백

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

Last updated on 2026-08-14