네임스페이스 관리

네임스페이스 관리 (Managing Namespaces)

Pulsar 네임스페이스는 토픽의 논리적 그룹이에요. 네임스페이스 단위로 복제 클러스터, 백로그 쿼터, 영속성, 번들, 메시지 TTL, 보존, 디스패치 스로틀링 같은 정책을 설정하고 관리할 수 있어요. 이 페이지에서는 네임스페이스의 생성·조회·삭제부터 각종 정책 설정까지 pulsar-admin CLI, REST API, Java admin API로 정리했어요.

출처: 문서

본문

tip

이 페이지는 자주 사용하는 일부 작업만 보여줘요.

  • Pulsar admin 명령, 플래그, 설명 등 최신·전체 정보는 Pulsar admin docs를 참고해요.
  • REST API 파라미터, 응답, 샘플 등 최신·전체 정보는 REST API doc을 참고해요.
  • Java admin API 클래스, 메서드, 설명 등 최신·전체 정보는 Java admin API doc을 참고해요.

Pulsar 네임스페이스는 토픽의 논리적 그룹이에요. 네임스페이스는 다음으로 관리할 수 있어요.

  • pulsar-admin 도구의 namespaces 명령
  • admin REST API의 /admin/v2/namespaces 엔드포인트
  • Java API의 PulsarAdmin 객체 namespaces 메서드

네임스페이스 리소스 (Namespaces resources)

네임스페이스 생성 (Create namespaces)

주어진 tenant 아래에 새 네임스페이스를 만들 수 있어요.

pulsar-admin

create 하위 명령에 네임스페이스를 이름으로 지정해요.

pulsar-admin namespaces create test-tenant/test-namespace

REST API: PUT /admin/v2/namespaces/{tenant}/{namespace}

Java

admin.namespaces().createNamespace(namespace);

정책 가져오기 (Get policies)

언제든 네임스페이스와 연관된 현재 정책을 가져올 수 있어요.

pulsar-admin

policies 하위 명령에 네임스페이스를 지정해요.

pulsar-admin namespaces policies test-tenant/test-namespace

예시 출력:

{
  "auth_policies": {
    "namespace_auth": {},
    "destination_auth": {}
  },
  "replication_clusters": [],
  "bundles_activated": true,
  "bundles": {
    "boundaries": [
      "0x00000000",
      "0xffffffff"
    ],
    "numBundles": 1
  },
  "backlog_quota_map": {},
  "persistence": null,
  "latency_stats_sample_rate": {},
  "message_ttl_in_seconds": 0,
  "retention_policies": null,
  "deleted": false
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}

Java

admin.namespaces().getPolicies(namespace);

네임스페이스 나열 (List namespaces)

주어진 Pulsar tenant 내의 모든 네임스페이스를 나열할 수 있어요.

pulsar-admin

list 하위 명령에 tenant를 지정해요.

pulsar-admin namespaces list test-tenant

예시 출력:

test-tenant/namespace1
test-tenant/namespace2

REST API: GET /admin/v2/namespaces/{tenant}

Java

admin.namespaces().getNamespaces(tenant);

네임스페이스 삭제 (Delete namespaces)

tenant에서 기존 네임스페이스를 삭제할 수 있어요.

pulsar-admin

delete 하위 명령에 네임스페이스를 지정해요.

pulsar-admin namespaces delete test-tenant/namespace1

REST API: DELETE /admin/v2/namespaces/{tenant}/{namespace}

Java

admin.namespaces().deleteNamespace(namespace);

복제 클러스터 구성 (Configure replication clusters)

복제 클러스터 설정 (Set replication cluster)

네임스페이스에 복제 클러스터를 설정해서 Pulsar가 게시된 메시지를 한 시설(colo)에서 다른 시설로 내부적으로 복제하게 할 수 있어요.

pulsar-admin

pulsar-admin namespaces set-clusters test-tenant/namespace1 --clusters cl1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/replication

Java

admin.namespaces().setNamespaceReplicationClusters(namespace, clusters);

복제 클러스터 가져오기 (Get replication cluster)

주어진 네임스페이스의 복제 클러스터 목록을 가져올 수 있어요.

pulsar-admin

pulsar-admin namespaces get-clusters test-tenant/cluster1/namespace1

예시 출력:

cluster2

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/replication

Java

admin.namespaces().getNamespaceReplicationClusters(namespace)

백로그 쿼터 정책 구성 (Configure backlog quota policies)

백로그 쿼터 정책 설정 (Set backlog quota policies)

