Kubernetes 에이전트로 작업할 때는 다음 작업을 활용합니다.

에이전트 보기#

설치된 agentk 버전은 Agent 탭에 표시됩니다.

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

에이전트 목록을 보려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 에이전트 구성 파일이 있는 프로젝트를 찾습니다. 에이전트 구성 파일이 없는 프로젝트에서는 등록된 에이전트를 볼 수 없습니다.
2. Operate > Kubernetes clusters를 선택합니다.
3. 에이전트를 통해 GitLab에 연결된 클러스터를 보려면 Agent 탭을 선택합니다.

이 페이지에서 다음 정보를 확인할 수 있습니다.

• 현재 프로젝트에 등록된 모든 에이전트
• 연결 상태
• 클러스터에 설치된 agentk의 버전
• 각 에이전트 구성 파일의 경로

에이전트 구성#

에이전트를 구성하려면 다음 단계를 따릅니다.

• 설치 과정에서 선택적으로 만든 config.yaml 파일에 내용을 추가합니다.

에이전트 목록에서 에이전트 구성 파일을 빠르게 찾을 수 있습니다. Configuration 칼럼은 config.yaml 파일의 위치를 나타내거나 파일을 만드는 방법을 안내합니다.

에이전트 구성 파일은 다음과 같은 여러 에이전트 기능을 관리합니다.

• GitLab CI/CD 워크플로용. 에이전트가 프로젝트에 액세스하도록 승인한 다음 .gitlab-ci.yml 파일에 kubectl 명령을 추가해야 합니다.
• GitLab UI 또는 로컬 터미널에서 클러스터에 대한 사용자 액세스용.
• 운영 컨테이너 스캐닝 구성용.
• 원격 워크스페이스 구성용.

사용 가능한 구성 파일 필드#

에이전트의 구성 파일 형식은 소스 리포지터리에 프로토콜 버퍼 메시지로 정의되어 있습니다.

사용 가능한 모든 구성 파일 필드를 보려면 다음 단계를 따릅니다.

1. 에이전트 구성 파일 전체의 필드를 보려면 생성된 문서의 ConfigurationFile로 이동합니다.
2. 필드 구조에 대한 자세한 내용을 보려면 필드 유형을 선택합니다.

공유 에이전트 보기#

프로젝트가 소유한 에이전트 외에도 ci_access와 user_access 키워드로 공유된 에이전트를 볼 수 있습니다. 에이전트가 프로젝트에 공유되면 해당 프로젝트의 에이전트 탭에 자동으로 표시됩니다.

공유 에이전트 목록을 보려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
3. Agent 탭을 선택합니다.

공유 에이전트와 해당 클러스터 목록이 표시됩니다.

에이전트 활동 정보 보기#

활동 로그는 문제를 식별하고 문제 해결에 필요한 정보를 얻는 데 도움이 됩니다. 현재 날짜로부터 1주일 전까지의 이벤트를 볼 수 있습니다. 에이전트 활동을 보려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 에이전트 구성 파일이 있는 프로젝트를 찾습니다.
2. Operate > Kubernetes clusters를 선택합니다.
3. 활동을 확인하려는 에이전트를 선택합니다.

활동 목록에는 다음이 포함됩니다.

• 에이전트 등록 이벤트. 새 토큰이 생성된 시점입니다.
• 연결 이벤트. 에이전트가 클러스터에 성공적으로 연결된 시점입니다.

연결 상태는 에이전트를 처음 연결할 때 또는 1시간 넘게 활동이 없다가 다시 연결할 때 기록됩니다.

UI에 대한 의견은 이 에픽에서 확인하고 남길 수 있습니다.

에이전트 디버그#

에이전트의 클러스터 측 구성 요소(agentk)를 디버그하려면 다음 옵션 중 하나로 로그 수준을 설정합니다.

• error
• info
• debug

에이전트에는 두 가지 로거가 있습니다.

