배포 그룹에 대한 에이전트 프로비저닝

아티클
11/21/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

배포 그룹은 Azure Pipelines의 클래식 릴리스 파이프라인에 대한 배포 대상 컴퓨터의 논리적 그룹입니다. 배포 그룹의 모든 대상 서버에는 배포 에이전트가 설치되어 있어야 합니다. 이 문서에서는 배포 그룹의 각 물리적 또는 가상 머신(VM)에 배포 에이전트를 설치하고 프로비전하는 방법을 설명합니다.

다음 방법 중 하나로 대상 컴퓨터에 에이전트를 설치할 수 있습니다.

배포 그룹을 만들 때 생성하는 스크립트를 실행합니다.
VM에 Azure Pipelines 에이전트 Azure VM 확장을 설치합니다.
릴리스 파이프라인에서 AzureResourceGroupDeploymentV2 작업을 사용하여 배포 그룹을 만들고 에이전트를 동적으로 프로비전합니다.

다음 섹션에서는 각 메서드를 구현하는 단계를 제공합니다.

필수 조건

Azure DevOps 조직 및 프로젝트. 조직 또는 프로젝트를 만들려면 새 조직 만들기 또는 Azure DevOps에서 프로젝트 만들기를 참조하세요.
적절한 권한이 있는 하나 이상의 Windows 또는 Linux 배포 대상 컴퓨터에 액세스합니다.
Azure Pipelines 에이전트 설치 방법의 경우 Azure VM을 만들고 관리할 수 있는 권한이 있는 Azure 계정 및 구독입니다. Azure 계정이 없는 경우 체험 계정에 등록합니다.

대상 서버에서 설치 스크립트 실행

배포 그룹을 만들 때 각 대상 컴퓨터에서 실행하여 서버를 등록하고 에이전트를 설치할 수 있는 스크립트가 생성됩니다. 생성된 등록 스크립트를 사용하여 에이전트를 설치하려면:

Azure DevOps 프로젝트에서 파이프라인>배포 그룹을 선택합니다.
배포 그룹 화면에서 새로 만들기를 선택하거나, 이 배포 그룹이 프로젝트의 첫 번째 배포 그룹인 경우 배포 그룹 추가를 선택합니다.
배포 그룹 이름 및 선택적 설명을 입력한 다음 만들기를 선택합니다.
다음 화면에서 등록할 대상 유형에 대해 Windows 또는 Linux를 선택합니다. 등록 스크립트가 생성됩니다.
인증을 위해 스크립트에서 개인용 액세스 토큰 사용을 선택합니다. 자세한 내용은 개인용 액세스 토큰 사용을 참조하세요.
클립보드에 스크립트 복사를 선택합니다.
각 대상 컴퓨터에서 관리 권한이 있는 계정을 사용하여 로그인합니다.
복사한 스크립트를 실행하여 컴퓨터를 등록하고 에이전트를 설치합니다. Windows 컴퓨터의 경우 관리자 권한 PowerShell 명령 프롬프트를 사용합니다.

스크립트가 실행됨에 따라 다음을 수행합니다.
- 배포 그룹 작업의 특정 서버에 배포를 제한할 수 있는 태그를 할당하려면 태그를 입력하라는 메시지가 표시되면 Y를 입력한 다음 이 VM에 대한 태그 또는 태그를 입력합니다.
  
  태그는 각각 256자로 제한되며 대/소문자를 구분하지 않으며 사용할 수 있는 태그 수에는 제한이 없습니다.
- 사용자 계정에 대한 메시지가 표시되면 기본값을 적용합니다.
참고 항목

보안 채널을 만들 수 없는 스크립트를 실행할 때 오류가 발생하면 관리자 PowerShell 프롬프트에서 다음 명령을 실행합니다.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

각 대상 서버를 설정한 후 스크립트는 메시지를 Service vstsagent.{organization-name}.{computer-name} started successfully반환해야 합니다.

Azure Pipelines 배포 그룹 페이지의 대상 탭에서 에이전트가 실행 중인지 확인할 수 있습니다. 필요한 경우 페이지를 새로 고칩니다.

Azure Pipelines 에이전트 Azure VM 확장 설치

