worker 배포하기

worker 배포하기 (Deploy workers)

셀프 매니지드 Boundary 배포에는 타깃을 담고 있는 각 네트워크 경계에 worker가 최소 하나 있어야 해요. 각 worker는 proxy 리스너, 업스트림, 그리고 디스크에 있는 자격 증명을 암호화하는 KMS 키를 정의하는 구성 파일로 boundary server 명령을 실행합니다.

worker를 배포하기 전에 다음 단계를 완료했어야 해요:

• 최소 세 개의 컨트롤러 노드에 Boundary 설치
• 세 개의 네트워크 경계 준비(또는 이미 보유): Public/DMZ 네트워크, Intermediate 네트워크, Private 네트워크
• 각 네트워크 경계에 Boundary 바이너리가 설치된 worker용 가상 머신 세 대 준비

다음 구성 파일들에는 공통 구성 컴포넌트와, Boundary worker가 수행하는 역할에 따라 달라지는 고유 컴포넌트가 있습니다. 각 고유 네트워크 경계의 worker 하나당 파일 하나씩, 총 세 개의 파일이 있어요. 또한 Boundary는 멀티홉 구성을 지원해서 worker가 ingress worker, ingress/egress worker, egress worker 중 하나의 역할을 할 수 있습니다.

출처: HashiCorp Boundary docs

본문

환경 파일 준비

HashiCorp는 구성 파일에 env:// 또는 file:// 표기법을 사용해서 비밀 구성 컴포넌트를 Boundary worker 바이너리에 안전하게 제공할 것을 권장합니다.

다음 구성 예시는 env://를 사용해서 AWS KMS 구성 항목을 보호해요.

패키지 관리자로 Boundary 바이너리를 설치하면 /etc/boundary.d/boundary.env에 환경 파일을 구성하는 유닛 파일이 포함됩니다. 이 파일로 Boundary worker 구성 파일의 민감한 값을 설정할 수 있어요.

다음 파일은 이 환경 파일을 구성하는 방법의 예시입니다:

/etc/boundary.d/boundary.env:

AWS_ACCESS_KEY_ID=«redacted:AKIA…»
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

위 예시에서 Boundary가 서로 다른 KMS 키에 접근하는 데 사용할 수 있도록, 주어진 AWS_ACCESS_KEY와 AWS_SECRET_ACCESS_KEY에 대한 적절한 IAM(Identity and Access Management) 역할과 권한이 갖춰져 있어야 합니다.

worker KMS 키 준비

worker-auth storage KMS 키는 worker가 인증 키를 암호화된 상태로 저장하는 데 사용해요. 이것은 controller-led나 worker-led 등록 방식을 사용하는 worker에 권장됩니다. 지정하지 않으면 인증 키가 디스크에 암호화되지 않고 저장됩니다.

선택적으로, KMS 인증 기반의 Boundary worker를 배포한다면 worker를 컨트롤러에 인증하기 위한 추가 KMS 키를 생성해야 합니다.

HashiCorp는 Boundary worker를 배포하는 클라우드 프로바이더의 KMS(키 관리 시스템)를 사용할 것을 강력히 권장합니다. Boundary worker는 클라우드 프로바이더의 KMS와 상호작용할 수 있는 올바른 수준의 권한을 가져야 해요. 자세한 내용은 클라우드 프로바이더 문서를 참고하세요.

worker 구성 만들기

선택한 클라우드 프로바이더에서 필수 키(들)를 만든 다음 worker 구성을 시작할 수 있어요.

다음 구성 예시들은 모두 worker-led 인증 흐름을 사용합니다. Boundary worker의 KMS 인증 구성에 대한 자세한 내용은 외부 KMS 등록 문서를 참고하세요.

ingress, intermediate, egress worker를 구성해서 멀티홉 worker 기능을 활용할 수 있어요. 'ingress', 'intermediate', 'egress'는 각 worker가 리소스와 상호작용하는 방식을 일반적으로 설명하는 말이며, 하나의 worker가 한 번에 두 개 이상의 역할을 할 수도 있습니다. 자세한 내용은 멀티홉 세션을 참고하세요.

아래 단계를 완료해서 worker를 구성하세요.

worker를 세션 녹화를 지원하도록 구성한다면, auth_storage_path 값을 추가하고 스토리지 백엔드를 구성해야 해요. 자세한 내용은 저장용 worker 구성 문서를 참고하세요.

ingress, intermediate, egress worker

'ingress', 'intermediate', 'egress'는 각 worker가 리소스와 상호작용하는 방식을 일반적으로 설명하는 말이에요. 하나의 worker가 한 번에 두 개 이상의 역할을 할 수 있다는 점을 기억하세요. 자세한 내용은 멀티홉 세션을 참고하세요.

Ingress worker 구성

ingress-worker.hcl 파일을 관련 구성 정보와 함께 만드세요:

/etc/boundary.d/ingress-worker.hcl:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<controller_lb_address>:9201"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker1", "upstream"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "ingress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey3"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Intermediate worker 구성

intermediate-worker.hcl 파일을 관련 구성 정보와 함께 만드세요:

