다음을 통해 공유

Azure AI Search에서 공유 프라이빗 링크 문제 해결

  • 아티클

공유 프라이빗 링크를 사용하면 Azure AI Search가 가상 네트워크의 고객 리소스에 액세스할 때 프라이빗 엔드포인트를 통해 안전한 아웃바운드 연결을 만들 수 있습니다. 이 문서는 발생할 수 있는 오류를 해결하는 데 도움이 될 수 있습니다.

공유 프라이빗 링크를 만드는 것은 검색 서비스 컨트롤 플레인 작업입니다. 포털 또는 관리 REST API를 사용하여 공유 프라이빗 링크를 만들 수 있습니다. 프로비저닝하는 동안 요청의 상태는 “업데이트 중”입니다. 작업이 성공적으로 완료되면 상태가 “성공”입니다. 모든 DNS 영역 및 매핑과 함께 리소스에 대한 프라이빗 엔드포인트가 만들어집니다. 이 엔드포인트는 검색 서비스 인스턴스에서만 사용되며 Azure AI Search를 통해 관리됩니다.

Steps involved in creating shared private link resources

만들기 단계 중에 발생하는 몇 가지 일반적인 오류는 다음과 같습니다.

유효성 검사 실패 요청

  • 지원되지 않는 SKU: 공유 프라이빗 링크는 기본 계층 이상에서 지원됩니다. 기술 세트가 있는 인덱서의 경우 최소 계층은 표준 2(S2)입니다.

  • 잘못된 이름: 공유 프라이빗 링크에 대한 명명 규칙은 다음과 같습니다.

    • 길이는 1~60자 사이여야 함
    • 영숫자 문자
    • 이름에 첫 번째 문자가 아닌 한 이름에 밑줄 _, 마침표 . 및 하이픈 -이 포함될 수 있습니다.

  • 잘못된 그룹 ID: 그룹 ID는 대/소문자를 구분하며 아래 표의 값 중 하나여야 합니다.

    Azure 리소스 그룹 ID 사용 가능한 첫 번째 API 버전
    Azure Storage - Blob(또는) ADLS Gen 2 blob 2020-08-01
    Azure Storage - 테이블 table 2020-08-01
    Azure Cosmos DB for NoSQL Sql 2020-08-01
    Azure SQL Database sqlServer 2020-08-01
    Azure Database for MySQL(미리 보기) mysqlServer 2020-08-01-Preview
    Azure Key Vault vault 2020-08-01
    Azure Functions(미리 보기) sites 2020-08-01-Preview

    관리 REST API 버전의 미리 보기 버전을 사용하여 “(미리 보기)”로 표시된 리소스를 만들어야 합니다.

  • privateLinkResourceId 형식 유효성 검사: Azure AI Search와 groupId마찬가지로 Azure AI Search는 "올바른" 리소스 종류가 에 지정되어 privateLinkResourceId있는지 확인합니다. 유효한 리소스 종류는 다음과 같습니다.

    Azure 리소스 리소스 종류 사용 가능한 첫 번째 API 버전
    Azure Storage Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Azure SQL Database Microsoft.Sql/servers 2020-08-01
    Azure Key Vault Microsoft.KeyVault/vaults 2020-08-01
    Azure Database for MySQL(미리 보기) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Azure Functions(미리 보기) Microsoft.Web/sites 2020-08-01-Preview
    Azure SQL Managed Instance(미리 보기) Microsoft.Sql/managedInstance 2020-08-01-Preview

    추가로 지정된 리소스 종류에 대해 지정된 groupId가 유효해야 합니다. 예를 들어 groupId “Blob”은 “Microsoft.Storage/storageAccounts” 종류에 유효하며, 다른 리소스 종류에는 사용할 수 없습니다. 지정된 검색 관리 API 버전의 경우 고객은 List supported API를 활용하여 지원되는 groupId 및 리소스 종류 세부 정보를 확인할 수 있습니다.

  • 할당량 제한 적용: 검색 서비스에는 만들 수 있는 공유 프라이빗 링크 리소스의 고유 수와 사용 중인 다양한 대상 리소스 유형(기준)의 수에 groupId대한 할당량이 적용됩니다. Azure AI Search 서비스 제한 페이지의 공유 프라이빗 링크 리소스 제한 섹션에 설명되어 있습니다.

