hydra gitops review¶

Review rendered Hydra applications against live cluster targets.

CLI help recording¶

Synopsis¶

hydra gitops review app <appId> [appId...] [flags]
hydra gitops review cluster <cluster> [flags]

Description¶

The cluster review command family is the cluster-connected counterpart to hydra local review.

For the cluster-side command path, Hydra now reads template and live entities from the shared resource model: rendered sources and live targets still come from different build phases, but review consumes one normalized per-ID inventory view instead of stitching together separate command-local template and live collections.

With color output and a TTY stderr, the initial full-cluster list used for review shows the same discovery footer progress bar as hydra gitops apply (one step per listable API resource type, current GVK as detail). After discovery, cluster review · post-discovery is a single footer bar that covers both the outer preparation steps and the reference-validation substeps (template sources vs live cluster, key enrichment, target index, and scan). Ref ownership uses one cluster review · ref ownership bar for the coarse 8-step flow. When the effective --parallel value is greater than 1, the two CPU-heavy passes each open their own footer bar under it: cluster review · template vs ref ownership (per-template-id work) and cluster review · assign live resources (per live inventory object), each with one worker status line per parallel worker under that sub-bar.

hydra gitops review app — Pass one or more App IDs (with wildcards). Hydra resolves the apps, then builds a source candidate set from the rendered templates and clone materializations of those apps only, applies API version normalization so template IDs match cluster IDs, then filters that candidate set to only include resources whose IDs also exist on the live cluster. Reference findings and ref-ownership findings are limited to that app selection. In particular, ref ownership: cluster-only resource has no Hydra app assignment is not emitted here; use hydra gitops review cluster when you need that audit.
hydra gitops review cluster — Pass a cluster name (a single path segment: no . — it is not an app id). Hydra loads every application defined for that cluster in the repository, optionally narrowed by --exclude-app, and runs the same review pipeline over all those apps’ rendered sources (filtered to objects that exist on the live cluster). The live target inventory is still the full cluster snapshot. This mode does emit ref ownership: cluster-only resource has no Hydra app assignment for eligible live objects (same namespace scope as hydra gitops uninstall leftover scanning).

In both modes, references are validated primarily against live cluster entities. For namespace-local references to ServiceAccount/default or ConfigMap/kube-root-ca.crt in the same namespace as the namespaced source, Hydra may also accept targets synthesized from the full enabled-app template render (so offline manifests model defaults the API creates per namespace). Cluster-scoped sources and cross-namespace references still require a live object. Resources that are rendered but not yet deployed to the cluster are not reviewed, but references from reviewed sources to targets that do not exist on the cluster (for example a deployed Deployment referencing a Secret that has not been created yet) are still reported.

Use this command when you need to know whether referenced objects and keys exist in the API for resources that are already deployed, including targets that other teams or controllers manage outside your selected render set.

The review validates:

