CLI overview

The monedula-gitops binary validates, diffs and applies manifests against a live cluster, and also runs the Kubernetes operator. Every command has the form monedula-gitops <command> [flags]; each command page lists its flags.

Commands

Command	Purpose
validate	Parse and validate manifests, and their cluster references when a cluster config is given.
diff	Show the operations needed to bring live state in line with the manifests. Exits 0 with or without drift, 2 on error.
verify	Run the same comparison as diff and exit 1 on drift, for CI gating.
apply	Apply the manifests to Kafka. --dry-run previews the planned operations.
doctor	Check connectivity and operational readiness for one cluster, without manifests. Never mutates Kafka.
import cluster	Read live cluster state and generate manifests from it. Never mutates Kafka.
operator	Run the monedula-gitops Kubernetes operator.
version	Print the version, commit and build date.
completion bash, zsh, fish, powershell	Generate the autocompletion script for that shell.

Global flags

• --log-level: works on every command. Sets the verbosity of the diagnostic logs on stderr: error, warn (default), info or debug. At warn, role-name typos and RBAC-coarsening warnings are visible; debug also enables the Kafka client’s own logs.
• -v, --version: root command only. Prints the version and exits, as in monedula-gitops --version.

Manifest input

validate, diff, verify and apply read manifests:

• -f, --filename: a manifest file or directory. Repeatable. - reads manifests from stdin. At least one is required.
• -R, --recursive: recurse into directories given to -f.

Add -R when manifests sit in subdirectories, for example the tree that import cluster --output-dir writes:

monedula-gitops verify -f ./imported -R --cluster-config-file ./clusters/prod.yaml   # exits 0: no drift

Reading from stdin lets any renderer that prints manifests, such as Kustomize or helm template, feed the CLI without a temporary file:

kubectl kustomize overlays/prod | monedula-gitops apply -f - --cluster-config-file env/prod/cluster.yaml

The CLI rejects duplicate identities when it loads manifests, and exits 2: two KafkaTopic resources with the same cluster and topicName, two KafkaQuota resources for the same cluster and entity, two KafkaUser resources with the same cluster and username, or two KafkaRoleBinding resources that compile to the same role binding. Each error names both resources, for example KafkaTopic dup-orders-b collides with dup-orders-a: both resolve to topicName "dup.orders" on cluster "shared". Role bindings are compared only when a cluster config is loaded, because their identity needs the cluster’s MDS cluster IDs. The operator handles duplicates as Enforce tenancy with admission webhooks describes.

Cluster config

Commands that talk to a cluster read KafkaCluster documents from a cluster config:

• -c, --cluster-config-file: a KafkaCluster config file or directory. Repeatable.
• --cluster: select a single cluster by name.

How each command uses it:

• validate works without a cluster config and needs no running Kafka. With one, it also checks that every clusterRef names a loaded cluster.
• diff, verify and apply require a cluster config, because they compare with live state. They work against one cluster; when the config holds more than one, select it with --cluster.
• doctor and import cluster require a cluster config and take no manifests. When more than one cluster is loaded, --cluster is required.

Credentials in a cluster config resolve from environment variables (valueFrom.env) or files (valueFrom.file, relative to the cluster-config directory). Kubernetes secretKeyRef references are resolved only by the operator. Resolved secret values are never logged.

diff, verify and apply read live state only for the kinds the loaded manifests declare: a set of topic manifests issues no ACL, quota, SCRAM, Schema Registry or MDS reads, so the connecting principal needs describe rights only for the kinds its pipeline manages (Least-privilege connecting principal).

There is no built-in environment concept; Promote changes across environments shows how to lay out the files.

Output

• -o, --output: the output format, human (default), yaml or json. yaml and json produce a deterministic document. Any other value exits 2.

Command output goes to stdout, and diagnostic logs go to stderr, so stdout stays clean at any log level and can be piped. For import cluster, -o selects the format of the import summary. Without --output-dir, it writes the manifests to stdout and the summary to stderr, so the manifest stream stays pipeable; with --output-dir, it writes files and prints the summary to stdout.

Operation outcomes

apply lists the outcome of every planned operation:

Outcome	Meaning
Succeeded	The operation ran.
Failed	The operation ran and returned an error.
Skipped	A prerequisite failed in the same run, for example the topic that an ACL belongs to could not be created.
Blocked	The operation needs --allow-destructive, which was not given.
Rejected	The operation is never allowed, for example a partition decrease.
Unsupported	The operation was approved but cannot be performed, for example a replication factor change.
ReportOnly	The operation belongs to a DetectOnly or ObserveOnly resource and is only reported.
PruneDisabled	An in-scope ACL or role binding that the manifests no longer list, kept because --prune was not given.

Execution is best-effort and never rolls back: independent operations continue past failures, and running apply again converges the rest. Safety gates explains the approval and prune gates.

Exit codes

Code	Meaning
0	Success, no drift for verify, or all checks pass for doctor.
1	Drift detected. verify only; drift on ObserveOnly resources is ignored.
2	Validation, configuration or connectivity error, an apply with any failed, skipped or rejected operation, or a failed doctor check.
3	apply only: the only non-OK operations are Blocked. The plan is sound, and gated operations wait for --allow-destructive.

Unconsented prune candidates (PruneDisabled) and report-only operations on DetectOnly or ObserveOnly resources count as OK for apply. diff exits 0 whether or not it finds drift, and 2 on errors.