Azure Data Explorer에 대한 Azure DevOps 태스크

아티클
07/17/2024

Azure DevOps Services는 고성능 파이프라인, 무료 프라이빗 Git 리포지토리, 구성 가능한 Kanban 보드, 광범위한 자동화된 지속적인 테스트 기능과 같은 개발 협업 도구를 제공합니다. Azure Pipelines는 모든 언어, 플랫폼 및 클라우드에서 작동하는 고성능 파이프라인을 통해 코드를 배포하는 CI/CD를 관리할 수 있도록 지원하는 Azure DevOps 기능입니다. Azure Data Explorer - 파이프라인 도구는 릴리스 파이프라인을 만들고 데이터베이스 변경 내용을 Azure Data Explorer 데이터베이스에 배포할 수 있도록 지원하는 Azure Pipelines 태스크입니다. 이는 Visual Studio Marketplace에서 무료로 사용할 수 있습니다. 이 확장에는 다음과 같은 기본 작업이 포함됩니다.

Azure Data Explorer 명령 - Azure Data Explorer 클러스터에 대해 관리자 명령을 실행합니다.
Azure Data Explorer 쿼리 - Azure Data Explorer 클러스터에 대해 쿼리를 실행하고 결과를 구문 분석합니다.
Azure Data Explorer 쿼리 서버 게이트 - 쿼리 결과에 따라 게이트에 대한 에이전트 없는 태스크가 릴리스됩니다.

이 문서에서는 Azure Data Explorer - 파이프라인 도구 태스크를 사용하여 스키마 변경 내용을 데이터베이스에 배포하는 간단한 예에 대해 설명합니다. 전체 CI/CD 파이프라인은 Azure DevOps 설명서를 참조하세요.

사전 요구 사항

Azure 구독 평가판 Azure 계정을 만듭니다.
Azure Data Explorer 클러스터 및 데이터베이스. 클러스터 및 데이터베이스를 만듭니다.
Azure Data Explorer 클러스터 설정:
- Microsoft Entra 애플리케이션을 프로비전하여 Microsoft Entra 앱을 만듭니다.
- Azure Data Explorer 데이터베이스 권한을 관리하여 Azure Data Explorer 데이터베이스에서 Microsoft Entra App에 대한 액세스 권한을 부여합니다.
Azure DevOps 설정:
확장 설치:
- Azure DevOps 인스턴스 소유자인 경우 Marketplace에서 확장을 설치하고, 그렇지 않으면 Azure DevOps 인스턴스 소유자에게 문의하여 설치하도록 요청합니다.

릴리스할 콘텐츠 준비

다음 메서드를 사용하여 작업 내의 클러스터에 대해 관리자 명령을 실행할 수 있습니다.

명령 소스 제어 옵션을 보여 주는 스크린샷.

검색 패턴을 사용하여 로컬 에이전트 폴더에서 여러 명령 파일을 가져옵니다(빌드 원본 또는 릴리스 아티팩트).
인라인 명령을 작성합니다.
Git 원본 제어에서 명령 파일을 직접 가져올 파일 경로 지정합니다(권장)

다음 샘플 폴더(Functions, Policies, Tables)를 Git 리포지토리에 만듭니다. 샘플 리포지토리의 파일을 해당 폴더에 복사하고 변경 내용을 커밋합니다. 샘플 파일은 다음 워크플로를 실행하기 위해 제공되는 것입니다.

팁

사용자 고유의 워크플로를 만드는 경우 코드를 idempotent로 만드는 것이 좋습니다. 예를 들어 .create table 대신 .create-merge table을 사용하고, .create 함수 대신 .create-or-alter 함수를 사용합니다.

릴리스 파이프라인 만들기

