Skip to content

[Doc] Add Pulsar isolation #9692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Anonymitaet merged 3 commits into from
Feb 25, 2021
Merged

[Doc] Add Pulsar isolation #9692

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e66cb4
[Doc] Add Pulsar isolation
Feb 24, 2021
e68bfb5
update
Feb 25, 2021
a961ab6
update
Feb 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions site2/docs/administration-isolation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
id: administration-isolation
title: Pulsar isolation
sidebar_label: Pulsar isolation
---

In an organization, a Pulsar instance provides services to multiple teams. When organizing the resources across multiple teams, you want to make a suitable isolation plan to avoid the resource competition between different teams and applications and provide high-quality messaging service. In this case, you need to take resource isolation into consideration and weigh your intended actions against expected and unexpected consequences.

To enforce resource isolation, you can use the Pulsar isolation policy, which allows you to allocate resources (**broker** and **bookie**) for the namespace.

## Broker isolation

In Pulsar, when namespaces (more specifically, namespace bundles) are assigned dynamically to brokers, the namespace isolation policy limits the set of brokers that can be used for assignment. Before topics are assigned to brokers, you can set the namespace isolation policy with a primary or a secondary regex to select desired brokers.

You can set a namespace isolation policy for a cluster using one of the following methods.

<!--DOCUSAURUS_CODE_TABS-->

<!--Admin CLI-->

```
pulsar-admin ns-isolation-policy set options
```