/etc/boundary.d/intermediate-worker.hcl:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<ingress_worker_address>:9202"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker2", "intermediate"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "intermediate-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey4"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Egress worker 구성

egress-worker.hcl 파일을 관련 구성 정보와 함께 만드세요:

/etc/boundary.d/egress-worker.hcl:

# disable memory from being swapped to disk
disable_mlock = true

# listener denoting this is a worker proxy
listener "tcp" {
  address = "0.0.0.0:9202"
  purpose = "proxy"
}

# worker block for configuring the specifics of the
# worker service
worker {
  public_addr = "<worker_public_addr>"
  initial_upstreams = ["<intermediate_worker_address>:9202"]
  auth_storage_path = "/var/lib/boundary"
  tags {
    type = ["worker3", "egress"]
  }
}

# Events (logging) configuration. This
# configures logging for ALL events to both
# stderr and a file at /var/log/boundary/<boundary_use>.log
events {
  audit_enabled       = true
  sysevents_enabled   = true
  observations_enable = true
  sink "stderr" {
    name = "all-events"
    description = "All events sent to stderr"
    event_types = ["*"]
    format = "cloudevents-json"
  }
  sink {
    name = "file-sink"
    description = "All events sent to a file"
    event_types = ["*"]
    format = "cloudevents-json"
    file {
      path = "/var/log/boundary"
      file_name = "egress-worker.log"
    }
    audit_config {
      audit_filter_overrides {
        sensitive = "redact"
        secret    = "redact"
      }
    }
  }
}

