Add a tutorial for the Helix Gateway Service

The Gateway service is the main architectural addition in 2.0.0, but
the 2.0.1 docs mentioned it only in passing: six word-mentions across
two pages, no tutorial page, and no entry in the tutorial outline.

Add tutorial_gateway.md, written from the helix-gateway source, link it
from the tutorial outline, and add a short Gateway section with a
topology figure to the README.

The page describes the Gateway as an additional participation mode
rather than a replacement. The 2.0.0 release notes call it "replacing
the legacy state transition message approach", but helix-core carries
no reference to the Gateway and no dependency on helix-gateway, so the
controller cannot tell a Gateway-backed participant from any other and
emits the same state transition messages either way. The Gateway joins
through the ordinary participant API and registers a catch-all
@Transition handler, and the embedded participant API is not
deprecated. What actually changes is where the Helix client and its
ZooKeeper connection live.

For the same reason the page avoids claiming the Gateway collapses
ZooKeeper usage to a single connection. A HelixGatewayParticipant is
created per connecting instance, and each one constructs its own
ZKHelixManager and calls connect(), so N app nodes mean N connections
consolidated into the Gateway process rather than eliminated, and the
Gateway becomes a component whose availability affects every instance
behind it.

The page also covers the state transition translation rules, the gRPC
contract, a client-side quick start, a 1.x-versus-2.0 comparison,
channel configuration with its defaults, and the current limitations:
OnlineOffline is the only supported state model and hybrid channel
modes are unsupported.

Three figures are included. They are referenced the way every other
Helix page references images, which resolves against the generated site
rather than the repository layout.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
6 files changed
tree: 71020c73bebc0a9891cc8ed8f17a74c61cd96f54
  1. .github/
  2. helix-agent/
  3. helix-common/
  4. helix-core/
  5. helix-gateway/
  6. helix-lock/
  7. helix-rest/
  8. helix-view-aggregator/
  9. meta-client/
  10. metadata-store-directory-common/
  11. metrics-common/
  12. recipes/
  13. scripts/
  14. website/
  15. zookeeper-api/
  16. .asf.yaml
  17. .gitignore
  18. AGENTS.md
  19. build
  20. bump-snapshot-mac.sh
  21. bump-snapshot.sh
  22. bump-up.sh
  23. deploySite.sh
  24. helix-style-intellij.xml
  25. helix-style.xml
  26. hpost-review.sh
  27. LICENSE
  28. NOTICE
  29. pom.xml
  30. README.md
  31. SECURITY.md
  32. THREAT_MODEL.md
README.md

Apache Helix

Helix CI Maven Central License codecov.io Flaky Tests Track

Helix Logo

Helix is part of the Apache Software Foundation.

Project page: http://helix.apache.org/

Mailing list: http://helix.apache.org/mail-lists.html

Build

mvn clean install -Dmaven.test.skip.exec=true

WHAT IS HELIX

Helix is a generic cluster management framework used for automatic management of partitioned, replicated and distributed resources hosted on a cluster of nodes. Helix provides the following features:

  1. Automatic assignment of resource/partition to nodes
  2. Node failure detection and recovery
  3. Dynamic addition of Resources
  4. Dynamic addition of nodes to the cluster
  5. Pluggable distributed state machine to manage the state of a resource via state transitions
  6. Automatic load balancing and throttling of transitions

Helix Gateway Service (2.0)

Helix 2.0 adds the Helix Gateway Service, which lets an application join a Helix-managed cluster over gRPC without embedding the Helix library or opening its own ZooKeeper connection. The embedded participant model from 1.x is unchanged and remains fully supported.

Helix 1.x embedded participants compared with the Helix 2.0 Gateway service