Azure VM을 배포 머신으로 사용하는 경우 각 VM에 Azure Pipelines 에이전트 확장을 설치할 수 있습니다. 확장은 Azure DevOps 프로젝트에서 지정된 배포 그룹에 에이전트를 자동으로 등록합니다.

확장을 사용하여 에이전트를 설치하려면 먼저 배포 그룹을 만듭니다.

Azure DevOps 프로젝트에서 파이프라인>배포 그룹을 선택합니다.
배포 그룹 화면에서 새로 만들기를 선택하거나, 이 배포 그룹이 프로젝트의 첫 번째 배포 그룹인 경우 배포 그룹 추가를 선택합니다.
배포 그룹 이름 및 선택적 설명을 입력한 다음 만들기를 선택합니다.

Azure Portal에서 각 대상 VM에 Azure Pipelines 에이전트 확장을 설치합니다.

VM 페이지의 왼쪽 탐색 영역에서 설정>확장 + 애플리케이션을 선택합니다.
확장 탭에서 추가를 선택합니다.
확장 설치 페이지에서 Azure Pipelines 에이전트를 검색하여 선택한 다음, 다음을 선택합니다.
Azure Pipelines 에이전트 확장 구성 화면에서 다음 정보를 지정합니다.
- Azure DevOps 조직 URL: Azure DevOps 조직의 URL을 입력합니다(예: https://dev.azure.com/contoso.).
- 팀 프로젝트: 프로젝트 이름(예: myProject)을 입력합니다.
- 배포 그룹: 만든 배포 그룹의 이름을 입력합니다.
- 에이전트 이름: 필요에 따라 에이전트의 이름을 입력합니다. 아무것도 입력하지 않으면 에이전트 이름이 VM 이름에 추가됩니다 -DG.
- 개인 액세스 토큰: Azure Pipelines 인증에 사용할 PAT(개인 액세스 토큰)를 입력합니다.
- 태그: 필요에 따라 에이전트에서 구성할 쉼표로 구분된 태그 목록을 지정합니다. 태그는 각각 256자로 제한되며 대/소문자를 구분하지 않으며 사용할 수 있는 태그 수에는 제한이 없습니다.
검토 + 만들기를 선택하고 유효성 검사를 통과하면 만들기를 선택합니다.

AzureResourceGroupDeploymentV2 작업 사용

AzureResourceGroupDeploymentV2 작업을 사용하여 ARM(Azure Resource Manager) 템플릿을 배포할 수 있습니다. 템플릿은 Azure VM을 만드는 동안 Azure Pipelines 에이전트 확장을 설치하거나 VM을 만든 후 확장을 적용하도록 리소스 그룹을 업데이트할 수 있습니다.

또는 AzureResourceGroupDeployment 작업의 고급 배포 옵션을 사용하여 에이전트를 배포할 수 있습니다.

배포 그룹 만들기

먼저 배포 그룹을 만듭니다.

Azure DevOps 프로젝트에서 파이프라인>배포 그룹을 선택합니다.
배포 그룹 화면에서 새로 만들기를 선택하거나, 이 배포 그룹이 프로젝트의 첫 번째 배포 그룹인 경우 배포 그룹 추가를 선택합니다.
배포 그룹 이름 및 선택적 설명을 입력한 다음 만들기를 선택합니다.

ARM 템플릿을 사용하여 에이전트 설치

ARM 템플릿은 선언적으로 Azure 리소스 집합을 정의하는 JSON 파일입니다. Azure는 템플릿을 자동으로 읽고 리소스를 프로비전합니다. 단일 템플릿에서 여러 서비스 및 해당 종속성을 배포할 수 있습니다.

ARM 템플릿을 사용하여 배포 에이전트를 등록하고 설치하려면 다음 코드와 같이 리소스 아래에 Microsoft.Compute/virtualMachine 리소스 요소를 추가합니다.

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|2|3",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

참고 항목

Linux VM의 경우 코드의 type 매개 properties 변수는 다음과 여야 TeamServicesAgentLinux합니다.

참고 항목

Azure DevOps Server 2022.1 이상에서는 허용되는 값 AgentMajorVersion 이 있습니다 auto|2|3. Azure DevOps Server 2022.0 이하에서는 허용되는 값 AgentMajorVersion 이 있습니다 auto|N.

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|N",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

위의 코드에서

VSTSAccountName 은 사용하는 데 필요한 Azure Pipelines 조직입니다. 예를 들어 Azure DevOps URL이면 지정하기만 하면 됩니다 https://dev.azure.com/contoso. contoso
TeamProject 는 배포 그룹이 정의된 필수 프로젝트입니다.
DeploymentGroup 는 에이전트를 등록하는 데 필요한 배포 그룹입니다.
AgentName 는 선택적 에이전트 이름입니다. 지정하지 않으면 에이전트에 추가된 VM 이름이 -DG 지정됩니다.
Tags 는 에이전트에서 설정할 쉼표로 구분된 선택적 태그 목록입니다. 태그는 각각 256자로 제한되며 대/소문자를 구분하지 않으며 사용할 수 있는 태그 수에는 제한이 없습니다.
PATToken 는 에이전트를 다운로드하고 구성하기 위해 Azure Pipelines에 인증하는 데 필요한 PAT입니다.

ARM 템플릿에 대한 자세한 내용은 Azure Resource Manager 템플릿에서 리소스 정의를 참조 하세요.

릴리스 파이프라인에서 템플릿 사용

릴리스 파이프라인 만들기:

왼쪽 메뉴에서 파이프라인>릴리스를 선택한 다음 새 릴리스 파이프라인을>선택합니다.
Azure Pipelines의 릴리스 탭에서 ARM 템플릿 배포 작업이 포함된 스테이지를 사용하여 릴리스 파이프라인을 만듭니다.
이 템플릿은 작업의 버전 2를 사용하므로 Azure 리소스 그룹 배포 설정 화면에서 작업 버전을 3.*에서 2.*로 변경합니다.
작업에 필요한 매개 변수(예: Azure 구독, 리소스 그룹 이름, 위치, 템플릿 정보 및 수행할 작업)를 제공합니다.
릴리스 파이프라인을 저장하고 파이프라인에서 릴리스를 만들어 에이전트를 설치합니다.

고급 배포 옵션을 사용하여 에이전트 설치

또는 고급 배포 옵션을 사용하여 에이전트를 설치할 수 있습니다. 위의 단계를 수행하지만 Azure 리소스 그룹 배포 설정 화면에서 가상 머신에 대한 고급 배포 옵션을 확장합니다.

필수 구성 요소 사용에서 배포 그룹 에이전트를 사용하여 구성을 선택합니다.
다음 필수 매개 변수 및 설정을 제공합니다.
- Azure Pipelines 서비스 연결: 대상을 가리키는 기존 서비스 연결을 선택합니다.
  
  기존 서비스 연결이 없는 경우 새로 만들기를 선택하고 새로 만듭니다. 자세한 내용은 서비스 연결 만들기를 참조하세요. 배포 그룹으로 제한된 범위의 PAT를 사용하도록 서비스 연결을 구성합니다.
- 팀 프로젝트: 배포 그룹이 포함된 프로젝트를 선택합니다.
- 배포 그룹: 에이전트를 등록할 배포 그룹을 선택합니다.
- 에이전트에 Azure VM 태그 복사를 선택하여 Azure VM에 이미 구성된 태그를 해당 배포 그룹 에이전트에 복사합니다.
  
  기본적으로 모든 Azure 태그는 예를 들어 Role: Web형식을 Key: Value 사용하여 복사됩니다.
파이프라인을 저장하고 에이전트를 설치하는 릴리스를 만듭니다.

확장 문제 해결

Azure Pipelines 에이전트 확장에는 몇 가지 알려진 문제가 있습니다.

상태 파일이 너무 큽

이 문제는 Windows VM에서 발생할 수 있습니다. 상태 파일에는 확장의 현재 상태를 설명하는 JSON 개체가 포함되어 있습니다. 개체는 지금까지 수행된 작업을 나열하는 자리 표시자입니다.

Azure는 이 상태 파일을 읽고 상태 개체를 API 요청에 대한 응답으로 전달합니다. 파일의 최대 크기는 허용됩니다. 크기가 최대값을 초과하면 Azure에서 완전히 읽을 수 없으며 상태에 대한 오류가 발생합니다.

확장이 처음에 설치될 수 있지만 머신이 다시 부팅될 때마다 확장은 상태 파일에 추가되는 일부 작업을 수행합니다. 컴퓨터가 여러 번 다시 부팅되면 상태 파일 크기가 임계값을 초과하여 오류가 Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes발생할 수 있습니다. 확장 설치에 성공하더라도 이 오류는 확장의 실제 상태를 숨깁니다.

이 컴퓨터 다시 부팅 문제는 Windows 확장 및 1.21.0.1 Linux 확장 버전 1.27.0.2 부터 해결되었습니다. 이제 다시 부팅하면 상태 파일에 아무 것도 추가하지 않습니다. 그러나 이전 버전의 확장에서 이 문제가 있었고 확장이 고정 버전으로 자동 업데이트된 경우 문제가 지속될 수 있습니다. 최신 버전의 확장은 여전히 이전 상태 파일에서 작동할 수 있습니다.

부 버전 자동 업데이트 기능을 해제하는 플래그와 함께 이전 버전의 확장을 사용하거나 이전 버전에서 고정 버전으로 큰 상태 파일이 전달된 경우 이 문제가 발생할 수 있습니다. 그렇다면 확장을 제거하고 다시 설치하여 문제를 해결할 수 있습니다. 확장을 제거하면 전체 확장 디렉터리가 정리되고 최신 버전의 새 설치를 위한 새 상태 파일이 만들어집니다.

사용자 지정 데이터 문제

Python 2는 더 이상 사용되지 않으며 Azure Pipelines 에이전트 확장은 Python 3에서 작동합니다. 기본적으로 Python 3이 설치되지 않은 OS 버전을 계속 사용하는 경우 확장을 실행하려면 VM에 Python 3을 설치하거나 기본적으로 Python 3이 설치된 OS 버전으로 전환해야 합니다. 그렇지 않으면 OS 버전을 전환할 때 VM의 사용자 지정 데이터 위치에 대한 혼동이 있을 수 있습니다.

Linux VM에서 사용자 지정 데이터는 이전 에이전트 버전의 경우 /var/lib/waagent/ovf-env.xml, 최신 버전의 경우 /var/lib/waagent/CustomData로 복사됩니다. 이러한 두 경로 중 하나만 하드 코딩하는 경우 다른 경로가 있지만 경로 중 하나가 새 OS 버전에 없기 때문에 OS 버전을 전환할 때 문제가 발생할 수 있습니다. VM 프로비저닝이 중단되지 않도록 하려면 템플릿에서 두 경로를 모두 사용하여 실패할 경우 다른 경로가 성공하도록 하는 것이 좋습니다.

도움말 및 지원

문제 해결 팁을 살펴보세요.
Stack Overflow에 대한 조언을 얻을 수 있습니다.
Azure DevOps 개발자 커뮤니티에서 질문을 게시하거나, 답변을 검색하거나, 기능을 제안합니다.
Azure DevOps에 대한 지원을 받 습니다.

다음을 통해 공유

배포 그룹에 대한 에이전트 프로비저닝

필수 조건

대상 서버에서 설치 스크립트 실행

Azure Pipelines 에이전트 Azure VM 확장 설치

AzureResourceGroupDeploymentV2 작업 사용

배포 그룹 만들기

ARM 템플릿을 사용하여 에이전트 설치

릴리스 파이프라인에서 템플릿 사용

고급 배포 옵션을 사용하여 에이전트 설치

확장 문제 해결

상태 파일이 너무 큽

사용자 지정 데이터 문제

도움말 및 지원

피드백

추가 리소스

다음을 통해 공유

배포 그룹에 대한 에이전트 프로비저닝

필수 조건

대상 서버에서 설치 스크립트 실행

Azure Pipelines 에이전트 Azure VM 확장 설치

AzureResourceGroupDeploymentV2 작업 사용

배포 그룹 만들기

ARM 템플릿을 사용하여 에이전트 설치

릴리스 파이프라인에서 템플릿 사용

고급 배포 옵션을 사용하여 에이전트 설치

확장 문제 해결

상태 파일이 너무 큽

사용자 지정 데이터 문제

도움말 및 지원

관련 콘텐츠

피드백

추가 리소스