Prerequisites

1. Prerequisites

1.1. Infrastructure Requirements

System SpecificationsStorage RequirementsNetwork Requirements

• Operating System:

  • Ubuntu 24.04
  • RHEL 8
  • RHEL 9

• Instance Requirements:

  • Single Node Controller: 1 node
  • High Availability Controller: 3 master nodes

• System Size (Minimum):

  • 'S': 32 CPU , 64G memory
  • 'M': 48 CPU , 96G memory
  • 'L': 64 CPU , 96G memory (Only HA)

Note: All node types (VM or bare-metal) must conform to these minimum specifications based on the deployment size.

• Root Disk: Minimum 500 GB
• Temp Directory (/tmp): Minimum 50GB (if not part of root disk)
• Data Disk: 1 TB (mounted as /data volume, size varies based on storage requirements)

• RHEL installations need connectivity to default repository servers
• Inbound port 443/tcp must be allowed to all instances
• All localhost ports must be reachable
• Port 30053/UDP must be reachable in non-DNS environments
• SELinux/firewall must be disabled on all nodes

Ensure that all nodes can communicate over internal network interfaces without firewall restrictions for proper operation of the controller cluster.

---

1.2. DNS Configuration

DNS records are required for the controller to function properly. Replace rafay.example.com with your desired domain.

Wildcard RecordIndividual Records

*.rafay.example.com

If wildcard DNS is not available, create these individual records:

api.<rafay.example.com>
console.<rafay.example.com>
fluentd-aggr.<rafay.example.com>
grafana.<rafay.example.com>
kibana.<rafay.example.com>
ops-console.<rafay.example.com>
repo.<rafay.example.com>
*.cdrelay.<rafay.example.com>
*.core-connector.<rafay.example.com>
*.core.<rafay.example.com>
*.connector.infrarelay.<rafay.example.com>
*.user.infrarelay.<rafay.example.com>
*.kubeapi-proxy.<rafay.example.com>
*.user.<rafay.example.com>

Note

DNS records should point to the controller nodes' IP addresses. For external SSL offloading, refer to the SSL Offloading section.

---

1.2.1. Hosted DNS Support (Optional)

In environments where DNS servers are not available or cannot be configured, the Rafay Controller can host its own DNS server and propagate DNS records to managed clusters.

Enable Hosted DNS

To enable hosted DNS functionality, add the following configuration to your config.yaml:

override-config:
  global.enable_hosted_dns_server: true

Local Machine Access

For accessing the controller UI from your local machine, add an entry to /etc/hosts pointing the console FQDN to your controller IP:

<Controller-IP>  console.<rafay.example.com>

Cluster Provisioning with Hosted DNS

When provisioning clusters in a hosted DNS environment, include the -dns-server parameter in the conjurer command:

$ tar -xjf conjurer-linux-amd64.tar.bz2 && sudo ./conjurer -edge-name="test" \
  -passphrase-file="passphrase.txt" -creds-file="credentials.pem" \
  -dns-server <Controller-IP>

RHEL 9 Node Configuration

On RHEL 9 nodes, configure DNS non-conf to preserve resolv.conf entries during node reboots:

1. Create the DNS configuration file:

   $ sudo vi /etc/NetworkManager/conf.d/90-dns-none-conf
   

2. Add the following content:

   [main]
   dns=none
   

3. Reload NetworkManager:

   $ sudo systemctl reload NetworkManager
   

Note

• These steps need to be executed on both cluster nodes as well as controller nodes.

• This configuration should be applied before running the radm init process on RHEL 9 nodes for the new controller setup.

• For existing controller, if you want to set this up, just manually execute these commands and proceed.

---

1.3. Additional Requirements

Logo

• Company logo in PNG format
• Size: Less than 600 KB
• Used for white labeling and branding

Note

This step is optional.

X509 Certificates

• X509 certificates are used to secure communication between services in the controller as well as between end users and the controller.

• Trusted CA signed wildcard certificate (2048 bit) are recommended for secure communication between the end user's browser and the air gapped controller.

• Acquire a signed wild card certificate for the end user facing domain "*.rafay.example.com".

