Deploy Your First App
Deploy hello-world with Kuberik. At the end, every build your CI publishes is picked up by a ReleaseSource and deployed by a Rollout through Flux.
On this page
Before you start, you need:
- A cluster with Flux 2.6 or later.
- Kuberik installed with Helm.
- A GitHub repository, here
acme/hello-world, whose CI can push toghcr.io/acme/hello-world.
Pick Rendered manifests or Image tag in the tabs below; Propagation Modes explains the difference.
Create the namespace
Kuberik looks up the ReleaseSource, Kustomization and OCIRepository in the Rollout’s own namespace, so everything on this page goes into one namespace.
kubectl create namespace hello-worldCreate a ReleaseSource
A ReleaseSource lists the tags of an OCI repository, orders them by a policy, and keeps the result as the catalogue of releases your Rollout reads. CI tags each build main-<sha>-<timestamp>, and the policy orders by the timestamp.
Scan the manifest artifact CI pushes for the production environment.
apiVersion: kuberik.com/v1alpha1
kind: ReleaseSource
metadata:
name: hello-world
namespace: hello-world
spec:
oci:
image: ghcr.io/acme/hello-world/production/manifests
filterTags:
pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)$'
extract: '$ts'
policy:
numerical:
order: asc # highest timestamp winsScan the container image your application is built into. The setup is the same as for rendered manifests apart from the repository path.
apiVersion: kuberik.com/v1alpha1
kind: ReleaseSource
metadata:
name: hello-world
namespace: hello-world
spec:
oci:
image: ghcr.io/acme/hello-world
filterTags:
pattern: '^main-[a-f0-9]+-(?P<ts>[0-9]+)$'
extract: '$ts'
policy:
numerical:
order: asc # highest timestamp winskubectl apply -f releasesource.yamlIts READY column reads False until CI has pushed the first tag; that is expected at this point. For a private registry, see Pull from a private registry: the ReleaseSource takes the pull secret, and so does the OCIRepository in the Rendered manifests steps. Releases are kept for 7 days, and at least 30 are always kept; change this with spec.retention.
Create the Rollout
The Rollout reads releases from the ReleaseSource and decides which one to deploy. The HealthCheck follows the Flux Kustomization you create in the next step, and the Rollout selects it, so a deploy succeeds only after Flux has applied it and it stayed healthy for the bake time. Both resources are identical in the two modes.
apiVersion: kuberik.com/v1alpha1
kind: HealthCheck
metadata:
name: hello-world
namespace: hello-world
labels:
app: hello-world
annotations:
healthcheck.kuberik.com/kustomization: "hello-world"
spec:
class: kustomization
---
apiVersion: kuberik.com/v1alpha1
kind: Rollout
metadata:
name: hello-world
namespace: hello-world
spec:
releaseSourceRef:
name: hello-world
bakeTime: 5m # healthy this long
deployTimeout: 10m
healthCheckSelector:
selector:
matchLabels:
app: hello-worlddeployTimeout fails a deploy whose health checks are not healthy within 10 minutes; without it, a bad build waits in Deploying forever and holds every newer release. Without a health check, the bake starts as soon as Kuberik writes the tag, so the deploy succeeds bakeTime later whether or not Flux applied anything. See Verify with Health Checks for the other checks.
kubectl apply -f rollout.yamlConnect Flux
Create the Flux objects the Rollout drives. The annotation names the Rollout that owns them.
Kuberik moves spec.ref.tag on the annotated OCIRepository. The Kustomization applies the artifact at that tag, so the cluster needs no substitution variable and no build tooling.
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: hello-world
namespace: hello-world
annotations:
rollout.kuberik.com/rollout: "hello-world"
spec:
interval: 1m
url: oci://ghcr.io/acme/hello-world/production/manifests
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: hello-world
namespace: hello-world
spec:
interval: 10m
prune: true
sourceRef:
kind: OCIRepository
name: hello-world
targetNamespace: hello-worldCI renders that artifact from the production overlay in acme/hello-world and builds the image from the Dockerfile beside it:
Dockerfile
deploy/
production/
kustomization.yaml
deployment.yamlapiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yamlapiVersion: apps/v1
kind: Deployment
metadata:
name: hello-world
spec:
selector:
matchLabels:
app: hello-world
template:
metadata:
labels:
app: hello-world
spec:
containers:
- name: app
image: ghcr.io/acme/hello-world # CI pins the build's tagUntil the first release, the OCIRepository pulls latest, which CI never pushes, so it reads Ready False. This clears when Kuberik writes the first tag.
Here Flux reads the manifests from a GitRepository; an OCIRepository or Bucket works the same. Kuberik writes the selected tag into postBuild.substitute on the annotated Kustomization.
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: hello-world
namespace: hello-world
spec:
interval: 1m
url: https://github.com/acme/hello-world
ref:
branch: main
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: hello-world
namespace: hello-world
annotations:
rollout.kuberik.com/substitute.APP_VERSION.from: "hello-world"
spec:
interval: 10m
path: ./deploy/production
prune: true
sourceRef:
kind: GitRepository
name: hello-world
targetNamespace: hello-worldThe Deployment in deploy/production of acme/hello-world reads the substitution variable:
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-world
spec:
selector:
matchLabels:
app: hello-world
template:
metadata:
labels:
app: hello-world
spec:
containers:
- name: app
image: ghcr.io/acme/hello-world:${APP_VERSION}Until the first release, Kuberik has no tag to write, so Flux applies the image with a literal ${APP_VERSION}: the Kustomization reads Ready while the pod sits in InvalidImageName. This clears when the first release is deployed.
kubectl apply -f flux.yamlPublish a release
Add the workflow for your mode to acme/hello-world and push a commit to main. Both workflows build the image from the Dockerfile at the repository root.
deploy/ with that image’s tag and pushes each as an artifact with the same tag. Here that is deploy/production alone, so it pushes ghcr.io/acme/hello-world/production/manifests.main-<sha>-<timestamp> tag.The ReleaseSource lists the new tag within a minute, and the Rollout deploys it.
Check the result
The ReleaseSource shows the newest tag it found and how many releases are in its catalogue.
kubectl get releasesource -n hello-world hello-worldNAME NEWEST COUNT READY AGE
hello-world main-3f9c2ab-1794583200 1 True 2mThe Rollout records each deploy in status.history, newest first. Deploying means Kuberik wrote the tag and waits for the health check to report healthy; InProgress means bake time is running; Succeeded means the check stayed healthy for the whole bake time. Gates never hold a Rollout’s first deploy: it deploys the newest release the gates allow, or the newest release if they allow none. From the second deploy on, gates hold releases they do not allow.
kubectl get rollout -n hello-world hello-world \
-o custom-columns='VERSION:.status.history[0].version.tag,BAKE:.status.history[0].bakeStatus,MESSAGE:.status.history[0].message'VERSION BAKE MESSAGE
main-3f9c2ab-1794583200 Succeeded Automatic deploymentIf the history stays empty, see No releases yet. If the deploy never leaves Deploying, see A deploy is stuck in Deploying and Troubleshoot Flux. If BAKE reads Failed, see The deployment failed.
The dashboard shows each rollout with its running build, the pipeline it moved through, and its health checks. It is off by default; Expose the Dashboard turns it on, and Use the Dashboard shows how to read it.


Next steps
- Ship releases Promote Across Environments Deploy to production only after staging has shipped the same release.
- Ship releases Define the Pipeline Once Write an app's Kuberik objects once in a kustomize component, and give each environment an overlay that sets only what differs.
- Ship releases Publish Releases from CI Tag images or manifest artifacts in CI so a ReleaseSource picks them up.