Install

1. Installation Process¶

1.1. Initial Setup¶

Create instances according to specifications in Prerequisites
Configure DNS entries for controller domains
Generate wildcard certificates (optional)

Rafay Controller Installation and Initialization Workflow

sequenceDiagram
    participant User
    participant Node
    participant DNS
    participant RafaySupport

    User->>Node: 1. Verify system meets prerequisites
    User->>DNS: 2. Create internal and external DNS records
    User->>RafaySupport: 3. Request and download package tarball
    User->>Node: 4. Extract (untar) package
    User->>Node: 5. Update config.yaml with required values

    User->>Node: 6. Run `radm init --config config.yaml`
    Note right of Node: ⚠️ INIT STEP — Initializes Rafay Control Plane<br>Installs Kubernetes layer, storage, and registry
    Node-->>User: Output post-init instructions

    User->>Node: 7. Verify installation (e.g., check pods)

    User->>Node: 8. Run `sudo radm dependency --config config.yaml`
    Note right of Node: ⚠️ INSTALLS DEPENDENCIES — Required components like cert-manager, Kafka, Istio, MinIO, etc.

    User->>Node: 9. Run `sudo radm application --config config.yaml`
    Note right of Node: ⚠️ DEPLOYS RAFAY SERVICES — Installs controller applications and services

    User->>Node: 10. Access Console UI via console.<domain>
    User->>Node: 11. Sign up with user/org details
    User->>Node: 12. Login to Rafay controller dashboard

    User->>Node: 13. Run `sudo radm cluster --config config.yaml`
    Note right of Node: ⚠️ PUSH CLUSTER ARTIFACTS — Uploads cluster images and assets to Nexus registry

1.2. Controller Installation¶

Download the air-gapped setup package using the URL provided by the support team.
```
wget <URL_of_airgap_installation_package>
```
Info

The air-gapped package is around 30 GB and may take ~15 minutes to download with wget.
For faster downloads, use aria2c, which supports parallel connections:
```
time aria2c -x 16 <URL_of_airgap_installation_package>
```
This can significantly reduce download time by using up to 16 connections.

On Ubuntu, you can install aria2c using:
```
sudo snap install aria2c
```
Validate the package checksum using md5sum to ensure the integrity of the downloaded file.
```
md5sum <name-of-downloaded-package>.tar.gz
```
Extract the package:
```
tar -xf <name-of-downloaded-package>.tar.gz
```
Info

To speed up extraction of large files (like the ~30GB air-gapped package), you can use pigz.

If pigz is installed, use the following command instead to significantly reduce untar time:
```
tar -I pigz -xvf <name-of-downloaded-package>.tar.gz
```
pigz leverages multiple CPU cores to accelerate the decompression process.

On Ubuntu, you can install pigz using:
```
sudo apt install pigz
```
For a detailed breakdown of the files included in this package, refer to the Controller Package Contents.

Set up configuration:

sudo mv ./radm /usr/bin/
cp -rp config.yaml-airgap-tmpl config.yaml
vi config.yaml

Configure mandatory fields in config.yaml:

spec:
  deployment:
    ha: true  # set to true for HA controller
  repo:
    archive-directory: /path/to/tar/location
    unarchive-path: /tmp # where to untar
  app-config:
    generate-self-signed-certs: true  # if using self-signed certificates
    partner:
      star-domain: "*.example.com"

1.3. Controller Initialization¶

About radm

radm is a Go-based CLI tool used to manage the full lifecycle of a Rafay air-gapped controller. It handles tasks such as installing infrastructure add-ons, Kubernetes cluster creation, software provisioning, and ongoing maintenance of the controller like config updates, upgrades etc. Using simple commands, radm takes care of all the heavy lifting internally, making complex operations seamless.

Single NodeHA Setup

sudo radm init --config config.yaml

Initialize first node:
```
sudo radm init --config config.yaml
```

Join additional control plane nodes:

sudo radm join <master-ip>:6443 --token <token> \
  --discovery-token-ca-cert-hash <hash> \
  --control-plane --certificate-key <key> --config config.yaml

Join worker nodes:

sudo radm join <master-ip>:6443 --token <token> \
  --discovery-token-ca-cert-hash <hash> --config config.yaml

1.4. Common Setup Steps (Applicable to Both Single Node and HA Setup)¶

Info

After each radm command is successfully executed, the CLI will print clear instructions to the console indicating the next steps in the installation process. This output is self-sufficient and acts as a guide, helping you proceed confidently without needing to refer back to the documentation for every step.

Configure kubeconfig:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) -R $HOME/.kube

Verify Kubernetes node and system pod status:

kubectl get nodes
kubectl get pods -n kube-system
kubectl get pods -n openebs

Initialize Dependencies:

In this step, all the necessary dependencies for Rafay applications are installed. These dependencies enable various core services and functionalities across the platform. This includes essential infrastructure components such as:

cert-manager, Metric Server, Kafka, Postgres Operator, Elasticsearch, Istio, HAProxy, ClickHouse, MinIO, and other supporting add-ons required by Rafay services.

Note

This step will take approximately 15 to 16 minutes to complete, as multiple components are being deployed and initialized.
```
sudo radm dependency --config config.yaml
```
Install Rafay application:

Once the dependencies are initialized, proceed to install the Rafay platform services.
```
sudo radm application --config config.yaml
```
Installation Time

Allow 20 minutes for all pods to become ready. You can monitor pod status in the rafay-core namespace:
```
kubectl get pods -n rafay-core
```

2. Accessing the Controller¶

Access the UI at: https://console.<your-domain>
You can create the first organization in one of two ways:
- Click "Sign Up" on the main console (https://console.<your-domain>)
- Or use the Operations Console at https://ops-console.<your-domain> using the super-user credentials set in config.yaml to create the organization and user.
When creating the organization, provide the following details:
- Organization Name
- Username / Email
- Password
After creating the organization and user, log in using the newly created credentials.

Note

Users must use the password they set during sign up, or the password set by an admin from the Operations Console, to log in to the Admin Console.

3. Additional Configuration¶

Info

If you plan to create or manage downstream clusters (EKS, MKS, GKE & Import) from this controller, don’t forget to run the below Cluster Dependencies step.

3.1. Cluster Dependencies¶

Upload cluster images and manifests to the built-in Nexus registry using the radm command below. This will push the required images, packs, and manifests to the built-in Nexus registry. These images and manifests will be used when creating or managing clusters with this air-gapped controller.

sudo radm cluster --config config.yaml

3.2. Multiple Interface Support (Optional)¶

Rafay Controller supports multiple interfaces, configurable via config.yaml. By default, the primary interface is used for all Kubernetes and Rafay app connections

Configure network interface in config.yaml:

spec:
  networking:
    interface: ens3

For complete interface isolation, add routing rules:

ip route add 10.96.0.0/12 dev <secondary-interface>
ip route add 10.224.0.0/16 dev <secondary-interface>

3.3. Cost Visibility (Optional)¶

Rafay Controller supports integrated cost visibility. For self-hosted setups, an external InfluxDB is required. Use the provided steps to deploy it on a single-node instance (min: 16 CPU, 32GB RAM, 200GB disk) and connect it

Enable cost metrics in config.yaml:

cost_metrics:
  enabled: false

Note

Requires pre-installed external InfluxDB with minimum 16 CPU, 32GB memory & 200GB disk.

Next Steps¶

➡️ To learn how to monitor the controller using a Grafana dashboard, head over to the Monitoring Section.