Install CloudGrange — Native Linux

Native Linux installs CloudGrange directly on an existing Ubuntu server. The installer runs locally as root: it installs K3s, then deploys the CloudGrange Helm chart onto it. No VM is created and no Windows or Hyper-V host is involved.

CloudGrange is in preview, not GA. The commands on this page always download the latest release, so they never point at an old version. See current product and release status.

What you download

One file from the release: Install-CloudGrange-K3s-Bundled.zip, with its checksum file Install-CloudGrange-K3s-Bundled.zip.sha256. The bundle contains the installer, the Helm chart, the pinned K3s and Helm builds, and every container image the chart uses. After you download it, the install itself does not need internet access.

If you already run Kubernetes, skip this page entirely — install the chart directly with Helm on your own Kubernetes.

Prerequisites

  • A dedicated, fresh install of Ubuntu 24.04 LTS (amd64), used only for CloudGrange. Once you install, CloudGrange owns the server's operating system and K3s and updates them through the admin-started Foundation card. CloudGrange tests with 4 vCPU, 8 GB RAM and a 30 GB disk. Full details: Linux script prerequisites
  • Root access through sudo
  • curl and python3 (both are on a stock Ubuntu 24.04 server). The first command below installs unzip, which the Ubuntu cloud images do not include
  • Outbound HTTPS to github.com to download the bundle
  • Inbound TCP 443 for the portal and API, and 8443 for managed agents
  • Ports 80, 443, 6443 and 8443 free. K3s binds 6443 for the Kubernetes API, and its Traefik ingress binds 80 and 443

Download and verify

sudo apt-get update && sudo apt-get install -y unzip
cd ~
curl -fsSLO https://github.com/CloudGrange/cloudgrange-deployment-installer/releases/latest/download/Install-CloudGrange-K3s-Bundled.zip
curl -fsSLO https://github.com/CloudGrange/cloudgrange-deployment-installer/releases/latest/download/Install-CloudGrange-K3s-Bundled.zip.sha256
sha256sum --check Install-CloudGrange-K3s-Bundled.zip.sha256
unzip -q Install-CloudGrange-K3s-Bundled.zip -d cloudgrange-k3s
cd cloudgrange-k3s

Expect exactly Install-CloudGrange-K3s-Bundled.zip: OK. If the check fails, do not continue: delete both files and download them again. The bundle is about 1.7 GB.

The download is trusted the same way CloudGrange trusts its updates: it comes over HTTPS from the CloudGrange GitHub release, and its SHA-256 must match the published checksum. Inside the bundle, the installer checks K3s, Helm and the image archive against their own SHA-256 files before it uses them. See How updates are verified.

To see which release you downloaded:

grep -m1 '^version:' charts/cloudgrange/Chart.yaml

Install

Use the DNS name or IP address operators will browse to:

sudo ./Install-CloudGrange-Linux.sh --hostname <your-hostname-or-ip>

The installer runs five checkpointed stages and records each one in /opt/cloudgrange/.install-state.json:

Stage What it does
prereqs-checked Verifies curl, installs a pinned checksum-verified Helm if absent, confirms the vendored charts are present
k3s-installed Installs the pinned K3s from the bundle's airgap/ directory (after checking its SHA-256), imports the bundled images, and waits for the node to report Ready
certmanager-installed Installs cert-manager as its own Helm release (its CRDs must exist before the main chart is validated)
chart-installed Runs helm upgrade --install cloudgrange with the single-node values
ready Fails the install if any pod is not Ready, or if the Ingress is missing

If the install is interrupted, re-run the same command — completed stages are skipped and it resumes at the first incomplete one.

Browse to https://<your-hostname-or-ip>/ to open the setup wizard and complete first-run setup. A browser warning is expected until you replace the generated self-signed certificate with one your organization trusts.

To confirm from the server that the platform is up and waiting for setup:

curl -sk https://<your-hostname-or-ip>/api/v1/setup/status; echo

Before setup is complete this returns "setupComplete":false.

Verify

This is a Kubernetes deployment, so docker commands will tell you nothing. Use:

sudo k3s kubectl get pods
sudo k3s kubectl get ingress
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm status cloudgrange

Every pod should be 1/1 Running, except cloudgrange-secrets-bootstrap-*, which is a one-shot Job and correctly ends 0/1 Completed.

If a pod is not Ready:

sudo k3s kubectl describe pod <pod-name>
sudo k3s kubectl logs <pod-name>

Credentials

You supply none. A Helm pre-install hook Job generates the Postgres, Keycloak admin, Keycloak API client, Grafana, relay enrollment and realm administrator secrets through the Kubernetes API, and only when they do not already exist — so re-running the installer never rotates a live database password.

To read the first-login realm administrator password:

sudo k3s kubectl get secret cloudgrange-secrets -o jsonpath='{.data.realm-admin-password}' | base64 -d; echo

Upgrading

cd ~/cloudgrange-k3s
sudo ./Install-CloudGrange-Linux.sh --hostname <your-hostname-or-ip>

Re-running is safe and idempotent. To upgrade to a newer release, repeat Download and verify, which fetches the latest release, and run its installer. Each release bundle stamps its own version into the chart's image tag, so an upgrade never relies on a latest tag.

Once the control plane is running, apply Platform updates in the portal under Platform → Updates. This server is a managed foundation, so the same page also offers Foundation updates (Ubuntu packages and K3s), which you start yourself. See Updates.

Uninstalling

From the directory you installed from:

cd ~/cloudgrange-k3s
sudo ./Install-CloudGrange-Linux.sh --uninstall

It asks you to confirm (add --yes to skip the prompt), then removes the CloudGrange services, K3s and everything running on it, including all CloudGrange data, and the CloudGrange directories under /opt, /etc and /var/lib. The server is then clean for a fresh install. To remove the release but keep the cluster and your data:

sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm uninstall cloudgrange

PersistentVolumeClaims survive helm uninstall by design.

After the control plane is running

See current product and release status.