백로그 쿼터는 네임스페이스가 특정 임계값에 도달하면 브로커가 그 네임스페이스의 대역폭·저장소를 제한하도록 도와줘요. 관리자는 한도를 설정하고, 한도에 도달한 후 취할 조치를 정할 수 있어요.

  • producer_request_hold: 프로듀서가 메시지를 보류하고 클라이언트 구성 sendTimeoutMs를 초과할 때까지 재시도해요
  • producer_exception: 프로듀서가 메시지 전송을 시도할 때 예외를 던져요
  • consumer_backlog_eviction: 브로커가 백로그 메시지를 버리기 시작해요

백로그 쿼터 제한은 backlog-quota-type: destination_storage의 제한을 정의해서 처리할 수 있어요.

pulsar-admin

pulsar-admin namespaces set-backlog-quota --limit 10G \
    --limitTime 36000 \
    --policy producer_request_hold \
    test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/backlogQuota

Java

admin.namespaces().setBacklogQuota(namespace, new BacklogQuota(limit, limitTime, policy))

백로그 쿼터 정책 가져오기 (Get backlog quota policies)

주어진 네임스페이스의 구성된 백로그 쿼터를 가져올 수 있어요.

pulsar-admin

pulsar-admin namespaces get-backlog-quotas test-tenant/namespace1

예시 출력:

destination_storage    BacklogQuotaImpl(limit=10737418240, limitSize=10737418240, limitTime=36000, policy=producer_request_hold)

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/backlogQuotaMap

Java

admin.namespaces().getBacklogQuotaMap(namespace);

백로그 쿼터 정책 제거 (Remove backlog quota policies)

주어진 네임스페이스의 백로그 쿼터 정책을 제거할 수 있어요.

pulsar-admin

pulsar-admin namespaces remove-backlog-quota test-tenant/namespace1

REST API: DELETE /admin/v2/namespaces/{tenant}/{namespace}/backlogQuota

Java

admin.namespaces().removeBacklogQuota(namespace, backlogQuotaType)

영속성 정책 구성 (Configure persistence policies)

영속성 정책 설정 (Set persistence policies)

영속성 정책은 주어진 네임스페이스 아래의 모든 토픽 메시지에 대한 영속성 수준을 구성할 수 있게 해줘요.

  • Bookkeeper-ack-quorum: 각 엔트리에 기다려야 하는 ack(보장된 복제본) 수, 기본 2
  • Bookkeeper-ensemble: 토픽에 사용할 부키 수, 기본 2
  • Bookkeeper-write-quorum: 각 엔트리에 기록할 쓰기 수, 기본 2
  • Ml-mark-delete-max-rate: mark-delete 연산의 스로틀링 비율 (0이면 스로틀링 없음), 기본 0

pulsar-admin

pulsar-admin namespaces set-persistence \
    --bookkeeper-ack-quorum 2 --bookkeeper-ensemble 3 \
    --bookkeeper-write-quorum 2 --ml-mark-delete-max-rate 0 \
    test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/persistence

Java

admin.namespaces().setPersistence(namespace,new PersistencePolicies(bookkeeperEnsemble, bookkeeperWriteQuorum,bookkeeperAckQuorum,managedLedgerMaxMarkDeleteRate))

영속성 정책 가져오기 (Get persistence policies)

주어진 네임스페이스의 구성된 영속성 정책을 가져올 수 있어요.

pulsar-admin

pulsar-admin namespaces get-persistence test-tenant/namespace1

예시 출력:

