imbajin commented on code in PR #532: URL: https://github.com/apache/hugegraph-doc/pull/532#discussion_r4327977001
########## content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md: ########## @@ -31,10 +31,20 @@ Store wait and Helm test reuse existing component images with `curl` already ins PD listens on REST 8620, gRPC 8686 and Raft 8610; Store on REST 8520, gRPC 8500 and Raft 8510; Server HTTP on 8080; Hubble HTTP on 8088. Client Services hide individual Pod addresses. NodePort is a separate allocated port on reachable nodes, not the application listener port. -PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener. Store startup waits for a majority of ready PD peers. +PD `/v1/ready` requires a Raft leader. On older images, `/v1/health` only confirms the listener. +Store startup waits for a majority of ready PD peers. Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap. No local Helm rendering verifies live cluster reachability, volumes or JVM capacity. +Images containing the [fatal PD health fix](https://github.com/apache/hugegraph/pull/3358) return `503` from `/v1/health` +after a terminal Raft error or shutdown; ordinary elections and quorum loss remain live (`200`). +After a failed snapshot, repair the disk or storage problem before an operator-initiated restart; freeing space alone does not reinitialize JRaft. +The probes below may already restart a failed PD automatically. If the underlying storage fault remains, those restarts can repeat without fixing it. +When `pd.replicas` is 1, chart templates default startup and liveness probes to `/v1/ready`, which already restarts a single PD after a terminal Raft error. Review Comment: ⚠️ Important: Blocking: no. Summary: This restart guarantee is unqualified for older PD images, but some images that predate `/v1/ready` do not serve that endpoint; an unknown-path request can return HTTP 200 with an Unauthorized body, which satisfies Kubernetes' status-only `httpGet` probe and will not restart a terminal PD. Please limit this sentence to images that include the endpoint and identify the supported image boundary. Evidence: The merged #3358 API-reference note documents the unknown-path 200 response and warns that a status-only probe can treat it as ready. ########## content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md: ########## @@ -127,6 +137,21 @@ Use `store.updateStrategy.type=OnDelete` for a controlled maintenance rollout, a Delete one Store Pod at a time. Before replacing the next, verify the previous Pod is Ready, has a fresh Store heartbeat and each shard group has its full membership and exactly one leader, read from the PD leader. PD's `Up` status alone does not prove completed shard recovery. PDBs limit voluntary eviction, not StatefulSet controller disruption. Stop on missing members or leaders. + +Images containing the [Store registration fix](https://github.com/apache/hugegraph/pull/3362) register `Up` after local engine restore +and attempt to report `Offline` on graceful shutdown; PD changes its record only if it accepts the report. Upgrade PD before Store to enable the restore gate. +Shutdown reports preserve the existing keepalive window without renewing it; expiry still applies if the Store does not return. +During recovery, Offline registrations renew the returned Store's lease while its engines restore on an owned worker. +The shutdown RPC requires a privileged internal credential: set `HG_PD_AUTH_SECRET_KEY` in Store to match PD's `auth.secret-key`. Review Comment: ⚠️ Important: Blocking: no. Summary: This is a shared privileged secret, not a per-Store identity: any Store able to read it can invoke `ReportStoreShutdown` with another Store ID. Please state that scope and restrict secret access to trusted internal Store workloads. Evidence: #3362 `StoreShutdownAuthentication` gates on the shared credential, while `PDService.reportStoreShutdown` forwards the request's Store ID directly to `StoreNodeService.reportStoreShutdown`. ########## content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md: ########## @@ -127,6 +137,21 @@ Use `store.updateStrategy.type=OnDelete` for a controlled maintenance rollout, a Delete one Store Pod at a time. Before replacing the next, verify the previous Pod is Ready, has a fresh Store heartbeat and each shard group has its full membership and exactly one leader, read from the PD leader. PD's `Up` status alone does not prove completed shard recovery. PDBs limit voluntary eviction, not StatefulSet controller disruption. Stop on missing members or leaders. + +Images containing the [Store registration fix](https://github.com/apache/hugegraph/pull/3362) register `Up` after local engine restore +and attempt to report `Offline` on graceful shutdown; PD changes its record only if it accepts the report. Upgrade PD before Store to enable the restore gate. +Shutdown reports preserve the existing keepalive window without renewing it; expiry still applies if the Store does not return. +During recovery, Offline registrations renew the returned Store's lease while its engines restore on an owned worker. +The shutdown RPC requires a privileged internal credential: set `HG_PD_AUTH_SECRET_KEY` in Store to match PD's `auth.secret-key`. +If the report is refused or fails, Store still shuts down and PD retains its previous record until the existing lease expires. Review Comment: ⚠️ Important: Blocking: no. Summary: A transport failure can occur after PD has persisted the Store as Offline but before Store receives the response, so an RPC error does not prove PD retained the prior record. Please qualify this as the outcome only when PD did not process the report; for an ambiguous result, advise checking the PD record. Evidence: #3362 `PDService` calls `StoreNodeService.reportStoreShutdown` before sending the response, and that method persists the Offline state before returning. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
