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

아티클
01/11/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",
        }
    }
}

작업 영역 커넥트 - 비밀 목록 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 and Get Secret Versions 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를 비밀 저장소로 사용하려면 Key Vault 범위의 엔드포인트 ID와 같은 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를 호출할 필요가 없습니다. 환경 변수는 배포의 사용자 컨테이너가 시작될 때 비밀로 채워집니다.
- 환경 변수에 삽입되는 값은 다음 세 가지 형식 중 하나일 수 있습니다.
  - 전체 목록 비밀 API(미리 보기) 응답입니다. API 응답 구조를 이해하고 구문 분석한 다음 사용자 컨테이너에서 사용해야 합니다.
  - 작업 영역 연결의 개별 비밀 또는 메타데이터입니다. 작업 영역 연결 API 응답 구조를 이해하지 않고 사용할 수 있습니다.
  - Key Vault의 개별 비밀 버전입니다. Key Vault API 응답 구조를 이해하지 않고 사용할 수 있습니다.

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

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

패턴	동작
`${{azureml://connections/<connection_name>}}`	전체 목록 비밀 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 온라인 엔드포인트를 배포하는 동안 발생할 수 있는 오류에 대한 자세한 내용은 비밀 삽입 오류를 참조 하세요.

비밀 사용

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

Share via

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

필수 조건

비밀 저장소 선택

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

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

사용자 ID 선택

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

엔드포인트 만들기

배포 만들기

비밀 사용

추가 리소스

Share via

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

필수 조건

비밀 저장소 선택

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

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

사용자 ID 선택

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

엔드포인트 만들기

배포 만들기

비밀 사용

관련 콘텐츠

추가 리소스