비밀 삽입을 사용하여 온라인 배포에서 비밀에 액세스(미리 보기)

아티클
09/03/2024

적용 대상:Azure CLI ml 확장 v2(현재)Python SDK azure-ai-ml v2(현재)

이 문서에서는 온라인 엔드포인트 및 배포에서 비밀 삽입을 사용하여 비밀 저장소의 비밀에 액세스하는 방법을 알아봅니다.

다음에 대해 알아봅니다.

사용자 ID 및 해당 권한 설정
비밀 저장소로 사용할 작업 영역 연결 및/또는 키 자격 증명 모음 만들기
비밀 삽입 기능을 사용하여 엔드포인트 및 배포 만들기

Important

이 기능은 현재 공개 미리 보기로 제공됩니다. 이 미리 보기 버전은 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다.

자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

필수 조건

Azure Machine Learning을 사용하려면 Azure 구독이 있어야 합니다. Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다. 지금 Azure Machine Learning 평가판 또는 유료 버전을 사용해 보세요.
Azure Machine Learning CLI(v2) 확장 또는 Azure Machine Learning Python SDK(v2)를 설치하고 구성합니다.
사용자(또는 사용하는 서비스 주체)에게 User Access Administrator 및 Contributor 액세스 권한이 있어야 하는 Azure 리소스 그룹입니다. 앞서 설명한 대로 Azure Machine Learning 확장을 구성한 경우 이러한 리소스 그룹이 있습니다.
Azure Machine Learning 작업 영역 앞서 설명한 대로 Azure Machine Learning 확장을 구성한 경우 작업 영역이 있습니다.
채점 및 배포에 사용할 수 있도록 학습된 기계 학습 모델

비밀 저장소 선택

다음 중 하나를 사용하여 비밀(예: API 키)을 저장하도록 선택할 수 있습니다.

작업 영역 아래의 작업 영역 연결: 이러한 종류의 비밀 저장소를 사용하는 경우 나중에(엔드포인트를 만들 때) 특정 조건이 충족되면 엔드포인트 ID에 작업 영역 연결에서 자동으로 비밀을 읽을 수 있는 권한을 부여할 수 있습니다. 자세한 내용은 엔드포인트 만들기 섹션에서 시스템 할당 ID 탭을 참조하세요.
반드시 작업 영역 아래에 있지 않은 키 자격 증명 모음: 이러한 종류의 비밀 저장소를 사용하는 경우 엔드포인트 ID에 키 자격 증명 모음에서 자동으로 비밀을 읽을 수 있는 권한이 부여되지 않습니다. 따라서 Microsoft Azure Key Vault와 같은 관리형 키 자격 증명 모음 서비스를 비밀 저장소로 사용하려면 나중에 적절한 역할을 할당해야 합니다.

작업 영역 연결을 비밀 저장소로 사용

배포에서 사용할 작업 영역 연결을 만들 수 있습니다. 예를 들어 작업 영역 연결 - REST API 만들기를 사용하여 Microsoft Azure OpenAI Service에 대한 연결을 만들 수 있습니다.

또는 Azure Machine Learning 스튜디오(프롬프트 흐름에 대한 사용자 지정 연결을 만드는 방법 참조) 또는 Azure AI Studio(AI Studio에서 사용자 지정 연결을 만드는 방법 참조)를 사용하여 사용자 지정 연결을 만들 수 있습니다.

Azure OpenAI 연결을 만듭니다.

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "ApiKey",
        "category": "AzureOpenAI",
        "credentials": {
            "key": "<key>",
            "endpoint": "https://<name>.openai.azure.com/",
        },
        "expiryTime": null,
        "target": "https://<name>.openai.azure.com/",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "ApiType": "Azure"
        }
    }
}

