Under the Hood (If Things Go Wrong)

Behind the scenes, KuboCD creates several Flux resources to manage the deployment.

You can inspect these resources to debug problems or understand the internals.

Check the events bound to the Release which was previously created:

kubectl describe release podinfo1

There are Events for each Flux resources create:

......
Events:
  Type    Reason                 Age   From     Message
  ----    ------                 ----  ----     -------
  Normal  OCIRepositoryCreated   49s   release  Created OCIRepository "kcd-podinfo1"
  Normal  HelmRepositoryCreated  45s   release  Created HelmRepository "kcd-podinfo1"
  Normal  HelmReleaseCreated     44s   release  Created HelmRelease "podinfo1-main"

All of these resources are created in the same namespace as the Release object (default in this sample).

The OCIRepository

This Flux resource pulls the KuboCD package image:

kubectl get OCIRepository

NAME           URL                                      READY   STATUS                                                                                                           AGE
kcd-podinfo1   oci://quay.io/kubodoc/packages/podinfo   True    stored artifact for digest '6.7.1-p01@sha256:985e4e2f89a4b17bd5cc2936a0b305df914ae479e0b8c96e61cb22725b61cd24'   9m1s

Tip

If the release is stuck in the WAIT_OCI state, check this resource and its events. Common issues include:

Incorrect URL
Image still private (set to public or provide authentication)

You can manually delete this resource to trigger a refresh:

kubectl delete ocirepository kcd-podinfo1

KuboCD will recreate it.

This can be useful to force a reload of a modified OCI image, without waiting for the sync period.

The HelmRepository

As the podinfo Helm the chart is embedded in the package, it must be served to Flux via an internal Helm repository.

KuboCD creates a HelmRepository resource pointing to its internal server:

kubectl get HelmRepository

NAME           URL                                                                            AGE    READY   STATUS
kcd-podinfo1   http://kubocd-ctrl-controller-helm-repository.kubocd.svc/hr/default/podinfo1   105m   True    stored artifact: revision 'sha256:d8db03cf45ecd75064c2a2582812dc4df5cd624d0e295b24ff79569bf46a070b'

This step rarely causes errors unless the internal controller is unreachable.

The HelmRelease

This Flux resource handles the actual Helm chart deployment.

kubectl get HelmRelease

NAME                AGE     READY   STATUS
podinfo1-main   7m29s   True    Helm install succeeded for release default/kcd-podinfo1-main.v1 with chart podinfo@6.7.1

Note

There will be one HelmRelease per module in the package.

If the release is stuck in WAIT_HREL, inspect this resource:

kubectl describe helmrelease podinfo1-main

.....
Events:
  Type    Reason            Age    From             Message
  ----    ------            ----   ----             -------
  Normal  HelmChartCreated  4m38s  helm-controller  Created HelmChart/default/default-podinfo1-main with SourceRef 'HelmRepository/default/kcd-podinfo1'
  Normal  InstallSucceeded  4m37s  helm-controller  Helm install succeeded for release default/podinfo1-main.v1 with chart podinfo@6.7.1

One of the point to check in case of problem is the generated values for the Helm chart deployment.

Note

You will need to install the yq command.

kubectl get HelmRelease podinfo1-main -o yaml | yq '.spec.values'

ingress:
  className: nginx
  enabled: true
  hosts:
    - host: podinfo1.ingress.kubodoc.local
      paths:
        - path: /
          pathType: ImplementationSpecific

Note

If deployment fails, you may need to wait for the Helm timeout to expire (default: 2 minutes) to have the failure reason. You can configure this value in the Package or in the Release.