#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

description: |
  The `pulsar-admin` tool enables you to manage Pulsar installations, including clusters, brokers, namespaces, properties, and more.
commands:
- name: broker-stats
  description: Operations to collect broker statistics
  subcommands:
  - name: allocator-stats
    description: Dump allocator stats
    argument: allocator-name
  - name: destinations
    description: Dump destination stats
    options:
    - flags: -i, --indent
      description: Indent JSON output
      default: 'false'
  - name: mbeans
    description: Dump Mbean stats
    options:
    - flags: -i, --indent
      description: Indent JSON output
      default: 'false'
  - name: monitoring-metrics
    description: dump metrics for Monitoring
    options:
    - flags: -i, --indent
      description: Indent JSON output
      default: 'false'
- name: brokers
  description: Operations about brokers
  subcommands:
  - name: list
    description: List active brokers of the cluster
    argument: cluster-name
  - name: namespaces
    description: List namespaces owned by the broker
    argument: cluster-name
    options:
    - flags: --url
      description: The URL for the broker
  - name: update-dynamic-config
    description: Update a broker's dynamic service configuration
    options:
    - flags: --config
      description: Service configuration parameter name
    - flags: --value
      description: Value for the configuration parameter value specified using the `--config` flag
  - name: list-dynamic-config
    description: Get list of updatable configuration name
  - name: get-all-dynamic-config
    description: Get all overridden dynamic-configuration values
- name: clusters
  description: Operations about clusters
  subcommands:
  - name: get
    description: Get the configuration data for the specified cluster
    argument: cluster-name
  - name: create
    description: Provisions a new cluster. This operation requires Pulsar super-user privileges.
    argument: cluster-name
    options:
    - flags: --broker-url
      description: The URL for the broker service.
    - flags: --broker-url-secure
      description: The broker service URL for a secure connection
    - flags: --url
      description: service-url
    - flags: --url-secure
      description: service-url for secure connection
  - name: update
    description: Update the configuration for a cluster
    argument: cluster-name
    options:
    - flags: --broker-url
      description: The URL for the broker service.
    - flags: --broker-url-secure
      description: The broker service URL for a secure connection
    - flags: --url
      description: service-url
    - flags: --url-secure
      description: service-url for secure connection
  - name: delete
    description: Deletes an existing cluster
    argument: cluster-name
  - name: list
    description: List the existing clusters
- name: namespaces
  description: Operations about namespaces
  subcommands:
  - name: list
    description: Get the namespaces for a property
    argument: property-name
  - name: list-cluster
    description: Get the namespaces for a property in the cluster
    argument: property/cluster
  - name: destinations
    description: Get the destinations for a namespace
    argument: property/cluster/namespace
  - name: policies
    description: Get the policies of a namespace
    argument: property/cluster/namespace
  - name: create
    description: Create a new namespace
    argument: property/cluster/namespace
    options:
    - flags: -b, --bundles
      description: The number of bundles to activate
      default: 0
  - name: delete
    description: Deletes a namespace
    argument: property/cluster/namespace
  - name: permissions
    description: Get the permissions on a namespace
    argument: property/cluster/namespace
  - name: grant-permission
    description: Grant permissions on a namespace
    argument: property/cluster/namespace
    options:
    - flags: --actions
      description: Actions to be granted (`produce` or `consume`)
    - flags: --role
      description: The client role to which to grant the permissions
  - name: revoke-permission
    description: Revoke permissions on a namespace
    argument: property/cluster/namespace
    options:
    - flags: --role
      description: The client role from which to revoke the permissions
  - name: set-clusters
    description: Set replication clusters for a namespace
    argument: property/cluster/namespace
    options:
    - flags: -c, --clusters
      description: Replication clusters ID list (comma-separated values)
  - name: get-clusters
    description: Get replication clusters for a namespace
    argument: property/cluster/namespace
  - name: get-backlog-quotas
    description: Get the backlog quota policies for a namespace
    argument: property/cluster/namespace
  - name: set-backlog-quota
    description: Set a backlog quota for a namespace
    argument: property/cluster/namespace
    example: |
      pulsar-admin namespaces set-backlog-quota my-prop/my-cluster/my-ns \
      --limit 2G \
      --policy producer_request_hold
    options:
    - flags: -l, --limit
      description: The backlog size limit (for example `10M` or `16G`)
    - flags: -p, --policy
      description: |
        The retention policy to enforce when the limit is reached. The valid options are:
        * `producer_request_hold`
        * `producer_exception`
        * `consumer_backlog_eviction`
  - name: remove-backlog-quota
    description: Remove a backlog quota policy from a namespace
    argument: property/cluster/namespace
  - name: get-persistence
    description: Get the persistence policies for a namespace
    argument: property/cluster/namespace
  - name: set-persistence
    description: Set the persistence policies for a namespace
    argument: property/cluster/namespace
    options:
    - flags: -a, --bookkeeper-ack-quorom
      description: The number of acks (guaranteed copies) to wait for each entry
      default: 0
    - flags: -e, --bookkeeper-ensemble
      description: The number of bookies to use for a topic
      default: 0
    - flags: -w, --bookkeeper-write-quorum
      description: How many writes to make of each entry
      default: 0
    - flags: -r, --ml-mark-delete-max-rate
      description: Throttling rate of mark-delete operation (0 means no throttle)
  - name: get-message-ttl
    description: Get the message TTL for a namespace
    argument: property/cluster/namespace
  - name: set-message-ttl
    description: Set the message TTL for a namespace
    options:
    - flags: -ttl, --messageTTL
      description: Message TTL in seconds
      default: 0
  - name: get-retention
    description: Get the retention policy for a namespace
    argument: property/cluster/namespace
  - name: set-retention
    description: Set the retention policy for a namespace
    argument: property/cluster/namespace
    options:
    - flags: -s, --size
      description: The retention size limits (for example `10M` or `16G`)
    - flags: -t, --time
      description: "The retention time in minutes, hours, days, or weeks. Examples: `100m`, `13h`, `2d`, `5w`."
  - name: unload
    description: Unload a namespace or namespace bundle from the current serving broker.
    argument: property/cluster/namespace
    options:
    - flags: -b, --bundle
      description: # `{start_boundary}_{end_boundary}`
  - name: clear-backlog
    description: Clear the backlog for a namespace
    argument: property/cluster/namespace
    options:
    - flags: -b, --bundle
      description: # `{start_boundary}_{end_boundary}`
    - flags: -f, --force
      description: Whether to force a clear backlog without prompt
      default: 'false'
    - flags: -s, --sub
      description: The subscription name
  - name: unsubscribe
    description: Unsubscribe the given subscription on all destinations on a namespace
    argument: property/cluster/namespace
    options:
    - flags: -b, --bundle
      description: # `{start_boundary}_{end_boundary}`
    - flags: -s, --sub
      description: The subscription name
