Skip to content
In this Guide

In this Guide

Deep Dives

AI: Claude and Codex patterns

ConfigHub: Deploy and manage

Journey 3 of 5

My app does not fit my platform

An app assumes things about the cluster it lands on: an ingress controller of a certain class, something that issues certificates, something that scrapes metrics. You can find out whether the platform you picked provides them before anything is applied, and fix whichever side is wrong.

Time. About six minutes. Needs. cub, the workshop plugin, oras, and a network that can reach europe-west1-docker.pkg.dev. Steps 3, 5, 6 and 7 use oras to pull each Catalog bundle by digest from that registry, anonymously, and keep a copy under $TMPDIR/cub-stack-bundles for later runs. No server, no account, no cluster.

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/3-what-my-app-needs

# 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. Ask what the app needs from a platform

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.

$ cub app check shop-web.yaml

Look for three NEEDS lines: an ingress controller, cert-manager, and a Prometheus operator.

2. Look at the platform you picked first

Three Catalog parts and the app.

$ grep -E "^  name:|- name:|authored:" platform-first-try.yaml

Look for cert-manager, traefik and metrics-server, each a Catalog bundle pinned by digest, then your own shop-web file.

3. Certify the app on that platform, and get refused

$ cub stack check platform-first-try.yaml

Look for => REFUSED and the two reasons. The Ingress asks for class nginx and this platform's controller is Traefik. The ServiceMonitor needs a Prometheus operator and nothing here provides one. Both would have failed quietly on a real cluster.

4. Fix both sides

The app changes one line and moves to the traefik ingress class, because the platform already has that controller. The platform gains one part from the Catalog, kube-prometheus-stack, because the app asked for a Prometheus operator and should keep its monitoring. Two diffs show every line.

$ diff shop-web.yaml shop-web-adapted.yaml

$ diff platform-first-try.yaml platform.yaml

Lines marked < are before and lines marked > are after. Each diff exits 1 because the files differ.

5. Certify again

$ cub stack check platform.yaml

Look for => CHECKED: no conflicts across 215 objects, CRDs ordered before the resources that need them, and app needs met naming all three needs from step 1. Look at the warnings too. Certify says what it cannot see from here: five namespaces and a ClusterIssuer that must already exist on the cluster you deliver to.

6. Render the platform with the app on it

$ mkdir -p work

$ cub stack sandbox platform.yaml --out work/platform.yaml

$ grep -c "^kind:" work/platform.yaml

Every object, in the order it has to be applied. kubectl, Argo CD and Flux all take that file as it is. Look for 215, the same count the check read.

7. Save it as a workspace you can edit and check again

The workspace holds the editable parts, the manifest, the render and the verdict.

$ rm -rf work/shop-platform

$ cub stack sandbox platform.yaml --workspace work/shop-platform

$ ls work/shop-platform

Look for components, stack.yaml, rendered.yaml and result.json. Edit a component, then run cub stack check work/shop-platform/stack.yaml to check it again.

Use it on your own configuration

The README's section Continue with your own rendered app runs the same check on your own files. This is its first command, and the section goes on from there.

$ set -eu

$ umask 077

$ mkdir -p work

$ mkdir work/own-app

$ APP_YAML='/absolute/path/to/my-rendered-app.yaml'

$ cp "$APP_YAML" work/own-app/app.yaml

$ cub app check work/own-app/app.yaml

$ cub config list --role ingress

$ cub config list --role certificates

$ cub config list --role metrics

For every need the app check reports, inspect the candidate and evidence. Choose an exact listing ID yourself; the command never chooses one for you.

These Guides go further: Put an app on a platform · Compose and review a local workshop stack.

Why it happens

Checking your stack explains it.

Where it continues

Stacks · Apps. The next journey is My chart behaves differently in GitOps.