Boundary Enterprise용 멀티홉 세션 구성

Boundary Enterprise용 멀티홉 세션 구성 (Configure multi-hop sessions for Boundary Enterprise)

Boundary Enterprise에서는 ingress, intermediate, egress worker를 구성해서 멀티홉 worker 기능을 활용할 수 있어요. 이 페이지는 세 개의 worker로 이루어진 체인을 자세히 다룹니다.

Ingress worker는 컨트롤러에 연결하고, intermediate worker는 ingress worker에 연결하며, egress worker는 intermediate worker에 연결하고 타깃에 도달해요. 'ingress', 'intermediate', 'egress'는 각 worker가 리소스와 상호작용하는 방식을 일반적으로 설명하는 말이라는 점을 기억하세요. 하나의 worker가 한 번에 두 개 이상의 역할을 할 수도 있습니다. 자세한 내용은 멀티홉 세션을 참고하세요.

출처: HashiCorp Boundary docs

본문

사전 요구 사항

멀티홉 체인을 구성하기 전에 다음이 준비되어 있어야 해요:

• 실행 중인 Boundary Enterprise 컨트롤 플레인
• 각 네트워크에 하나씩, Boundary 바이너리가 설치된 호스트 세 대 (Boundary 설치 참고)
• 다음 네트워크 경로:
  • ingress worker가 컨트롤러에 9201 포트로 도달하고, 클라이언트는 9202 포트로 ingress worker에 도달
  • intermediate worker가 9202 포트로 ingress worker에 도달
  • egress worker가 9202 포트로 intermediate worker에 도달하고, 타깃 호스트에 도달

네트워크 경계 사이에 인바운드 네트워크 규칙은 필요 없어요. 각 worker는 업스트림으로 아웃바운드 연결을 하고, Boundary는 그 연결을 양방향으로 사용합니다.

worker 구성하기

각 호스트에 구성 파일을 만듭니다. 파일은 세 군데에서 달라요: initial_upstreams 값, 태그, 그리고 worker의 자격 증명을 암호화하는 KMS 키입니다.

예시는 worker 기반(worker-led) 등록 방식을 사용해요. 다른 방식을 쓰려면 worker 등록을 참고하세요.

Ingress worker 구성

Ingress worker는 initial_upstreams를 컨트롤러 로드 밸런서 주소로 지정합니다. 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는 initial_upstreams를 9202 포트의 ingress 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는 initial_upstreams를 9202 포트의 intermediate 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 (bool: false) — 서버가 메모리를 디스크로 스왑하지 못하게 하는 mlock 시스템 콜의 실행을 비활성화해요. 로컬 개발과 테스트에는 mlock을 꺼도 괜찮습니다. 다만 프로덕션에서는, Boundary를 실행하는 시스템이 암호화된 스왑만 사용하거나 스왑을 전혀 쓰지 않는 경우가 아니라면 권장하지 않아요. Boundary는 Linux와 FreeBSD처럼 mlock() 시스템 콜을 지원하는 UNIX 계열 시스템에서만 메모리 잠금을 지원합니다. Linux에서 루트로 실행하지 않고 Boundary 실행 파일이 mlock 시스템 콜을 쓰게 하려면 다음 명령을 실행하세요:

sudo setcap cap_ipc_lock=+ep $(readlink -f $(which boundary))

최신 systemd를 쓰는 Linux 배포판이라면 [Service] 구성 섹션에 다음 지시어를 추가할 수도 있어요:

LimitMEMLOCK=infinity

• listener — Boundary가 트래픽을 서비스하는 리스너(API 클러스터와 프록시)를 구성해요.
• worker — worker를 구성합니다. boundary server에 있으면 worker 하위 프로세스를 시작해요.
• events — 이벤트별 파라미터를 구성합니다. 예시의 events 구성은 완전해서 모든 이벤트를 stderr와 파일 양쪽에 기록해요. 이 구성이 조직의 로깅 솔루션에 맞지 않을 수도 있습니다.
• kms — 여러 목적을 위한 KMS 블록을 구성해요. 서로 다른 클라우드 KMS 블록의 구성 정보는 아래 링크를 참고하세요: AWS, Azure, GCP, OCI, AliCloud, Vault Transit

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

worker 시작 및 등록

체인의 맨 위부터 아래 순서로 worker를 시작해요. 다운스트림 worker는 업스트림이 실행되고 인증되기 전까지 연결할 수 없어요. Ingress worker부터 시작해서 각 worker에 대해 다음 단계를 완료하세요:

worker를 호스트에서 시작해요:

$ boundary server -config=/etc/boundary.d/ingress-worker.hcl

systemd나 컨테이너에서 worker를 실행하려면 worker 시작 및 검증을 참고하세요.

시작 출력에서 Worker Auth Registration Request 값을 복사해요. worker의 auth_storage_path 디렉터리에 있는 auth_request_token 파일에서도 읽을 수 있습니다.