For more information about the command `pulsar-admin ns-isolation-policy set options`, see [here](http://pulsar.apache.org/tools/pulsar-admin/).

**Example**

```shell
bin/pulsar-admin ns-isolation-policy set \
--auto-failover-policy-type min_available \
--auto-failover-policy-params min_limit=1,usage_threshold=80 \
--namespaces my-tenant/my-namespace \
--primary 10.193.216.* my-cluster policy-name

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
--primary 10.193.216.* my-cluster policy-name
--primary 10.193.216.* my-cluster policy-name

Explain what people should put in --primary.

```

<!--REST API-->

[PUT /admin/v2/namespaces/{tenant}/{namespace}](https://pulsar.apache.org/admin-rest-api/?version=master&apiversion=v2#operation/createNamespace)

<!--Java admin API-->

For how to set namespace isolation policy using Java admin API, see [here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/NamespacesImpl.java#L251).

<!--END_DOCUSAURUS_CODE_TABS-->

## Bookie isolation

A namespace can be isolated into user-defined groups of bookies, which guarantees all the data that belongs to the namespace is stored in desired bookies. The bookie affinity group uses the BookKeeper [rack-aware placement policy](https://bookkeeper.apache.org/docs/latest/api/javadoc/org/apache/bookkeeper/client/EnsemblePlacementPolicy.html) and it is a way to feed rack information which is stored as JSON format in znode.

You can set a bookie affinity group using one of the following methods.

<!--DOCUSAURUS_CODE_TABS-->

<!--Admin CLI-->

```
pulsar-admin namespaces set-bookie-affinity-group options
```

For more information about the command `pulsar-admin namespaces set-bookie-affinity-group options`, see [here](http://pulsar.apache.org/tools/pulsar-admin/).

**Example**

```shell
bin/pulsar-admin bookies set-bookie-rack \

@eolivelli eolivelli Feb 24, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we could cite this command
bin/pulsar-admin bookies list-bookies

that allows you to have the list of available bookies.

otherwise it is not clear to the user where to pick the bookie identifiers

this new command is available only from 2.8.0 anwards

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's decouple the documentation change into two different pull requests. The documentation here can simply be copied to other releases to improve the documentation there. bin/pulsar-admin bookies list-bookies is a separate command introduced in 2.8.0. Let's not couple them together.

When people try to set bookie track, people already know which bookie to set the track information. The bookie can be found in many different ways. I don't think we should add bookies list-bookies to confuse people.

One note that Yu can add is that the set-bookie-rack is to specify the track information for only one bookie. If people want to specify the track for all bookies, they have to run the command for individual bookie. But they can put a script when starting a bookie to set its rack.

@eolivelli eolivelli Feb 24, 2021 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bookie can be found in many different ways

the only alternative way I know is with bin/bookkeeper shell listbookies -a

As I know how BK works it is easy for me to find a way to get the list of bookies, but I am not sure that the regular user knows how the Bookie identifies itself.

I am saying this because I had to help users in the past to search for the actual bookie id in their cluster

btw I have no strong opinion on this, we cannot cite that command.
Anyone who is using pulsar-admin bookies will easily find the 'list-bookies' command

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eolivelli - listbookies serves a different purpose for people to list the available bookies. People don't use listbookies to get the list of bookies and then use set-bookie-rack to set rack for individual bookie. People should have a startup script to call set-bookie-rack when a bookie is starting up. See my other comments with @Anonymitaet. Let's avoid giving misleading information on how people should use set-bookie-rack

@eolivelli eolivelli Feb 24, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sijie I am fine with not telling about this command here in this document

For your interest pulsar-admin bookies list_bookies and bookkeeper shell listbookies -a
reports all of the existent bookies, in spite of their state.

bookkeeper shell listbookies -rw reports only the available bookies

--bookie 127.0.0.1:3181 \

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
--bookie 127.0.0.1:3181 \
--bookie 127.0.0.1:3181 \

127.0.0.1:3181 should be changed to bookie-id. The bookie id is in <hostname>:<port> format.

@Anonymitaet Anonymitaet Feb 24, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sijie thanks for your suggestions.

I think your note, --bookie bookie-id (the bookie id is in <hostname>:<port> format), and Explain what people should put in --primary. are "explanations" for the command pulsar-admin bookies set-bookie-rack, right?

Currently, both pulsar-admin bookies list-bookies and pulsar-admin bookies set-bookie-rack are not available on the pulsar-admin website, and it seems that we have the following bookie related commands but none of them are available on the pulsar-admin website.
image

Will these commands be shown on the pulsar-admin website? If so, I think the explanations talked above should be added to the command pulsar-admin bookies set-bookie-rackon the pulsar-admin website rather than here because users who want to use pulsar-admin commands would navigate to the pulsar-admin website to see descriptions, notes, and flags. And here are just example values.

For example, I added the descriptions for --primary-group and --secondary-group on the pulsar-admin website rather than every occurrence they are shown on Pulsar website docs.
image

Thoughts?

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those commands should show up. You might want to ping @tuteng to see why they don't show up.

@Anonymitaet Anonymitaet Feb 25, 2021 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, then I'll add explanations (note, --bookie bookie-id (the bookie id is in <hostname>:<port> format), and Explain what people should put in --primary.) on pulsar-admin website rather than here.

@Anonymitaet Anonymitaet Feb 25, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @tuteng, we have the following bookie related commands but none of them are shown on the pulsar-admin website, could you please take a look? thanks
image

@Anonymitaet Anonymitaet Feb 25, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @tuteng I've created an issue here: #9717

--hostname 127.0.0.1:3181 \

@sijie sijie Feb 24, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

--group group-bookie1 \
--rack rack1

bin/pulsar-admin namespaces set-bookie-affinity-group public/default \
--primary-group group-bookie1
```

<!--REST API-->

[POST /admin/v2/namespaces/{tenant}/{namespace}/persistence/bookieAffinity](https://pulsar.apache.org/admin-rest-api/?version=master&apiversion=v2#operation/setBookieAffinityGroup)

<!--Java admin API-->

For how to set bookie affinity group for a namespace using Java admin API, see [here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/NamespacesImpl.java#L1164).

<!--END_DOCUSAURUS_CODE_TABS-->
3 changes: 2 additions & 1 deletion site2/website/sidebars.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,8 @@
"administration-stats",
"administration-load-balance",
"administration-proxy",
"administration-upgrade"
"administration-upgrade",
"administration-isolation"
],
"Security": [
"security-overview",
Expand Down
79 changes: 79 additions & 0 deletions site2/website/versioned_docs/version-2.7.1/administration-isolation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
id: version-2.7.1-administration-isolation
title: Pulsar isolation
sidebar_label: Pulsar isolation
original_id: administration-isolation
---

In an organization, a Pulsar instance provides services to multiple teams. When organizing the resources across multiple teams, you want to make a suitable isolation plan to avoid the resource competition between different teams and applications and provide high-quality messaging service. In this case, you need to take resource isolation into consideration and weigh your intended actions against expected and unexpected consequences.

To enforce resource isolation, you can use the Pulsar isolation policy, which allows you to allocate resources (**broker** and **bookie**) for the namespace.

## Broker isolation

In Pulsar, when namespaces (more specifically, namespace bundles) are assigned dynamically to brokers, the namespace isolation policy limits the set of brokers that can be used for assignment. Before topics are assigned to brokers, you can set the namespace isolation policy with a primary or a secondary regex to select desired brokers.

You can set a namespace isolation policy for a cluster using one of the following methods.

<!--DOCUSAURUS_CODE_TABS-->

<!--Admin CLI-->

```
pulsar-admin ns-isolation-policy set options
```

For more information about the command `pulsar-admin ns-isolation-policy set options`, see [here](http://pulsar.apache.org/tools/pulsar-admin/).

**Example**

```shell
bin/pulsar-admin ns-isolation-policy set \
--auto-failover-policy-type min_available \
--auto-failover-policy-params min_limit=1,usage_threshold=80 \
--namespaces my-tenant/my-namespace \
--primary 10.193.216.* my-cluster policy-name
```

<!--REST API-->

[PUT /admin/v2/namespaces/{tenant}/{namespace}](https://pulsar.apache.org/admin-rest-api/?version=2.7.0&apiversion=v2#operation/createNamespace)

<!--Java admin API-->

For how to set namespace isolation policy using Java admin API, see [here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/NamespacesImpl.java#L251).

<!--END_DOCUSAURUS_CODE_TABS-->

## Bookie isolation

A namespace can be isolated into user-defined groups of bookies, which guarantees all the data that belongs to the namespace is stored in desired bookies. The bookie affinity group uses the BookKeeper [rack-aware placement policy](https://bookkeeper.apache.org/docs/latest/api/javadoc/org/apache/bookkeeper/client/EnsemblePlacementPolicy.html) and it is a way to feed rack information which is stored as JSON format in znode.

You can set a bookie affinity group using one of the following methods.

<!--DOCUSAURUS_CODE_TABS-->

<!--Admin CLI-->

```
pulsar-admin namespaces set-bookie-affinity-group options
```

For more information about the command `pulsar-admin namespaces set-bookie-affinity-group options`, see [here](http://pulsar.apache.org/tools/pulsar-admin/).

**Example**

```shell
bin/pulsar-admin namespaces set-bookie-affinity-group public/default \
--primary-group group-bookie1
```

<!--REST API-->

[POST /admin/v2/namespaces/{tenant}/{namespace}/persistence/bookieAffinity](https://pulsar.apache.org/admin-rest-api/?version=2.7.0&apiversion=v2#operation/setBookieAffinityGroup)

<!--Java admin API-->

For how to set bookie affinity group for a namespace using Java admin API, see [here](https://github.com/apache/pulsar/blob/master/pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/NamespacesImpl.java#L1164).

<!--END_DOCUSAURUS_CODE_TABS-->
3 changes: 2 additions & 1 deletion site2/website/versioned_sidebars/version-2.7.1-sidebars.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,8 @@
"version-2.7.1-administration-stats",
"version-2.7.1-administration-load-balance",
"version-2.7.1-administration-proxy",
"version-2.7.1-administration-upgrade"
"version-2.7.1-administration-upgrade",
"version-2.7.1-administration-isolation"
],
"Security": [
"version-2.7.1-security-overview",
Expand Down