CLI reference

The controller manager binary also exposes small operator-facing CLI commands. When invoked with Kubernetes manager flags, it starts the controller. When invoked with a Kuvryn Sync subcommand, it talks to the current kubeconfig context.

Every command that reads the cluster takes -n or --namespace. It defaults to default, not to the kubeconfig context’s namespace. Flags may come before or after the arguments.

Read commands

List Applications:

ksync apps -n default
ksync applications --namespace default

The read commands print a table whose columns are aligned with spaces:

NAME       SYNC              HEALTH   DESIRED       DEPLOYED      SERVICEACCOUNT
podinfo    AwaitingApproval  Unknown  a30f1c2e9b7d                podinfo-deployer
guestbook  Synced            Healthy  b939e830aae1  b939e830aae1  guestbook-deployer

List Repositories:

ksync repos -n default
ksync repositories --namespace default

Read one Repository:

ksync repo get platform -n default

Read one Application:

ksync get payments -n default
ksync status payments -n default

List Application history, newest first by when each Revision’s rollout started, or by when it was created before it has:

ksync history payments -n default

NAME                  PHASE       REVISION      APPROVED BY
podinfo-b939e830aae1  RolledBack  a30f1c2e9b7d  system:admin
podinfo-1a77a0f91d12  Failed      dd50c3a1f2e4  system:admin

APPROVED BY names who approved the Revision’s current plan, and shows — when no approval covers it: the Revision has none, is AwaitingApproval, where any approval it still carries was for an earlier plan, or its desired state changed since it was approved. The plan digest of a deployed Revision moves on as Kuvryn Sync re-plans it against the live state, so the approval of the rollout it ran still counts.

Export the audit trail, oldest first by creation, with every recorded approver, plan digest, start and completion times, and outcome. Failure messages are redacted:

ksync history payments -n default -o json

Read one Revision summary:

ksync revision payments-abc123 -n default

Plan output

Print the plan of the Revision an Application currently wants deployed:

ksync plan payments -n default

That is the Revision for its desired state, not the newest one created: the target of a pending rollback, from the moment it is requested, which is the Revision of the rollback’s commit awaiting approval if there is one, else the Revision the rollback chose (sync.kuvryn.io/rollback-target-revision); otherwise the Revision of status.desiredRevision, such as one awaiting approval; or, while a completed rollback holds the desired commit, the rollback target the Application keeps running. Among several Revisions of that commit it shows the newest one no rollback holds. Without such a Revision it shows the newest one.

The text output names the Revision object, its commit and its phase. A plan awaiting approval ends with the exact command that approves it; it passes -n when you gave one or the namespace is not default:

Application: podinfo
Revision:    podinfo-b939e830aae1
Commit:      b939e830aae1c0ffee
Phase:       AwaitingApproval

0 changed
2 created
0 deleted
0 unchanged

Approve with: ksync sync podinfo -n ksync-demo --revision podinfo-b939e830aae1

Render a plan from a saved Revision object:

kubectl get revision payments-abc123 -o yaml > revision.yaml
ksync plan payments -f revision.yaml

Structured output is available:

ksync plan payments -n default -o json
ksync plan payments -n default -o yaml

Structured output has application, revision (the commit), revisionName, phase and plan.

Plan output is bounded and redacted. Secret values and sensitive fields must not appear in CLI output.

Mutation commands

Approve an exact Revision for a manual sync policy (ksync approve is an alias):

ksync sync payments -n default --revision payments-abc123

The command prints the Revision’s plan digest and approves exactly that digest; if the plan changes before the request is admitted, it is refused and you review ksync plan again. Running it again after an ApprovalStale Event re-approves the new plan. The approval is recorded under your own Kubernetes identity; see Manual approval.

Request rollback to the newest known-good Revision, Healthy or deployed by an earlier rollback, whose source revision is neither the desired nor the deployed one. The command fails when there is none:

ksync rollback payments -n default

Request rollback to a specific Revision object:

ksync rollback payments -n default --revision payments-abc123

The command names the Revision object it rolls back to in sync.kuvryn.io/rollback-target-revision. On an Application with manual sync, the rollback is also the approval of that Revision, while it renders the desired state its last completed rollout deployed and the sync policy and strategy are the ones you asked under: the command says that it approves and deploys it, under whose Kubernetes identity, and that no ksync sync is needed:

rollback requested for podinfo to podinfo-b939e830aae1 (a30f1c2e9b7d)
the request approves and deploys podinfo-b939e830aae1 as system:admin while it renders what it deployed; no ksync sync is needed
holding dd50c3a1f2e4 once the rollback completes

If the Application’s path, render settings or service account changed since that Revision was built, the rollback plans a new Revision of the commit from the current spec. The command says so instead, names the new Revision, and prints the ksync plan and ksync sync --revision commands that review and approve it, with -n outside the default namespace; with automatic sync, it says that Revision deploys. Running ksync rollback again while a request is pending keeps that request’s record; if spec.sync or spec.strategy changed since, the command says the request no longer approves the target and prints the ksync sync command. If the chosen Revision renders differently from what it deployed when Kuvryn Sync re-plans it, for example after a Helm valuesFrom change, or spec.sync or spec.strategy changed after the request, it also waits for ksync sync, with a RollbackTargetChanged Event. A Revision that never deployed in a completed rollout is not approved by a rollback; the command says so and prints the ksync sync command. With automatic sync the second line is the request deploys <revision>. When no requester was recorded, the command says the target awaits approval and prints the ksync sync command for it. See Rollback.

