다음을 통해 공유

Azure AI 검색의 공유 프라이빗 링크 문제 해결

  • 아티클

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

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

공유 프라이빗 링크 리소스 만들기의 단계

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

요청 유효성 검사 실패

  • 지원되지 않는 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 형식 유효성 검사: groupId와 마찬가지로 Azure AI 검색은 “올바른” 리소스 종류가 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 검색 서비스 제한 페이지의 공유 프라이빗 링크 리소스 제한 섹션에서 설명되어 있습니다.

배포 실패

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

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

배포 실패 사유 설명 해결 방법
"LinkedAuthorizationFailed" 오류 메시지는 클라이언트가 검색 서비스에서 공유 프라이빗 링크를 만들 수 있는 권한이 있지만 연결된 범위에서 'privateEndpointConnectionApproval/action' 작업을 수행할 수 있는 권한이 없음을 나타냅니다. 요청에서 프라이빗 링크 ID를 다시 확인하여 URI에 오류나 누락이 없는지 확인합니다. Azure AI 검색과 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 검색은 공유 프라이빗 링크 리소스에 대한 groupId로 “Sql”만 지원합니다. “Sql” 유형의 공유 프라이빗 링크가 비 Sql 데이터베이스 계정을 가리키는 privateLinkResourceId에 대해 만들어진 경우 groupId 불일치로 인해 Azure Resource Manager 배포가 실패합니다. Azure Cosmos DB 계정의 Azure 리소스 ID가 사용 중인 API 유형을 확인하기에 충분하지 않습니다. Azure AI 검색이 프라이빗 엔드포인트를 만들려고 시도하지만, 이는 Azure Cosmos DB에 의해 거부됩니다. 지정된 Azure Cosmos DB 리소스의 privateLinkResourceId가 “Sql” API 유형의 데이터베이스 계정에 대한 것인지 확인해야 합니다.
대상 리소스를 찾을 수 없음 privateLinkResourceId에 지정된 대상 리소스의 존재는 Azure Resource Manager 배포 실행 도중에만 확인됩니다. 대상 리소스를 더 이상 사용할 수 없는 경우 배포에 실패합니다. 대상 리소스가 지정된 구독 및 리소스 그룹에 있고 이동/삭제되지 않았는지 확인해야 합니다.
임시/기타 오류 인프라 중단이 발생하거나 예기치 않은 다른 이유로 인해 Azure Resource Manager 배포가 실패할 수 있습니다. 이는 드물게 발생하며 일반적으로 임시 상태를 나타냅니다. 나중에 이 리소스 만들기를 다시 시도합니다. 문제가 계속되면 Azure 지원에 문의하세요.

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

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

Search Service 네트워크 연결 변경이 "업데이트 중" 상태에서 중단됨

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

공용 네트워크 액세스를 사용 안 함으로 변경하는 스크린샷.

연결 변경 작업에 상당한 시간이 걸리는 경우 몇 시간 동안 기다리세요. 연결 변경 작업에는 예상보다 오래 걸릴 수 있는 DNS 레코드 업데이트와 같은 작업이 포함됩니다.

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

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

드물게 Azure AI 검색에서 공유 프라이빗 링크 리소스의 상태가 종료 상태(Succeeded 또는 Failed)로 올바르게 표시되지 않을 수 있습니다. 이는 일반적으로 예기치 않은 오류로 인해 발생합니다. 공유 프라이빗 링크 리소스가 최종이 아닌 상태로 몇 시간 이상 “지속”되면 자동으로 Failed 상태로 전환됩니다.

공유 프라이빗 링크 리소스가 최종 상태로 전환되지 않은 것이 확인되면 Failed 상태가 될 때까지 몇 시간 동안 기다린 다음, 삭제하고 다시 만들 수 있습니다. 또는 기다리는 대신 다른 이름(다른 매개 변수는 동일하게 유지)으로 된 공유 프라이빗 링크 리소스를 만들 수 있습니다.

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

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

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

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

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

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

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

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

공유 프라이빗 링크 리소스 삭제의 단계

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

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

다음 단계

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