- name: ns-isolation-policy
  description: Operations for managing namespace isolation policies.
  subcommands:
  - name: set
    description: Create/update a namespace isolation policy for a cluster. This operation requires Pulsar superuser privileges.
    argument: cluster-name policy-name
    options:
    - flags: --auto-failover-policy-params
      description: Comma-separated `name=value` auto failover policy parameters
      default: '[]'
    - flags: --auto-failover-policy-type
      description: "Auto failover policy type name. Currently available options: `min_available`."
      default: '[]'
    - flags: --namespaces
      description: Comma-separated namespaces regex list
      default: '[]'
    - flags: --primary
      description: Comma-separated primary broker regex list
      default: '[]'
    - flags: --secondary
      description: Comma-separated secondary broker regex list
      default: '[]'
  - name: get
    description: Get the namespace isolation policy of a cluster. This operation requires Pulsar superuser privileges.
    argument: cluster-name policy-name
  - name: list
    description: List all namespace isolation policies of a cluster. This operation requires Pulsar superuser privileges.
    argument: cluster-name
  - name: delete
    description: Delete namespace isolation policy of a cluster. This operation requires superuser privileges.
- name: persistent
  description: Operations on persistent topics
  subcommands:
  - name: list
    description: Get the list of topics under a namespace
    argument: property/cluster/namespace
  - name: permissions
    description: Get the permissions on a topic. Retrieve the effective permissions for a desination. These permissions are defined by the permissions set at the namespace level combined (union) with any eventual specific permissions set on the topic.
    argument: persistent://property/cluster/namespace/topic
  - name: grant-permission
    description: Grant a new permission to a client role on a single topic
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: --actions
      description: Actions to be granted (`produce` or `consume`)
    - flags: --role
      description: The client role to which permissions are to be granted
  - name: revoke-permission
    description: Revoke permissions to a client role on a single topic. If the permission was not set at the topic level, but rather at the namespace level, this operation will return an error (HTTP status code 412).
    argument: persistent://property/cluster/namespace/topic
  - name: lookup
    description: Look up a topic from the current serving broker
    argument: persistent://property/cluster/namespace/topic
  - name: bundle-range
    description: Get the namespace bundle which contains the given topic  
    argument: persistent://property/cluster/namespace/topic
  - name: delete
    description: Delete a topic. The topic cannot be deleted if there are any active subscriptions or producers connected to the topic.
    argument: persistent://property/cluster/namespace/topic
  - name: unload
    description: Unload a topic
    argument: persistent://property/cluster/namespace/topic    
  - name: subscriptions
    description: Get the list of subscriptions on the topic
    argument: persistent://property/cluster/namespace/topic
  - name: unsubscribe
    description: Delete a durable subscriber from a topic
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -s, --subscription
      description: The subscription to delete
  - name: stats
    description: Get the stats for the topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.
    argument: persistent://property/cluster/namespace/topic
  - name: stats-internal
    description: Get the internal stats for the topic
    argument: persistent://property/cluster/namespace/topic
  - name: info-internal
    description: Get the internal metadata info for the topic
    argument: persistent://property/cluster/namespace/topic
  - name: partitioned-stats
    description: Get the stats for the partitioned topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: --per-partition
      description: Get per-partition stats
      default: 'false'
  - name: skip
    description: SKip some messages for the subscription
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -n, --count
      description: The number of messages to skip
      default: 0
    - flags: -s, --subscription
      description: The subscription on which to skip messages
  - name: skip-all
    description: Skip all the messages for the subscription
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -s, --subscription
      description: The subscription to clear
  - name: expire-messages
    description: Expire messages that are older than the given expiry time (in seconds) for the subscription.
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -t, --expireTime
      description: Expire messages older than the time (in seconds)
      default: 0
    - flags: -s, --subscription
      description: The subscription to skip messages on
  - name: expire-messages-all-subscriptions
    description: Expire messages older than the given expiry time (in seconds) for all subscriptions
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -t, --expireTime
      description: Expire messages older than the time (in seconds)
      default: 0
  - name: create-partitioned-topic
    description: Create a partitioned topic
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -p, --partitions
      description: The number of partitions for the topic
      default: 0
  - name: get-partitioned-topic-metadata
    description: Get the partitioned topic metadata. If the topic is not created or is a non-partitioned topic, this will return an empty topic with zero partitions.
    argument: persistent://property/cluster/namespace/topic
  - name: delete-partitioned-topic
    description: Delete a partitioned topic. This will also delete all the partitions of the topic if they exist.
    argument: persistent://property/cluster/namespace/topic
  - name: peek-messages
    description: Peek some messages for the subscription.
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -n, --count
      description: The number of messages
      default: 1
    - flags: -s, --subscription
      description: Subscription to get messages from
  - name: reset-cursor
    description: Reset position for subscription to closest to timestamp
    argument: persistent://property/cluster/namespace/topic
    options:
    - flags: -s, --subscription
      description: Subscription to reset position on
    - flags: -t, --time
      description: "The time, in minutes, to reset back to (or minutes, hours, days, weeks, etc.). Examples: `100m`, `3h`, `2d`, `5w`."