• All other domains will use auto generated, self-signed certificates. These are not end user facing and are used for mTLS based inter service communication.

Note

For non-prod environments, self-signed certificates can be auto-generated. Set generate-self-signed-certs: true in config.yaml for auto-generation.

---

1.4. SSL Offloading Configuration (Optional)

• Rafay controller supports SSL offload at load balancer level using ACM/certificates. This would need two load balancers, one for UI FQDNs which requires SSL offload and another for backed FQDNs which requires SSL passthrough.

• To enable external SSL offloading, the below override-config has to be enabled in config.yaml.

  override-config.global.external_lb: true

---

1.5. DNS Settings for Using External SSL Offload (Optional)

For extended security, all Rafay backend endpoints use mTLS and do not support SSL offloading, except for the frontend UI endpoints.

Frontend FQDNs (Point to Classic Load Balancer for SSL Offloading)

• api.<rafay.example.com>
• console.<rafay.example.com>
• fluentd-aggr.<rafay.example.com>
• ops-console.<rafay.example.com>
• grafana.<rafay.example.com>
• repo.<rafay.example.com>

Backend FQDNs (Point to NLB for mTLS)

• registry.<rafay.example.com>
• *.core-connector.<rafay.example.com>
• *.core.<rafay.example.com>
• *.kubeapi-proxy.<rafay.example.com>
• *.user.<rafay.example.com>
• *.cdrelay.<rafay.example.com>
• *.infrarelay.<rafay.example.com>
• *.connector.infrarelay.<rafay.example.com>
• *.user.infrarelay.<rafay.example.com>

---

1.6. Load Balancer Setup (Optional)

Load balancer settings with External SSL offloadLoad balancer with certificateLoad balancer with SSL passthroughHealth check configurations

• Requires two load balancers:
  1. Load balancer with certificate for SSL offloading in UI traffic.
  2. Load balancer with SSL passthrough for mTLS traffic
• Enable with: override-config.global.external_lb: true in config.yaml

Certificate Requirements:

• CA signed wildcard certificate
• Ports: 80/TCP and 443/TCP inbound
• Redirecting Connections as per the below table

Port Configuration:

Frontend Port	Frontend Protocol	Backend Port	Backend Protocol
80	HTTP	30426	HTTP
443	SECURE TCP(SSL)	30726	TCP

SSL Passthrough Configuration:

Frontend Port	Frontend Protocol	Backend Port	Backend Protocol
443	TCP	30526	TCP

Ping Protocol: HTTP
Ping Port: 30326
Ping Path: /healthz/ready

---

Preflight Checks During Controller Initialization

When the radm init or radm join command is executed, a series of preflight checks are performed to validate the system environment. These checks ensure that the host meets the minimum requirements before proceeding with the controller installation.

./radm init --config config.yaml

(or)

./radm join --config config.yaml

