`commands` — Boundary CLI 개요

commands — Boundary CLI 개요

Boundary의 CLI는 다양한 명령어 전반에 걸쳐 예측 가능한 동작을 보여요. 이 페이지는 CLI를 더 잘 활용하도록 도와주는 공통 패턴을 자세히 설명해요.

출처: HashiCorp Boundary docs

본문

CLI 명령 구조 (CLI command structure)

사용할 수 있는 명령어와 하위 명령어 옵션이 여럿 있어요. 모든 명령 옵션을 보려면 boundary -h를, 모든 하위 명령 옵션을 보려면 boundary <command> -h를 실행하세요.

대부분의 Boundary CLI 명령의 전형적인 구조는 아래와 같아요:

boundary <command> <subcommand> [options] [args]

• options — 추가 설정을 지정하는 클라이언트(client) 및 연결(connection) 옵션이에요.
• args — 작업에 특화된 API 인자예요.

예시 (Examples)

다음 예시는 요청을 보낼 Boundary 컨트롤러를 지정하기 위해 -addr 플래그를 사용하는 방법을 보여줘요:

$ boundary authenticate password \
    -addr=https://boundary.example.com:9200 \
    -auth-method-id=ampw_1234567890

매 명령어마다 -addr 플래그를 지정하는 대신, 환경 변수 BOUNDARY_ADDR=https://boundary.controller.com:9200을 설정할 수 있어요.

자동 완성 (Autocompletion)

Boundary의 CLI는 자동 완성(autocompletion)을 지원해요. 명령어, 플래그, 그리고 경우에 따라 해당 플래그의 파라미터를 탭으로 완성하게 해줘요.

CLI에 자동 완성을 설치하려면 다음 명령어를 실행하세요.

$ boundary config autocomplete install

Bash로 자동 완성을 수동으로 설치하려면 ~/.bash_profile이나 이와 유사한 파일에 다음 줄을 추가하세요.

complete -C /path/to/boundary boundary

키링 토큰 저장 (Keyring token storage)

Boundary는 나중에 사용하기 위해 인증 토큰을 안전하게 저장하기 위해 플랫폼에 따라 다양한 메커니즘을 사용해요. 각 플랫폼에는 플랫폼별 옵션이 있어요. Windows와 macOS에서는 플랫폼별 옵션이 기본값이에요. Unix 비밀번호 관리자 pass는 모든 플랫폼에서 사용할 수 있어요. -keyring-type을 none으로 설정하거나 환경 변수 BOUNDARY_KEYRING_TYPE을 사용해 모든 플랫폼에서 토큰의 저장과 검색을 비활성화할 수도 있어요.

추가로, -token-name 플래그 또는 BOUNDARY_TOKEN_NAME 환경 변수를 사용해 한 번에 둘 이상의 토큰을 저장하거나 검색할 수 있어요. 여러 토큰을 구성하면 서로 다른 Boundary 설치에서 사용하는 토큰이나 기타 필요에 따라 토큰을 저장할 수 있어요.

Windows

Windows에서 Boundary는 기본 Windows 자격 증명 저장소인 wincred를 사용해요.

사용 가능한 키링 타입은 다음과 같아요:

• wincred (기본값)
• pass
• none

macOS

macOS에서 Boundary는 /usr/bin/security를 통해 Keychain을 사용해요. 이 바이너리를 사용하면 Boundary 바이너리를 정적으로 링크된 상태로 유지할 수 있고, 이 방식을 선호해요.

사용 가능한 키링 타입은 다음과 같아요:

• keychain (기본값)
• pass
• none

그 외 플랫폼 (Other platforms)

그 외 모든 플랫폼에서 기본값은 pass예요. 단, gnome-keyring, kwallet 또는 다른 애플리케이션을 통해 freedesktop.org secret service 구현을 사용할 수 있다면 그걸 사용할 수 있어요.

사용 가능한 키링 타입은 다음과 같아요:

• pass (기본값)
• secret-service
• none

컬렉션 및 하위 타입으로의 매핑 (Map to collections and sub-types)

일반적으로 Boundary의 CLI 명령은 작동하는 컬렉션(collection)에 매핑돼요. 예를 들어 역할(role)을 조작할 때는 명령어가 boundary roles ...예요.