또는 사용자 지정 연결을 만들 수 있습니다.

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "CustomKeys",
        "category": "CustomKeys",
        "credentials": {
            "keys": {
                "OPENAI_API_KEY": "<key>",
                "SPEECH_API_KEY": "<key>"
            }
        },
        "expiryTime": null,
        "target": "_",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "OPENAI_API_BASE": "<oai endpoint>",
            "OPENAI_API_VERSION": "<oai version>",
            "OPENAI_API_TYPE": "azure",
            "SPEECH_REGION": "eastus",
        }
    }
}

작업 영역 연결 - List Secrets REST API(미리 보기)를 사용하여 사용자 ID가 작업 영역 연결에서 비밀을 읽을 수 있는지 확인합니다.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

참고 항목

이전 코드 조각은 REST API를 호출할 때 Authorization 헤더에서 토큰을 사용합니다. az account get-access-token을 실행하여 토큰을 가져올 수 있습니다. 토큰을 가져오는 방법에 대한 자세한 내용은 액세스 토큰 가져오기를 참조하세요.

(선택 사항) Azure Key Vault를 비밀 저장소로 사용

키 자격 증명 모음을 만들고 배포에서 사용할 비밀을 설정합니다. 키 자격 증명 모음을 만드는 방법에 대한 자세한 내용은 Azure CLI를 사용하여 Azure Key Vault에서 비밀 설정 및 검색을 참조하세요. 또한,

az keyvault CLI 및 Set Secret REST API는 비밀을 설정하는 방법을 보여줍니다.
az keyvault secret show CLI 및 Get Secret Version REST API는 비밀 버전을 검색하는 방법을 보여줍니다.

Azure Key Vault를 만듭니다.

az keyvault create --name mykeyvault --resource-group myrg --location eastus

비밀을 만듭니다.
```
az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>
```
이 명령은 만든 비밀 버전을 반환합니다. 응답의 id 속성을 확인하여 비밀 버전을 얻을 수 있습니다. 반환된 응답은 https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>과 비슷합니다.
사용자 ID가 키 자격 증명 모음에서 비밀을 읽을 수 있는지 확인합니다.
```
az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>
```

Important

키 자격 증명 모음을 비밀 삽입을 위한 비밀 저장소로 사용하는 경우 키 자격 증명 모음의 권한 모델을 Azure RBAC(역할 기반 액세스 제어)로 구성해야 합니다. 자세한 내용은 Key Vault용 액세스 정책 및 Azure RBAC를 참조하세요.

사용자 ID 선택

온라인 엔드포인트 및 온라인 배포를 만드는 데 사용할 사용자 ID를 선택합니다. 이 사용자 ID는 Microsoft Entra ID의 사용자 계정, 서비스 주체 계정 또는 관리 ID일 수 있습니다. 사용자 ID를 설정하려면 Azure Machine Learning 리소스 및 워크플로에 대한 인증 설정의 단계를 수행합니다.

(선택 사항) 사용자 ID에 역할 할당

사용자 ID가 엔드포인트의 SAI(시스템 할당 ID)에 작업 영역 연결에서 비밀을 읽을 수 있는 권한을 자동으로 부여하려는 경우 사용자 ID에게 작업 영역 범위에 대한 Azure Machine Learning Workspace Connection Secrets Reader 역할(또는 그 이상)이 있어야 합니다.
- Microsoft.Authorization/roleAssignments/write 권한이 있는 관리자는 CLI 명령을 실행하여 사용자 ID에 역할을 할당할 수 있습니다.
```
az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
```
참고 항목

엔드포인트의 SAI(시스템 할당 ID)에는 키 자격 증명 모음에서 비밀을 읽을 수 있는 권한이 자동으로 부여되지 않습니다. 따라서 사용자 ID는 Key Vault에 대한 역할이 할당될 필요가 없습니다.
엔드포인트에 UAI(사용자 할당 ID)를 사용하려는 경우 사용자 ID에 역할을 할당하기 위해 필요가 없습니다. 대신, 비밀 삽입 기능을 사용하려는 경우 역할을 엔드포인트의 UAI에 수동으로 할당해야 합니다.
- Microsoft.Authorization/roleAssignments/write 권한이 있는 관리자는 다음 명령을 실행하여 엔드포인트 ID에 역할을 할당할 수 있습니다.
  
  작업 영역 연결의 경우:
