Skip to content

feat(docker): add attachable Hubble Compose add-on for the 3-node cluster - #3149

Open
bitflicker64 wants to merge 2 commits into
apache:masterfrom
bitflicker64:hubble-compose-addon
Open

feat(docker): add attachable Hubble Compose add-on for the 3-node cluster#3149
bitflicker64 wants to merge 2 commits into
apache:masterfrom
bitflicker64:hubble-compose-addon

Conversation

@bitflicker64

Copy link
Copy Markdown
Contributor

What this PR does

Adds an attachable Hubble deployment for the distributed Compose topology:

  • docker/docker-compose-hubble.yml (new) — defines only the Hubble
    service. It joins the pre-created cluster network and has no depends_on
    on cluster services, so attaching, upgrading, or removing Hubble never
    recreates PD, Store, or Server containers.
  • docker/docker-compose-3pd-3store-3server.yml — adds the Server
    PD-registration and auth settings Hubble needs (cluster name, PD mode,
    per-replica REST URL, required admin password and shared token secret),
    mirroring what fix(docker): integrate Hubble with PD deployment #3143 did for the single-node file.
  • docker/hugegraph-hubble-3x3.properties (new) — Hubble topology
    config for the 3-node cluster.
  • docker/README.md — documents the three flows: attach to a running
    cluster, fresh cluster + Hubble in one command, and a local Hubble image
    override for development.
  • .github/workflows/server-ci.yml — extends the existing compose
    contract checks to the cluster file and the add-on.
  • Doc call-site updates (root/server/pd/store docs) — the old documented
    commands no longer work with the required-credential guards.

Design rationale (why it is shaped this way)

  • Add-on file over duplication: the add-on defines only Hubble and
    merges with the canonical cluster file via -f flags, so the topology
    is never maintained in two places. This is the pattern Elastic documents
    for attaching Kibana to a running Elasticsearch over a shared Docker
    network with versions matched through one variable, and the attach model
    TiDB Operator provides via its standalone TidbDashboard resource.
  • Pre-created external network: Compose validates external: networks
    before creating project networks and refuses to adopt unlabeled ones, so
    both files declare the shared network as external with a well-known name
    (hugegraph-net, override via HUGEGRAPH_NETWORK) and setup includes a
    one-time docker network create. Verified empirically; the generated
    per-project network name cannot support the one-command fresh flow.
  • Explicit -p hugegraph-hubble for the attach flow: without it the
    attach project takes the directory name, colliding with other projects
    and making documented lifecycle commands cross project boundaries.
  • latest as the current default: the authenticated PD/Hubble
    integration is not in 1.7.x, so pinning to an existing release would
    ship a broken combination. Once the next release publishes, the default
    should move to that tag; deployments pin today via HUGEGRAPH_VERSION
    in docker/.env. (Unpinned latest with no compatibility story is the
    documented failure mode of Dgraph's Ratel — hence the single shared
    version variable.)

Breaking change owned by this PR

Existing 3-node deployments: the first up -d after this change recreates
all nine containers (network move; named volumes survive), and the graph
APIs begin requiring authentication (401 for previously anonymous
clients). The README carries an upgrade note covering .env creation,
the orphaned old network, and verifying sign-in before decommissioning
existing access paths.

Validation evidence

  • Fresh combined up: 10/10 containers healthy; Hubble login through PD
    (HTTP 200, role SUPERADMIN); Operations view shows 1 logical Server +
    3 PD + 3 Store, all UP.
  • Attach flow: cluster brought up alone, container IDs recorded; one
    add-on command attached Hubble; all cluster container IDs unchanged.
  • Single-node regression: docker/docker-compose.yml path unaffected and
    healthy.
  • CI checks replicated locally (positive and negative cases).

…ster

Add docker-compose-hubble.yml, a Hubble-only add-on that joins the
cluster's pre-created external network (HUGEGRAPH_NETWORK, default
hugegraph-net) with no depends_on, so attaching, upgrading, or removing
Hubble never recreates PD, Store, or Server containers. Attach flow uses
an explicit project (-p hugegraph-hubble); the fresh flow brings up
cluster plus Hubble in one command with both -f flags.

Give the 3-node cluster the Server settings Hubble's PD mode requires:
PD registration (HG_SERVER_CLUSTER/USE_PD/REST_URL per replica via a
shared env anchor), a required shared auth token secret so tokens
validate on every replica, and a required admin password. The Server
healthcheck now probes the bound REST URL. Hubble reads the 3x3 topology
from hugegraph-hubble-3x3.properties.

Document the attach, fresh, and dev-override flows plus migration notes
in docker/README.md, update the cluster call sites across the docs, and
extend the CI compose contract checks to the cluster file and add-on.
Image tags stay on latest until the 1.8.0 release publishes; pin via
HUGEGRAPH_VERSION in docker/.env.
@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. feature New feature labels Aug 10, 2026
…in compose checks

Render the combined cluster+Hubble topology with non-default network and
version values and assert the overridden network name and all four image
tags, so CI fails if any Compose file stops honoring either override. The
standalone add-on render keeps asserting the defaults and now strips any
runner-level overrides for hermeticity.
@codecov

codecov Bot commented Aug 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 34.74%. Comparing base (4f1a8b3) to head (620f7ff).

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3149      +/-   ##
============================================
- Coverage     39.30%   34.74%   -4.57%     
- Complexity      264      498     +234     
============================================
  Files           771      782      +11     
  Lines         65915    67065    +1150     
  Branches       8754     8951     +197     
============================================
- Hits          25910    23302    -2608     
- Misses        37241    41163    +3922     
+ Partials       2764     2600     -164     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New feature size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Add a Hubble Compose add-on to attach the dashboard to a running cluster

1 participant