그 결과 읽기, 삭제, 목록 조회 패턴은 예측 가능해요:

• boundary <collection> read
• boundary <collection> delete
• boundary <collection> list

read와 delete 명령은 항상 특정 리소스 식별자에 대해 동작하므로 -id 파라미터가 필요해요. list 명령은 컬렉션에 대해 동작하므로 -scope-id 파라미터 또는 타입에 따라 -auth-method-id 같은 상위 수준 리소스 식별자가 필요해요.

리소스 타입이 추상(abstract)이라면 리소스를 만들거나 갱신할 때 추가 파라미터가 필요할 수 있어요. 추상 리소스 타입은 직접 조작할 수 없고 구현(implementation)을 통해서만 조작해야 해요. 예를 들어 역할은 추상 타입이 아니고 다양한 구현이 없어요. 따라서 아래 예시처럼 역할을 직접 조작할 수 있어요:

• boundary roles create
• boundary roles update.

반면 대상(target)은 여러 종류의 대상 중 하나일 수 있고, 대상의 구체적인 구현은 tcp 타입의 대상이에요. 따라서 대상을 만들거나 갱신할 때 추가 파라미터가 필요해요:

• boundary targets create tcp
• boundary targets update tcp

이 형식 덕분에 CLI가 주어진 타입에 맞게 파라미터와 함수의 프레젠테이션과 검증을 제대로 수행할 수 있어요.

read와 유사하게 update 명령은 기존 대상에 대해 동작하므로 항상 -id 파라미터가 필요해요. list와 유사하게 create 명령은 컬렉션에 대해 동작하므로 항상 -scope-id 파라미터 또는 상위 리소스를 정의하는 파라미터가 필요해요.

파라미터 처리 (Parameter handling)

CLI에 지정된 모든 파라미터는 단일 대시를 사용하는 Go 스타일 플래그로 지정돼요. 예: -id. 해당 플래그의 인자는 등호를 사용해 -id=r_1234567890처럼 지정하거나 공백을 사용해 -id r_1234567890처럼 지정할 수 있어요.

사용 가능한 파라미터를 보려면 아무 명령어에 -h 플래그를 전달하세요.

플래그는 부분적으로 위치에 의존해요. 플래그는 명령 정의 뒤에 와야 하지만 그 외에는 순서에 의존하지 않아요.

예를 들어 다음 명령어들은 동일해요:

• boundary roles create -scope-id global -name foo
• boundary roles create -name foo -scope-id global

하지만 다음 예시는 오류가 발생해요:

• boundary roles -name foo -scope-id global create

이 구조는 -h 명령 사용에도 적용돼요.

값 비우기/기본값 (Clear/default values)

CLI에서 null을 값으로 사용해 Boundary에 값을 해제(unset)하고자 한다는 것을 알리고, 값을 Boundary의 기본값으로 되돌릴 수 있어요. 대부분의 경우 이 기본값은 비어 있지만, 어떤 경우엔 그렇지 않아요. 예를 들어 name이나 description 파라미터는 기본적으로 비어 있지만, 비밀번호 인증 방법의 최소 비밀번호 길이는 0이 아니라 8이에요.

또한 문자열 값을 빈 문자열 ""로 설정하는 것은 일반적으로 허용되지 않아요. 특정 값은 비어 있으면 안 되기 때문이에요. 값을 비우려면 null을 사용해 Boundary가 권장하는 기본값으로 되돌리는 게 좋아요.

참고: Boundary가 null을 사용하는 이유는 API가 JSON이기 때문이에요. 값을 null로 사용하면 그 파라미터의 키가 최종 API 호출의 JSON 객체에 삽입되되 값은 JSON null로 설정돼요. 그러면 컨트롤러에 값이 기본값으로 설정되어야 한다는 신호가 전달돼요. 이는 데이터베이스 NULL 의미론과 직접적으로 일치하지는 않는다는 점을 기억하세요.

연결 옵션 (Connection options)

API 호출로 이어지는 모든 명령에는 연결 옵션을 제어하는 플래그 집합이 포함돼요. 이 옵션들은 연결의 TLS 및 기타 설정을 제어해요.

사용 가능한 모든 CLI 명령 옵션을 출력하려면 -help 또는 -h 플래그로 명령어를 실행하세요.