Azure DevOps 조직에 로그인합니다.
왼쪽 메뉴에서 파이프라인>릴리스를 차례로 선택하고, 새 파이프라인을 선택합니다.
새 릴리스 파이프라인 창이 열립니다. 파이프라인 탭의 템플릿 선택 창에서 빈 작업을 선택합니다.
스테이지 단추를 선택합니다. 스테이지 창에서 스테이지 이름을 추가합니다. 저장을 선택하여 파이프라인을 저장합니다.
아티팩트 추가 단추를 선택합니다. 아티팩트 추가 창에서 코드가 있는 리포지토리를 선택하고 관련 정보를 입력한 다음 추가를 선택합니다. 저장을 선택하여 파이프라인을 저장합니다.
변수 탭에서 + 추가를 선택하여 작업에 사용되는 엔드포인트 URL에 대한 변수를 만듭니다. 엔드포인트의 이름 및 값을 적어 둡니다. 저장을 선택하여 파이프라인을 저장합니다.

엔드포인트 URL을 찾으려면 Azure Portal에서 Azure Data Explorer 클러스터의 개요 페이지로 이동하여 클러스터 URI를 복사합니다. 변수 URI를 다음 형식으로 생성합니다 https://<ClusterURI>?DatabaseName=<DBName>. 예를 들어 https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

폴더 배포 작업 만들기

파이프라인 탭에서 1개 작업, 0개 작업을 선택하여 작업을 추가합니다.

다음 단계를 반복하여 Tables, Functions 및 Policies 폴더에서 파일을 배포하는 명령 태스크를 만듭니다.

Azure Data Explorer 관리자 명령을 추가하는 방법을 보여 주는 스크린샷

태스크 탭에서 에이전트 작업별로 +를 선택하고, Azure Data Explorer를 검색합니다.
Azure Data Explorer 실행 명령에서 추가를 선택합니다.

Kusto 명령을 선택하고, 태스크를 다음 정보로 업데이트합니다.