• 기본값이 info 인 범용 로거
• 기본값이 error 인 gRPC 로거

에이전트 구성 파일의 최상위 observability 섹션에서 로그 수준을 변경할 수 있습니다. 예를 들어 수준을 debug와 warn으로 설정합니다.

observability:
  logging:
    level: debug
    grpc_level: warn

grpc_level을 info 이하로 설정하면 gRPC 로그가 매우 많이 생성됩니다.

구성 변경 사항을 커밋하고 에이전트 서비스 로그를 확인합니다.

kubectl logs -f -l=app=gitlab-agent -n gitlab-agent

디버깅에 대한 자세한 내용은 문제 해결 문서를 참고합니다.

에이전트 토큰 초기화#

에이전트는 한 번에 활성 토큰을 두 개까지만 가질 수 있습니다.

다운타임 없이 에이전트 토큰을 초기화하려면 다음 단계를 따릅니다.

1. 새 토큰을 만듭니다.
   1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
   2. Operate > Kubernetes clusters를 선택합니다.
   3. 토큰을 만들려는 에이전트를 선택합니다.
   4. Access tokens 탭에서 Create token을 선택합니다.
   5. 토큰 이름과 설명(선택 사항)을 입력하고 Create token을 선택합니다.
2. 생성된 토큰을 안전하게 보관합니다.
3. 이 토큰으로 클러스터에 에이전트를 설치하고 에이전트를 다른 버전으로 업데이트합니다.
4. 더 이상 사용하지 않는 토큰을 삭제하려면 토큰 목록으로 돌아가 Revoke ([remove])를 선택합니다.

에이전트 제거#

GitLab UI 또는 GraphQL API를 사용해 에이전트를 제거할 수 있습니다. 에이전트와 연결된 토큰은 GitLab에서 제거되지만 Kubernetes 클러스터에는 아무런 변경이 적용되지 않습니다. 해당 리소스는 직접 정리해야 합니다.

GitLab UI를 통한 에이전트 제거#

UI에서 에이전트를 제거하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 에이전트 구성 파일이 있는 프로젝트를 찾습니다.
2. Operate > Kubernetes clusters를 선택합니다.
3. 표에서 해당 에이전트 행의 Options 칼럼에 있는 세로 줄임표 (⋮)를 선택합니다.
4. Delete agent를 선택합니다.

GitLab GraphQL API를 사용한 에이전트 제거#

1. 대화형 GraphQL 탐색기에서 쿼리를 실행해 <cluster-agent-token-id>를 가져옵니다.

   • GitLab.com에서는 https://gitlab.com/-/graphql-explorer로 이동해 GraphQL Explorer를 엽니다.
   • GitLab Self-Managed에서는 https://gitlab.example.com/-/graphql-explorer로 이동하며, gitlab.example.com은 인스턴스 URL로 바꿉니다.

   query{
     project(fullPath: "<full-path-to-agent-configuration-project>") {
       clusterAgent(name: "<agent-name>") {
         id
         tokens {
           edges {
             node {
               id
             }
           }
         }
       }
     }
   }
   

2. clusterAgentToken을 삭제해 GraphQL로 에이전트 레코드를 제거합니다.

   mutation deleteAgent {
     clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) {
       errors
     }
   }
   
   mutation deleteToken {
     clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) {
       errors
     }
   }
   

3. 제거가 성공했는지 확인합니다. Pod 로그 출력에 unauthenticated가 포함되어 있으면 에이전트가 성공적으로 제거된 것입니다.

   {
       "level": "warn",
       "time": "2021-04-29T23:44:07.598Z",
       "msg": "GetConfiguration.Recv failed",
       "error": "rpc error: code = Unauthenticated desc = unauthenticated"
   }
   

4. 클러스터에서 에이전트를 삭제합니다.

   kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml
   

관련 주제#

• 에이전트의 워크스페이스 관리