$ boundary dev -help

• -addr (string: "") — 완전한 URL로서의 Boundary 컨트롤러 주소예요. 예: https://boundary.example.com:9200. 주소는 BOUNDARY_ADDR 환경 변수로도 지정할 수 있어요.
• -ca-cert (string: "") — 컨트롤러 또는 워커 서버의 SSL 인증서를 검증하는 데 사용하는 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로예요. 이 값은 -ca-path보다 우선해요. 경로는 BOUNDARY_CACERT 환경 변수로도 지정할 수 있어요.
• -ca-path (string: "") — 컨트롤러의 SSL 인증서를 검증할 PEM 인코딩 CA 인증서 디렉터리의 로컬 디스크 경로예요. 경로는 BOUNDARY_CAPATH 환경 변수로도 지정할 수 있어요.
• -client-cert (string: "") — Boundary 컨트롤러에 대한 TLS 인증에 사용할 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로예요. 이 플래그를 지정하면 -client-key 플래그도 필요해요. 경로는 BOUNDARY_CLIENT_CERT 환경 변수로도 지정할 수 있어요.
• -client-key (string: "") — -client-cert의 클라이언트 인증서와 일치하는 단일 PEM 인코딩 개인 키의 로컬 디스크 경로예요. 경로는 BOUNDARY_CLIENT_KEY 환경 변수로도 지정할 수 있어요.
• -tls-insecure — 설정하면 TLS 인증서 검증을 비활성화해요. 이 옵션은 Boundary 서버와의 데이터 전송 보안을 낮추므로 사용을 강력히 권장하지 않아요. 기본값은 false예요. TLS 인증서 검증 비활성화는 BOUNDARY_TLS_INSECURE 환경 변수로도 지정할 수 있어요.
• -tls-server-name (string: "") — TLS를 사용해 Boundary 서버에 연결할 때 SNI 호스트로 사용할 이름이에요. SNI 호스트 이름은 BOUNDARY_TLS_SERVER_NAME 환경 변수로도 지정할 수 있어요.

클라이언트 옵션 (Client options)

API 호출로 이어지는 모든 명령에는 클라이언트 옵션을 제어하는 플래그 집합이 포함돼요. 주목할 만한 옵션은 다음과 같아요.

