# Answer the questions Kubara users ask

Kubara manages a cluster's add-ons: the certificate manager, the ingress
controller, monitoring, secrets and the rest of what a cluster needs before an
app can run. Kubara calls that set a platform, and so does this Guide. It does
not hand you one chart's values; it takes a platform
description, a target cluster, and a set of enabled services, and generates
the Helm charts and cluster-specific values an Argo CD bootstrap renders into
one platform's worth of objects. The Workshop treats a Kubara entry the same
way it treats every other source: generate the exact objects, check what they
need, and carry the bootstrap, secret, and CRD work forward with them.

If you run Kubara and want its add-ons governed in ConfigHub, use `cub kubara`
from [kubara-confighub](https://github.com/confighub/kubara-confighub) instead of
this Guide. Your path is `kubara generate`, then `cub kubara plan` and
`render`, which run offline, then `apply`, `handover` and `check`. `handback`
returns the hub to Git. The path has no stack step.
[Bring Kubara's managed add-ons into ConfigHub](https://confighub.github.io/helm-expt/site/bring-kubara-into-confighub.html)
gives the order and what each step changes, and the
[cub kubara guide](https://github.com/confighub/kubara-confighub/blob/main/docs/user/cub-kubara.md)
walks it. This Guide answers a different question: what a generated Kubara
platform contains, needs and carries, read as a Catalog entry.

You can work through this Guide two ways, and both use the same commands.
Read it top to bottom yourself and run each command as it appears, or hand
the whole Guide to an agent with the assistant task below and check its
answers against the same retained files. Generating a platform for the first
time needs the `kubara` CLI; every command below reads only committed files
and needs neither that CLI nor network access.

The Catalog retains one Kubara entry today, `kubara-local-platform`, at
`v0.12.0`: Argo CD, cert-manager, External Secrets, a small portal, Prometheus,
Metrics Server, and Traefik generated for one test cluster. Its retained base
resolves from its listing first:
[site/listings/kubara-local-platform-v0-12-0-base.json](../../site/listings/kubara-local-platform-v0-12-0-base.json).
Read the listing before running anything; it names the enabled services, the
object-set digest, and the flattening status for this exact entry.

[Jump to the assistant task](#give-an-assistant-the-whole-kubara-path).
Complete the setup first if this is your first Guide.

## Set up

Install the pinned Workshop plugin as described in the
[Adapt setup](./workshop-adapt-guide.md#prerequisites-and-setup). That gives
you the `cub` command surface this Guide uses. Every command below runs in
the evidence checkout, this repository, against the committed Kubara entry
under [examples/kubara/local-platform](../../examples/kubara/local-platform).
Generating a platform from scratch with the `kubara` CLI needs network access
to build the Helm chart dependencies it selects; reading the retained
generated source, the rendered objects, and the receipts does not.

## Check your agent the same way every time

Predicting the exit code and the one answering field before you run each
command is the same rule the skill states from the agent's side in
["Say What You Expect Before You Run It"](../../skills/config-workshop/SKILL.md#say-what-you-expect-before-you-run-it),
and the three moves in
[the Helm Guide's agent-checking section](./workshop-helm-questions-guide.md#check-your-agent-the-same-way-every-time)
apply here without change: make the agent cite full object identities
(`apiextensions.k8s.io/v1|CustomResourceDefinition||applications.argoproj.io`,
not "the Argo CD CRD"), compare its answer with the retained inventory or
route-intent file the question names, then run that question's gate and
confirm it rejects a wrong answer before you trust that it accepts a right
one.

One Kubara-specific habit sits beside those three. `cub variant upload`
deliberately omits rendered Secret objects, including ones whose current data
is not sensitive, so an agent reporting "77 objects retained" after upload
has overstated what actually landed. Ask it to say 75, and name the two
Secrets it expects were left out.

## 1. What does this generated platform contain, and what must already exist?

A platform team has Kubara's generated Argo CD bootstrap and wants the exact
object list and the destination prerequisites before choosing a cluster.

**Why Kubara does this.** Kubara's platform description and its target
cluster's actual capabilities are two different things. The generated objects
answer what the bootstrap will create. They do not answer what the cluster
must already provide, because a served CRD, a working Secret store, or a
completed Job are target facts, not objects the render itself contains.

This base is one already-generated, single-file object set rather than a
multi-component stack graph, so the check-rung command here is `cub config
check`, the same one every other Guide's first question uses.
[The Compose Guide](./workshop-compose-guide.md) is where `cub stack
check` and `cub stack sandbox` apply, to a separate composed stack manifest
that places this platform alongside an application; this question checks the
platform's own generated bytes.

**Run it in the evidence checkout.**

**Predict first.** Before you run it, ask your agent what this will print:
the exit code, and the one field that answers the question (here, the object
count and the four lifecycle counters for CRDs, hooks, jobs, and webhooks).
Run it. If the result matches, the explanation stands. If it differs, the
agent guessed; read the real output before trusting it.

```sh
cub config check examples/kubara/local-platform/rendered/release-objects.yaml
```

**Read the result.** Expect exit `0`. The command reports 77 objects across
eighteen kinds, including 17 `ApplicationSet`, 3 `CustomResourceDefinition`,
2 `Secret`, and 1 `Job`, and reports no required-existing namespace, because
one of the 77 objects is the `argocd` Namespace itself and every other
namespaced object in this render targets that same namespace. What `cub
config check` cannot read out of the object list is which of the three
included CRDs the 17 `ApplicationSet` objects in the same file actually
depend on being Established first, or that the one `Job` is a Helm
pre-install hook Kubara's upstream Argo CD chart uses to create a Redis
Secret before Argo CD starts; both are ordering facts about objects that are
all present, not a missing-object count.
[The generation receipt's routing summary](../../examples/kubara/local-platform/generation-receipt.yaml)
records the same shape as a fixed count: 3 CRDs, 4 Helm-hook-annotated
objects, 2 rendered Secrets `cub variant upload` will omit, and 1 External
Secrets prerequisite.

**Check the agent.** Ask it to name all three CRD identities and the Job's
purpose, then compare its answer with
[the route intent](../../examples/kubara/local-platform/route-intent.yaml),
which names the three CRDs by full identity:
`applications.argoproj.io`, `applicationsets.argoproj.io`, and
`appprojects.argoproj.io`. Then run the gate:

```sh
npm run kubara-example:verify
```

The command prints `verified Kubara v0.12.0 local platform (77 objects, 3
CRDs, 4 hook resources, 2 Secrets, 1 OCI layout)`, checking the generated
source, the rendered object count and digest, and the route-intent record
against the committed receipts for this base.

**What this does not prove.** Reading 77 generated objects establishes
nothing about the cluster. Whether the Argo CD CRDs are already Established,
whether the External Secrets CRD and its `ClusterSecretStore` exist, and
whether the two omitted Secrets have been provisioned through an approved
path are all recorded as `recorded-not-live`, not checked by this command.

**Where it goes next.** Retain the reviewed object set with the same command
the listing itself gives:

```sh
cub variant upload --dry-run --component local-platform --variant base --space kubara-local-platform-v0-12-0-base --unit-annotation workshop.confighub.com/object-set-sha256=sha256:d8061dd05c290ac90542560bcb29bd49c655b03183362da0894585275ef4a5d8 ./rendered
```

## 2. What bootstrap, secret, and ordering work travels with this platform?

A platform operator has the 77 generated objects and needs to know what work
has to happen around them, in what order, and who owns it, before Argo CD can
reconcile any of it.

**Why Kubara does this.** A generated Argo CD bootstrap mixes objects that
apply cleanly with objects that only mean something once other work has
happened: CRDs must be Established before their custom resources, a Job must
run and complete before the chart's own Secret exists, and an
`ExternalSecret` needs its CRD and a working store before it resolves. Kubara
generates the objects; it does not perform this surrounding work, so it has
to be recorded beside them rather than discovered at apply time.

**Read the record**, in the evidence checkout:
[the route intent](../../examples/kubara/local-platform/route-intent.yaml)
names four steps, each `status: recorded-not-live`.

- `argocd-crds-first` applies the three Argo CD CRDs and waits for Established
  before applying Argo CD custom resources.
- `argocd-redis-secret-init` applies the hook RBAC and the
  `kubara-platform-argocd-redis-secret-init` Job, waits for it to complete,
  then continues; the upstream Argo CD chart marks these as a Helm pre-install
  and pre-upgrade hook.
- `external-secrets-crd` checks the External Secrets CRD and the
  `test-cluster-local` `ClusterSecretStore` before applying the
  `image-pull-secret-ces` `ClusterExternalSecret`.
- `rendered-secrets` creates or binds `argocd-secret` and
  `cluster-kubernetes.default.svc` through an approved Secret path, because
  `cub variant upload` does not upload rendered Secret objects.

**Check the agent.** Ask it which of these four steps has to finish before
any Argo CD custom resource is applied, and confirm it names
`argocd-crds-first` specifically, not the Job or the ExternalSecret step.
Then run the gate:

```sh
npm run kubara-oci-delivery:verify
```

The command prints `verified the Kubara OCI delivery proof`, checking
[the live delivery proof receipt](../../runs/kubara-oci-delivery-proof/receipt.yaml)
against its recorded claim: the live trial installed the Argo CD CRDs first,
supplied the target-owned Secrets, ran the Redis initializer, packaged 69
prepared objects as a portable OCI artifact, and watched bootstrap Argo CD
reconcile that digest and create one Synced and Healthy Metrics Server
Application. The `ClusterExternalSecret` and a gRPC Ingress were deferred in
that same trial because their controllers and target data were not present.

**What this does not prove.** The route-intent record is a plan, not a
completed run, for this exact `v0.12.0` base; the live proof its gate checks
ran one kind cluster, one selected service, and a temporary OCI registry, not
the full seven-service profile this base generates. A multi-cluster wave has
not run.

**Where it goes next.** Resolve `argocd-crds-first` and
`argocd-redis-secret-init` for the destination you have chosen, in that
order, before relying on Argo CD to reconcile anything else this base
generates.

## 3. How does this platform reach more than one cluster?

A platform team has one reviewed platform base and needs to know how it
places across a fleet, not only how it renders for one test cluster.

**Why Kubara does this.** This base's `operations.target.selection` already
states the rule: pick one test cluster first, and expand only after the
platform configuration and its dependent service are healthy there.
`cub fleet plan` is the Workshop's tool for expanding a manifest into cluster
placements before anything is applied, demonstrated in
[the Helm Guide's fleet question](./workshop-helm-questions-guide.md#7-where-does-this-vulnerable-image-run-and-how-can-i-update-it-safely)
against a different, generic fleet manifest.

**Read the record**, in the evidence checkout:
[the BaseVariantRecord](../../data/base-variant-records/records/kubara-local-platform-v0-12-0-base.yaml)
states the rollout method plainly:
`pilot-cluster-then-platform-wave`, sequence "test cluster" then "selected
fleet wave," with the current rollout limit recorded as "one kind cluster and
one downstream service passed; a multi-cluster wave has not run."

**Check the agent.** Ask it whether a `cub fleet plan` run against this base
today would be reading a completed placement or previewing one that has not
happened. The honest answer is the second: no fleet manifest for this
platform exists in this repository yet, so there is nothing to run for this
question today. Do not let an agent invent one, and do not accept a
fabricated placement count in its place.

**What this does not prove.** Nothing here has expanded this base to a
second cluster. The rollout method and sequence are recorded intent, not a
placement result.

**Where it goes next.** Compose a fleet manifest that places this platform's
reviewed base across the intended clusters, then run `cub fleet plan` against
it as a dry run before any wave beyond the first test cluster. That manifest
and its dry run are the pending doorway step this Guide does not have local
evidence for yet.

## Give an assistant the whole Kubara path

Start a fresh session with this checkout prepared and ordinary tool
approvals:

```text
Walk the three questions in docs/user/workshop-kubara-guide.md in order. For
each one, run the given command, save its output to its own file, and report
the actual exit code. Name object identities in full, including API version,
kind, namespace, and name. For question 1, compare your answer with
examples/kubara/local-platform/route-intent.yaml and run
npm run kubara-example:verify. For question 2, name all four routes and their
recorded status, then run npm run kubara-oci-delivery:verify and report
whether the live trial's own scope (one kind cluster, one service) matches
this base's full seven-service profile. For question 3, state plainly that no
fleet manifest for this platform exists in this repository, and do not
report a fleet-plan result you did not run. Do not run the kubara CLI or any
cub command beyond the ones this Guide names, and do not contact a cluster,
ConfigHub, or a registry. State every boundary each question lists as not
proven, and mark anything you did not run as not checked rather than
passing.
```

Read the report against this Guide rather than accepting it. An agent that
reports "77 objects were retained in ConfigHub" has missed that two are
Secrets `cub variant upload` leaves out; the correct number is 75, and the
report should say so.

## Know what this Guide does not settle

Every answer above comes from reading generated objects and retained
receipts. That is a local result. It is not a ConfigHub record, a delivered
change, or a live-cluster proof, whatever the object count or exit code
says.

This base's flattening status is `not-assessed`, not `flatten-with-routes`
or `born-flattened`; the record says so plainly rather than picking a verdict
it has not earned. The route-intent record covers the bootstrap's own CRD,
secret, and ordering work; it does not extend to the seven referenced
platform services' own charts, each of which keeps its own separate
processing and lifecycle decisions, the same boundary
[the BaseVariantRecord](../../data/base-variant-records/records/kubara-local-platform-v0-12-0-base.yaml)
states.

The object counts and digests cited throughout this Guide are the committed
Catalog evidence for this entry:
[the BaseVariantRecord](../../data/base-variant-records/records/kubara-local-platform-v0-12-0-base.yaml)
and
[the live delivery proof](../../runs/kubara-oci-delivery-proof/receipt.yaml).
Composing a fleet manifest, running a real multi-cluster wave, and watching
the full seven-service profile reconcile and stay healthy are the pending
trial this Guide does not run. Missing coverage stays marked as not checked,
here and everywhere else.