{
  "bookkeeperEnsemble": 3,
  "bookkeeperWriteQuorum": 2,
  "bookkeeperAckQuorum": 2,
  "managedLedgerMaxMarkDeleteRate": 0
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/persistence

Java

admin.namespaces().getPersistence(namespace)

네임스페이스 번들 구성 (Configure namespace bundles)

네임스페이스 번들 언로드 (Unload namespace bundles)

네임스페이스 번들은 같은 네임스페이스에 속한 토픽의 가상 그룹이에요. 브로커가 번들 수 때문에 과부하가 걸리면, 이 명령으로 그 브로커에서 번들을 언로드해서 부하가 덜한 다른 브로커가 서빙하게 할 수 있어요. 네임스페이스 번들 ID는 0x00000000부터 0xffffffff까지의 범위예요.

pulsar-admin

pulsar-admin namespaces unload --bundle 0x00000000_0xffffffff test-tenant/namespace1
pulsar-admin namespaces unload --bundle 0x00000000_0xffffffff test-tenant/namespace1
pulsar-admin namespaces unload --bundle 0x00000000_0xffffffff --destinationBroker broker1.use.org.com:8080 test-tenant/namespace1

REST API: PUT /admin/v2/namespaces/{tenant}/{namespace}/{bundle}/unload

Java

admin.namespaces().unloadNamespaceBundle(namespace, bundle)

네임스페이스 번들 분할 (Split namespace bundles)

하나의 네임스페이스 번들은 여러 토픽을 담을 수 있지만 단 하나의 브로커만이 서빙할 수 있어요. 단일 번들이 브로커에 과도한 부하를 만든다면, 아래 명령으로 번들을 분할할 수 있어요. 그러면 새 번들 중 하나 이상을 언로드해 브로커 간 부하를 분산할 수 있어요.

pulsar-admin

pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenant/namespace1

REST API: PUT /admin/v2/namespaces/{tenant}/{namespace}/{bundle}/split

Java

admin.namespaces().splitNamespaceBundle(namespace, bundle, unloadSplitBundles, splitAlgorithmName)

메시지 TTL 구성 (Configure message TTL)

메시지 TTL 설정 (Set message-ttl)

메시지의 time-to-live(TTL, 초 단위) 기간을 구성할 수 있어요. 아래 예시에서는 message-ttl을 100초로 설정해요.

pulsar-admin

pulsar-admin namespaces set-message-ttl --messageTTL 100 test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Java

admin.namespaces().setNamespaceMessageTTL(namespace, messageTTL)

메시지 TTL 가져오기 (Get message-ttl)

네임스페이스의 message-ttl이 설정되면 아래 명령으로 구성된 값을 가져올 수 있어요. 이 예시는 set message-ttl 명령 예시를 이어가므로 반환값은 100(초)이에요.

pulsar-admin

pulsar-admin namespaces get-message-ttl test-tenant/namespace1

예시 출력:

100

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Java

admin.namespaces().getNamespaceMessageTTL(namespace)

100

메시지 TTL 제거 (Remove message-ttl)

구성된 네임스페이스의 메시지 TTL을 제거해요.

pulsar-admin

pulsar-admin namespaces remove-message-ttl test-tenant/namespace1

REST API: DELETE /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Java

admin.namespaces().removeNamespaceMessageTTL(namespace)

백로그 정리 (Clear backlog)

네임스페이스 백로그 정리 (Clear namespace backlog)

특정 네임스페이스에 속한 모든 토픽의 모든 메시지 백로그를 정리해요. 특정 구독의 백로그만 정리할 수도 있어요.

pulsar-admin

pulsar-admin namespaces clear-backlog --sub my-subscription test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/clearBacklog/{subscription}

Java

admin.namespaces().clearNamespaceBacklogForSubscription(namespace, subscription)

번들 백로그 정리 (Clear bundle backlog)

특정 NamespaceBundle에 속한 모든 토픽의 모든 메시지 백로그를 정리해요. 특정 구독의 백로그만 정리할 수도 있어요.

pulsar-admin

pulsar-admin namespaces clear-backlog \
    --bundle 0x00000000_0xffffffff \
    --sub my-subscription \
    test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/{bundle}/clearBacklog/{subscription}

Java

admin.namespaces().clearNamespaceBundleBacklogForSubscription(namespace, bundle, subscription)

보존(retention) 구성 (Configure retention)

보존 설정 (Set retention)

각 네임스페이스는 여러 토픽을 포함하며, 각 토픽의 보존 크기(저장소 크기)는 특정 임계값을 넘지 않거나 일정 기간 저장되어야 해요. 이 명령은 주어진 네임스페이스의 토픽 보존 크기와 시간을 구성해요.

pulsar-admin

pulsar-admin namespaces set-retention --size 100M --time 10m test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/retention

Java

admin.namespaces().setRetention(namespace, new RetentionPolicies(retentionTimeInMin, retentionSizeInMB))

보존 가져오기 (Get retention)

주어진 네임스페이스의 보존 정보를 보여줘요.

pulsar-admin

pulsar-admin namespaces get-retention test-tenant/namespace1

{
  "retentionTimeInMinutes": 10,
  "retentionSizeInMB": 100
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/retention

Java

admin.namespaces().getRetention(namespace)

토픽 디스패치 스로틀링 구성 (Configure dispatch throttling for topics)

토픽 디스패치 스로틀링 설정 (Set dispatch throttling for topics)

주어진 네임스페이스 아래 모든 토픽의 메시지 디스패치 비율을 설정해요. 디스패치 비율은 X초당 메시지 수(msg-dispatch-rate) 또는 X초당 메시지 바이트 수(byte-dispatch-rate)로 제한할 수 있어요. 디스패치 비율은 초 단위이고 dispatch-rate-period로 구성할 수 있어요. msg-dispatch-rate와 byte-dispatch-rate의 기본값은 -1로, 이는 스로틀링을 비활성화해요.

note

  • clusterDispatchRate도 topicDispatchRate도 구성하지 않으면 디스패치 스로틀링이 비활성화돼요.
  • topicDispatchRate를 구성하지 않으면 clusterDispatchRate가 적용돼요.
  • topicDispatchRate를 구성하면 topicDispatchRate가 적용돼요.

pulsar-admin

pulsar-admin namespaces set-dispatch-rate test-tenant/namespace1 \
    --msg-dispatch-rate 1000 \
    --byte-dispatch-rate 1048576 \
    --dispatch-rate-period 1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/dispatchRate

Java

admin.namespaces().setDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))