컨트롤러에 worker를 등록합니다:

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

이 단계를 intermediate worker에, 그다음 egress worker에 반복합니다. 다운스트림 worker는 업스트림 worker를 통해 등록돼요. Intermediate와 egress worker는 컨트롤 플레인에 네트워크 접근이 필요 없습니다.

체인 검증

Directly Connected Downstream Workers 필드로 체인의 모양을 확인할 수 있어요.

Ingress worker를 읽어 보세요:

$ boundary workers read -id w_UJ3Qq63Jx0

출력은 intermediate worker를 다운스트림으로 나열합니다:

Worker information:
  Active Connection Count:   0
  Address:                   10.0.0.10:9202
  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
  Version:                   1
  Tags:
    Configuration:
      type: ["worker1" "ingress"]
  Directly Connected Downstream Workers:
    w_GHBqIeHMyR

Intermediate worker를 읽어서 egress worker를 다운스트림으로 나열하는지 확인하세요. Egress worker는 체인의 끝에 있으므로 다운스트림 worker가 없습니다.

체인을 통한 타깃 트래픽 라우팅

Worker 필터는 세션에 어떤 worker를 쓸지 제어해요. 클라이언트가 연결할 위치를 고르는 ingress 필터와, 타깃에 닿을 worker를 고르는 egress 필터를 설정합니다. ingress와 egress worker 사이의 경로는 Boundary가 자동으로 선택해요. Intermediate worker에는 필터를 적용하지 않습니다.

UI에서 Boundary에 로그인하고, 조직을 선택한 다음 타깃이 들어 있는 프로젝트를 선택하세요. Targets에서 타깃을 선택하고, Workers 탭을 선택합니다. Ingress workers 옆에서 Add Worker Filter를 클릭하고 ingress worker의 태그와 일치하는 필터를 입력해요:

"ingress" in "/tags/type"

Save를 클릭합니다. Egress workers 옆에서 Add Worker Filter를 클릭하고 egress worker의 태그와 일치하는 필터를 입력해요:

"egress" in "/tags/type"

Save를 클릭합니다. 타깃에 해당 역할의 필터가 없으면 버튼은 Add Worker Filter로, 필터가 이미 있으면 Edit Worker Filter로 표시돼요.

Tip — 필터 편집기에는 worker 태그나 worker 이름에서 필터를 자동으로 만들어 주는 생성기가 있어요. Admin UI에서 필터 생성을 참고하세요.

CLI에서 ingress worker의 태그와 일치하는 ingress worker 필터를 설정해요:

$ boundary targets update tcp -id ttcp_uPVxp2NGiD \
  -ingress-worker-filter='"ingress" in "/tags/type"'

egress worker의 태그와 일치하는 egress worker 필터를 설정해요:

$ boundary targets update tcp -id ttcp_uPVxp2NGiD \
  -egress-worker-filter='"egress" in "/tags/type"'

Boundary는 두 필터가 모두 적용된 업데이트된 타깃을 반환합니다:

Target information:
  Address:                    10.10.10.50
  Description:                Multi-hop target
  Egress Worker Filter:       "egress" in "/tags/type"
  ID:                         ttcp_uPVxp2NGiD
  Ingress Worker Filter:      "ingress" in "/tags/type"
  Name:                       private-web
  Session Connection Limit:   -1
  Session Max Seconds:        28800
  Type:                       tcp
  Version:                    3

다음 Terraform 구성을 적용해요:

resource "boundary_target" "private_web" {
  type                 = "tcp"
  name                 = "private-web"
  description          = "Multi-hop target"
  scope_id             = boundary_scope.project.id
  default_port         = 443
  ingress_worker_filter = "\"ingress\" in \"/tags/type\""
  egress_worker_filter  = "\"egress\" in \"/tags/type\""
}

더 많은 필터 예시는 worker 필터 구성을 참고하세요.

연결 테스트

세션이 체인을 제대로 통과하는지 타깃에 연결해서 확인해요:

$ boundary connect -target-id ttcp_uPVxp2NGiD

Boundary는 로컬 프록시 상세 정보를 반환합니다:

Proxy listening information:
  Address:             127.0.0.1
  Connection Limit:    -1
  Expiration:          Fri, 07 Aug 2026 21:46:08 MDT
  Port:                52234
  Protocol:            tcp
  Session ID:          s_phGLOoaB7v

필터와 일치하는 worker가 없어서 세션이 실패한다면 worker 문제 해결을 참고하세요.

더 알아보기 (Learn more)

체인을 구성한 뒤에는 다음을 할 수 있어요:

• 별도의 KMS 트러스트 도메인으로 다운스트림 worker 인증
• egress worker에서 SSH 호스트 ID 검증
• worker 관리로 구성 리로드 또는 세션 드레인