Installing Ascender on Kubernetes

Overview

This guide covers installing Ascender on a Kubernetes cluster that you already manage yourself, where the installer is not responsible for provisioning or configuring the cluster. This includes upstream Kubernetes (kubeadm), Rancher, Tanzu, vanilla self-managed clusters, or any other distribution that exposes a standard Kubernetes API.

The installer uses the rke2 platform type for this flow. It is the most general of the supported platform types and assumes the cluster is already running, reachable, and configured with the prerequisites below.

For common configuration variables (Ascender application, Ascender Pro, PostgreSQL, TLS), see the main install guide.

Note

If you are running RKE2 specifically, use the RKE2 guide instead. It includes RKE2 installation steps and HA setup with keepalived.

Prerequisites

In addition to the general prerequisites, a generic Kubernetes install requires:

A running Kubernetes cluster, version 1.27 or newer, with at least one worker node
A valid kubeconfig at ~/.kube/config on the install machine, with cluster-scoped admin permissions and readable by root (the installer runs under sudo)
A reachable Kubernetes API server endpoint from the install machine
A running ingress controller on the cluster (e.g., ingress-nginx, Traefik, HAProxy)
A default StorageClass for the Ascender PostgreSQL PVC, unless using an external PostgreSQL server
A DNS record (or /etc/hosts entry) pointing ASCENDER_HOSTNAME to the ingress controller's external address

Pod Security Standards

If your cluster enforces the restricted Pod Security Standard by default, the Ascender Operator pods may be rejected. Adjust the enforcement on the ASCENDER_NAMESPACE before running the installer.

Verifying the cluster

Confirm the cluster is reachable and the kubeconfig is in the expected location:


kubectl get nodes

All nodes should report Ready. Confirm a default StorageClass exists:


kubectl get storageclass

The default class is marked with (default) in the output. If no default is set, either mark one as the default or set POSTGRES_STORAGE_CLASS explicitly in custom.config.yml.

Confirm an ingress controller is installed:


kubectl get ingressclass

Installing Ascender

Clone the ascender-install repository if you don't have it:


git clone https://github.com/ctrliq/ascender-install.git
cd ascender-install

Generate a TLS certificate for the Ascender web UI. Run this from inside the ascender-install directory so the installer can locate the files automatically:


openssl req -x509 -newkey rsa:4096 -keyout ascender.key -out ascender.crt -days 365 -nodes \
  -subj "/CN=<ascender.example.com>" \
  -addext "subjectAltName=DNS:<ascender.example.com>"

For production deployments, use a certificate signed by a trusted CA or a certificate manager instead of a self-signed certificate.

Create custom.config.yml. The key settings are k8s_platform: rke2, kube_install: false, and download_kubeconfig: false. This tells the installer to skip cluster provisioning and use the kubeconfig already in place at ~/.kube/config:


k8s_platform: rke2
k8s_lb_protocol: https
kube_install: false
download_kubeconfig: false
use_etc_hosts: false

tls_crt_path: "{{ playbook_dir }}/../ascender.crt"
tls_key_path: "{{ playbook_dir }}/../ascender.key"

ASCENDER_HOSTNAME: <ascender.example.com>
ASCENDER_NAMESPACE: ascender
ASCENDER_ADMIN_USER: admin
ASCENDER_ADMIN_PASSWORD: "<change-me>"
ASCENDER_VERSION: 25.4.0
ASCENDER_OPERATOR_VERSION: 2.19.6

ascender_garbage_collect_secrets: true
ascender_setup_playbooks: true

To include Ascender Pro, add the following to custom.config.yml:


LEDGER_INSTALL: true
LEDGER_HOSTNAME: <ledger.example.com>
LEDGER_NAMESPACE: ledger
LEDGER_REGISTRY:
  BASE: depot.ciq.com
  USERNAME: <your-depot-username>
  PASSWORD: <your-depot-token>
LEDGER_ADMIN_PASSWORD: "<change-me>"
LEDGER_DB_PASSWORD: "<change-me>"
LEDGER_VERSION: latest
LEDGER_WEB_IMAGE: depot.ciq.com/ascender-ledger-pro/ascender-ledger-pro-images/ledger-web
LEDGER_PARSER_IMAGE: depot.ciq.com/ascender-ledger-pro/ascender-ledger-pro-images/ledger-parser
LEDGER_DB_IMAGE: depot.ciq.com/ascender-ledger-pro/ascender-ledger-pro-images/ledger-db

See the Ascender Pro Installation Guide for the full variable reference and post-install steps.

For multi-node clusters, increase the replica counts to take advantage of available capacity:


ascender_replicas: 2
ledger_web_replicas: 2
ledger_parser_replicas: 2

Each additional replica adds roughly 1 GB of memory overhead. Adjust counts based on your available node resources.

For all available configuration options, refer to default.config.yml in the repository. See the main install guide for the full variable reference.

Run the installer:


sudo ./setup.sh

A typical install takes 10-20 minutes, most of which is the Ascender Operator waiting for the Ascender API to come up. The installer ends with:


ASCENDER SUCCESSFULLY SETUP

DNS

Point ASCENDER_HOSTNAME (and LEDGER_HOSTNAME if installing Ascender Pro) at an address that reaches your ingress controller. The right address depends on how your cluster is exposed (LoadBalancer external IP, a node IP for NodePort or hostNetwork controllers, or an upstream VIP or proxy). Consult whoever manages your cluster networking if you're not sure.

Verifying the Installation


kubectl get pods -n ascender

All pods should reach Running or Completed state. Access the Ascender web UI at https://ASCENDER_HOSTNAME and log in with the ASCENDER_ADMIN_USER and ASCENDER_ADMIN_PASSWORD values from your custom.config.yml.

If Ascender Pro was installed:


kubectl get pods -n ledger

Log into the Ascender Pro web UI, navigate to Settings > License, and upload the .json license file provided by CIQ to activate it.

Installing Ascender on GKE Installing Ascender on RKE2