# kms block for encrypting the authentication PKI material
kms "awskms" {
  purpose    = "worker-auth-storage"
  region     = "us-east-1"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey5"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

위 예시에서 사용된 파라미터에 대한 설명은 컨트롤러 구성의 파라미터 표를 참고하세요(disable_mlock, listener, worker, events, kms). 서로 다른 클라우드 kms 블록의 구성 정보는 다음 링크를 참고하세요: AWS, Azure, GCP, OCI, AliCloud, Vault Transit.

추가 최상위 구성 옵션과 worker별 옵션 문서도 참고하세요.

Boundary 서비스 시작

각 Boundary worker 노드에 구성 파일이 있으면 systemd로 각 노드에서 바이너리를 활성화하고 시작할 수 있어요.

각 worker 노드에서 서비스를 활성화·시작하려면 다음 명령을 실행하세요:

$ sudo systemctl enable boundary

$ sudo systemctl start boundary

$ sudo systemctl status boundary

systemd 수동 구성 (선택)

Boundary를 수동으로 설치했다면, systemd 아래에서 Boundary를 서비스로 실행하도록 구성할 수 있어요.

시작하기 전에 디스크에서 worker 구성 파일의 위치를 확인하세요(예: 이 페이지 예시의 /etc/boundary.d/egress-worker.hcl). 유닛 파일을 설정할 때 .hcl 구성 파일의 위치를 참조합니다.

HashiCorp는 Boundary를 비루트 사용자로 실행하고, 그 사용자로 systemd 아래의 Boundary 프로세스를 관리할 것을 권장합니다.

worker를 systemd 서비스로 실행하려면 다음 단계를 완료하세요:

$ sudo adduser --system --group boundary || true ;
$ sudo chown boundary:boundary /etc/boundary.d/egress-worker.hcl ;
$ sudo chown boundary:boundary /usr/local/bin/boundary

/etc/systemd/system/boundary-worker.service 유닛 파일:

[Unit]
Description="HashiCorp Boundary worker"
Documentation=https://developer.hashicorp.com/boundary/docs
StartLimitIntervalSec=60
StartLimitBurst=3

[Service]
EnvironmentFile=-/etc/boundary.d/boundary.env
User=boundary
Group=boundary
ProtectSystem=full
ProtectHome=read-only
ExecStart=/usr/bin/boundary server -config=/etc/boundary.d/egress-worker.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

유닛 파일 권한을 설정하고 서비스를 활성화·시작합니다:

$ sudo chmod 664 /etc/systemd/system/boundary-worker.service

$ sudo systemctl daemon-reload ;
$ sudo systemctl enable boundary-worker ;
$ sudo systemctl start boundary-worker

$ sudo systemctl status boundary-worker

worker-led 등록 방식을 사용한다면, worker는 등록 요청을 auth_storage_path 디렉터리의 auth_request_token 파일에 씁니다. 그 값을 서비스 로그에서도 찾을 수 있어요:

$ sudo journalctl -u boundary-worker | grep "Worker Auth Registration Request"

worker 등록

위에서 설명한 worker-led 방식으로 worker를 배포했다면, Boundary worker를 컨트롤러에 등록해야 합니다.

CLI로 worker를 등록하려면 다음 단계를 완료하세요:

Boundary 주소를 설정합니다:

$ export BOUNDARY_ADDR="https://boundary.example.com:9200"

인증합니다:

$ boundary authenticate password \
  -auth-method-id=ampw_nihdQAQjRN \
  -login-name=admin

Authentication information:
  Account ID:      acctpw_mGfnmjtath
  Auth Method ID:  ampw_nihdQAQjRN
  Expiration Time: Fri, 14 Aug 2026 13:44:25 MDT
  User ID:         u_GENi0SquNe

The token name "default" was successfully stored in the chosen keyring and is not displayed here.

worker 토큰을 내보냅니다:

$ export WORKER_TOKEN=$(cat /var/lib/boundary/auth_request_token)

worker를 등록합니다:

$ boundary workers create worker-led -worker-generated-auth-token=$WORKER_TOKEN

Worker information:
  Active Connection Count:   0
  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT
  ID:                        w_UJ3Qq63Jx0
  Local Storage State:       unknown
  Type:                      pki
  Updated Time:              Fri, 07 Aug 2026 13:44:30 MDT
  Version:                   1

  Scope:
    ID:                      global
    Name:                    global
    Type:                    global

  Authorized Actions:
    no-op
    read
    update
    delete
    add-worker-tags
    set-worker-tags
    remove-worker-tags

worker가 등록된 후, Boundary는 worker의 auth_storage_path 디렉터리에서 auth_request_token 파일을 삭제합니다. 활성화 토큰은 단회용이므로 같은 토큰으로 같은 worker를 두 번 등록할 수 없어요.

다른 worker(intermediate, egress worker)에 대해 등록 과정을 반복합니다.

worker 검증

다음 명령으로 컨트롤러에 등록된 worker 목록을 확인합니다:

$ boundary workers list

Boundary는 등록된 각 worker, 그 주소, 릴리스 버전을 반환합니다:

Worker information:
  ID:                        w_UJ3Qq63Jx0
    Version:                 1
    Address:                 10.0.0.10:9202
    ReleaseVersion:          Boundary v1.0.0+ent
    Last Status Time:        Fri, 07 Aug 2026 19:45:12 UTC
    Authorized Actions:
      no-op
      read
      update
      delete
      add-worker-tags
      set-worker-tags
      remove-worker-tags

Last Status Time이 최근 값이면 worker가 업스트림에 연결되어 상태를 보고하고 있다는 뜻이에요.

특정 worker의 상세 정보를 보려면 다음 명령을 사용하세요:

$ boundary workers read -id w_UJ3Qq63Jx0

Boundary는 worker의 구성 태그, 저장 상태, 연결된 다운스트림 worker를 반환합니다:

Worker information:
  Active Connection Count:   0
  Address:                   10.0.0.10:9202
  Created Time:              Fri, 07 Aug 2026 13:44:30 MDT
  ID:                        w_UJ3Qq63Jx0
  Last Status Time:          2026-08-07 19:45:22.616245 +0000 UTC
  Local Storage State:       not configured
  Release Version:           Boundary v1.0.0+ent
  Type:                      pki
  Updated Time:              Fri, 07 Aug 2026 13:45:22 MDT
  Version:                   1

  Scope:
    ID:                      global
    Name:                    global
    Type:                    global

  Tags:
    Configuration:
      type: ["worker1" "ingress"]
    Canonical:
      type: ["worker1" "ingress"]

  Authorized Actions:
    no-op
    read
    update
    delete
    add-worker-tags
    set-worker-tags
    remove-worker-tags

출력에는 worker 상태를 나타내는 다음 필드가 들어 있어요:

• Last Status Time — worker가 컨트롤러에 상태를 마지막으로 보고한 시간
• Local Storage State — worker 로컬 저장소 상태. 세션 녹화용으로 worker를 구성하지 않았다면 not configured.
• Release Version — worker가 실행 중인 Boundary 버전
• Tags — Configuration 태그는 worker 구성 파일에서 가져온 것. Canonical 태그는 구성 태그와 API로 추가한 태그를 모두 포함.

멀티홉 배포에서는 Directly Connected Downstream Workers 필드로 체인 모양을 확인할 수 있어요. ingress worker를 읽어서 intermediate worker를 나열하는지 확인하고, intermediate worker를 읽어서 egress worker를 나열하는지 확인하세요.

worker가 나타나지 않거나 상태를 보고하지 않는다면 worker 문제 해결을 참고하세요.

문제 해결

Boundary worker를 배포하고 등록할 때 흔한 문제는 다음과 같습니다:

• 만료된 auth_request_token — Worker Auth Registration Request 토큰은 시간 제한이 있어요. 토큰이 만료되어 등록이 실패하면 worker를 다시 시작해서 새 토큰을 생성하고 등록 단계를 반복하세요.
• worker 등록 실패 — worker 구성 파일이 등록 흐름(worker-led, controller-led, KMS)에 맞는 올바른 KMS 키나 인증 방법을 참조하는지, 그리고 컨트롤러의 cluster 리스너가 worker의 네트워크 경계에서 도달 가능한지 확인하세요.

더 알아보기 (Learn more)

worker를 구성한 다음에는 다음을 해야 해요:

• Boundary 초기화
• Boundary 클라이언트 설치

이 worker들을 통해 세션 트래픽을 라우팅하려면 worker를 통한 트래픽 라우팅과 Boundary Enterprise용 멀티홉 세션 구성을 참고하세요.