배포 실패

검색 서비스는 공유 프라이빗 링크를 만들기 위한 요청을 시작하지만 Azure Resource Manager는 실제 작업을 수행합니다. 포털 또는 쿼리를 통해 배포의 상태 검사 발생할 수 있는 오류를 해결할 수 있습니다.

Azure Resource Manager 배포에 실패한 공유 프라이빗 링크 리소스는 목록 및 가져오기 API 호출에 표시되지만 "프로비전 상태"가 Failed있습니다. Azure Resource Manager 배포 실패 사유가 확인되면 Failed 리소스를 삭제하고 다음 표에서 적절한 해결 방법을 적용한 후 리소스를 다시 만듭니다.

배포 실패 사유 설명 해결 방법
"LinkedAuthorizationFailed" 오류 메시지에는 클라이언트가 검색 서비스에서 공유 프라이빗 링크를 만들 수 있는 권한이 있지만 연결된 범위에서 'privateEndpoint커넥트ionApproval/action' 작업을 수행할 수 있는 권한이 없음을 나타냅니다. 요청에서 프라이빗 링크 ID를 다시 검사 URI에 오류 또는 누락이 없는지 확인합니다. Azure AI Search와 Azure PaaS 리소스가 서로 다른 구독에 있고 REST 또는 명령줄 인터페이스를 사용하는 경우 활성 Azure 계정이 Azure PaaS 리소스용인지 확인합니다. REST 클라이언트의 경우 만료된 전달자 토큰을 사용하지 않고 토큰이 활성 구독에 유효한지 확인합니다.
대상 리소스의 구독에 등록되지 않은 네트워크 리소스 공급자 Microsoft.Network RP(리소스 공급자)를 통해 대상 리소스(스토리지 계정, Azure Cosmos DB, Azure SQL)에 대해 프라이빗 엔드포인트(및 연결된 DNS 매핑)가 생성됩니다. 대상 리소스를 호스트하는 구독(“대상 구독”)이 Microsoft.Network RP에 등록되지 않은 경우 Azure Resource Manager 배포가 실패할 수 있습니다. 대상 구독에서 이 RP를 등록해야 합니다. Azure Portal, PowerShell 또는 CLI를 사용하여 리소스 공급자를 등록할 수 있습니다.
대상 리소스에 대해 유효하지 않음 groupId Azure Cosmos DB 계정을 만들면 데이터베이스 계정에 대한 API 유형을 지정할 수 있습니다. Azure Cosmos DB는 여러 가지 API 유형을 제공하지만 Azure AI Search는 공유 프라이빗 링크 리소스에 groupId 대한 "Sql"만 지원합니다. “Sql” 유형의 공유 프라이빗 링크가 비 Sql 데이터베이스 계정을 가리키는 privateLinkResourceId에 대해 만들어진 경우 groupId 불일치로 인해 Azure Resource Manager 배포가 실패합니다. Azure Cosmos DB 계정의 Azure 리소스 ID가 사용 중인 API 유형을 확인하기에 충분하지 않습니다. Azure AI Search는 프라이빗 엔드포인트를 만들려고 시도합니다. 그러면 Azure Cosmos DB에서 거부됩니다. 지정된 Azure Cosmos DB 리소스의 privateLinkResourceId가 “Sql” API 유형의 데이터베이스 계정에 대한 것인지 확인해야 합니다.
대상 리소스를 찾을 수 없음 지정된 privateLinkResourceId 대상 리소스의 존재는 Azure Resource Manager 배포가 시작되는 동안에만 검사. 대상 리소스를 더 이상 사용할 수 없는 경우 배포가 실패합니다. 대상 리소스가 지정된 구독 및 리소스 그룹에 있고 이동/삭제되지 않았는지 확인해야 합니다.
일시적/기타 오류 인프라가 중단되거나 다른 예기치 않은 이유로 인해 Azure Resource Manager 배포가 실패할 수 있습니다. 이는 드물어야 하며 일반적으로 일시적인 상태를 나타냅니다. 나중에 이 리소스 만들기를 다시 시도합니다. 문제가 계속되면 Azure 지원에 문의하세요.

