Add loadbalancer documentation by dveeden · Pull Request #5555 · pingcap/docs

dveeden · 2021-04-29T16:51:44Z

What is changed, added or deleted? (Required)

Add documentation about how to use loadbalancers with TiDB

Which TiDB version(s) do your changes apply to? (Required)

dveeden · 2021-05-04T16:13:54Z

We could link this to https://docs.pingcap.com/tidb/stable/java-app-best-practices

dveeden · 2021-05-04T20:44:47Z

We should consider merging or linking this with https://docs.pingcap.com/tidb/stable/haproxy-best-practices

TomShawn · 2021-05-06T03:12:52Z

/label needs-cherry-pick-5.0
/translation doing
/assign @Liuxiaozhen12
@dveeden Could you please involve technical review(s)? Thanks!

TomShawn · 2021-05-06T03:13:45Z

We could link this to https://docs.pingcap.com/tidb/stable/java-app-best-practices

You can link this to these docs in this PR.

morgo · 2021-07-27T16:41:52Z

/merge

ti-chi-bot · 2021-07-27T16:41:55Z

@morgo: /merge in this pull request requires 2 approval(s).

Details

In response to this:

/merge

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository.

dveeden · 2021-07-28T07:19:45Z

@TomShawn PTAL

TomShawn · 2021-07-28T14:05:27Z

+
+The first type of loadbalancing that is available is *connector based loadbalancing*. Many of the MySQL connectors like MySQL Connector/J and MySQL Connector/C++. The benefits from this are that there is no extra network hop and the application has more information about which server it is connected to. The drawback of this is that there is no central administration and when changing the configuration you have to do this on all your application hosts. Depending on the programming language you are using the loadbalancing may not be available or not offer more advanced options. This can work with most third-party applications as this is often configured in the connection string (JDBC url for Java for example).
+
+It is also possible to use DNS round-robin. However this is not advisable as this won't prevent connections from going to a machine that is unavailable. This means that your application may have to re-try connections more often if not all servers are available.


If this is not advisable, then we should not document it here.

As DNS-RR is a common practice I think we should explain here why other solutions are better.

@morgo what's your take on this?

I agree with @dveeden , it's very common and users need to know why we don't recommend it.

OK, let's keep it.

TomShawn · 2021-07-28T14:36:34Z

@dveeden This is really a great article with a comprehensive introduction to loadbalancing. These are my general comments. PTAL for reference.

Some part of it, to me, looks like a blog post article that uses plain passages than a user document which usually prefers listing things out in unordered/ordered lists or tables (in a really structured layout). For example, the "Loadbalancing types" section introduces several types. It might be better to organize the information of this passage using a table, which makes your information clearer and more readable to readers.

Loadbalancing types	User scenarios	Benefits	Drawbacks
Connector-based loadbalancing, such as MySQL Connector/J and MySQL Connector/C++	This can work with most third-party applications because this is often configured in the connection string (JDBC url for Java for example).	There is no extra network hop and the application has more information about which server it is connected to.	There is no central administration. When changing the configuration on one host, you have to do this on all your application hosts.
DNS round-robin

Another question is the target audience. To me, this can be confusing. I think it would be better to clarify what this article introduces and its aim at the very beginning. Then readers will get a general idea of the article from the beginning and decide whether or not to go on reading.

If it is about the best practices of loadbalancing in TiDB, then maybe we should not introduce too much about the loadbalancing types (including the benefit and drawback, even for the unrecommended types). And its TOC position can also be changed. "Best Practices" might be a better place for it.
If it is about a task-oriented instruction/guide for TiDB maintenance, then maybe many of the concept introductions look unnecessary and can be removed.

Then it is about the language style issue. In user documentation, we usually follow these styles:

