My app installs but will not start

Run it yourself

The journey is a folder in the public workshop-demo repository. Its script pauses before each command, and Enter runs it. Read each command before continuing; stop with Ctrl+C whenever you have the result you need. ConfigHub sign-in, upload and protected-update steps are optional later work, not prerequisites for the local check.

# get the journeys
$ git clone https://github.com/monadic/workshop-demo

# use the version this page describes
$ git -C workshop-demo checkout --quiet 0e91722fb417

# open this journey
$ cd workshop-demo/5-it-installs-and-never-starts

# walk the steps, one command at a time
$ ./run.sh

Or let your agent run it

Give your agent the journey's PROMPT.md and nothing else. It follows the same steps, with the same numbers, and shows you the command after each one. You decide at each step whether to go on.

Keep this page and the README from your agent. They say what each step finds, so an agent that reads them knows the answers before it starts.

The steps

These are the steps in the journey's README. Run them from the journey's folder. The output of a real run is in expected/.

# the steps write their output here
$ mkdir -p work

1. Read what the assistant wrote

An ordinary values file for a well-known chart.

2. Render it and run the usual checks

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.

$ mkdir -p work

$ helm template shop-db oci://registry-1.docker.io/bitnamicharts/mysql --version 14.0.3 --namespace shop -f values.yaml > work/mysql.yaml

$ cub config check work/mysql.yaml

Every line passes, including the image line: the image is pinned to a version, which is what you want. The chart itself still downloads, because the chart was never withdrawn.

3. Ask whether the images can be pulled at all

$ cub config check work/mysql.yaml --images

Look for NOT FOUND: docker.io/bitnami/mysql:9.4.0-debian-12-r1. The chart is fine, the values are fine, and the image this chart runs is gone. This is the one part of check that uses the network, which is why it is a flag.

4. Read the Workshop's own record of that

$ curl -s -o work/receipt.json https://raw.githubusercontent.com/confighub/helm-expt/main/runs/bitnami-source-fetch/all-originals-receipt.json

$ grep -E '"(chart|reference|status|legacyStatus)":' work/receipt.json

For each pinned Bitnami chart the Workshop keeps, the receipt records the image it runs and whether that image resolves. mysql and rabbitmq report not-found, with the same tag available under bitnamilegacy, which receives no updates. The other four run an image tagged latest.

5. Check what the Catalog offers instead

$ helm template shop-db mysql-operator --repo https://mysql.github.io/mysql-operator/ --version 2.3.1 --namespace shop --include-crds > work/successor.yaml

$ cub config check work/successor.yaml --images

The Catalog's reviewed successor for MySQL is the operator from Oracle's own MySQL team. Its images pull, and the check names the five CRDs it carries. The Catalog reviewed version 2.3.0, which the upstream chart repository no longer serves, so this renders 2.3.1, the release that replaced it.

--include-crds matters: helm template leaves a chart's CRDs out unless you ask for them, so without it this render is 8 objects and the check reads CRDs: 0 for a chart that ships five. Say plainly what the move costs. This is an operator, so it installs a controller and not a database, and the shop then needs a custom resource and a Secret you write. None of the old values carry over.

6. Prove it on a real cluster

Optional, and off by default.

$ DEMO_CLUSTER=1 ./run.sh 6

It builds a throwaway cluster with kind, installs the chart that passed every local check, and shows the pods. Look for ImagePullBackOff on the same image --images called NOT FOUND, and for the fact that helm install said nothing. ./run.sh --reset deletes the cluster. It touches no other cluster or kubeconfig you have.

Use it on your own configuration

The README's section Use the image check in your own CI runs the same check on your own files. This is its first command, and the section goes on from there.

$ cub config check path/to/rendered.yaml --images --exit-code

Exit 0 means every discovered image manifest was checked anonymously. Exit 1 means a registry confirmed that at least one image is missing. Exit 2 means the check was incomplete, such as a network or authentication failure, or the command was invalid. The ordinary cub config check ... --images command in step 3 remains advisory and does not fail the build. This gate checks images found by the static image extractor at the time it runs; it does not prove startup, scheduling, chart compatibility, or application health.

These Guides go further: Did your Bitnami chart stop pulling?.

Why it happens

What this project does not claim explains it.

How the check knows

cub config check --images reads every container image in the rendered objects, normalises each name the way a registry expects it, and asks that registry for the image's manifest with no credentials. The answers are pulls, NOT FOUND, needs credentials for a private image your cluster may still be able to pull, and could not be checked. Nothing is installed and nothing is downloaded but the manifest.

Where it continues

Configs, with the image state in each row.