지원 프라이빗 엔드포인트 승인 문제

프라이빗 엔드포인트는 공유 프라이빗 링크 만들기 요청에 지정된 대로 대상 Azure 리소스에 만들어집니다. 이는 비동기 Azure Resource Manager 배포 작업의 마지막 단계 중 하나이지만 Azure AI Search는 네트워크 구성의 일부로 프라이빗 엔드포인트의 개인 IP 주소를 연결해야 합니다. 이 링크가 완료되면 공유 프라이빗 링크 리소스의 provisioningState가 최종 성공 상태 Succeeded로 전환됩니다. 고객은 상태가 Succeeded로 전환된 후에만 승인 또는 거부(또는 일반적으로 지원 프라이빗 엔드포인트의 구성을 수정)해야 합니다. 이렇게 하기 전에 어떤 방식으로든 프라이빗 엔드포인트를 수정하면 배포 작업이 불완전해질 수 있으며 공유 프라이빗 링크 리소스가 즉시 또는 일반적으로 몇 시간 내에 Failed 상태가 될 수 있습니다.

검색 서비스 네트워크 연결 변경이 "업데이트 중" 상태로 중단됨

공유 프라이빗 링크 및 프라이빗 엔드포인트는 검색 서비스 공용 네트워크 액세스를사용할 수 없는 경우에 사용됩니다. 일반적으로 네트워크 연결 변경은 요청이 수락된 후 몇 분 후에 성공해야 합니다. 경우에 따라 Azure AI Search는 연결 변경 작업을 완료하는 데 몇 시간이 걸릴 수 있습니다.

Screenshot of changing public network access to disabled.

연결 변경 작업에 상당한 시간이 걸리는 것을 관찰하는 경우 몇 시간 동안 기다립니다. 커넥트성 변경 작업에는 예상보다 오래 걸릴 수 있는 DNS 레코드 업데이트와 같은 작업이 포함됩니다.

공용 네트워크 액세스가 변경되면 기존 공유 프라이빗 링크 및 프라이빗 엔드포인트가 제대로 작동하지 않을 수 있습니다. 연결 변경 작업 중에 기존 공유 프라이빗 링크 및 프라이빗 엔드포인트가 작동을 중지하는 경우 작업이 완료되기까지 몇 시간을 기다립니다. 아직 작동하지 않는 경우 삭제하고 다시 만들어 보세요.

일반적으로 공유 프라이빗 링크 리소스는 요청이 수락된 후 몇 분 후에 터미널 상태(Succeeded 또는 Failed)로 이동해야 합니다.

드문 경우지만 Azure AI Search는 공유 프라이빗 링크 리소스의 상태를 터미널 상태(Succeeded 또는 Failed)로 올바르게 표시하지 못할 수 있습니다. 일반적으로 예기치 않은 오류로 인해 발생합니다. 공유 프라이빗 링크 리소스가 최종이 아닌 상태로 몇 시간 이상 “지속”되면 자동으로 Failed 상태로 전환됩니다.

공유 프라이빗 링크 리소스가 터미널 상태로 전환되지 않은 경우 몇 시간 동안 기다렸다가 Failed 삭제하고 다시 만들 수 있습니다. 또는 대기하는 대신 다른 이름으로 다른 공유 프라이빗 링크 리소스를 만들 수 있습니다(다른 모든 매개 변수는 동일하게 유지).

기존 공유 프라이빗 링크 리소스는 만들기 또는 업데이트 API를 사용하여 업데이트할 수 있습니다. 검색은 공유 프라이빗 링크 리소스에 대한 좁은 업데이트만 허용합니다. 요청 메시지만 이 API를 통해 수정할 수 있습니다.

  • 기존 공유 프라이빗 링크 리소스(예: privateLinkResourceId 또는 groupId)의 “핵심” 속성은 업데이트할 수 없으며, 이는 항상 지원되지 않습니다. 요청 메시지 외에 다른 속성을 변경해야 하는 경우 공유 프라이빗 링크 리소스를 삭제하고 다시 만드는 것이 좋습니다.

  • 공유 프라이빗 링크 리소스의 요청 메시지를 업데이트하려는 시도는 프로비전 상태에 Succeeded도달한 경우에만 가능합니다.