Kubernetes bootstrap defaults — Only hydra gitops review cluster runs a post-pass that compares the live cluster inventory to the same upstream bootstrap catalog as local review (initial namespaces, core ServiceAccounts / ConfigMaps / kubernetes Service, RBAC bootstrap ClusterRole / ClusterRoleBinding names). Each expected object that is absent is reported with the message missing cluster default resource (empty sources). hydra gitops review app omits this full-catalog audit (same scope split as unassigned ref-ownership findings). The catalog is filtered by the API server’s minor version from discovery so older clusters are not expected to include RBAC objects introduced only in newer releases. If the server version cannot be read, this audit is skipped. When the audit runs, references to a missing bootstrap object do not also emit missing target resource; the bootstrap finding covers that ID. The catalog is not distribution-specific (no k3s/k3d extensions). Namespace-local default synthesis from templates is independent of this audit and still applies when discovery cannot read a server version.
Per-namespace defaults from templates — The same default ServiceAccount and kube-root-ca.crt ConfigMap bundle as in local review is derived from namespaces seen in the enabled-app template render. It supplies the standard ca.crt key for key-aware checks. It does not satisfy cross-namespace RoleBinding / ClusterRoleBinding subjects or other references where the target namespace differs from the source’s namespace.
missing target resources such as Secret or ConfigMap reported as missing target resource when neither a matching live object exists nor a recursive, fixpoint-stabilized chain of refs whose attributes include "origin:generated": job or "origin:generated": controller (per app-declared parsers) accounts for that target, including multi-hop materialization
missing explicitly referenced keys inside live Secret and ConfigMap targets (or their generated key sets when modeled)
Ref ownership — after reference checks, every template resource id is evaluated like hydra local review: uninstall / uninstall-safe / uninstall-force / backup predicates without ref groups tagged runtime. Before that step, hydra gitops review normalizes apiVersion on the merged enabled-app render and on each app’s standalone render to the cluster’s preferred versions (same scope as source filtering), so template ids align with live objects even when charts still emit deprecated API versions (for example Strimzi Kafka / KafkaTopic at kafka.strimzi.io/v1 while the manifest shows v1beta2). For live cluster objects, Hydra uses that same non-runtime predicate set when the object’s id appears in a standalone template render, so broad runtime rules never claim template-mapped resources. When the id appears in no template (cluster-only), the full predicate set including runtime applies (aligned with hydra gitops uninstall for non-template resources). Live v1/Namespace objects whose metadata.name is listed under global.hydra.ownerNamespaces for an app are assigned to that app (after ref predicates, before metadata.ownerReferences expansion) so they are not treated as unassigned solely because the chart did not render a Namespace manifest. If ref predicates already assigned a different app to that Namespace object, the review emits ref ownership: v1/Namespace ref assignment conflicts with global.hydra.ownerNamespaces. Hydra then applies the same metadata.ownerReferences propagation as hydra gitops uninstall: once a direct owner in the live inventory is assigned to an app, children inherit that app (transitive chains such as Pod → ReplicaSet → Deployment). If owner references resolve to more than one app, the review emits ref ownership ambiguous: owner references resolve to multiple apps. If more than one app matches ref predicates alone for a cluster-only id, the review emits ref ownership ambiguous for cluster-only resource. If a cluster-only object still has no app after predicates, ownerNamespaces matching (for v1/Namespace only), and owner propagation, and it lives in a namespace in the uninstall leftover namespace set (exclusive namespaces plus every namespace from enabled apps’ renders plus every namespace declared in global.hydra.ownerNamespaces), the review may emit ref ownership: cluster-only resource has no Hydra app assignment (the same class of object that would abort hydra gitops uninstall without --force-all) — only when you run hydra gitops review cluster, not hydra gitops review app, unless the object matches an active global.hydra.presets untracked rule (builtin coredns / kubernetes / flannel plus merged overrides): preset-only matches suppress that unassigned finding. When a cluster-only object does have a Hydra app assignment and matches an active untracked preset, the review additionally emits ref ownership: cluster-only resource matches untracked preset(s) and a Hydra app assignment. For that finding, objects whose metadata.ownerReferences include a UID that resolves to another object in the live inventory are skipped so only the ownership root of each chain is reported (not child objects such as Pods or ReplicaSets when the parent workload object is also unassigned). Kubernetes-managed defaults are excluded from that unassigned finding: the same upstream bootstrap catalog as the missing cluster default resource audit, plus ServiceAccount/default and ConfigMap/kube-root-ca.crt in any namespace (the objects the API injects per namespace, matching the synthetic bundle used for reference checks).
repeated findings grouped by identical target and message

Optional Kubernetes references (optional: true on the same fields as in local review) are tagged optional:ref in the reference model and are not validated here yet (the UI graph shows that tag on edges).

Controller-managed objects often include metadata.ownerReferences on the live cluster; Hydra’s built-in parsers emit corresponding graph edges (labels controller / owner, attribute origin:owner). Templates usually omit owner references, so this is most visible when sources or targets come from the API.

Rendered sources may omit metadata.namespace on namespaced objects. Hydra normalizes those sources to the application's target namespace before running the same reference checks as local review, so source-side identities and lookups stay consistent while targets still come from the live API (with their real namespaces).

Applications with enabled: false are not rendered by Hydra, so they contribute no reference sources in this command. Targets still come only from the live API: the inventory is the full cluster snapshot Hydra loads, independent of whether an app is currently enabled in Git (objects from an earlier rollout may still be present on the cluster).

hydra local review and hydra gitops review share the same reference-review implementation; cluster mode builds sources from rendered templates and clone materializations filtered to only resources present on the cluster, and supplies targets from the live cluster inventory (without clone materializations) plus the auxiliary per-namespace default bundle from the enabled-app template render for qualifying same-namespace references. In the current cluster command implementation, those template and live sides are read back out of the same resource model. For StatefulSet volumeClaimTemplates, cluster mode also feeds the live API snapshot into the CEL inventory used while parsing sources, so edges to real PVCs can be confirmed when metadata.ownerReferences shows the StatefulSet as controller (in addition to expected PVC names from the template). This overlay applies only to hydra gitops review, not to hydra gitops refs tree aggregation.

Hydra may still collect and group all findings in memory before anything is printed; stdout is filled after that, one finding at a time in final order. By default the text output groups findings by message type (for example unassigned cluster-only ref ownership uses one heading that includes the scope note, e.g. ref ownership: cluster-only resource has no Hydra app assignment (would remain unassigned for hydra gitops uninstall in this namespace scope), with one Target line per resource and no redundant Detail line for that class), omits a Sources section when it would be empty, and may add a per-target Message or Detail line when the full text adds detail beyond the shared type. Use --yaml for the previous behavior: one YAML sequence element per finding, without marshaling the full list as a single YAML value at the end. You do not get partial findings while grouping is still running.

When findings exist, hydra gitops review exits with a non-zero status so it can be used in pre-apply checks or CI automation.