[ademidoff]

Ticket number: PMM-14989

Feature build: N/A - documentation only.

Based on doc-3.10.0, not main.

The problem

This is the user-facing half of PMM-14989. The reporter followed the Kubernetes page exactly,
created the PV and PVC it asks for, and still lost every database Service they had added whenever
the pod restarted or the client image was upgraded. The page was wrong in four ways at once:

• The volume was introduced as "persistent storage for PMM Client data between pod restarts" and
  then mounted at /usr/local/percona/pmm/tmp, never at config, where the Agent identity lives.
• PMM_AGENT_CONFIG_FILE was the relative config/pmm-agent.yaml, resolving under the image's
  WORKDIR and so onto the container's ephemeral layer rather than the volume.
• The workload was a Deployment, so the pod hostname, and with it the Node name, changed on every
  rollout.
• PMM_AGENT_SETUP_FORCE=1 was set, which makes PMM Server remove the Node together with every
  Service configured on it.

The first two mean nothing was ever persisted; the last two mean the Node would have been replaced
even if it had been.

The example now

A StatefulSet, whose pod name is stable and is passed to PMM_AGENT_SETUP_NODE_NAME, with the
volume claimed from a volumeClaimTemplates entry and mounted at both directories that have to
survive a restart: config for the identity, tmp for the metrics the Client buffers on disk while
PMM Server is unreachable. PMM_AGENT_CONFIG_FILE is absolute so it cannot drift from the mount,
and fsGroup: 1002 replaces the chown init container.

The force flag is gone from the manifest and documented instead as the one-off recovery for a volume
lost while its Node still exists in PMM, with the consequence spelled out.

Setup still runs on every start. That is only safe from 3.10.0, where PMM-15260 (#5890)
makes pmm-agent setup idempotent, so the page states the requirement up front - on earlier
versions this manifest still loses Services, and quietly.

Also adds a step that deletes the pod to show the identity surviving the restart, and fixes the
troubleshooting section, which pointed at pmm-client-pvc, a claim the flow no longer creates.

The sidecar example

Its deployment pattern is unchanged and correct: an ephemeral configuration file, a forced setup and
a prerun script that re-adds the database service on every start. A sidecar's lifecycle is the
database's, so it rebuilds its state rather than keeping it, which is what the Percona database
operators do too.

What it did carry was the same false promise as the standalone example. It created a 10Gi
PersistentVolume and claim for the PMM Client and declared a pod volume for them, none of which any
container ever mounted, and step 2 introduced that storage as being "for storing PMM Client and
MySQL data between pod restarts". Second commit removes the volume, the claim and the pod volume
entry, says the remaining storage is for MySQL, and states why the Client gets none - so the
removal does not read later as an omission to correct. Every volume the example declares is now
mounted by a container.

The command pages

pmm-agent setup and pmm-admin config are what the manifests on the install pages actually run, so
the pages describing them carry the same promise. They described the idempotent registration as it
stood when they were written, and one sentence had since become wrong: --force does not replace
the Node PMM Server holds the pmm-agent on when the names differ. It registers the name you gave as a
new Node and leaves the other one, with its Services, behind. That is the state the install examples
exist to avoid, so the wording is corrected on both pages.

Both now list what a re-run does rather than running it together in one paragraph, and cover what was
missing from it:

• the configuration file being left unchanged when setup did not read it, which is the pmm-admin config path
• an unverifiable PMM Server keeping the registration, warning on standard error, and still succeeding
• an encrypted configuration file needing its key before setup can tell whether the Node is registered
• a registered Node address or type being reported rather than quietly ignored
• the Agent ID --skip-registration expects, and where it may come from

The --force row in the options table matches the flag's own help text again.

Verification

No local mkdocs build - the change is confined to one page and adds no new links, so linkspector
in CI covers what a build would. The manifest itself was checked, since it is hand-written and
readers copy it verbatim:

• every manifest on the page parses as YAML, and kubectl apply --dry-run=client accepts each one
• PMM_AGENT_CONFIG_FILE resolves inside a mounted path, which is the specific defect being fixed
• no PMM_AGENT_SETUP_FORCE in the manifest
• code fences balanced across the page, and the admonition classes match those already used in
  documentation/docs

Related

• PMM-15260 Make pmm-agent Node registration idempotent #5890 - PMM-15260, the pmm-agent change this page depends on.
• PMM-14989 Retain state on client pod restart percona-helm-charts#954 - the pmm-ha chart, which already deploys its Client pods this
  way and will drop its own registration gate once 3.10.0 is out.

A release note for PMM-15260 is not yet in documentation/docs/release-notes/3.10.0.md; its ticket
asks for one, and it is not part of this PR.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[catalinaadam]

Pushed commit with a linguistic review and updated rel notes separately with 88679ab