Example Output

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Rafay Controller PreFlight Check                                                       ║
║                                                             Radm Version: v3.3,x                                                             ║
║                                                              Date: May 26, 2025                                                              ║
╠═══════════════════════╦════════╦════════╦════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CHECK                 ║ RESULT ║ STATUS ║                                               DETAILS                                              ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Operating System      ║ Passed ║ ✔      ║                OS: Ubuntu 24.04.2 LTS. Supported OS: [Ubuntu 24.04, RHEL 8, RHEL 9]                ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ CPU                   ║ Passed ║ ✔      ║                                 Required: 32 CPU, Available: 64 CPU                                ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Memory                ║ Passed ║ ✔      ║                               Required: 63488 MB, Available: 64275 MB                              ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Root Disk             ║ Passed ║ ✔      ║                                 Required: 500 GB, Available: 600 GB                                ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Data Disk Check       ║ Passed ║ ✔      ║       Mount point /data not found. Assuming external mount is acceptable (Expected: 1024 GB)       ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ /tmp                  ║ Passed ║ ✔      ║                               Found 501 GB available at /tmp                                       ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Internet Port 80      ║ Passed ║ ✔      ║                   Warning: Port 80 is open to internet (should ideally be closed)                  ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Internet Port 443     ║ Passed ║ ✔      ║                  Warning: Port 443 is open to internet (should ideally be closed)                  ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ DNS Resolution        ║ Passed ║ ✔      ║                     Successfully resolved ops-console.rafay.dev.rafay-edge.net                     ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Free Space            ║ Passed ║ ✔      ║            Working directory has enough space: /home/ubuntu/controller, 501 GB available           ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Firewall Status       ║ Passed ║ ✔      ║                                     No active firewall detected                                    ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ AppArmor Status       ║ Passed ║ ✔      ║                       AppArmor is enabled (ensure proper profiles are loaded)                      ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ iptables Rules        ║ Passed ║ ✔      ║                                  Only default ACCEPT rules present                                 ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Local Ports Check     ║ Passed ║ ✔      ║   All required local ports are available and not in use (checked ports: [80 443 5000 5006 5005])   ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Var Mount Point Check ║ Passed ║ ✔      ║ /var is part of the root filesystem (acceptable, but separate mount is recommended for production) ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ DNS Server            ║ Passed ║ ✔      ║                                 No conflicting DNS server detected                                 ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ iscsid Service        ║ Passed ║ ✔      ║                                iscsid service is not in failed state                               ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Container Runtimes    ║ Passed ║ ✔      ║                             No conflicting container runtimes detected                             ║
╠═══════════════════════╬════════╬════════╬════════════════════════════════════════════════════════════════════════════════════════════════════╣
║ Files                 ║ Passed ║ ✔      ║                                       All Files are present!!                                      ║
╚═══════════════════════╩════════╩════════╩════════════════════════════════════════════════════════════════════════════════════════════════════╝

To bypass preflight checks during initialization or joining, use the --skip-preflight flag.

radm init --config config.yaml --skip-preflight

(or)

./radm join --config config.yaml --skip-preflight

Command-Specific Preflight Checks

Some preflight checks are not included in the output of init or join commands because they depend on configuration steps that happen after those commands are run.

• Kubeconfig Check: Checks if the provided Kubernetes kubeconfig file is accessible and correctly configured.

./radm dependency --config config.yaml --kubeconfig <kubeconfig file>

./radm application --config config.yaml --kubeconfig <kubeconfig file>

Example Output

╔══════════════════════════════════════════════════════════════════════════════════╗
║                         Rafay Controller PreFlight Check                         ║
║                               Radm Version: 3.3.x                                ║
║                                Date: May 21, 2025                                ║
╠═════════════════════════╦════════╦════════╦══════════════════════════════════════╣
║ CHECK                   ║ RESULT ║ STATUS ║                DETAILS               ║
╠═════════════════════════╬════════╬════════╬══════════════════════════════════════╣
║ Kubeconfig Reachability ║ Passed ║ ✔      ║ Able to reach Kubernetes API server. ║
╚═════════════════════════╩════════╩════════╩══════════════════════════════════════╝

To skip this preflight check, use the following commands:

radm dependency --config <config file path> --kubeconfig <kubeconfig path> --skip-preflight

(&

radm application --config <config file path> --kubeconfig <kubeconfig path> --skip-preflight

• DNS Resolution Check: Validates that required DNS endpoints can be resolved.

./radm cluster --config config.yaml

Example Output

╔═══════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                  Rafay Controller PreFlight Check                                 ║
║                                       Radm Version: 3.3.x                                         ║
║                                         Date: May 21, 2025                                        ║
╠════════════════╦════════════╦════════╦════════════════════════════════════════════════════════════╣
║ CHECK          ║ RESULT     ║ STATUS ║                           DETAILS                          ║
╠════════════════╬════════════╬════════╬════════════════════════════════════════════════════════════╣
║ DNS Resolution ║ Successful ║ ✔      ║ Successfully resolved ops-console.rafay.rafay-edge.net     ║
╚════════════════╩════════════╩════════╩════════════════════════════════════════════════════════════╝

To skip this preflight check, use the following command:

radm cluster --config <config file path> --skip-preflight

These checks are automatically triggered during the relevant phases and do not require manual execution of any preflight command.

---

Next Steps

➡️ Continue to Installation Guide

---