- name: non-persistent
  description: Operations on persistent topics
  subcommands:
  - name: stats
    description: Get the stats for the topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.
    argument: non-persistent://property/cluster/namespace/topic
  - name: stats-internal
    description: Get the internal stats for the topic
    argument: non-persistent://property/cluster/namespace/topic
  - name: get-partitioned-topic-metadata
    description: Get the partitioned topic metadata. If the topic is not created or is a non-partitioned topic, this will return an empty topic with zero partitions.
    argument: non-persistent://property/cluster/namespace/topic
  - name: unload
    description: Unload a topic
    argument: non-persistent://property/cluster/namespace/topic
- name: properties
  description: Operations about properties
  subcommands:
  - name: list
    description: List the existing properties
  - name: get
    description: Gets the configuration of a property
    argument: property-name
  - name: create
    description: Creates a new property
    argument: property-name
    options:
    - flags: -r, --admin-roles
      description: Comma-separated admin roles
    - flags: -c, --allowed-clusters
      description: Comma-separated allowed clusters
  - name: update
    description: Updates a property
    argument: property-name
    options:
    - flags: -r, --admin-roles
      description: Comma-separated admin roles
    - flags: -c, --allowed-clusters
      description: Comma-separated allowed clusters
  - name: delete
    description: Deletes an existing property
    argument: property-name
- name: resource-quotas
  description: Operations about resource quotas
  subcommands:
  - name: get
    description: Get the resource quota for a specified namespace bundle, or default quota if no namespace/bundle is specified.
    options:
    - flags: -b, --bundle
      description: A bundle of the form `{start-boundary}_{end_boundary}`. This must be specified together with `-n`/`--namespace`.
    - flags: -n, --namespace
      description: The namespace
      argument: property/cluster/namespace
  - name: set
    description: Set the resource quota for the specified namespace bundle, or default quota if no namespace/bundle is specified.
    options:
    - flags: -bi, --bandwidthIn
      description: The expected inbound bandwidth (in bytes/second)
      default: 0
    - flags: -bo, --bandwidthOut
      description: Expected outbound bandwidth (in bytes/second)
      default: 0
    - flags: -b, --bundle
      description: A bundle of the form `{start-boundary}_{end_boundary}`. This must be specified together with `-n`/`--namespace`.
    - flags: -d, --dynamic
      description: Allow to be dynamically re-calculated (or not)
      default: 'false'
    - flags: -mem, --memory
      description: Expectred memory usage (in megabytes)
      default: 0
    - flags: -mi, --msgRateIn
      description: Expected incoming messages per second
      default: 0
    - flags: -mo, --msgRateOut
      description: Expected outgoing messages per second
      default: 0
    - flags: -n, --namespace
      description: The namespace as `property/cluster/namespace`, for example `my-prop/my-cluster/my-ns`. Must be specified together with `-b`/`--bundle`.
  - name: reset-namespace-bundle-quota
    description: Reset the specifed namespace bundle's resource quota to a default value.
    options:
    - flags: -b, --bundle
      description: A bundle of the form `{start-boundary}_{end_boundary}`.
    - flags: -n, --namespace
      description: The namespace as `property/cluster/namespace`, for example `my-prop/my-cluster/my-ns`.