Complete the local edit-and-review Guide with direct cub commands or an assistant, including saved results and a failure case.
Review an edit with cub or your assistant
Start with two local Kubernetes YAML files. This example needs Git, Node.js and cub; it needs no account or cluster. Install the Workshop plugin from the tested source revision, then copy the retained Prometheus Deployment excerpt:
New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.
git clone https://github.com/confighub/cub-workshop.git
cd cub-workshop
git checkout 569d74f968b0b60cc3d55bffe91aef22de10fa29
cub plugin install .
mkdir adapt-demo
cp examples/adapt/prometheus-before.yaml adapt-demo/before.yaml
cp adapt-demo/before.yaml adapt-demo/after.yamlIn adapt-demo/after.yaml, change only spec.replicas from 1 to 2. Leave the original unchanged, then compare:
cub config diff adapt-demo/before.yaml adapt-demo/after.yaml --json --out adapt-demo/diff.jsonExpected result: one changed object, Deployment monitoring/prometheus-server, with /spec/replicas changing from 1 to 2. The saved result includes both input hashes. The excerpt is for reviewing an edit; it is not a complete deployable Prometheus chart.
Use the same task in Claude Code or Codex
Use cub config diff on adapt-demo/before.yaml and adapt-demo/after.yaml.
Save the result to a new file adapt-demo/assistant-diff.json.
Report every changed object and field. The only intended change is Deployment
monitoring/prometheus-server /spec/replicas from 1 to 2. Flag any extra change
without hiding or repairing it. Leave both inputs unchanged. Do not upload,
deploy or contact a target. Explain which checks have not run.Recover, retain and continue
If an output file already exists, choose a new name. If an input is malformed or contains duplicate object identities, correct the input and rerun. Exit 0 means the comparison succeeded; with --exit-code, differences return 1 and errors return 2. Review the result before accepting an edit.
Move the whole adapt-demo directory to continue elsewhere. Rerun against its two files with a new output name: the hashes and findings should agree. Send the directory and the intended change to a teammate. This is a local comparison; it does not merge upstream changes, validate schemas or observe running workloads.
Read the direct CLI and both assistant trials. Both assistants flagged an additional history-limit edit and preserved the result after moving files.
Preserve intent through an upstream upgrade: the existing protected-upgrade receipt records a two-replica change surviving chart 29.8.0 to 29.9.0 in ConfigHub. That historical run is separate from this exercise and did not deploy to Kubernetes. Continue with managed variants when you have selected an organization and reviewed the destination.
What a promotion review answers
| Question | Promotion answer |
|---|---|
| What do I have? | The exact current and proposed object sets, their identities, and their differences. |
| What will it produce? | Materialize both sources before using this page. The browser compares the output; it does not run Helm, AICR, Timoni, or another processor. |
| Can this destination accept it? | Add current destination checks for the same proposed digest. Without them, the answer remains not run. |
| Did it work? | Add staging or live results only after the exact revision has been deployed. One passing target does not cover another target. |
1. Promotion review
·
| Exact configuration | |
|---|---|
| Next stage | |
| What blocks it | |
| Current result |
Redis example: both inputs use the catalog's reuse-existing-secret configuration. The default configuration is not used because it can generate or reuse a password during rendering. Both inputs also contain the recorded change from three replicas to two. This comparison contains the chart's 13 Kubernetes objects; cub installer adds the explicit Namespace as the fourteenth deployable object.
What changes
What stays the same
Before this reaches the destination
Where the changes came from
Show the most relevant field changes
| Source | Object and field | Result |
|---|
How to read inherited, overridden, upstream-added, and no-op changes.
Hooks, CRDs, and required setup
What you should test
Target results
| Target | Result | Digest | Note |
|---|
What to do next
Current file:
Proposed file:
These hashes identify the files compared in this browser. Use the proposed hash in staging and production so a later render cannot quietly replace the reviewed result.
Open the review record
Read the PromotionReview schema.
Use your own AI assistant
Download both YAML files and the review record. Then give this prompt to Claude, Codex, or the assistant you already use. It asks the assistant to work locally, explain the object changes, and keep untested claims visible.
Install the ConfigHub Workshop agent skill when you want these checks and reporting rules available for repeated reviews.
Keep and run the promotion in ConfigHub
The browser review stops before deployment. Preview commands do not change ConfigHub. The write commands are separate so you can run them only after the preview, destination checks, and approval pass.
If a downstream Space does not exist, the preview shows its one-time creation command as a comment. Create it, then run the preview again before using the write commands.
Preview
Run after approval
Open the Redis promotion, two-cluster rollout, and rollback evidence · Redis 25.5.3 · Redis 27.0.0
Test candidates, then promote the one that passed
A configuration can answer a smoke test and still be wrong for its destination. This recorded NGINX run tested three exact object sets. The destination required two ready replicas, so the one-replica candidate was not promoted. Two and three replicas passed; the stated rule selected the smaller one.
| Candidate | HTTP | Ready replicas | Destination | Decision |
|---|---|---|---|---|
replicas-1 | 60/60 | 1 | Blocked | Not promoted |
replicas-2 | 60/60 | 2 | Pass | Selected |
replicas-3 | 60/60 | 3 | Pass | Passed, not selected |
The selected object hash stayed the same in the ConfigHub base, staging, and production. Argo CD then used the ConfigHub release digest and Kubernetes reported two ready replicas.
Read the worked example · Check the recorded result
A difficult upgrade: Kube Prometheus Stack
Question: can the no-crds configuration move from 85.3.3 to 86.1.0 without breaking CRD ordering, webhook setup, or namespaces?
The checked candidate keeps 130 Kubernetes objects. The upgrade changes 111 of them. ConfigHub retains the current objects as a base and the candidate as a staging variant. Approval is required. ConfigHub publishes an exact release OCI for each version.
| Destination check | Recorded result |
|---|---|
| Namespaces | Pass: five Services remain in kube-system; monitoring objects remain in monitoring. |
| Prerequisites | Pass: two target-owned Secrets and ten established CRDs. |
| Setup work | Pass: both completed setup Jobs were replaced and the webhook certificate handoff was checked. |
| Delivery | Pass: Argo CD reconciled both exact ConfigHub release digests using server-side apply for the large CRDs. |
| Runtime | Pass: six workloads, the operator endpoint, and Kubernetes admission checks. |
This proves one chart, one version pair, one Argo CD path and one test target. Limits. Rollback, a long soak, automatic route selection and any untested cluster all remain unproven.
Read the result · Open the promotion review · Open the destination route · 85.3.3 chart page · 86.1.0 chart page
Roll back the selected release
Keep the previous approved object set and release digest. Rehearse the reverse comparison in staging, then publish that recorded object set again if the rollback is approved. The Redis proof restores one bounded desired-object release on two test clusters. Limits. Database migrations, cloud resources and other external effects stay where they are.
Check the bounded Redis rollback result · Follow the walkthrough
2. What are you changing?
Choose the job, then add the current and proposed Kubernetes YAML. Use two Catalog configurations, two Helm or AICR outputs, two configuration OCI packages, or exported YAML from the current and proposed environments. Materialize each source first so you compare the objects that will actually be delivered.
Current configuration
For example: the rendered objects that development or production uses now.
Proposed configuration
For example: the rendered objects from the new chart version or settings you want to move next.
Explain which changes came from the source and which are later edits
Add the render before later edits for each side. For Helm, these are the old and new chart renders. The browser can then separate chart or values changes from ConfigHub or environment changes.
Current source render
Proposed source render
Catalog source and intent record
Add a BaseVariantRecord when this configuration comes from the Catalog. It carries the exact source, rendered objects, OCI reference, prerequisites, routes, policy, and evidence status.
Add staging or fleet results
Use one line per target: name | pass, watch, blocked, or not-run | note | candidate digest. A partial fleet stays partial, because one passing target says nothing about the rest.
3. What this page can decide
This page compares exact object sets and records their hashes. If you add both source renders, it separates source changes from later edits. If you add a Catalog record, it carries the known hooks, CRDs, prerequisites, and evidence into the review.
Limits. It compares objects and stops there. Helm stays unrun, Kubernetes is never contacted, and hooks, CRDs, application tests and rollback all remain outside it. Target results count only when you add the result for the same proposed digest. ConfigHub is where the accepted configuration, downstream variants, approvals, release OCI, and live results can remain connected.
For a fleet rollout
The intended sequence is: choose targets by label, preview the exact target list, publish to a small wave, inspect every result, then continue or stop. The browser records target results, while selecting clusters and pausing or resuming a live wave stay outside it. Use the Sveltos fleet example for the current two-wave proof; managed pause and resume controls remain planned.
Check hooks, CRDs, and setup order · Check current evidence · Promotion instructions · Known gaps
4. What has run
These results show what the current examples prove. A partial result means that some parts have run, but the complete workflow has not.
| Need | Status | Result and limit |
|---|---|---|
| Ordered stages and parallel targets | proved | A four-cluster test moved one change through pilot, staging, and two production targets in that order. Sveltos environment rollout This was one local four-cluster run. It did not test a failed target or a large fleet. |
| The exact reviewed configuration moves | proved | Redis and NGINX tests kept the reviewed object hash through ConfigHub, release OCI, and Argo CD. Redis upgrade and rollback · Tested NGINX candidates These results cover the recorded examples, not every chart or application. |
| Tests, policy, compatibility, and approval gates | partial | Candidate tests, destination requirements, schema checks, placeholder checks, policy warnings, and approval gates have run in separate examples. Tested NGINX candidates · Apply-gate results Prior-stage success, compatibility, approval, and application tests have not all been exercised in one workflow. |
| Current sync and application health | partial | Argo CD sync, health, exact objects, ready replicas, and application checks were recorded after bounded Redis, NGINX, and inference changes. Redis upgrade and rollback · EKS inference promotion ConfigHub does not yet hold a fresh observation for every target, so an old green result must not be treated as current. |
| Approvals, workflow history, and emergency exceptions | partial | Exact revisions, approvals, promotions, releases, and rollback records are queryable in the recorded examples. Apply-policy assignments · Redis promotion history A time-bounded emergency exception and its later resolution have not been run end to end. |
| Windows, target selection, soak, pause, and resume | partial | The Sveltos test selected pilot, staging, and production targets and moved the change in waves. Sveltos environment rollout Scheduled windows, risk tiers, long soak, failed-target pause, and safe resume have not been proved. |
| Release or CI automation with optional approval | partial | Approved ConfigHub revisions have been published as OCI and pulled by delivery controllers. OCI deploy, stage, and rollout · Apply-gate results A Git or CI event starting the complete ordered workflow has not been run. |
| Separate change, reconciliation, and rollout responsibilities | proved | ConfigHub retained and published the reviewed configuration, Argo CD reconciled its digest, and Sveltos selected and updated workload clusters. Sveltos OCI delivery · Redis upgrade and rollback The separation is proved for these controllers and examples. Other delivery and rollout controllers need their own results. |
Upload a reviewed result into ConfigHub when you need ordered stages, approvals, release OCI, promotion history, and current observations to remain connected.