리소스 필터링과 나열하기

필터 표현식은 Boundary의 여러 부분에서 유용한 기능을 제공하는 데 사용돼요. 각 필터 표현식은 매칭 연산자(matching operator)와 선택자(selector), 값(value)으로 구성돼요. 이 페이지는 전체 문법을 설명하고, 각종 기능에서 필터링에 사용할 수 있는 구체적인 값에 대한 정보와 예시를 제공해요.

출처: HashiCorp Boundary docs

본문

필터 표현식은 Boundary의 여러 부분에서 유용한 기능을 제공하는 데 사용돼요. 각 필터 표현식은 매칭 연산자를 선택자와 값으로 조합해서 만들어요.

이벤트, 워커, 대상(target), 자격 증명 저장소(credential store)에 대한 필터를 만드는 방법에 대한 자세한 내용은 다음 주제를 참고하세요.

표현식 만들기

단일 표현식은 선택자와 값을 가진 매칭 연산자예요. 일반 텍스트 형식으로 작성되며, 부울 논리(Boolean logic)와 괄호(parenthesization)를 지원해요. 일반적으로 공백은 무시되지만, 리터럴 문자열 안에서는 무시되지 않아요.

매칭 연산자

모든 매칭 연산자는 어떤 데이터를 매칭할지 고르기 위해 선택자 또는 값을 사용해요. 필터링을 지원하는 각 엔드포인트는 서로 다른 선택자 목록을 받을 수 있으며, 이는 해당 엔드포인트의 API 문서에 자세히 나와 있어요.

// Equality & Inequality checks
<Selector> == "<Value>"
<Selector> != "<Value>"

// Emptiness checks
<Selector> is empty
<Selector> is not empty

// Contains checks or Substring Matching
"<Value>" in <Selector>
"<Value>" not in <Selector>
<Selector> contains "<Value>"
<Selector> not contains "<Value>"

// Regular Expression Matching
<Selector> matches "<Value>"
<Selector> not matches "<Value>"

선택자(Selectors)

선택자는 매칭 연산자가 표현식을 만드는 데 사용해요. 필터 표현식의 입력은 JSON(또는 JSON 파생)이므로, 선택자는 입력에서 값을 고르기 위해 JSON Pointer를 사용해요. 각 선택자는 따옴표로 묶어야 하고, 선행 슬래시(/)를 포함한 유효한 JSON Pointer 경로를 담고 있어야 해요.

// 입력 `{ "foo": { "bar": "zipzap" } }`에서 `zipzap` 값을 선택
"/foo/bar"

값(Values)

값은 매칭 연산자가 표현식을 만드는 데 사용해요. 값은 유효한 선택자, 숫자, 또는 문자열일 수 있어요. 값을 따옴표로 묶는 것이 모범 사례예요.

숫자는 10진수 정수 또는 부동 소수점 수일 수 있어요.

문자열을 따옴표로 묶을 때는 큰따옴표(")나 백틱(`)을 사용할 수 있어요. 백틱으로 묶으면 원시 문자열로 취급되어 \n 같은 이스케이프 시퀀스가 확장되지 않아요.

표현식 연결하기

표현식을 연결하는 방법은 여러 가지가 있어요.

논리 or
논리 and
논리 not
괄호로 그룹화
매칭 표현식

// Logical Or - 두 하위 표현식 중 하나라도 참이면 참으로 평가
<Expression 1> or <Expression 2>

// Logical And - 두 하위 표현식이 모두 참이면 참으로 평가
<Expression 1> and <Expression 2>

// Logical Not - 하위 표현식이 참이 아니면 참으로 평가
not <Expression 1>

// Grouping - 일반적인 우선순위 규칙을 재정의
( <Expression 1> )

// Inspects data to check for a match
<Matching Expression 1>

각 형식에 대해 표준 연산자 우선순위를 기대할 수 있어요. 예를 들어 다음 두 표현식은 동일해요.

<Expression 1> and not <Expression 2> or <Expression 3>

( <Expression 1> and (not <Expression 2> )) or <Expression 3>

성능

필터는 컨트롤러에서 실행되므로 컨트롤러에서 어느 정도 CPU 시간을 소비해요.

리소스 나열하기(Listing resources)

이 절은 리소스를 나열할 때 필터를 사용하는 방법을 설명해요. 나열(list) 작업을 수행할 때 반환되는 리소스 집합을 줄이는 데 사용할 수 있어요.

Note: 이 기능은 클라이언트에 유용한 서비스를 제공하기 위한 것이에요. 이 작업을 위해 생성되는 데이터베이스 쿼리에는 영향을 주지 않으므로 더 큰 효율을 제공하도록 설계되지 않았어요.

나열 작업을 실행할 때 필터를 지정할 수 있어요. Boundary의 다른 곳에서 사용하는 표준 필터 문법을 사용해요. 특정 나열 엔드포인트에 달리 명시되지 않는 한, 반환되는 항목 목록을 순회하며 각 항목의 JSON 표현에 대해 필터를 실행해요. 그 데이터가 어떻게 생겼는지 보는 좋은 방법은 명령줄에서 대표적인 JSON 출력을 보는 거예요. 예를 들어 다음은 dev 인스턴스에서 boundary targets list -scope-id p_1234567890 -format json를 실행한 출력이에요(가독성을 위해 jq로 파이프함).

[
  {
    "id": "ttcp_1234567890",
    "scope_id": "p_1234567890",
    "scope": {
      "id": "p_1234567890",
      "type": "project",
      "name": "Generated project scope",
      "description": "Provides an initial project scope in Boundary",
      "parent_scope_id": "o_1234567890"
    },
    "name": "Generated target",
    "description": "Provides an initial target in Boundary",
    "created_time": "2021-02-24T22:19:50.640476Z",
    "updated_time": "2021-02-24T22:19:50.640476Z",
    "version": 1,
    "type": "tcp",
    "session_max_seconds": 28800,
    "session_connection_limit": -1,
    "attributes": {
      "default_port": 22
    },
    "authorized_actions": [
      "read",
      "update",
      "delete",
      "add-host-sources",
      "set-host-sources",
      "remove-host-sources",
      "authorize-session"
    ]
  }
]

필터가 반환되는 각 항목을 검사할 때, 테스트 중인 데이터를 필터 안의 /item에 배치해요.

CLI에서는 -filter로 필터를 지정할 수 있어요.

큰따옴표는 필터 문법의 일부예요. CLI를 사용할 때는 큰따옴표를 이스케이프 처리하는 것보다 필터를 작은따옴표로 감싸는 것이 더 쉬울 거예요.

HTTP API를 사용할 때는 filter 쿼리 파라미터예요.

쿼리 파라미터가 제대로 이스케이프되었는지 확인하세요! 대부분의 HTTP 라이브러리가 알아서 처리해줘요. 문제가 있다면 Boundary CLI의 -output-curl-string 플래그를 시도해보세요.

$ boundary targets list -scope-id p_1234567890 -format json -filter '"authorize-session" in "/item/authorized_actions"' -output-curl-string
curl -H "Authorization: Bearer *** config get-token -keyring-type pass -token-name default)" -H "Content-Type: application/json" 'http://127.0.0.1:9200/v1/targets?filter=%22authorize-session%22+in+%22%2Fitem%2Fauthorized_actions%22&scope_id=p_1234567890'

다음은 몇 가지 예시예요.

사용자가 "update" 동작을 실행할 수 있는 리소스: "update" in "/item/authorized_actions"
이름 패턴과 일치하지만 조직 스코프 안에 있는 리소스만: "/item/name" matches "groupa-*" and "/item/scope/type" == "org"