Make the node model workload-aware so a job can run once per deployment

[karldebisschop]

The problem

A Deployment with three replicas produces three Rundeck nodes. For most jobs
that is exactly right — you want the command on every pod. But a large class of
maintenance work must run once per deployment, not once per pod, because the
replicas share state: a database migration, a cache rebuild, a data backfill, a
scheduled cleanup, anything that writes to the backend the replicas have in
common.

Running such a job on every pod is wasteful in the best case. In the worst case
it is a correctness bug: three replicas executing the same migration
concurrently against one database is a race that testing on a single-replica
environment will never reveal, and that surfaces in production as partial
writes, duplicate rows, or deadlocks.

Why this cannot be expressed today

The resource model names each node <pod name>-<container name>, and exposes
the pod's labels. Neither gives you a way to select exactly one pod of a
deployment, durably:

• Pod names are ephemeral. billing-7f4b8bbfc6-2q2hd contains a
  pod-template-hash and a random suffix, both of which change on every rollout.
  A node filter naming a specific pod stops matching the next time you deploy.
• Labels identify the group, not a member. Filtering labels:app = billing
  selects all three replicas — which is the situation we are trying to avoid.

There is currently no stable identifier for "the deployment this pod belongs
to", and no deterministic way to pick one of its pods.

What this adds

default:workload — the owning controller with the Deployment
pod-template-hash stripped, so billing-7f4b8bbfc6-2q2hd reports billing.
Derived from the pod's controlling ownerReference rather than by parsing the
pod name, falling back to the first reference and then the pod name, so
StatefulSets, DaemonSets, Jobs and bare pods all resolve sensibly. Unlike the
pod name, this survives rollouts.

index — an ordinal within namespace/workload/container, assigned only to
pods that are actually emitted, so a filtered-out Terminated pod does not
consume a number and index == 1 always matches. Because the counter is scoped
per workload, one filter selects one pod from each deployment:

3 deployments x 3 replicas = 9 nodes
nodes matching  index == 1 : 3
     prod / billing   (billing-7f4b8bbfc6-aaaaa)
     prod / search    (search-7f4b8bbfc6-aaaaa)
  staging / billing   (billing-7f4b8bbfc6-aaaaa)

One Node Per Workload (RD_CONFIG_ONE_PER_WORKLOAD, default off) — does the
same thing at the model level for operators who would rather not rely on every
job remembering the filter. The node count then stays stable as replicas scale.

Node Name Format — node names become a ${attribute} template, so they can
be built from the stable identity rather than the ephemeral pod name, for
example ${default:namespace}-${default:workload}. The full pod name remains
available as default:name for traceability.

Custom Mapping sources now resolve against any node attribute rather than the
default:* set alone. That makes a label with an awkward key usable in a
template — service.selector=labels:app.kubernetes.io/name, then ${service} —
and fixes mappings from labels: silently producing nothing.

Compatibility

Both new behaviors are opt-in and the defaults reproduce today's output:

• The default template is ${default:name}-${default:container_name}, which is
  the historical <pod name>-<container name> exactly.
• An explicit nodename from Custom Mapping or Default attributes still wins
  over the template, so the documented nodename.selector=default:name keeps
  working. Renaming a node makes Rundeck treat it as a different node, so this
  ordering matters.
• One Node Per Workload defaults to false; the node set is unchanged unless it
  is enabled.
• default:workload and index are additive attributes.

An unset attribute renders as an empty string rather than the literal None,
so a pending pod with no podIP cannot produce my-app-None — or give several
pending pods the same name.

Testing

The resource-model suite goes from 33 to 49 tests, covering workload derivation
and controller-owner preference, per-workload numbering including the
filtered-pod case, the one-per-workload toggle, template rendering with labels
and unset attributes, explicit-nodename precedence, and mapping from a label.

[Copilot]

Pull request overview

This PR makes the Kubernetes pods resource model workload-aware so operators can target exactly one pod per Deployment (or other controller) for “run once per workload” maintenance jobs, while keeping the existing default behavior unchanged unless explicitly enabled.

Changes:

• Add a stable default:workload attribute derived from the pod’s owning controller (stripping the Deployment pod-template-hash) and an index ordinal per workload/container for deterministic replica selection.
• Add configurable node naming via a ${attribute} template (nodename_format) and a one_per_workload toggle to collapse replicas at the model level.
• Expand and update the unit test suite to cover workload derivation, indexing behavior, one-per-workload mode, and template rendering.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
plugin.yaml	Adds new plugin config options (nodename_format, one_per_workload) and updates mapping documentation.
contents/pods-resource-model.py	Implements workload derivation, per-workload indexing, node name template rendering, and one-per-workload emission behavior.
contents/tests/test_pods_resource_model.py	Adds tests covering new workload/index semantics, nodename templates, mapping-from-label behavior, and one-per-workload behavior.

Suppressed comments (1)

plugin.yaml:95

• The implementation deduplicates on namespace/workload/container (one node per workload per container). The config description currently says “single node per workload”, which can be misleading for multi-container pods where more than one node will still be emitted.

        title: One Node Per Workload?
        description: 'Emit a single node per workload (Deployment/StatefulSet/etc.) instead of one per pod, so a job runs once per deployment without every job needing an index filter. The emitted node keeps the first matching pod name in default:name; default:workload carries the stable workload name.'
        default: "false"

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[karldebisschop]

Both descriptions updated