Install

1. Installation Process

1.1. Initial Setup

1. Create instances according to specifications in Prerequisites
2. Configure DNS entries for controller domains
3. Generate wildcard certificates (optional)
4. Run the Pre-Flight Check (Recommended): To avoid common installation issues, run the pre-flight check script on the controller nodes. This tool validates OS, node size, and other important configurations before the actual installation.

   curl -sSL https://rafay-airgap-controller.s3.us-west-2.amazonaws.com/Publish/preflight-check.sh | bash

Important

Please do not proceed to the next step unless the preflight checks pass.

Rafay Controller Installation and Initialization Workflow

1. Verify system meets prerequisites
2. Create internal and external DNS records
3. Request and download package tarball
4. Extract (untar) package
5. Update config.yaml with required values
6. Run radm init --config config.yaml Output post-init instructions
7. Verify installation (e.g., check pods)
8. Run sudo radm dependency --config config.yaml
9. Run sudo radm application --config config.yaml
10. Access Console UI via console.
11. Sign up with user/org details
12. Login to Rafay controller dashboard
13. Run sudo radm cluster --config config.yaml

1.2. Controller Installation

1. Download the air-gapped setup package using the URL provided by the support team.

   wget <URL_of_airgap_installation_package>

Info

Navigate to this URL to view the list of available versions of the Rafay Controller software packages. You will need the Rafay CS team to onboard you to Rafay's Zendesk account in order to get authentication credentials.

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

2. Validate the package checksum using md5sum to ensure the integrity of the downloaded file.

   md5sum <name-of-downloaded-package>.tar.gz

3. 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

4. Set up configuration:

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

5. Configure mandatory fields in config.yaml:

   spec:
        deployment:
          ha: true  # set to true for HA controller
          size: "M"          # Supports "POC","S","M","L" and "XL".
        repo:
          archive-directory: /path/to/extracted-controller-archive
          unarchive-path: /tmp # where to untar
        app-config:
          generate-self-signed-certs: true  # if using self-signed certificates
          partner:
            star-domain: "example.com"
        gaap:
          enabled: false  # default value; enables or disables GenAI services

Controller Sizing
Set deployment.size and deployment.ha based on your deployment type:

• POC / evaluation: Set size to "POC" for a proof of concept controller. This profile is for evaluation only and is not supported for production.
• Production: Set size to "S", "M", "L", or "XL" based on your environment requirements. Enable HA by setting ha: true and provision a minimum of 3 controller nodes.

For sizing profiles and infrastructure requirements, see Prerequisites — Infrastructure Requirements.

Note
After enabling GAAP services in the config.yaml, the Super Admin must enable the Enable GenAI flag under Partner Settings. The GenAI screens are visible only for partners where this flag is enabled.

Updating the Controller with a CA-Signed Certificate

If the controller was initially installed using self-signed certificates, it can be updated later to use a certificate issued by a trusted Certificate Authority such as Let's Encrypt.

Update Controller Certificate

1. Ensure generate-self-signed-certs is set to true during the initial controller installation.

   spec:
        app-config:
          generate-self-signed-certs: true

2. Generate the TLS certificate and private key using a trusted Certificate Authority (for example, Let's Encrypt using ACME/certbot or any other CA-signed certificate provider). The generated files typically include:

   fullchain.pem
   privkey.pem
   

3. Update generate-self-signed-certs to false in config.yaml.

   spec:
        app-config:
          generate-self-signed-certs: false

4. Base64-encode the certificate and private key and store the encoded values in config.yaml as shown below:

   console-certificates:                    # add the wildcard cert for the star-domain only when generate-self-signed-certs is false.
        certificate: "<Base64-Encoded-Certificate>"   # Provide Base64 encoded certificate
        key: "<Base64-Encoded-Key>"                   # Provide Base64 encoded key

5. Run the following commands to apply the updated configuration:

   sudo radm dependency --config config.yaml
   sudo radm application --config config.yaml

6. After the update completes, access the controller UI and verify the certificate.

Replace Existing or Expired Certificates

1. Generate the TLS certificate and private key using a trusted Certificate Authority (for example, Let's Encrypt using ACME/certbot or any other CA-signed certificate provider). The generated files typically include:

   fullchain.pem
   privkey.pem
   

2. Ensure generate-self-signed-certs is set to false.

   spec:
        app-config:
          generate-self-signed-certs: false

3. Base64-encode the new certificate and private key.
4. Replace the existing certificate and key values in config.yaml with the newly encoded values.

   console-certificates:                    # add the wildcard cert for the star-domain only when generate-self-signed-certs is false.
        certificate: "<Base64-Encoded-Certificate>"   # Replace with the new Base64 encoded certificate
        key: "<Base64-Encoded-Key>"                   # Replace with the new Base64 encoded key

5. Run the following commands to apply the updated configuration:

   sudo radm dependency --config config.yaml
   sudo radm application --config config.yaml

6. After the update completes, access the controller UI and verify the certificate.

Note
If the browser still shows the previous certificate, clear the browser cache or reopen the URL in an incognito/private window.

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.

   sudo radm init --config config.yaml

1. Initialize first node:

   sudo radm init --config config.yaml

2. 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

3. 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)

1. 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

2. Verify Kubernetes node and system pod status:

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

3. 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.

External Storage Configuration

Rafay Controller supports both internal (OpenEBS) and external storage backends for dynamic PVC provisioning. By default, the controller installs and uses OpenEBS for local storage.

If you intend to use external storage instead of the default OpenEBS, you must first enable it within config.yaml (as configured in step 3.5) and install the necessary CSI drivers on the Controller nodes before executing this dependency command.

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

4. 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

1. Access the UI at: https://console.<your-domain>

2. 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.

3. When creating the organization, provide the following details:

   • Organization Name
   • Username / Email
   • Password

4. 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

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.

3.4. SMTP Email Configuration (Optional)

If you want to configure SMTP email functionality for email alerts, user onboarding, password resets, and other email-driven workflows, you can set up SMTP configuration in your controller.

For detailed instructions on configuring SMTP with various providers (Gmail, SendGrid, etc.), see the SMTP Email Configuration Guide.

3.5. External Storage Support (Optional)

Production Recommendation

It is recommended to use external storage for production-based controllers.

To use external storage instead of the default OpenEBS, you need to enable the external storage option and provide the appropriate StorageClass names in the config.yaml file.

Important

If you plan to use external storage, configure this before running the radm dependency command (step 1.4.3). You must also install the necessary CSI drivers on the Controller nodes before executing the dependency command.

Configure external storage in config.yaml:

     storage:
       external:
         enabled: true       # When true, skip installing internal storage OpenEBS
       storageClass:
         readWriteOnce: "ceph-rbd"       # StorageClass for RWO PVCs (default for internal storage: "openebs-hostpath")
         readWriteMany: "ceph-cephfs"     # StorageClass for RWX PVCs (default for internal storage: "openebs-kernel-nfs")

For detailed information about prerequisites, supported storage backends, configuration examples, validation steps, and troubleshooting, refer to the External Storage Configuration Guide.

3.6. Node Maintenance

Important

Always cordon and drain controller nodes before rebooting them. Rebooting without draining can leave pods stuck in Terminating or prevent stateful pods from restarting cleanly.

For the full procedure and recovery guidance, see Node Reboot in the troubleshooting guide.