[Doc] Add Pulsar isolation #9692

Anonymitaet · 2021-02-24T07:23:06Z

Add docs to fix #3104, #8977, and #8976.

eolivelli

thank you very much for providing this useful information !
I really missed it when I started using this feature.

I left some feedback, please take a look @Anonymitaet

eolivelli · 2021-02-24T08:20:29Z

site2/docs/administration-isolation.md

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


we should not have a pointer to a specific version 2.8.0-SNAPSHOT, probably for links to the Pulsar website itself we can use simply reletive references

@eolivelli thanks for your suggestion. While the Pulsar website itself (Pulsar Admin CLI doc) does not contain this command and the information on the "Pulsar Admin CLI" page is far behind from pulsar-admin where contains the latest information.

Seems that there was an issue (create automatic workflow) to sync contents from pulsar-admin to the Pulsar website, but no more updates for a long time. I think right now the best choice is to point users to get the latest information and we can update the link once we have a better option.

eolivelli · 2021-02-24T08:22:12Z

site2/docs/administration-isolation.md

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


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

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.

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

@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

@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

sijie · 2021-02-24T09:15:04Z

site2/docs/administration-isolation.md

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


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.

sijie · 2021-02-24T09:15:36Z

site2/docs/administration-isolation.md

+
+```shell
+bin/pulsar-admin bookies set-bookie-rack \
+--bookie 127.0.0.1:3181 \


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.

@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.

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.

Thoughts?

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

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.

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

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

sijie · 2021-02-24T09:15:42Z

site2/docs/administration-isolation.md

+```shell
+bin/pulsar-admin bookies set-bookie-rack \
+--bookie 127.0.0.1:3181 \
+--hostname 127.0.0.1:3181 \


sijie · 2021-02-24T09:16:17Z

site2/docs/administration-isolation.md

+--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


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.

Huanli-Meng

a minor comment. PTAL

Huanli-Meng · 2021-02-24T10:30:26Z

site2/docs/administration-isolation.md

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


I think it's better not to specify the specific version of pulsar-admin

@Huanli-Meng thanks for your suggestion. While the Pulsar website itself (Pulsar Admin CLI doc) does not contain this command and the information on the "Pulsar Admin CLI" page is far behind from pulsar-admin where contains the latest information.

Seems that there was an issue (create automatic workflow) to sync contents from pulsar-admin to the Pulsar website, but no more updates for a long time. I think right now the best choice is to point users to get the latest information and we can update the link once we have a better option.

@Anonymitaet I have the same concern here, it's better not to specify the version. You can use the general one http://pulsar.apache.org/tools/pulsar-admin/
or use variable for the version.

OK, I've changed them to general links.

then you can use variable, like this
http://pulsar.apache.org/tools/pulsar-admin/{{pulsar:version}}-SNAPSHOT/#-em-set-em-

@jennifer88huang this variable does not work for all cases, since for minor releases, for example, 2.6.3, http://pulsar.apache.org/tools/pulsar-admin/ does not have 2.6.3-SNAPSHOT, so I change the specific link (http://pulsar.apache.org/tools/pulsar-admin/2.8.0-SNAPSHOT/#-em-set-em-) to a general link http://pulsar.apache.org/tools/pulsar-admin/. PTAL.

[Doc] Add Pulsar isolation

9e66cb4

Anonymitaet requested review from Huanli-Meng, Jennifer88huang-zz and codelipenghui February 24, 2021 07:23

Anonymitaet mentioned this pull request Feb 24, 2021

ISSUE-8977: Add docs of how namespace broker isolation policy works streamnative/pulsar-archived#1895

Closed

codelipenghui approved these changes Feb 24, 2021

View reviewed changes

eolivelli requested changes Feb 24, 2021

View reviewed changes

sijie added this to the 2.8.0 milestone Feb 24, 2021

sijie assigned Anonymitaet Feb 24, 2021

sijie added the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Feb 24, 2021

sijie reviewed Feb 24, 2021

View reviewed changes

Huanli-Meng reviewed Feb 24, 2021

View reviewed changes

update

e68bfb5

Jennifer88huang-zz added the release/2.7.1 label Feb 25, 2021

Huanli-Meng approved these changes Feb 25, 2021

View reviewed changes

update

a961ab6

Jennifer88huang-zz approved these changes Feb 25, 2021

View reviewed changes

Anonymitaet mentioned this pull request Feb 25, 2021

[Website] pulsar-admin bookies related commands are not shown on pulsar-admin website #9717

Closed

Anonymitaet merged commit 796c011 into apache:master Feb 25, 2021

Anonymitaet deleted the 0224 branch February 25, 2021 10:02

sijie mentioned this pull request Feb 25, 2021

ISSUE-9717: [Website] pulsar-admin bookies related commands are not shown on pulsar-admin website streamnative/pulsar-archived#2211

Open

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

[Doc] Add Pulsar isolation #9692

[Doc] Add Pulsar isolation #9692

Uh oh!

Conversation

Anonymitaet commented Feb 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eolivelli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Anonymitaet Feb 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eolivelli Feb 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Anonymitaet Feb 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Huanli-Meng left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Anonymitaet Feb 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Anonymitaet commented Feb 24, 2021 •

edited

Loading

Anonymitaet Feb 24, 2021 •

edited

Loading

eolivelli Feb 24, 2021 •

edited

Loading

Anonymitaet Feb 25, 2021 •

edited

Loading

Anonymitaet Feb 25, 2021 •

edited

Loading