The command records the desired revision as the one rolled back from. Once the rollback completes, that revision is held: it is not deployed again, even with automatic sync, until a new commit arrives. Rolling back explicitly to a held Revision lifts its hold. The target must belong to the Application. ksync approve refuses a held Revision. See Rollback.

Suspend or resume reconciliation:

ksync suspend payments -n default
ksync resume payments -n default

Diagnosis

Explain why an Application is not Healthy. The command prints the Ready condition when it is False, such as a SourceFailure or RetryBlocked, the latest Revision failure, and every cause recorded in status.diagnosis, each with its chain from the unhealthy managed resource down to the root cause. When Ready repeats the Revision failure’s reason and message, it is printed once, as the failure:

ksync diagnose payments -n default

payments: health Degraded, sync OutOfSync
Failure: HealthFailure: One or more resources are degraded
Causes (1):

1. MissingSecret  Secret/payments/db
   Secret payments/db does not exist; Pod api-7d9f-x2k: CreateContainerConfigError: ...
   Deployment/payments/api
   └─ ReplicaSet/payments/api-7d9f
      └─ Pod/payments/api-7d9f-x2k
         └─ Secret/payments/db

See Reading a diagnosis.

Resource graph

Print the live resource graph of an Application: its managed resources, the ReplicaSets, Pods and EndpointSlices below them, and the ConfigMaps, Secrets, claims, volumes and ServiceAccounts they refer to:

ksync graph payments -n default
ksync graph payments -n default -o json
ksync graph payments -n default -o dot | dot -Tsvg > payments.svg

By default it prints a text tree, in the style of ksync diagnose’s chains: each managed resource, then what it leads to, each line naming the edge type:

payments: 1 managed resource, 4 objects, 1 missing
Deployment/payments/api
├─ Owns ReplicaSet/payments/api-7d9f
│  ├─ Owns Pod/payments/api-7d9f-x2k
│  │  └─ Uses Secret/payments/db  (missing)
│  └─ Uses Secret/payments/db  (missing)
└─ Uses Secret/payments/db  (missing)

An object reached again is marked shown above instead of being expanded twice, and a managed resource another one leads to is marked managed, since it has its own tree; references that are optional are marked optional. Objects no managed resource leads to are listed after the tree, under Not linked to a managed resource, and failed reads under Could not read.

-o json prints sorted nodes and edges, as before the text tree became the default; -o dot prints Graphviz DOT. A node marked missing is referenced but does not exist; one marked unreadable could not be checked, and unread (a comment in DOT) lists the lists that failed, such as could not list Pods: forbidden. See Resource graph and diagnosis for the edges.

The command reads the cluster with your own kubeconfig credentials, so it shows only what you may read. It needs, in the Application’s destination namespace:

  • get on the Application, in its own namespace;
  • list on every kind in the Application’s status.managedKinds;
  • list on replicasets, pods and endpointslices;
  • get on the objects they refer to: configmaps, secrets, serviceaccounts, persistentvolumeclaims, services, any HorizontalPodAutoscaler target, and cluster-scoped persistentvolumes.

Secrets, ConfigMaps and ServiceAccounts are listed and read as metadata only, so their data never leaves the API server; Kubernetes RBAC still asks for the list and get verbs on them. A kind you may not list is left out, and a reference you may not read is marked unreadable.

drift currently aliases the Application read path:

ksync drift payments -n default

Web console 

ksync console --session-key-file /etc/ksync/session/session-key
ksync console --oidc-issuer-url https://dex.example.com --oidc-client-id ksync \
  --redirect-url https://console.example.com/auth/callback \
  --session-key-file /etc/ksync/session/session-key

Serves the read-only web console, which reads the cluster as each signed-in user. People sign in with a Kubernetes token; with --oidc-issuer-url and --oidc-client-id, which go together, OIDC is offered as well. ksync console --help lists every flag. See Web console for token sign-in, the Dex setup and the Helm chart values.

Help 

ksync help

Lists every command. An unknown command prints the same list.

ksync version

Prints the version.

Install helper 

ksync install

This prints the commands that install the release the binary was built from: kubectl apply of the release’s install.yaml, or the Helm chart from a checkout of the release tag, with a note on pulling the image when the GHCR package is private. It does not change the cluster. For v0.6.2:

Install Kuvryn Sync v0.6.2. cert-manager must be running first.

With the release manifests:

  kubectl apply -f https://github.com/azrtydxb/kuvryn-sync/releases/download/v0.6.2/install.yaml

Or with the Helm chart, from a checkout of the release tag:

  git clone --depth 1 --branch v0.6.2 https://github.com/azrtydxb/kuvryn-sync.git
  cd kuvryn-sync
  kubectl apply -f config/crd/bases
  helm upgrade --install kuvryn-sync charts/kuvryn-sync \
    --namespace kuvryn-sync-system --create-namespace

The image ghcr.io/azrtydxb/kuvryn-sync:v0.6.2 may be private: create a pull Secret and set
image.pullSecrets with Helm, or patch the Deployment with the raw manifests.
See https://github.com/azrtydxb/kuvryn-sync/blob/v0.6.2/docs/install.md

A development build, whose version is dev or sha-<commit>, has no release to install; it says so and points to Install.

This site uses Just the Docs, a documentation theme for Jekyll.