토픽 구성된 메시지 비율 가져오기 (Get configured message-rate for topics)

네임스페이스의 구성된 메시지 비율을 보여줘요(이 네임스페이스 아래 토픽은 초당 이만큼 메시지를 디스패치할 수 있어요).

pulsar-admin

pulsar-admin namespaces get-dispatch-rate test-tenant/namespace1

예시 출력:

{
  "dispatchThrottlingRateInMsg" : 1000,
  "dispatchThrottlingRateInByte" : 1048576,
  "relativeToPublishRate" : false,
  "ratePeriodInSecond" : 1
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/dispatchRate

Java

admin.namespaces().getDispatchRate(namespace)

구독 디스패치 스로틀링 구성 (Configure dispatch throttling for subscription)

구독 디스패치 스로틀링 설정 (Set dispatch throttling for subscription)

주어진 네임스페이스 아래 토픽의 모든 구독에 대한 메시지 디스패치 비율을 설정해요. 디스패치 비율은 X초당 메시지 수(msg-dispatch-rate) 또는 X초당 메시지 바이트 수(byte-dispatch-rate)로 제한할 수 있어요. 디스패치 비율은 초 단위이고 dispatch-rate-period로 구성할 수 있어요. msg-dispatch-rate와 byte-dispatch-rate의 기본값은 -1로, 스로틀링을 비활성화해요.

pulsar-admin

pulsar-admin namespaces set-subscription-dispatch-rate test-tenant/namespace1 \
    --msg-dispatch-rate 1000 \
    --byte-dispatch-rate 1048576 \
    --dispatch-rate-period 1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/subscriptionDispatchRate

Java

admin.namespaces().setSubscriptionDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))

구독 구성된 메시지 비율 가져오기 (Get configured message-rate for subscription)

네임스페이스의 구성된 메시지 비율을 보여줘요(이 네임스페이스 아래 토픽은 초당 이만큼 메시지를 디스패치할 수 있어요).

pulsar-admin

pulsar-admin namespaces get-subscription-dispatch-rate test-tenant/namespace1

예시 출력:

{
  "dispatchThrottlingRateInMsg" : 1000,
  "dispatchThrottlingRateInByte" : 1048576,
  "relativeToPublishRate" : false,
  "ratePeriodInSecond" : 1
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/subscriptionDispatchRate

Java

admin.namespaces().getSubscriptionDispatchRate(namespace)

복제기(replicator) 디스패치 스로틀링 구성 (Configure dispatch throttling for replicators)

복제기 디스패치 스로틀링 설정 (Set dispatch throttling for replicators)

주어진 네임스페이스 아래 복제 클러스터 간의 모든 복제기에 대한 메시지 디스패치 비율을 설정해요. 디스패치 비율은 X초당 메시지 수(msg-dispatch-rate) 또는 X초당 메시지 바이트 수(byte-dispatch-rate)로 제한할 수 있어요. 디스패치 비율은 초 단위이고 dispatch-rate-period로 구성할 수 있어요. msg-dispatch-rate와 byte-dispatch-rate의 기본값은 -1로, 스로틀링을 비활성화해요.

pulsar-admin

pulsar-admin namespaces set-replicator-dispatch-rate test-tenant/namespace1 \
    --msg-dispatch-rate 1000 \
    --byte-dispatch-rate 1048576 \
    --dispatch-rate-period 1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/dispatchRate

Java

admin.namespaces().setReplicatorDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))

복제기 구성된 메시지 비율 가져오기 (Get configured message-rate for replicators)

네임스페이스의 구성된 메시지 비율을 보여줘요(이 네임스페이스 아래 토픽은 초당 이만큼 메시지를 디스패치할 수 있어요).

pulsar-admin

pulsar-admin namespaces get-replicator-dispatch-rate test-tenant/namespace1

