HCP Waypoint 에이전트 생성 및 관리

이 페이지는 액션을 실행하기 위한 HCP Waypoint 에이전트를 관리하는 방법을 설명해요. 플랫폼 엔지니어가 자주 수행하는 작업이에요. 추가 정보는 액션 문서를 참고해 주세요.

출처: 문서

본문

에이전트 그룹 만들기

에이전트 그룹을 만들려면 다음 단계를 완료해 주세요:

HCP 포털에 로그인하고 Services 메뉴에서 Waypoint를 클릭해요.
사이드바에서 Agents를 클릭한 다음 Create an agent group을 클릭해요.
에이전트 그룹의 Agent group name과 Description을 입력해요. 에이전트 그룹 이름은 특정 액션을 실행해야 하는 Waypoint 에이전트를 정의해요.
Create agent group을 클릭해요.

에이전트 그룹을 만든 후 HCP Waypoint는 예시 에이전트 구성 파일을 보여 줘요.

액션 만들기

액션을 만들려면 다음 단계를 완료해 주세요:

HCP 포털에 로그인하고 Services 메뉴에서 Waypoint를 클릭해요.
사이드바에서 Actions를 클릭한 다음 Create an action을 클릭해요.
액션의 Action name과 Description을 입력해요.
Action type 아래에서 Agent를 선택해요.
Action details 아래에서 agent group을 선택해요.
에이전트 구성의 action 블록 이름과 일치하는 action identifier를 입력해요.

에이전트 구성 파일 만들기

에이전트 구성 파일은 에이전트가 실행할 수 있는 하나 이상의 액션을 정의해요. 자세한 내용은 에이전트 구성 문법 문서를 참고해 주세요.

다음 예시는 redis-cli 명령을 직접 실행하는 clear-user-cache 액션을 정의해요. 또한 같은 디렉터리에 있는 populate_cache.sh라는 스크립트를 호출하는 populate-user-cache 액션도 만들어요. 이 액션은 HCP Waypoint에 정의된 count 변수를 스크립트로 전달해요.

agent.hcl

group "internal-us-west-2" {
  action "clear-user-cache" {
    run {
      command = "redis-cli KEYS \"user_cache_*\" | xargs redis-cli DEL"
    }
  }

  action "populate-user-cache" {
    run {
      command = "./populate_cache.sh ${var.count}"
    }
  }
}

액션에서 변수를 사용하는 방법은 액션 변수 참조 문서를 참고해 주세요.

HCP CLI 설치하기

HCP Waypoint 에이전트는 HCP CLI의 일부로 제공돼요. CLI 설치는 HCP CLI 설치 문서를 참고해 주세요. 공식 HCP 컨테이너 이미지를 사용해 Docker, Kubernetes, Nomad 또는 기타 컨테이너 오케스트레이터에서 에이전트를 실행할 수도 있어요.

에이전트 인증 및 실행하기

참고: HashiCorp Cloud Platform(HCP) 유럽 조직은 아직 HCP CLI를 지원하지 않아요. 자세한 내용은 HCP 유럽을 참고해 주세요.

각 HCP Waypoint 에이전트를 실행하려면 먼저 에이전트를 HCP로 인증해야 해요. 에이전트를 HCP로 인증하는 방법은 다음과 같아요:

hcp auth login 명령으로 대화형 인증. 자세한 내용은 HCP CLI 문서를 참고해 주세요. HCP CLI가 제공하는 링크로 인증한 후 hcp waypoint agent run 명령을 사용해 에이전트를 시작하고 에이전트 구성 파일 경로를 전달해요:

$ hcp waypoint agent run --config=agent.hcl

환경 변수를 사용해 서비스 주체로 비대화형 인증.

$ HCP_CLIENT_ID=<client-id> HCP_CLIENT_SECRET=<client-secret> hcp waypoint agent run --config=agent.hcl

자격 증명 파일로 비대화형 인증. 먼저 서비스 주체를 만든 다음, 서비스 주체 키를 만들어 자격 증명 파일을 만들 수 있어요. 먼저 새 서비스 주체를 만들어요:

$ hcp iam service-principals create example-sp --project="<project-id>"
Resource Name: iam/project/12345678-1234-1234-1234-123456789010/service-principal/example-sp
Resource ID:   example-sp-12345678-1234-1234-1234-123456789010
Display Name:  example-sp
Created At:    2025-05-23T19:15:13.738Z

Resource ID 필드를 기록해 두거나, hcp iam service-principals read 명령으로 가져와요:

$ hcp iam service-principals read example-sp --format=json | jq -r ".id"

리소스 ID를 사용해 프로젝트의 서비스 주체에 roles/admin 역할을 부여해요:

$ hcp projects iam add-binding --member=example-sp-12345678-1234-1234-1234-123456789010 --role=roles/admin

다음으로 서비스 주체 키를 만들고 --output-cred-file을 포함해 자격 증명 파일을 만들어요:

$ hcp iam service-principals keys create example-sp --output-cred-file=cred_file.json

마지막으로 HCP Waypoint 에이전트를 시작하고 HCP_CRED_FILE 환경 변수로 자격 증명 파일 경로를 전달해요:

$ HCP_CRED_FILE=cred_file.json hcp waypoint agent run --config=agent.hcl

HCP Waypoint 에이전트 생성 및 관리