Avoid using the first person (I/me/we/us/our/let's). Mostly, use "You" or passive voice.
Avoid abbreviations (let's, don't, e.g., etc...)
Avoid using "may" because it is ambiguous. Use "might" instead.
Make sentences as short and concise as possible.
Briefly introduce/summarize each section in one or two sentences at the beginning of the section.

Co-authored-by: Morgan Tocker <tocker@gmail.com> Co-authored-by: bb7133 <bb7133@gmail.com>

dveeden · 2021-08-10T14:13:19Z

@TomShawn I went over your comments.

For the loadbalancer types I don't know if we should:

Use a table (as you suggested). This gets quite long
Use paragraphs (as the original had)
Use a table an paragraphs (current state) This avoids a table with very high/long cells.
Use subsections per type

What do you think?

dveeden · 2021-08-10T14:14:53Z

In some places (pingcap/tidb, pingcap/docs, pingcap/tidb-operator) the solution with envoy an istio is used. However I don't think that should be part of this PR as that's mostly a TiDB Operator thing.

dveeden · 2021-11-22T16:07:44Z

This has been published as a blog instead of as part of the documentation.

ti-chi-bot · 2021-11-22T16:07:52Z

@dveeden: PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

ti-chi-bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 29, 2021

ti-chi-bot requested a review from TomShawn April 29, 2021 16:51

ti-chi-bot added missing-translation-status This PR does not have translation status info. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Apr 29, 2021

dveeden force-pushed the lb branch from cc8688a to fc8a6f3 Compare April 30, 2021 07:13

ti-chi-bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Apr 30, 2021

dveeden force-pushed the lb branch 2 times, most recently from 1e0b0ae to e3ca504 Compare May 4, 2021 08:35

ti-chi-bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 4, 2021

dveeden marked this pull request as ready for review May 4, 2021 08:48

ti-chi-bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label May 4, 2021

dveeden force-pushed the lb branch 2 times, most recently from cda1411 to b4577f8 Compare May 4, 2021 09:49

dveeden mentioned this pull request May 4, 2021

TiDB Operator - Cannot connect to TiDB Service for TiDB Cluster External IP pingcap/tidb-operator#3941

Closed

ti-chi-bot assigned Liuxiaozhen12 May 6, 2021

ti-chi-bot added translation/doing This PR's assignee is translating this PR. needs-cherry-pick-5.0 and removed missing-translation-status This PR does not have translation status info. labels May 6, 2021

morgo reviewed May 31, 2021

View reviewed changes

Comment thread loadbalancing.md Outdated

TomShawn added the needs-cherry-pick-release-5.1 label Jun 22, 2021

dveeden force-pushed the lb branch from b4577f8 to e97cc87 Compare June 22, 2021 09:32

dveeden requested a review from morgo June 22, 2021 09:32

dveeden force-pushed the lb branch 2 times, most recently from 6044d7c to 0b239c6 Compare June 22, 2021 10:39

TomShawn reviewed Jul 28, 2021

View reviewed changes

dveeden marked this pull request as draft July 29, 2021 08:05

ti-chi-bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jul 29, 2021

Add loadbalancer documentation

6fbc08a

Co-authored-by: Morgan Tocker <tocker@gmail.com> Co-authored-by: bb7133 <bb7133@gmail.com>

dveeden force-pushed the lb branch from 66aa0e1 to 6fbc08a Compare August 10, 2021 14:10

dveeden marked this pull request as ready for review August 23, 2021 06:18

ti-chi-bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 23, 2021

dveeden requested a review from TomShawn August 23, 2021 06:18

morgo mentioned this pull request Aug 25, 2021

sql: improve kill's description #6233

Merged

12 tasks

TomShawn added sig/docs Indicates that the Issue or PR belongs to the docs SIG. area/sql-infra Indicates that the Issue or PR belongs to the area of sql-infra and sql-metadata. labels Sep 6, 2021

dveeden closed this Nov 22, 2021

ti-chi-bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 22, 2021

ti-chi-bot added the status/LGT1 Indicates that a PR has LGTM 1. label Nov 23, 2021

TomShawn unassigned Liuxiaozhen12 Nov 23, 2021


		The first type of loadbalancing that is available is connector based loadbalancing. Many of the MySQL connectors like MySQL Connector/J and MySQL Connector/C++. The benefits from this are that there is no extra network hop and the application has more information about which server it is connected to. The drawback of this is that there is no central administration and when changing the configuration you have to do this on all your application hosts. Depending on the programming language you are using the loadbalancing may not be available or not offer more advanced options. This can work with most third-party applications as this is often configured in the connection string (JDBC url for Java for example).

		It is also possible to use DNS round-robin. However this is not advisable as this won't prevent connections from going to a machine that is unavailable. This means that your application may have to re-try connections more often if not all servers are available.

Conversation

dveeden commented Apr 29, 2021 • edited by TomShawn Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

Uh oh!

dveeden commented May 4, 2021

Uh oh!

dveeden commented May 4, 2021

Uh oh!

TomShawn commented May 6, 2021

Uh oh!

TomShawn commented May 6, 2021

Uh oh!

Uh oh!

morgo commented Jul 27, 2021

Uh oh!

ti-chi-bot commented Jul 27, 2021

Uh oh!

dveeden commented Jul 28, 2021

Uh oh!

TomShawn Jul 28, 2021

Choose a reason for hiding this comment

Uh oh!

dveeden Jul 28, 2021

Choose a reason for hiding this comment

Uh oh!

morgo Jul 28, 2021

Choose a reason for hiding this comment

Uh oh!

TomShawn Jul 29, 2021

Choose a reason for hiding this comment

Uh oh!

TomShawn commented Jul 28, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dveeden commented Aug 10, 2021

Uh oh!

dveeden commented Aug 10, 2021

Uh oh!

dveeden commented Nov 22, 2021

Uh oh!

ti-chi-bot commented Nov 22, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

dveeden commented Apr 29, 2021 •

edited by TomShawn

Loading

TomShawn commented Jul 28, 2021 •

edited

Loading