{
  "dispatchThrottlingRatePerTopicInMsg" : 1000,
  "dispatchThrottlingRatePerTopicInByte" : 1048576,
  "ratePeriodInSecond" : 1
}

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/dispatchRate

Java

admin.namespaces().getReplicatorDispatchRate(namespace)

중복 제거 스냅샷 간격 구성 (Configure deduplication snapshot interval)

중복 제거 스냅샷 간격 가져오기 (Get deduplication snapshot interval)

네임스페이스의 구성된 deduplicationSnapshotInterval을 보여줘요(네임스페이스 아래 각 토픽은 이 간격에 따라 중복 제거 스냅샷을 찍어요).

pulsar-admin

pulsar-admin namespaces get-deduplication-snapshot-interval test-tenant/namespace1

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/deduplicationSnapshotInterval

Java

admin.namespaces().getDeduplicationSnapshotInterval(namespace)

중복 제거 스냅샷 간격 설정 (Set deduplication snapshot interval)

네임스페이스의 구성된 deduplicationSnapshotInterval을 설정해요. 네임스페이스 아래 각 토픽은 이 간격에 따라 중복 제거 스냅샷을 찍어요. 이 속성이 적용되려면 brokerDeduplicationEnabled가 true로 설정되어야 해요.

pulsar-admin

pulsar-admin namespaces set-deduplication-snapshot-interval test-tenant/namespace1 --interval 1000

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/deduplicationSnapshotInterval

Java

admin.namespaces().setDeduplicationSnapshotInterval(namespace, 1000)

중복 제거 스냅샷 간격 제거 (Remove deduplication snapshot interval)

네임스페이스의 구성된 deduplicationSnapshotInterval을 제거해요(네임스페이스 아래 각 토픽은 이 간격에 따라 중복 제거 스냅샷을 찍어요).

pulsar-admin

pulsar-admin namespaces remove-deduplication-snapshot-interval test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/deduplicationSnapshotInterval

Java

admin.namespaces().removeDeduplicationSnapshotInterval(namespace)

네임스페이스 격리 (Namespace isolation)

Pulsar 격리 정책을 사용해 네임스페이스에 리소스(브로커와 부키)를 할당할 수 있어요.

브로커에서 네임스페이스 언로드 (Unload namespaces from a broker)

현재 담당하고 있는 Pulsar 브로커에서 네임스페이스 또는 네임스페이스 번들을 언로드할 수 있어요.

pulsar-admin

namespaces 명령의 unload 하위 명령을 사용해요.

pulsar-admin namespaces unload my-tenant/my-ns

REST API: PUT /admin/v2/namespaces/{tenant}/{namespace}/unload

Java

admin.namespaces().unload(namespace)

엔트리 필터 정책 구성 (Configure entry filters policy)

엔트리 필터 정책 설정 (Set entry filters policy)

엔트리 필터는 서버 쪽에서 메시지를 필터링하는 데 도움을 줘요.

pulsar-admin

pulsar-admin namespaces set-entry-filters \
    --desc "The description of the entry filter to be used for user help." \
    --entry-filters-name "The class name for the entry filter." \
    --entry-filters-dir "The directory for all the entry filter implementations." \
    test-tenant/namespace1

REST API: POST /admin/v2/namespaces/{tenant}/{namespace}/entryFilters

Java

admin.namespaces().setEntryFilters(namespace, new EntryFilters("desc", "classes name", "class files localtion"))

엔트리 필터 정책 가져오기 (Get entry filters policies)

주어진 네임스페이스의 구성된 엔트리 필터를 가져올 수 있어요.

pulsar-admin

pulsar-admin namespaces get-entry-filters test-tenant/namespace1

REST API: GET /admin/v2/namespaces/{tenant}/{namespace}/entryFilters

Java

admin.namespaces().getEntryFilters(namespace);

엔트리 필터 정책 제거 (Remove entry filters policies)

주어진 네임스페이스의 엔트리 필터 정책을 제거할 수 있어요.

pulsar-admin

pulsar-admin namespaces remove-entry-filters test-tenant/namespace1

REST API: DELETE /admin/v2/namespaces/{tenant}/{namespace}/entryFilters

Java

admin.namespaces().removeEntryFilters(namespace)

더 알아보기 (Learn more)

  • 네임스페이스 관련 전체 명령은 pulsar-admin의 namespaces 명령 참고서를 확인해요.
  • REST API 엔드포인트 상세는 /admin/v2/namespaces 문서를 참고해요.
  • Java admin API의 namespaces 메서드는 PulsarAdmin 객체 문서에서 볼 수 있어요.
  • 네임스페이스와 번들의 내부 개념이 궁금하다면 핵심 개념 문서를 참고해요.