Skip to content
GitHub

Deploy your first app

Everything in Kuben works from the web console and from the REST API. This walkthrough shows both. The API examples assume:

Terminal window
export KUBEN_URL=http://localhost:8080      # or https://kuben.example.com
export KUBEN_TOKEN=kbn_pat_…                # see below

1. Create a project and an environment

Section titled “1. Create a project and an environment”

A project groups related apps (a product, a customer, a team). An environment is where apps run: each environment is its own Kubernetes namespace with a resource quota and a NetworkPolicy, so staging and production cannot talk to each other.

  1. On Home, in the Projects section, press New project. Enter shop as the Name and Online Shop as the Display name, then press Create project.
  2. On the project page, press New environment, enter staging as the Name, leave the Type at Standard, and press Create environment.

Behind the scenes Kuben recorded both in its database and wrote a Project and an Environment resource (shop-staging) to the cluster; the environment controller then created the namespace kb-shop-staging, which the environment page shows under its name:

Terminal window
kubectl get projects,environments -A
kubectl get ns -l kuben.dev/environment

2. Deploy an image

Section titled “2. Deploy an image”

We will use traefik/whoami, a tiny HTTP server that prints its request. Any image that listens on a port works the same way.

On the staging environment page press Deploy app, then fill in:

  • Name: hello
  • Image: traefik/whoami:v1.10
  • Port: 80

Leave the rest at their defaults and press Deploy.

The app page shows the rollout: its Overview tab lists the pods, and the Deployments tab follows each deployment through its phases to Succeeded. New pods must pass their readiness check before old ones stop; slow starters get up to five minutes through a startup probe, and a rollout that makes no progress for ten minutes is reported as RolloutFailed.

3. Reach it

Section titled “3. Reach it”

If you have not configured a base domain yet, the app has a cluster-internal Service only. Port-forward to it:

Terminal window
kubectl -n kb-shop-staging port-forward svc/hello 8000:80
curl localhost:8000

Once platform.baseDomain and a Gateway are set (see Exposing apps and HTTPS), every HTTP app also gets https://<app>-<project>-<environment>.<baseDomain>, for example https://hello-shop-staging.apps.example.com, plus any custom domains you add.

4. Look around

Section titled “4. Look around”
  • The Logs tab shows the lines of the app’s pods (up to ten); Follow keeps them coming live. The stream is server-sent events, so it survives proxies that dislike WebSockets.
  • The Releases tab lists every change as a numbered revision. Change a variable on the Settings tab under Environment variables and press Save and roll out: revision 2 appears. Roll back on revision 1 deploys it again, as a new revision. See Rollbacks.
  • Home in the sidebar shows open incidents, the latest deployments and the health of Kuben itself.
  • Audit in the sidebar (readable by admins and owners) shows who did what, including this deploy.
  • On the cluster, kubectl -n kb-shop-staging get applicationruntimes shows the app as the cluster agent received it. Without a cluster agent, Kuben writes an App resource instead: kubectl -n kb-shop-staging get app hello -o yaml, with a Ready condition and, for HTTP apps, Exposed.

5. Clean up

Section titled “5. Clean up”

On the app page, open the Settings tab and press Delete app under Danger zone, then type the app’s name to confirm. Volumes, if any, are kept unless you tick Also delete the app’s volumes when deleting it. Through the API, add ?delete_volumes=true.

Where next

Section titled “Where next”
  • Concepts explains what Kuben created on the cluster and why.
  • Deploy from CI turns this into a deploy from GitHub Actions.
  • One-click templates gives the app a PostgreSQL database with generated credentials.