Get started

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
  1. Create the namespace
  2. Create a ReleaseSource
  3. Create the Rollout
  4. Connect Flux
  5. Publish a release
  6. Check the result
  7. Next steps

Before you start, you need:

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.

Terminal
kubectl create namespace hello-world

Create 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.

releasesource.yamlYAML
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 wins

Scan the container image your application is built into. The setup is the same as for rendered manifests apart from the repository path.

releasesource.yamlYAML
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 wins
Terminal
kubectl apply -f releasesource.yaml

Its 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.

rollout.yamlYAML
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-world

deployTimeout 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.

Terminal
kubectl apply -f rollout.yaml

Connect 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.

flux.yamlYAML
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-world

CI renders that artifact from the production overlay in acme/hello-world and builds the image from the Dockerfile beside it:

acme/hello-worldText
Dockerfile
deploy/
  production/
    kustomization.yaml
    deployment.yaml
deploy/production/kustomization.yamlYAML
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
deploy/production/deployment.yamlYAML
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  # CI pins the build's tag

Until 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.

flux.yamlYAML
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-world

The Deployment in deploy/production of acme/hello-world reads the substitution variable:

deploy/production/deployment.yamlYAML
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.

Terminal
kubectl apply -f flux.yaml

Publish 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.

Use the workflow in Publish rendered manifests. It pushes the image, then renders every overlay under 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.
Use the workflow in Tag every build on main. It pushes the image with a 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.

Terminal
kubectl get releasesource -n hello-world hello-world
OutputText
NAME          NEWEST                    COUNT   READY   AGE
hello-world   main-3f9c2ab-1794583200   1       True    2m

The 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.

Terminal
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'
OutputText
VERSION                   BAKE        MESSAGE
main-3f9c2ab-1794583200   Succeeded   Automatic deployment

If 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.

The deployment pipeline of a production rollout with the shape this tutorial builds: two steps, Started then Check, both done, and the check timer doneThe deployment pipeline of a production rollout with the shape this tutorial builds: two steps, Started then Check, both done, and the check timer done

Next steps