```
az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
```
  키 자격 증명 모음의 경우:
```
az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>
```
Azure Portal의 리소스로 이동하여 ID(사용자 ID 또는 엔드포인트 ID)에 할당된 역할이 있는지 확인합니다. 예를 들어 Azure Machine Learning 작업 영역 또는 Key Vault에서 다음을 수행합니다.
1. 액세스 제어(IAM) 탭을 선택합니다.
2. 액세스 확인 단추를 선택하고 ID를 찾습니다.
3. 현재 역할 할당 탭 아래에 올바른 역할이 표시되는지 확인합니다.

SAI(시스템 할당 ID)를 엔드포인트 ID로 사용하는 경우 엔드포인트 ID에 기본 비밀 저장소(즉, 작업 영역 아래의 작업 영역 연결)에 대한 액세스를 적용할지 여부를 지정합니다.

endpoint.yaml 파일을 만듭니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
properties:
    enforce_access_to_default_secret_stores: enabled  # default: disabled

endpoint.yaml 파일을 사용하여 엔드포인트를 만듭니다.
```
az ml online-endpoint create -f endpoint.yaml
```

엔드포인트 정의에서 identity 속성을 지정하지 않으면 엔드포인트는 기본적으로 SAI를 사용합니다.

다음 조건이 충족되면 엔드포인트 ID에 작업 영역 범위에 대한 Azure Machine Learning Workspace Connection Secrets Reader 역할(또는 그 이상)이 자동으로 부여됩니다.

엔드포인트를 만드는 사용자 ID에는 작업 영역 연결(Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action)에서 비밀을 읽을 수 있는 동일한 권한이 있습니다.
엔드포인트는 SAI를 사용합니다.
엔드포인트는 엔드포인트를 만들 때 플래그를 사용하여 기본 비밀 저장소(현재 작업 영역 아래의 작업 영역 연결)에 대한 액세스를 적용하도록 정의됩니다.

엔드포인트 ID에는 Key Vault에서 비밀을 읽는 역할이 자동으로 부여되지 않습니다. Key Vault를 비밀 저장소로 사용하려면 엔드포인트 ID에게 Key Vault 범위에 대한 Key Vault Secrets User와 같은 적절한 역할을 수동으로 할당해야 합니다. 역할에 대한 자세한 내용은 Key Vault 데이터 평면 작업에 대한 Azure 기본 제공 역할을 참조하세요.

UAI(사용자 할당 ID)를 엔드포인트 ID로 사용하는 경우 enforce_access_to_default_secret_stores 플래그를 지정할 수 없습니다.

endpoint.yaml 파일을 만듭니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
identity:
    type: user_assigned
    user_assigned_identities: /subscriptions/00000000-0000-0000-000-000000000000/resourcegroups/myrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity

endpoint.yaml 파일을 사용하여 엔드포인트를 만듭니다.
```
az ml online-endpoint create -f endpoint.yaml
```

UAI를 사용하는 경우 선택적 섹션 사용자 ID에 역할 할당에 설명된 대로 엔드포인트 ID에 필요한 역할을 수동으로 할당해야 합니다.

배포 만들기

배포가 환경 변수를 통해 비밀을 사용할 수 있도록 채점 스크립트 또는 Dockerfile 및 관련 스크립트를 작성합니다.
- 작업 영역 연결 또는 키 자격 증명 모음에 대한 비밀 검색 API를 호출할 필요가 없습니다. 배포의 사용자 컨테이너가 시작될 때 환경 변수가 비밀로 채워집니다.
- 환경 변수에 삽입되는 값은 다음 세 가지 형식 중 하나일 수 있습니다.
  - 전체 List Secrets API(미리 보기) 응답. API 응답 구조를 이해하고 구문 분석한 다음 사용자 컨테이너에서 사용해야 합니다.
  - 작업 영역 연결의 개별 비밀 또는 메타데이터. 작업 영역 연결 API 응답 구조를 이해하지 않고 사용할 수 있습니다.
  - Key Vault의 개별 비밀 버전. Key Vault API 응답 구조를 이해하지 않고 사용할 수 있습니다.

