docs: unclear points about resource readiness checks about tilt.build

[lizzthabet]

@ahmetb, those are great questions! i appreciate you opening an issue to ask for better documentation.

tilt looks at pods and jobs to determine readiness for kubernetes resources. a pod is considered ready when all of its containers are ready, (which may take into account readiness probes if they're defined on a container). a job is considered ready when it has completed.

if a k8s workload object, including a CRD, doesn't create pods, there isn't a way for tilt to know when it's ready. that's why there's a pod_readiness='ignore' option, which tells tilt that it shouldn't be waiting for pods to show up to determine a resource's readiness.

there are a couple CRD examples linked in our docs, if that's helpful, or you can take a look at the knative extension for more info about what that looks like in practice.

i'll follow up with a docs pr, too.

[ahmetb]

if a k8s workload object, including a CRD, doesn't create pods, there isn't a way for tilt to know when it's ready.

I think this definition is inherently problematic. For example, Knative Service CRD creates Pods but deletes them later if they don't receive any requests. The readiness definition for many CRDs (incl. Knative) is converging towards the kstatus convention (the snippet/link I added in my original comment). So checking the Pods is not a good indicator, but the CRD itself reports its readiness.

Would it be noteworthy to consider looking at status.conditions[*].type~Ready.status=="True" to determine readiness of other resources? I suspect this convention is only going to get more widespread, and can be a good indicator, if present.

[lizzthabet]

let's move our discussion over to #3301, so other tilt folks can chime in and this issue for docs can be closed. upvotes and comments on existing issues are great, since it helps us gauge interest/need.

i'll tag you and include your comments there.

[Venryx]

For others looking for how to "wait for CRDs to be ready", the key part from the examples is here: https://github.com/tilt-dev/tilt-example-frameworks/blob/5d8554023431587916400917f2b716edebe99ad5/prometheus/Tiltfile#L39

However, I found the kubectl wait command wasn't finding the CRD I wanted it to wait for, for some reason. (probably missing a namespace indicator or something)

Anyway, I switched to using the tilt wait command instead:

k8s_resource(new_name="my-crd-definition",
	objects=[my_crd_name],
	pod_readiness="ignore")

# wait until the CRD is ready
local_resource("my-crd-definition-ready",
	cmd="tilt wait --for=condition=Ready uiresource/my-crd-definition",
	resource_deps=["my-crd-definition"])

k8s_resource("the-resource-to-start-afterward",
	resource_deps=["my-crd-definition-ready"])