표시 이름: 태스크의 이름입니다. 예를 들어 만드는 Deploy <FOLDER> 배포 작업의 폴더 이름은 어디에 <FOLDER> 있습니다.
파일 경로: 각 폴더에 대해 경로를 */<FOLDER>/*.csl로 지정합니다. 여기서 <FOLDER>는 태스크와 관련된 폴더입니다.
엔드포인트 URL: 이전 단계에서 만든 EndPoint URL 변수를 지정합니다.
서비스 엔드포인트 사용: 이 옵션을 선택합니다.

서비스 엔드포인트: Azure Data Explorer 서비스 연결 추가 창에서 다음 정보를 제공하여 기존 서비스 엔드포인트를 선택하거나 새 서비스 엔드포인트를 만듭니다(+ 새로 만들기).

설정	제안 값
인증 방법	FIC(페더레이션 ID 자격 증명)(권장) 또는 SPA(서비스 주체 인증)를 선택합니다.
연결 이름	이 서비스 엔드포인트를 식별할 이름을 입력합니다.
클러스터 URL	값은 Azure Portal에 있는 Azure Data Explorer 클러스터의 개요 섹션에서 확인할 수 있습니다.
서비스 주체 ID	Microsoft Entra 앱 ID를 입력합니다(필수 구성 요소로 생성됨).
서비스 주체 앱 키	Microsoft Entra 앱 키 입력(필수 구성 요소로 생성됨)
Microsoft Entra 테넌트 ID	Microsoft Entra 테넌트(예: microsoft.com 또는 contoso.com)를 입력합니다.

모든 파이프라인에서 이 연결을 사용하도록 허용합니다. 확인란을 선택한 다음, 확인을 선택합니다.

서비스 연결을 추가하는 방법을 보여 주는 스크린샷

저장을 선택한 다음, 태스크 탭에서 세 가지 태스크(테이블 배포, 함수 배포 및 정책 배포)가 있는지 확인합니다.

쿼리 태스크 만들기

필요한 경우 클러스터에 대해 쿼리를 실행하는 작업을 만듭니다. 빌드 또는 릴리스 파이프라인에서 쿼리를 실행하면 데이터 세트의 유효성을 검사하고 쿼리 결과에 따라 단계가 성공하거나 실패할 수 있습니다. 태스크 성공 조건은 쿼리에서 반환하는 항목에 따라 행 수 임계값 또는 단일 값을 기반으로 할 수 있습니다.

태스크 탭에서 에이전트 작업별로 +를 선택하고, Azure Data Explorer를 검색합니다.
Azure Data Explorer 쿼리 실행 아래에서 추가를 선택합니다.
Kusto 쿼리를 선택하고, 태스크를 다음 정보로 업데이트합니다.
- 표시 이름: 태스크의 이름입니다. 예를 들어 클러스터 쿼리입니다.
- 형식: 인라인을 선택합니다.
- 쿼리: 실행하려는 쿼리를 입력합니다.
- 엔드포인트 URL: 이전에 만든 EndPoint URL 변수를 지정합니다.
- 서비스 엔드포인트 사용: 이 옵션을 선택합니다.
- 서비스 엔드포인트: 서비스 엔드포인트를 선택합니다.
[태스크 결과] 아래에서 다음과 같이 쿼리 결과에 따라 태스크의 성공 조건을 선택합니다.
- 쿼리에서 행을 반환하는 경우 행 개수를 선택하고 필요한 조건을 제공합니다.
- 쿼리에서 값을 반환하는 경우 단일 값을 선택하고 예상 결과를 제공합니다.

쿼리 서버 게이트 태스크 만들기

필요한 경우 클러스터에 대해 쿼리를 실행하는 작업을 만들고 쿼리 결과 행 개수 보류 중인 릴리스 진행률을 제어합니다. 서버 쿼리 게이트 태스크는 에이전트 없는 작업입니다. 즉, 쿼리가 Azure DevOps 서버에서 직접 실행됩니다.

태스크 탭에서 에이전트 없는 작업별로 +를 선택하고, Azure Data Explorer를 검색합니다.
Azure Data Explorer 쿼리 서버 게이트 실행 아래에서 추가를 선택합니다.
Kusto 서버 쿼리 게이트를 선택한 다음, 서버 게이트 테스트를 선택합니다.
다음 정보를 제공하여 태스크를 구성합니다.
- 표시 이름: 게이트의 이름입니다.
- 서비스 엔드포인트: 서비스 엔드포인트를 선택합니다.
- 데이터베이스 이름: 데이터베이스 이름을 지정합니다.
- 형식: 인라인 쿼리를 선택합니다.
- 쿼리: 실행하려는 쿼리를 입력합니다.
- 최대 임계값: 쿼리의 성공 조건에 대한 최대 행 개수를 지정합니다.

참고 항목

릴리스를 실행하면 다음과 같은 결과가 표시됩니다.

쿼리 게이트 작업 결과 예제를 보여 주는 스크린샷.

릴리스 실행

+ 릴리스>릴리스 만들기를 차례로 선택하여 릴리스를 만듭니다.
로그 탭에서 배포 상태가 성공인지 확인합니다.

이제 사전 프로덕션에 배포하기 위한 릴리스 파이프라인 만들기가 완료되었습니다.

Azure Data Explorer DevOps 작업에 대한 키 없는 인증 지원

확장은 Azure Data Explorer 클러스터에 대한 키 없는 인증을 지원합니다. 키 없는 인증을 사용하면 키를 사용하지 않고 Azure Data Explorer 클러스터에 인증할 수 있으며 키를 사용하는 것보다 더 안전하고 관리하기 쉽습니다.

Azure Data Explorer 서비스 연결에서 FIC(페더레이션 ID 자격 증명) 인증 사용

DevOps 인스턴스에서 프로젝트 설정>서비스 연결 새 서비스 연결>>Azure Data Explorer로 이동합니다.
페더레이션 ID 자격 증명을 선택하고 클러스터 URL, 서비스 주체 ID, 테넌트 ID, 서비스 연결 이름을 입력한 다음 저장을 선택합니다.
Azure Portal에서 지정된 서비스 주체에 대한 Microsoft Entra 앱을 엽니다.
인증서 및 비밀에서 페더레이션된 자격 증명을 선택합니다.
자격 증명 추가를 선택한 다음, 페더레이션 자격 증명 시나리오의 경우 다른 발급자를 선택하고 다음 정보를 사용하여 설정을 작성합니다.
- 발급자: <https://vstoken.dev.azure.com/{System.CollectionId}> Azure DevOps 조직의 컬렉션 ID는 어디에 {System.CollectionId} 있나요? 컬렉션 ID는 다음과 같은 방법으로 찾을 수 있습니다.
  - Azure DevOps 클래식 릴리스 파이프라인에서 작업 초기화를 선택합니다. 컬렉션 ID가 로그에 표시됩니다.
- 주체 식별자: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> Azure DevOps 조직 이름은 {Project_Name} 프로젝트 {DevOps_Org_name} 이름이며 {Service_Connection_Name} 이전에 만든 서비스 연결 이름입니다.
  
  참고 항목
  
  서비스 연결 이름에 공백이 있는 경우 필드에 공백과 함께 사용할 수 있습니다. 예: sc://MyOrg/MyProject/My Service Connection
- 이름: 자격 증명의 이름을 입력합니다.
추가를 선택합니다.

ARM(Azure Resource Manager) 서비스 연결에서 페더레이션 ID 자격 증명 또는 관리 ID 사용

DevOps 인스턴스에서 Project Settings>Service 연결 새 서비스 연결>>Azure Resource Manager로 이동합니다.
인증 방법에서 워크로드 ID 페더레이션(자동)을 선택합니다. 또는 수동 워크로드 ID 페더레이션(수동) 옵션을 사용하여 워크로드 ID 페더레이션 세부 정보를 지정하거나 관리 ID 옵션을 사용할 수 있습니다 . Azure Resource Management를 사용하여 관리 ID를 설정하는 방법에 대한 자세한 내용은 ARM(Azure Resource Manager) 서비스 연결을 참조 하세요.
필요한 세부 정보를 입력하고 확인을 선택한 다음 저장을 선택합니다.

Yaml 파이프라인 구성

작업은 Azure DevOps 웹 UI 및 파이프라인 스키마 내의 Yaml 코드를 통해 구성할 수 있습니다.

관리자 명령 샘플 사용

steps:
- task: Azure-Kusto.PublishToADX.PublishToADX.PublishToADX@4
  displayName: '<Task Name>'
  inputs:
    targetType: 'inline'
    script: '<inline Script>'
    waitForOperation: true
    kustoUrls: '$(CONNECTIONSTRING):443?DatabaseName=""'
    authType: 'armserviceconn'
    connectedServiceARM: '<ARM Service Endpoint Name>'
    serialDelay: 1000
  continueOnError: true
  condition: ne(variables['ProductVersion'], '') ## Custom condition Sample

쿼리 샘플 사용량

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@4
  displayName: '<Task Display Name>'
  inputs:
    targetType: 'inline'
    script: |
     let badVer=
     RunnersLogs | where Timestamp > ago(30m)
         | where EventText startswith "$$runnerresult" and Source has "ShowDiagnostics"
         | extend State = extract(@"Status='(.*)', Duration.*",1, EventText)
         | where State == "Unhealthy"
         | extend Reason = extract(@'"NotHealthyReason":"(.*)","IsAttentionRequired.*',1, EventText)
         | extend Cluster = extract(@'Kusto.(Engine|DM|CM|ArmResourceProvider).(.*).ShowDiagnostics',2, Source)
         | where Reason != "Merge success rate past 60min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%, Merge success rate past 60min is < 90%"
         | where isnotempty(Cluster)
         | summarize max(Timestamp) by Cluster,Reason
         | order by  max_Timestamp desc
         | where Reason startswith "Differe"
         | summarize by Cluster
     ;
      DimClusters | where Cluster in (badVer)
     | summarize by Cluster , CmConnectionString , ServiceConnectionString ,DeploymentRing
     | extend ServiceConnectionString = strcat("#connect ", ServiceConnectionString)
     | where DeploymentRing == "$(DeploymentRing)"
    kustoUrls: 'https://<ClusterName>.kusto.windows.net?DatabaseName=<DataBaneName>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true

다음을 통해 공유