• -keyring-type (string: "") — 사용할 키링의 타입이에요. 기본값은 auto이며 플랫폼에 따라 Windows 자격 증명 관리자, OSX 키체인, 또는 크로스 플랫폼 비밀번호 저장소를 사용해요. none으로 설정하면 키링 기능을 비활성화해요. 플랫폼에 따라 사용 가능한 키링 타입은 wincred, keychain, pass, secret-service예요. 키링 타입은 BOUNDARY_KEYRING_TYPE 환경 변수로도 지정할 수 있어요.
• -output-client-agent-cli-error — true로 설정하면 Boundary가 클라이언트 에이전트 콜백 중에 발생하는 모든 CLI 오류를 출력해요. 기본값은 false예요. 오류 출력 여부는 BOUNDARY_CLIENT_AGENT_CLI_ERROR_OUTPUT 환경 변수로도 지정할 수 있어요.
• -output-curl-string — 설정하면 실행됐을 명령을 명령줄에서 직접 사용할 수 있는 curl 문자열로 포맷해요. CLI 함수가 API 호출에 어떻게 매핑되는지 발견하는 좋은 방법이에요. 기본값은 false예요.
• -recovery-config (string: "") — 설정하면 Boundary 컨트롤러 내 복구 워크플로에 사용하도록 구성된 KMS에 접근하는 데 필요한 정보가 담긴 구성 파일을 지정해요. 구성 파일은 BOUNDARY_RECOVERY_CONFIG 환경 변수로도 지정할 수 있어요.
• -skip-cache-daemon — 설정하면 캐싱 데몬 시작 또는 현재 사용 중이거나 검색한 토큰을 캐싱 데몬으로 보내는 것을 건너뛰어요. 기본값은 false예요. 이 값은 BOUNDARY_SKIP_CACHE_DAEMON 환경 변수로도 지정할 수 있어요.
• -token (string: "") — 디스크의 파일 (file://) 또는 환경 변수 (env://)를 가리키는 URL로, 여기서 토큰을 읽어와요. 이 값은 token-name 파라미터를 덮어써요.
• -token-name (string: "") — 토큰의 이름이에요. CLI가 인증하면 플랫폼별 OS 자격 증명 저장소에 토큰을 저장해요. token-name 파라미터를 사용해 한 번에 둘 이상의 토큰을 저장할 수 있어요. 인증 중에 이 파라미터를 지정하면 Boundary는 저장 키의 일부로 주어진 이름을 사용해요. 다른 명령에 지정하면 해당 호출에 해당 토큰을 사용해요. 토큰 이름은 BOUNDARY_TOKEN_NAME 환경 변수로도 지정할 수 있어요.

출력 옵션 (Output options)

거의 모든 명령어는 -format json을 통해 성공 출력을 JSON으로 포맷하는 것을 지원해요. API 호출로 이어지는 명령의 경우 JSON 출력은 컨트롤러의 정확한 출력이에요. 스크립트나 다른 도구의 파라미터로 CLI 출력을 사용한다면 항상 포맷된 출력을 사용하세요. 기본 텍스트 출력은 사람을 위한 것이고, 원본 JSON의 형식이나 포함 정보는 언제든 바뀔 수 있어요.

boundary authenticate 명령에서 -format json을 사용하면 Boundary가 토큰을 시스템 비밀번호 저장소에 저장하지 않는다는 점에 유의하세요. 이 경우 인증 정보는 JSON 형식으로 터미널에만 출력돼요. 이후 명령에서 BOUNDARY_TOKEN 환경 변수나 -token 플래그를 사용해 토큰을 제공할 수 있어요.

• -format (string: "") — 출력을 표시할 형식이에요. 유효한 형식은 table 또는 json이에요. 기본값은 table이에요. 형식은 BOUNDARY_CLI_FORMAT 환경 변수로도 지정할 수 있어요.

환경 변수 (Environment variables)

CLI는 동작 기본값을 설정하기 위해 다음 환경 변수를 읽어요. 환경 변수는 플래그를 반복 입력해야 하는 번거로움을 덜 수 있어요. 플래그는 항상 환경 변수보다 우선해요.

연결 옵션 (Connection options)

Boundary는 연결 옵션을 구성하는 데 도움이 되는 다음 환경 변수를 포함해요.

BOUNDARY_ADDR

완전한 URL로서의 Boundary 컨트롤러 주소예요. 예: https://boundary.example.com:9200.

BOUNDARY_CACERT

컨트롤러 또는 워커의 SSL 인증서를 검증할 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로예요. 이 변수는 지정된 경우 BOUNDARY_CAPATH 변수나 -ca-path 연결 옵션보다 우선해요.

BOUNDARY_CAPATH

컨트롤러의 SSL 인증서를 검증할 PEM 인코딩 CA 인증서 디렉터리의 로컬 디스크 경로예요.

BOUNDARY_CLIENT_CERT

Boundary 컨트롤러에 대한 TLS 인증에 사용할 단일 PEM 인코딩 CA 인증서의 로컬 디스크 경로예요. 경로를 설정하면 BOUNDARY_CLIENT_KEY 변수나 -client-key 연결 옵션으로 클라이언트 키도 지정해야 해요.

BOUNDARY_CLIENT_KEY

BOUNDARY_CLIENT_CERT 변수나 -client-cert 연결 옵션으로 지정한 클라이언트 인증서와 일치하는 단일 PEM 인코딩 개인 키의 로컬 디스크 경로예요.

BOUNDARY_SKIP_CACHE_DAEMON

Boundary가 캐싱 데몬을 시작하거나 현재 사용 중이거나 검색한 토큰을 캐싱 데몬으로 보내는 것을 막아요. BOUNDARY_SKIP_CACHE_DAEMON 변수나 -skip-cache-daemon 연결 옵션을 사용할 수 있어요.

BOUNDARY_TLS_INSECURE

설정하면 TLS 인증서 검증을 비활성화해요. 이 옵션은 Boundary 서버와의 데이터 전송 보안을 낮추므로 사용을 강력히 권장하지 않아요. 기본값은 false예요.

BOUNDARY_TLS_SERVER_NAME

TLS를 사용해 Boundary 서버에 연결할 때 SNI 호스트로 사용할 이름이에요.

클라이언트 옵션 (Client options)

Boundary는 클라이언트 옵션을 구성하는 데 도움이 되는 다음 환경 변수를 포함해요.

BOUNDARY_KEYRING_TYPE

사용할 키링의 타입이에요. 플랫폼에 따라 Windows 자격 증명 관리자, OSX 키체인, 또는 크로스 플랫폼 비밀번호 저장소를 사용하는 auto가 기본값이에요. none으로 설정하면 키링 기능을 비활성화해요. 플랫폼에 따라 사용 가능한 키링 타입은 다음과 같아요:

• wincred
• keychain
• pass
• secret-service

BOUNDARY_RECOVERY_CONFIG

설정하면 주어진 구성 파일이 purpose가 recovery인 "kms" 블록에 대해 파싱되는지 결정해요. 값을 지정하면 Boundary는 복구 메커니즘을 사용해 호출을 승인해요.

BOUNDARY_TOKEN_NAME

시스템 자격 증명 저장소에 저장할 때의 토큰 이름이에요. 토큰 이름을 지정하면 서로 다른 명령에서 사용자 신원을 전환할 수 있어요.

연결 옵션 (Connect options)

Boundary는 연결 옵션을 구성하는 데 도움이 되는 다음 환경 변수를 포함해요.

BOUNDARY_CONNECT_AUTHZ_TOKEN

대상에 대해 "authorize-session" 작업이 사용될 때 Boundary 컨트롤러에서 반환되는 인가 문자열이에요. 문자열을 -로 설정하면 명령이 표준 입력에서 인가 문자열을 읽으려 시도해요.

BOUNDARY_CONNECT_EXEC

설정하면 워커에 연결한 후 주어진 바이너리를 실행해요. 이 환경 변수는 경로에 있는 바이너리거나 절대 경로여야 해요. 명령 플래그 뒤에 --(공백, 대시 두 개, 공백)를 붙이면 그 뒤의 모든 인자는 바이너리로 직접 전달돼요.

BOUNDARY_CONNECT_LISTEN_ADDR

설정하면 수신(listening) 주소를 주어진 값에 바인딩하려 시도해요. 이 값은 IP 주소여야 해요. CLI가 주소를 바인딩할 수 없으면 명령이 오류를 만들어요. 설정하지 않으면 가장 흔한 IPv4 루프백 주소인 127.0.0.1로 기본 설정돼요.

BOUNDARY_CONNECT_LISTEN_PORT

설정하면 수신 포트를 주어진 값에 바인딩하려 시도해요. CLI가 주소를 바인딩할 수 없으면 명령이 오류를 만들어요.

BOUNDARY_CONNECT_TARGET_SCOPE_ID

스코프 파라미터와 대상 이름으로 세션을 인가하는 경우 사용할 대상 스코프 ID예요. 이 변수는 BOUNDARY_CONNECT_TARGET_SCOPE_NAME과 상호 배타적이에요.

BOUNDARY_CONNECT_TARGET_SCOPE_NAME

스코프 파라미터와 대상 이름으로 세션을 인가하는 경우 사용할 대상 스코프 이름이에요. 이 변수는 BOUNDARY_CONNECT_TARGET_SCOPE_ID와 상호 배타적이에요.

명령 옵션 (Command options)

Boundary는 명령 옵션을 구성하는 데 도움이 되는 다음 환경 변수를 포함해요.

BOUNDARY_AUTH_METHOD_ID

인증 방법(auth method) ID예요.

BOUNDARY_LOG_LEVEL

주로 이벤트의 폴백으로 쓰이는 로그 상세 수준이에요. 상세한 정도가 높은 순에서 낮은 순으로 지원되는 값은 다음과 같아요:

• trace
• debug
• info
• warn
• err

BOUNDARY_SCOPE_ID

작업에 사용할 스코프예요.

출력 옵션 (Output options)

Boundary는 출력 옵션을 구성하는 데 도움이 되는 다음 환경 변수를 포함해요.

BOUNDARY_CLI_FORMAT

출력을 표시할 형식이에요. 유효한 형식은 table과 json이에요. 기본값은 table이에요.