[doc] Add a tutorial for the Helix Gateway Service

[MarkGaox]

Issues

• My PR addresses the following Helix issues and references them in the PR description:

No tracking issue — documentation-only change. Happy to file one if the project would prefer.

Description

• Here are some details about my PR:

What

Adds website/2.0.1/src/site/markdown/tutorial_gateway.md, a tutorial page for the Helix Gateway Service, links it from the tutorial outline, and adds a short Gateway section with a topology figure to the README.

Why

The Gateway service is the main architectural addition in 2.0.0, but the 2.0.1 docs mention it only in passing — six word-mentions across tutorial_admin.md and tutorial_rest_service.md, no tutorial page, and no entry in the tutorial outline.

Contents

• How the Gateway participates in a cluster, and the deployment topology compared with 1.x embedded participants.
• The state transition translation rules (ADD_SHARD / DELETE_SHARD / CHANGE_ROLE), from StateTransitionMessageTranslateUtil.
• The gRPC contract from HelixGatewayService.proto, and a client-side quick start mirroring the flow in TestGatewayServiceConnection.
• A 1.x-versus-2.0 comparison table to help choose between the two modes.
• GatewayServiceChannelConfig options with their defaults.
• Current limitations: OnlineOffline is the only supported state model (GatewayServiceManager.SUPPORTED_MULTI_STATE_MODEL_TYPES), and hybrid channel modes are unsupported.

---

Two places where the page departs from the 2.0.0 release notes

Both were checked against the source and are stated below as findings, with the evidence, so a maintainer can see the reasoning rather than take my word for it. Flagging them because the release notes read differently — if either reflects intended future direction rather than current behaviour, tell me and I will reword.

1. The Gateway is an additional participation mode; it does not replace the message flow.

The release notes say the Gateway replaces "the legacy state transition message approach". The code shows the coordination model is unchanged:

• helix-core contains no reference to the Gateway at all — grep -ril gateway helix-core/src/main/java/ returns nothing, and helix-core/pom.xml has no dependency on helix-gateway (the dependency runs the other way). The controller therefore cannot distinguish a Gateway-backed participant from any other; it emits the same state transition messages either way.
• The Gateway registers through the ordinary participant API: HelixGatewayParticipant.Builder.build() calls participantManager.getStateMachineEngine().registerStateModelFactory(...) and then participantManager.connect() (HelixGatewayParticipant.java:246-250) — the same calls tutorial_participant.md documents.
• HelixGatewayMultiTopStateStateModel extends StateModel and registers a catch-all @Transition(to = "*", from = "*") handler, which forwards to processStateTransitionMessage(Message) — a standard Helix Message.
• HelixManagerFactory, InstanceType, StateModelFactory and StateModel carry no @Deprecated annotation in 2.x.

The page therefore presents the Gateway as an additional way to participate. Describing it as a replacement would imply 1.x participants are on a deprecation path, which the code does not support.

2. The Gateway holds one ZooKeeper connection per connected app node, so connections are consolidated rather than reduced.

• GatewayServiceManager.ParticipantConnectionProcessor.run() calls createHelixGatewayParticipant(clusterName, instanceName, …) on each CONNECT event (GatewayServiceManager.java:203-206), i.e. once per connecting application instance.
• Participants are stored per instance: Map<String, Map<String, HelixGatewayParticipant>> keyed by cluster then instance (GatewayServiceManager.java:58, :241).
• Each build() constructs new ZKHelixManager(_clusterName, _instanceName, InstanceType.PARTICIPANT, _zkAddress) and calls connect() (HelixGatewayParticipant.java:242, :250).

So N connected app nodes produce N ZooKeeper connections, all held inside the Gateway process. The page and the figure are worded that way, and the page notes the sizing and availability consequences. The benefit still holds — application nodes carry no Helix dependency and open no ZooKeeper connection of their own — but it is a consolidation rather than a reduction.

A related detail: the release notes describe the service as using a poll-mode channel, whereas GatewayServiceProcessorConfigBuilder defaults ChannelMode to PUSH_MODE (GatewayServiceChannelConfig.java:159). The page documents both modes and states the default as push.

---

Note on reviewing this page

Parts of this page look wrong in GitHub's file preview but are correct in the generated site. Three conventions used throughout src/site/markdown/ resolve against the generated site rather than the repository layout, and this page follows all three as the existing pages do:

Convention	GitHub preview	Maven site	Existing pages using it
./images/…	broken	OK	all image-bearing pages
<head><title>…</title></head>	not rendered	sets the HTML <title>	26 of 31
./Tutorial.html	dead link	OK	25 of 31

To view the three figures, open the PNGs under website/2.0.1/src/site/resources/images/gateway/, or build the site. I chose not to duplicate the images into src/site/markdown/images/ purely to satisfy the preview, but I am happy to change the approach if you would prefer.

Tests

• The following tests are written for this issue:

None — documentation only; no source under the helix-* modules is touched.

• The following is the result of the "mvn test" command on the appropriate module:

Not run; this change touches only README.md and website/2.0.1/, which no test module covers.

mvn site has also not been run, as Maven was unavailable in my authoring environment, so the rendered HTML is unverified. I did validate statically: balanced code fences, ASF licence header present for RAT, <head>/<title> and breadcrumb conventions matching sibling pages, well-formed tables, and every internal link and image reference resolving to a file that exists. A site build before merge would be worthwhile, and I am glad to fix anything it turns up.

Changes that Break Backward Compatibility (Optional)

None. Documentation only.

Documentation (Optional)

This PR is the documentation change.

Commits

• My commits follow the guidelines from "How to write a good git commit message"

Code Quality

• My diff has been formatted using helix-style.xml

Not applicable — no Java source is modified.

[MarkGaox]

@junkaixue @xyuanlu Could you please take a look? Thanks.