채점 스크립트(사용자 지정 모델을 사용하는 경우) 또는 Dockerfile(BYOC 배포 방식을 사용하는 경우)을 사용하여 배포 만들기를 시작합니다. 사용자가 사용자 컨테이너 내에서 예상하는 환경 변수를 지정합니다.

환경 변수에 매핑된 값이 특정 패턴을 따르는 경우 엔드포인트 ID를 사용하여 비밀 검색 및 삽입을 수행합니다.

패턴	동작
`${{azureml://connections/<connection_name>}}`	전체 List Secrets API(미리 보기) 응답이 환경 변수에 삽입됩니다.
`${{azureml://connections/<connection_name>/credentials/<credential_name>}}`	자격 증명의 값이 환경 변수에 삽입됩니다.
`${{azureml://connections/<connection_name>/metadata/<metadata_name>}}`	메타데이터의 값이 환경 변수에 삽입됩니다.
`${{azureml://connections/<connection_name>/target}}`	대상(해당하는 경우)의 값이 환경 변수에 삽입됩니다.
`${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}}`	비밀 버전의 값이 환경 변수에 삽입됩니다.

예시:

deployment.yaml을 만듭니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
#…
environment_variables:
    AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}
    LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

    OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}
    OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

    USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

배포 만들기:

az ml online-deployment create -f deployment.yaml

엔드포인트에 enforce_access_to_default_secret_stores 플래그가 설정된 경우 엔드포인트를 만들 때와 배포를 만들 때 모두 작업 영역 연결에서 비밀을 읽을 수 있는 사용자 ID의 권한이 확인됩니다. 사용자 ID에 권한이 없으면 만들기가 실패합니다.

배포를 만들 때 환경 변수가 이전 테이블의 패턴을 따르는 값에 매핑되는 경우 엔드포인트 ID(SAI 또는 UAI)를 사용하여 비밀 검색 및 삽입이 수행됩니다. 엔드포인트 ID에 지정된 비밀 저장소(작업 영역 연결 또는 키 자격 증명 모음)에서 비밀을 읽을 수 있는 권한이 없는 경우 배포 만들기가 실패합니다. 또한 지정된 비밀 참조가 비밀 저장소에 없으면 배포 만들기가 실패합니다.

Azure Machine Learning 온라인 엔드포인트를 배포하는 동안 발생할 수 있는 오류에 대한 자세한 내용은 비밀 삽입 오류를 참조하세요.

비밀 사용

배포에서 실행되는 사용자 컨테이너 내의 환경 변수에서 비밀을 검색하여 사용할 수 있습니다.

다음을 통해 공유

비밀 삽입을 사용하여 온라인 배포에서 비밀에 액세스(미리 보기)

필수 조건

비밀 저장소 선택

작업 영역 연결을 비밀 저장소로 사용

(선택 사항) Azure Key Vault를 비밀 저장소로 사용

사용자 ID 선택

(선택 사항) 사용자 ID에 역할 할당

엔드포인트 만들기

배포 만들기

비밀 사용

피드백

추가 리소스

다음을 통해 공유

비밀 삽입을 사용하여 온라인 배포에서 비밀에 액세스(미리 보기)

필수 조건

비밀 저장소 선택

작업 영역 연결을 비밀 저장소로 사용

(선택 사항) Azure Key Vault를 비밀 저장소로 사용

사용자 ID 선택

(선택 사항) 사용자 ID에 역할 할당

엔드포인트 만들기

배포 만들기

비밀 사용

관련 콘텐츠

피드백

추가 리소스