service.json Is Not values.yaml

The sentence that keeps getting shortened is this one: Flisk and Helm are not alternatives.

tdk up starts Docker containers on your machine through Tilt. helm upgrade creates Deployments and Services in a cluster. service.json describes the local service. values.yaml configures Kubernetes objects. The files share a few words. They are not a translation.

The project's Helm note says there is no export command. tdk config verify checks generated project files against .tdk/project.json. It does not lint service.json, and it does not lint Helm values. tdk doctor checks whether this machine can run the local stack. A green doctor is not a green chart.

The words that look like a mapping

This table is the conceptual one from the Helm doc. Read the last column louder than the first.

You wrote this locally	Someone will look for this in the chart	Why the copy fails
appName	Release name or controller id	Identity only. Chart naming is configurable.
appType	Deployment, Job, or CronJob	A local type does not select the cluster controller.
port	service.main.ports.http.port	Confirm the container port and the Service port for the image you actually published.
healthCheckPath	Readiness or liveness path	Add the probes. Tune them. A local curl check is not a probe spec.
dependsOn	Hooks, init containers, ordering	Local startup order is not a cluster startup contract.
Traefik on *.localhost	Ingress or Gateway host	Class, DNS, and TLS are yours.
Local Postgres	External database or a chart dependency	Lifecycle, persistence, credentials, backups.

A worker is the cleanest example. Locally it is a process in a container. In the cluster it is a Job or a CronJob, and a CronJob needs a schedule. Flisk cannot infer either. A frontend that nginx and Traefik served on your laptop still needs an Ingress or a Gateway that you configure. The local route disappearing from the laptop does not create that object.

Do not copy the generated tree

.autogenerated/ is local Docker and Tilt output. .tdk/.tdk-out/ is the same family of output. Neither is a chart. The failure mode is a pull request that adds the generated Dockerfile, the generated nginx config, or the generated Tiltfile under charts/ because an agent noticed the files existed and assumed they were the deployable form.

They are not. The local image is built from golden layers that exist only on the machine that built them. Flisk does not publish that image. Before Helm can run anything, your existing CI has to build and push an image to a registry the cluster can pull. The tag in values.yaml is that image. It is not shop_orders-api:dev.

The handwritten example in the repo keeps bjw-s-labs app-template for production and pins oci://ghcr.io/bjw-s-labs/helm/app-template at 5.2.1. It shows an image repository, a tag, and an HTTP port. It intentionally leaves replicas, probes, ingress, PVCs, resources, security context, identity, and autoscaling to the person who owns the release. The example is a handoff sketch, not a supported production chart. The doc tells you to pull that pinned chart and lint the sample without installing it:

helm pull oci://ghcr.io/bjw-s-labs/helm/app-template \
  --version 5.2.1 --untar --untardir /tmp/tdk-helm-example
helm lint /tmp/tdk-helm-example/app-template \
  --values examples/one-backend-helm/values.yaml
helm template api /tmp/tdk-helm-example/app-template \
  --values examples/one-backend-helm/values.yaml

That is the whole integration. Keep the chart you already use. Flisk does not install it and does not take it over.

The review that actually catches the drift

tdk up shop can be healthy while the chart is a lie, because nothing in the local loop reads the chart. Put the check in the pull request instead.

• The image repository and tag in values point at an image CI published. Not at a local golden-layer tag.
• The container port in values was confirmed against the image, not copied from service.json because the numbers matched last month.
• Probes were added on purpose. healthCheckPath was an input to that decision, not the probe.
• A worker has an explicit Job or CronJob, and a CronJob has a schedule.
• A frontend has an Ingress or Gateway that is not *.localhost.
• No file under .autogenerated/ or .tdk/.tdk-out/ was copied into the chart.
• Secrets, IRSA, HPA, node selectors, and PVCs are still owned by the deployment, because the local manifest has nowhere to put them.

Skip Flisk entirely when helm install, Compose, or a Tiltfile you already like is the local environment. Adding service.json beside a working chart does not make the chart more true. It adds a second file that can drift.

The size of the handoff

Flisk's job ends at the laptop. Helm's job starts at the registry. The dangerous area is the inch between them, where a port, a path, and an image name look portable.

Carry those three across by hand. Then lint the chart. The CLI that started the container is not going to do it for you.