Skip to content

Installing on your Kubernetes cluster

On a cluster of your own, the same installer runs on a jump host instead of on the server: it fetches the release with your account, takes your configuration, applies the hub to the cluster your kubectl points at, builds your images' customer layer with the jump host's docker and runs the smoke test. Upgrades and rollbacks are the same commands as on a single host. This page describes release v0.5.0.

What the cluster must provide

A conformant Kubernetes cluster with:

  • dynamic provisioning through a default StorageClass (ReadWriteOnce is enough),
  • an Ingress controller that terminates TLS for the hub's three host names, or a proxy in front of it that does,
  • NetworkPolicy enforcement by the CNI,
  • outbound access to the package repositories named in hub.env, or to your mirrors,
  • a kubeconfig with cluster-admin.

Optional: a ReadWriteMany StorageClass for pipeline stores that apps mount, an S3-compatible bucket for backups and a stateless registry, and a node pool for user code (see session_pool).

The jump host: Ubuntu or Debian with kubectl (current context: the cluster), docker and bash, able to reach the cluster, our distribution registry, your package mirrors and your registry. The installer keeps its releases and state under /opt/hub, or under HUB_HOME if you set it. DNS for the three host names must point at your ingress before the install, with TLS there: the customer layer is pushed to the registry's host name, and the smoke test opens the hub's.

Install

curl -fsSLo install.sh https://images.hub.linnerprogramming.com/install.sh
bash install.sh generate --cluster --name acme --domain hub.acme.example --account acme

generate writes the overlay to /opt/hub/overlay/acme without touching the cluster; the options are those of a single host (features, IDEs, --auth oidc), or we maintain the overlay for you and install fetches it instead. Review what a cluster decides and the generator cannot know:

  • patches/quota.yaml: what the hub may use of the cluster; the generated numbers are the example's.
  • patches/registry.yaml and ingress_class in hub.env: the ingress class, and TLS on the registry's Ingress where the controller terminates it (cert-manager's annotation, or leave tls: out behind a proxy).
  • kustomization.yaml: the Redis and registry components (the platform's own, or yours), the IDE tiles.
  • hub.env: storage_class_rwx or single_node if apps are to mount pipeline stores, session_pool with a node pool.

Then:

bash install.sh install --cluster --overlay /opt/hub/overlay/acme --account acme

It fetches the newest release (or --version vX.Y.Z), applies the hub, builds the customer layer and pushes it to your registry, restarts what waited for the images, and runs the smoke test, which deploys the sample app from inside the cluster and removes it. At the end it prints the hub's address. With an overlay we maintain, leave --overlay out: install syncs it for your account and asks for the secrets it needs.

Upgrading and rolling back

As on a single host, from the jump host:

bash install.sh upgrade latest     # or a version
bash install.sh rollback
bash install.sh status
bash install.sh diagnose

upgrade fetches the release, backs the namespace up where backups are configured, builds the customer layer for the new version, applies it and runs the smoke test; sessions and apps keep running. rollback applies the previous release again, unless the release notes of the version you run say No rollback.

Changing the configuration

Edit the overlay under /opt/hub/overlay/<name>, then bash install.sh upgrade <the version you run>. A change to the package stack, the certificates, the system packages or the templates is an image change, which that command builds; new sessions pick it up. A change to secrets.env alone rolls nothing by itself; after the apply, delete the ShinyProxy pods (kubectl delete pod -n <namespace> -l app=shinyproxy) and sessions and apps survive, their state is in Redis.

A network without access to our registry

If the jump host cannot reach images.hub.linnerprogramming.com, we send you two things for a version: the release archive hub-release-v0.5.0.tar.gz and the platform images as docker archives. The release directory carries the same scripts the installer uses:

tar xzf hub-release-v0.5.0.tar.gz && cd hub-release-v0.5.0
for f in ../images-v0.5.0-acme/*.tar; do docker load -i "$f"; done
cp -r /opt/hub/overlay/acme platform/overlays/acme
scripts/deploy-platform.sh acme                                           # the hub, and its registry
scripts/build-images.sh acme v0.5.0 --customer-only --platform-from local
scripts/deploy-platform.sh acme                                           # now the images exist
scripts/smoke-test.sh acme --no-apply

Upgrades take the next release archive and image archives the same way.