Azure Data Explorer에 대한 Azure DevOps 태스크

아티클
03/21/2023

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 앱에 대한 액세스 권한을 부여합니다.
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에 대한 변수를 만듭니다. 엔드포인트의 이름 및 값을 적어 둡니다. 저장을 선택하여 파이프라인을 저장합니다.

Endpoint_URL을 찾으려면 Azure Portal에 있는 Azure Data Explorer 클러스터의 개요 페이지에 포함되어 있는 Data Explorer 클러스터 URI를 확인합니다. URI를 https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName> 형식으로 구성합니다. 예를 들어 https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

폴더를 배포하는 태스크 만들기

파이프라인 탭에서 작업을 추가할 1개 작업, 0개 태스크를 클릭합니다.

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

관리 명령 추가

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

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

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

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

설정	제안 값
연결 이름	이 서비스 엔드포인트를 식별할 이름을 입력합니다.
클러스터 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 서버 쿼리 게이트를 선택한 다음, 서버 게이트 테스트를 선택합니다.
다음 정보를 제공하여 태스크를 구성합니다.
- 표시 이름: 게이트의 이름입니다.
- 서비스 엔드포인트: 서비스 엔드포인트를 선택합니다.
- 데이터베이스 이름: 데이터베이스 이름을 지정합니다.
- 형식: 인라인 쿼리를 선택합니다.
- 쿼리: 실행하려는 쿼리를 입력합니다.
- 최대 임계값: 쿼리의 성공 조건에 대한 최대 행 개수를 지정합니다.

참고

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

쿼리 게이트 태스크

릴리스 실행

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

이제 사전 프로덕션에 배포할 릴리스 파이프라인 만들기를 완료했습니다.

Yaml 파이프라인 구성

태스크는 Azure DevOps 웹 UI(위와 같음) 및 파이프라인 스키마 내의 Yaml 코드 모두를 통해 구성할 수 있습니다.

관리 명령 샘플 사용

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

쿼리 샘플 사용

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@1
  displayName: '<Task Display Name>'
  inputs:
    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>'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
  continueOnError: true