From 397882968c9ba534e95d630cc8a27edce1449bde Mon Sep 17 00:00:00 2001 From: He-Pin Date: Sat, 9 May 2026 23:49:09 +0800 Subject: [PATCH] docs: link published management docs Motivation: Eligible upstream source commit https://github.com/akka/akka-core/commit/f3a1da23268300e7ed85b53f6a4f8b863b872199, which is now Apache licensed, improved navigation from core documentation to Management documentation. The rolling updates page from that change has not been released for Pekko yet, so this port should only link published Management pages. Modification: Convert published Pekko Management documentation links to Paradox extrefs and fix directly related documentation typos. Result: Core documentation resolves checked extrefs for available Management pages without pointing readers at unreleased rolling update content. Tests: - sbt docs/paradox - git diff --check References: Refs upstream source commit: https://github.com/akka/akka-core/commit/f3a1da23268300e7ed85b53f6a4f8b863b872199 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/main/paradox/additional/deploying.md | 9 ++++----- docs/src/main/paradox/additional/rolling-updates.md | 2 +- docs/src/main/paradox/common/other-modules.md | 11 +++++------ docs/src/main/paradox/coordination.md | 2 +- .../paradox/project/downstream-upgrade-strategy.md | 2 +- docs/src/main/paradox/split-brain-resolver.md | 4 ++-- docs/src/main/paradox/typed/cluster-membership.md | 2 +- docs/src/main/paradox/typed/cluster-sharding.md | 2 +- 8 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/src/main/paradox/additional/deploying.md b/docs/src/main/paradox/additional/deploying.md index c8eadef86b6..fb9f5730ac4 100644 --- a/docs/src/main/paradox/additional/deploying.md +++ b/docs/src/main/paradox/additional/deploying.md @@ -5,19 +5,19 @@ project.description: How to deploy an Apache Pekko Cluster to Kubernetes and Doc ## Deploying to Kubernetes -Deploy to Kubernetes according to the guide and example project for [Deploying a Pekko Cluster to Kubernetes]($pekko.doc.dns$/docs/pekko-management/current/kubernetes-deployment/index.html), but that requires more expertise of Kubernetes. +Deploy to Kubernetes according to the guide and example project for @extref:[Deploying a Pekko Cluster to Kubernetes](pekko-management:kubernetes-deployment/index.html), but that requires more expertise of Kubernetes. ### Cluster bootstrap -To take advantage of running inside Kubernetes while forming a cluster, -[Pekko Cluster Bootstrap]($pekko.doc.dns$/docs/pekko-management/current/bootstrap/) helps forming or joining a cluster using Pekko Discovery with +To take advantage of running inside Kubernetes while forming a cluster, +@extref:[Pekko Cluster Bootstrap](pekko-management:bootstrap/) helps forming or joining a cluster using Pekko Discovery with the Kubernetes API or Kubernetes via DNS to discover peer nodes. You can look at the @java[[Cluster with Kubernetes example project](https://github.com/apache/pekko-samples/tree/main/pekko-sample-cluster-kubernetes-java)] @scala[[Cluster with Kubernetes example project](https://github.com/apache/pekko-samples/tree/main/pekko-sample-cluster-kubernetes-scala)] to see what this looks like in practice. - + ### Resource limits To avoid CFS scheduler limits, it is best not to use `resources.limits.cpu` limits, but use `resources.requests.cpu` configuration instead. @@ -50,4 +50,3 @@ the allowed CPU usage even when more CPU cycles are available from the host syst starved of CPU time, but your system appears idle. For this reason, it is best to avoid `--cpus` and `--cpu-quota` entirely, and instead specify relative container weights using `--cpu-shares` instead. - diff --git a/docs/src/main/paradox/additional/rolling-updates.md b/docs/src/main/paradox/additional/rolling-updates.md index 08687000ebc..91ebd64900b 100644 --- a/docs/src/main/paradox/additional/rolling-updates.md +++ b/docs/src/main/paradox/additional/rolling-updates.md @@ -79,7 +79,7 @@ Otherwise, in the worst case cluster singletons may be migrated from node to nod overhead several times. [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with `RollingUpdate` -strategy will roll out updates in this preferred order, from newest to oldest. +strategy will roll out updates in this preferred order, from newest to oldest. ## Cluster Shutdown diff --git a/docs/src/main/paradox/common/other-modules.md b/docs/src/main/paradox/common/other-modules.md index c59a5951a78..8da5f7b6929 100644 --- a/docs/src/main/paradox/common/other-modules.md +++ b/docs/src/main/paradox/common/other-modules.md @@ -40,9 +40,8 @@ A Pekko Persistence journal and snapshot store for use with R2DBC-compatible dat ## Apache Pekko Management -* [Pekko Management]($pekko.doc.dns$/docs/pekko-management/current/) provides a central HTTP endpoint for Pekko management extensions. -* [Pekko Cluster Bootstrap]($pekko.doc.dns$/docs/pekko-management/current/bootstrap/) helps bootstrapping a Pekko cluster using Pekko Discovery. -* [Pekko Management Cluster HTTP]($pekko.doc.dns$/docs/pekko-management/current/cluster-http-management.html) provides HTTP endpoints for introspecting and managing Pekko clusters. -* [Pekko Discovery for Kubernetes, Consul, Marathon, and AWS]($pekko.doc.dns$/docs/pekko-management/current/discovery/) -* [Kubernetes Lease]($pekko.doc.dns$/docs/pekko-management/current/kubernetes-lease.html) - +* @extref:[Pekko Management](pekko-management:) provides a central HTTP endpoint for Pekko management extensions. +* @extref:[Pekko Cluster Bootstrap](pekko-management:bootstrap/) helps bootstrapping a Pekko cluster using Pekko Discovery. +* @extref:[Pekko Management Cluster HTTP](pekko-management:cluster-http-management.html) provides HTTP endpoints for introspecting and managing Pekko clusters. +* @extref:[Pekko Discovery for Kubernetes, Consul, Marathon, and AWS](pekko-management:discovery/) +* @extref:[Kubernetes Lease](pekko-management:kubernetes-lease.html) diff --git a/docs/src/main/paradox/coordination.md b/docs/src/main/paradox/coordination.md index 1a3b4c88b37..e7eca7a7e5c 100644 --- a/docs/src/main/paradox/coordination.md +++ b/docs/src/main/paradox/coordination.md @@ -80,7 +80,7 @@ Leases can be used for @ref[Split Brain Resolver](split-brain-resolver.md#lease) ## Lease implementations -* [Kubernetes API]($pekko.doc.dns$/docs/pekko-management/current/kubernetes-lease.html) +* @extref:[Kubernetes API](pekko-management:kubernetes-lease.html) ## Implementing a lease diff --git a/docs/src/main/paradox/project/downstream-upgrade-strategy.md b/docs/src/main/paradox/project/downstream-upgrade-strategy.md index d49db9c02a9..5c741507893 100644 --- a/docs/src/main/paradox/project/downstream-upgrade-strategy.md +++ b/docs/src/main/paradox/project/downstream-upgrade-strategy.md @@ -4,7 +4,7 @@ project.description: Upgrade strategy for downstream libraries # Downstream upgrade strategy When a new Pekko version is released, downstream projects (such as -[Pekko Management]($pekko.doc.dns$/docs/pekko-management/current/), +@extref:[Pekko Management](pekko-management:), [Pekko HTTP]($pekko.doc.dns$/docs/pekko-http/current/) and [Pekko gRPC]($pekko.doc.dns$/docs/pekko-grpc/current/)) do not need to update immediately: because of our diff --git a/docs/src/main/paradox/split-brain-resolver.md b/docs/src/main/paradox/split-brain-resolver.md index a92fa7218b7..671f0b8af84 100644 --- a/docs/src/main/paradox/split-brain-resolver.md +++ b/docs/src/main/paradox/split-brain-resolver.md @@ -345,7 +345,7 @@ before trying to acquire the lease on the minority side. There is currently one supported implementation of the lease which is backed by a [Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -in Kubernetes. It is described in the [Kubernetes Lease]($pekko.doc.dns$/docs/pekko-management/current/kubernetes-lease.html) +in Kubernetes. It is described in the @extref:[Kubernetes Lease](pekko-management:kubernetes-lease.html) documentation. This strategy is very safe since coordination is added by an external arbiter. The trade-off compared to other @@ -376,7 +376,7 @@ pekko { @@snip [reference.conf](/cluster/src/main/resources/reference.conf) { #lease-majority } -See also configuration and additional dependency in [Kubernetes Lease]($pekko.doc.dns$/docs/pekko-management/current/kubernetes-lease.html) +See also configuration and additional dependency in @extref:[Kubernetes Lease](pekko-management:kubernetes-lease.html) ## Indirectly connected nodes diff --git a/docs/src/main/paradox/typed/cluster-membership.md b/docs/src/main/paradox/typed/cluster-membership.md index e26313693b7..2c6bf793aa2 100644 --- a/docs/src/main/paradox/typed/cluster-membership.md +++ b/docs/src/main/paradox/typed/cluster-membership.md @@ -164,7 +164,7 @@ startup if a node to join have been specified in the configuration * **leave** - tell a node to leave the cluster gracefully, normally triggered by ActorSystem or JVM shutdown through @ref[coordinated shutdown](../coordinated-shutdown.md) - * **down** - mark a node as down. This action is required to remove crashed nodes (that did not 'leave') from the cluster. It can be triggered manually, through [Cluster HTTP Management]($pekko.doc.dns$/docs/pekko-management/current/cluster-http-management.html#put-cluster-members-address-responses), or automatically by a @ref[downing provider](cluster.md#downing) like @ref:[Split Brain Resolver](../split-brain-resolver.md) + * **down** - mark a node as down. This action is required to remove crashed nodes (that did not 'leave') from the cluster. It can be triggered manually, through @extref:[Cluster HTTP Management](pekko-management:cluster-http-management.html#put-cluster-members-address-responses), or automatically by a @ref[downing provider](cluster.md#downing) like @ref:[Split Brain Resolver](../split-brain-resolver.md) #### Leader Actions diff --git a/docs/src/main/paradox/typed/cluster-sharding.md b/docs/src/main/paradox/typed/cluster-sharding.md index 7a442e1cefd..c43faba2b6d 100644 --- a/docs/src/main/paradox/typed/cluster-sharding.md +++ b/docs/src/main/paradox/typed/cluster-sharding.md @@ -708,7 +708,7 @@ for more information about `min-nr-of-members`. ## Health check -An [Pekko Management compatible health check]($pekko.doc.dns$/docs/pekko-management/current/healthchecks.html) is included that returns healthy once the local shard region +An @extref:[Pekko Management compatible health check](pekko-management:healthchecks.html) is included that returns healthy once the local shard region has registered with the coordinator. This health check should be used in cases where you don't want to receive production traffic until the local shard region is ready to retrieve locations for shards. For shard regions that aren't critical and therefore should not block this node becoming ready do not include them.