고객은 Delete API를 통해 기존 공유 프라이빗 링크 리소스를 삭제할 수 있습니다. 생성(또는 업데이트) 프로세스와 마찬가지로 다음 네 단계로 구성된 비동기 작업이기도 합니다.

  1. 공유 프라이빗 링크 리소스를 삭제하도록 검색 서비스를 요청합니다.

  2. 검색 서비스는 리소스가 존재하며 삭제에 유효한 상태인지 확인합니다. 유효한 상태인 경우 리소스를 제거할 Azure Resource Manager 삭제 작업이 시작됩니다.

  3. 작업 완료에 대해 쿼리를 검색합니다(일반적으로 몇 분 정도 소요됨). 이 시점에서 공유 프라이빗 링크 리소스는 프로비전 상태가 "삭제 중"입니다.

  4. 작업이 성공적으로 완료되면 지원 프라이빗 엔드포인트 및 연결된 DNS 매핑이 제거됩니다. 리소스는 List 작업의 일부로 표시되지 않으며 이 리소스에 Get 작업을 시도하면 404 찾을 수 없음 오류가 발생합니다.

Steps involved in deleting shared private link resources

삭제 단계 중에 발생하는 몇 가지 일반적인 오류는 다음과 같습니다.

오류 유형 설명 해결 방법
리소스가 터미널이 아닌 상태입니다. 최종 상태(Succeeded 또는Failed)가 아닌 공유 프라이빗 링크 리소스는 삭제할 수 없습니다. 공유 프라이빗 링크 리소스가 터미널이 아닌 상태에서 최대 8시간 동안 중단될 수 있습니다(드문 경우). 리소스가 터미널 상태에 도달할 때까지 기다렸다가 삭제 요청을 다시 시도합니다.
"충돌" 오류로 삭제 작업이 실패했습니다. 공유 프라이빗 링크 리소스를 삭제하는 Azure Resource Manager 작업은 프라이빗 엔드포인트 및 DNS 매핑을 제거하기 전에 지정된 대상 리소스 privateLinkResourceId 의 리소스 공급자("대상 RP")에 도달합니다. 고객은 Azure 리소스 잠금을 활용하여 리소스가 변경되지 않도록 할 수 있습니다. Azure Resource Manager가 대상 RP에 도달하면 대상 RP에서 대상 리소스의 상태를 수정해야 합니다(메타데이터로부터 프라이빗 엔드포인트에 관한 세부 정보를 제거해야 함). 대상 리소스에 구성된 잠금(또는 해당 리소스 그룹/구독)이 있는 경우 Azure Resource Manager 작업이 실패하고 “충돌”(및 적절한 세부 정보)이 발생합니다. 공유 프라이빗 링크 리소스는 삭제되지 않습니다. 고객은 삭제 작업을 다시 시도하기 전에 대상 리소스에 대한 잠금을 제거해야 합니다. 참고: 고객이 "잠긴" 대상 리소스를 가리키는 공유 프라이빗 링크 리소스가 있는 검색 서비스를 삭제하려고 할 때도 이 문제가 발생할 수 있습니다.
삭제 작업 실패 드물게 비동기 Azure Resource Manager 삭제 작업이 실패할 수 있습니다. 이 작업이 실패하면 비동기 작업의 상태를 쿼리하면 고객에게 오류 메시지와 적절한 세부 정보가 표시됩니다. 나중에 작업을 다시 시도하거나 문제가 지속되면 Azure 지원에 문의하세요.
리소스가 "삭제 중" 상태로 중단됨 드물게 공유 프라이빗 링크 리소스가 검색 RP의 치명적인 오류로 인해 최대 8시간 동안 "삭제 중" 상태로 중단될 수 있습니다. 8시간 동안 기다린 후 리소스가 Failed 상태로 전환되면 요청을 다시 실행합니다.

다음 단계

공유 프라이빗 링크 리소스 및 이를 사용하여 보호되는 콘텐츠에 대해 보안 액세스를 하는 방법을 자세히 알아보세요.