This page describes the installation of Kubernetes using the OpsRamp ISO/OVA for both single-node and multi-node setups.

Overview

The OpsRamp-provided ISO and OVA images come pre-bundled with Kubernetes, a lightweight Kubernetes distribution. This integration simplifies the Kubernetes installation process, allowing you to bring up a functional cluster using a single command with no complex configuration required.

About Kubernetes in OpsRamp Gateway

Kubernetes is used to host and run the NextGen Gateway as a collection of Kubernetes-native applications. These applications are deployed using Helm charts and rely on Docker container images. During installation and runtime, access to a container registry is essential.

  • By default, the Gateway is configured to use the OpsRamp cloud-hosted container registry to pull the required Helm charts and images.
  • Alternatively, organizations can configure their own private or public registry to meet internal security or compliance requirements.

Registry Configuration (Optional)

Before installing Kubernetes, it is recommended to review your container registry configuration. This step is optional if you plan to use the default OpsRamp registry.

When You Can Skip Registry Configuration

If you are using the OpsRamp registry to pull Helm charts and Docker images, no additional configuration is required. The Gateway will automatically connect to OpsRamp’s registry during deployment.

When You Must Configure a Custom Registry

If you choose not to use the OpsRamp registry and instead prefer to use your own registry (public or private), you must configure it before installing Kubernetes.

Steps to Configure a Custom Registry (Optional)

  1. Open the registry configuration template:
    vi /var/cgw/asserts_k3s/registries.yaml.template
  2. Uncomment the configs section and update it with your registry credentials and endpoint:
    mirrors:
  artifact.registry:
    endpoint:
      - "https://{your-private-repo}"

configs:
  "{your-private-repo}":
    auth:
      username: "{your-username}"
      password: "{your-password}"
    Ensure proper YAML indentation to avoid syntax issues during deployment.
    Example:
    mirrors:
  artifact.registry:
    endpoint:
      - "https://hub.testrepo.com"

configs:
  "hub.testrepo.com":
    auth:
      username: "test-user"
      password: "test-password"

Installation Steps

Single Node
Multi-Node

Initialize Kubernetes (K8s) Cluster

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Select Initialize Kubernetes (K8s) Cluster to install Kubernetes on the first node.
    FieldDescription
    RepositoryContainer image repository.
    Repo UserRepository username.
    Repo PasswordRepository password.
    Read Repopass From FileReads the repository password from a file.
    Cluster CIDRKubernetes cluster network CIDR.
    Service CIDRKubernetes service network CIDR.
    Proxy UsernameProxy Username
    Proxy PasswordProxy Password
    Proxy ProtocolProxy protocol
    Proxy IPProxy server IP address
    Proxy PortProxy Port
    Skip PrechecksSkip Prechecks
    Container Attestation EnabledContainer Attestation Enabled

    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

Step 2: Verifying Kubernetes Installation

Upon successful installation, you will see output similar to:
root@node1:/home/gateway-admin# opsramp-collector-start setup init
Installing RKE2
Installed RKE2
CoreDNS is ready

Check the Kubernetes service status:

service rke2-server status

Expected output:

● rke2-server.service - Rancher Kubernetes Engine v2 (server)
     Loaded: loaded (/usr/local/lib/systemd/system/rke2-server.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/rke2-server.service.d
             └─10-environment.conf
     Active: active (running) since Tue 2026-09-29 06:53:47 UTC; 5h 55min ago
 Invocation: 4f2994dbfaf74c1a86ca4b840b1079ea
       Docs: https://github.com/rancher/rke2#readme
    Process: 1920859 ExecCondition=/bin/sh -c if systemctl is-active --quiet rke2-agent.service; then echo "Error: rke2-agent is running!"; exit 1; fi (code=exited, status=0/SUCCESS)
    Process: 1920861 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
    Process: 1920864 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
   Main PID: 1920867 (rke2)

Troubleshooting

If Kubernetes fails to install or the service is not in a running state:

  • Review the installation logs.
  • Review the Kubernetes service logs to identify the underlying error messages related to the issue (for example etcd timeouts, API server errors, or networking/plugin failures).
    sudo journalctl -u rke2-server

Initialize K8s Cluster

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Use Initialize K8s Cluster to install Kubernetes on the first node.
    FieldDescription
    Enable HAEnables high-availability deployment.
    Loadbalancer IPLoad balancer IP address for HA deployments.
    RepositoryContainer image repository.
    Repo UserRepository username.
    Repo PasswordRepository password.
    Read Repopass From FileReads the repository password from a file.
    Cluster CIDRKubernetes cluster network CIDR.
    Service CIDRKubernetes service network CIDR.
    Proxy UsernameProxy Username
    Proxy PasswordProxy Password
    Proxy ProtocolProxy protocol
    Proxy IPProxy server IP address
    Proxy PortProxy Port
    Skip PrechecksSkip Prechecks
    Container Attestation EnabledContainer Attestation Enabled

    Load Balancer IP Configuration

    The {loadbalancerIp} parameter supports specifying single IPs, IP ranges, or CIDR blocks. Below are the supported formats and examples:

    IP-rangeDescriptionResult Value
    192.25.254.45/32This is used to add single metallb IP192.25.254.45
    192.25.254.45/30This is used to add 4 IPs from a given IP192.25.254.44 - 192.25.254.47
    192.25.254.44 - 192.25.254.49This is used to add a custom range192.25.254.44 - 192.25.254.49

    Examples of {loadbalancerIp} Usage

    • Single IP:
       192.25.254.45/32
    • CIDR block of 4 IPs:
       192.25.254.45/30
    • Custom IP range:
       192.25.254.44-192.25.254.49
    • Multiple IPs and ranges (comma-separated):
       192.25.251.12/32,192.25.251.23/28,192.25.251.50-192.25.251.56

    CIDR Range Configuration (Optional)

    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

Step 1b: Adding Additional Nodes to the Cluster

After completing the setup of the first node, the next step is to add additional nodes to the existing Kubernetes cluster to achieve High Availability (HA).

Step i: View K8s Join Token

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Select View K8s Join Token to display the information required to add additional nodes.
    FieldDescription
    Kubernetes Cluster URLCluster endpoint URL.
    Kubernetes Join TokenToken required when joining a node to the cluster.
    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

Step ii: Add K8s Node

On each new node that you want to add, run the following command to join it to the existing cluster:

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Use Add K8s Node to join a node to an existing Kubernetes cluster.
    FieldDescription
    K8S TokenKubernetes join token.
    Kubernetes Cluster URLCluster endpoint URL.
    Cluster CIDRKubernetes cluster network CIDR.
    Service CIDRKubernetes service network CIDR.
    ForceForces node join operation.
    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

Repeat Step i and Step ii for each additional node to build your HA cluster. For example,

  • For a 3-node cluster, add the third node following the above steps.
  • For a 5-node cluster, repeat the process on the third, fourth, and fifth nodes. Continue as needed for larger clusters.

Step 2: Verify the Cluster Status

After adding all nodes to your High Availability (HA) cluster, verify that the Kubernetes environment is healthy and all essential components are running correctly.

Step 2a: Confirm Node Readiness

Ensure all nodes in the cluster are in a Ready state:

kubectl get nodes

Sample Output:

pgsql
CopyEdit
NAME    STATUS   ROLES                       AGE     VERSION
nodea   Ready    control-plane,etcd,master   8m3s    v1.23.5+k3s1
nodeb   Ready    control-plane,etcd,master   5m13s   v1.23.5+k3s1
nodec   Ready    control-plane,etcd,master   4m5s    v1.23.5+k3s1

Step 2b: Verify Helm Chart Deployments

Ensure required Helm-based services like Longhorn (for storage) and MetalLB (for load balancing) have been deployed successfully:

helm list -A

Sample Output:

NAME              NAMESPACE           REVISION    UPDATED                                    STATUS      CHART                  APP VERSION
ipaddresspool     kube-system         1           2025-07-09 07:10:34 +0000 UTC              deployed    ipaddresspool-2.0.0    1.16.0
longhorn          longhorn-system     1           2025-07-09 07:08:04 +0000 UTC              deployed    longhorn-1.6.2         v1.6.1
metallb           kube-system         1           2025-07-09 07:07:59 +0000 UTC              deployed    metallb-6.3.6          0.14.5

Step 2c: Check Pod Status Across All Namespaces

Verify that all pods are in a Running state and all containers within them are Ready:

kubectl get pods -A

Sample Output:

NAMESPACE         NAME                                        READY   STATUS    RESTARTS   AGEdefault           nextgen-gw-0                                4/4     Running   0          23hdefault           stan-0                                      2/2     Running   0          23h
kube-system       coredns-d76bd69b-n8jhh                      1/1     Running   0          23h
kube-system       metallb-controller-7954c9c84d-pm89k         1/1     Running   0          23h
kube-system       metallb-speaker-j69tp                       1/1     Running   0          23h
kube-system       metallb-speaker-mddqj                       1/1     Running   0          23h
kube-system       metallb-speaker-n45g4                       1/1     Running   0          23h
kube-system       metrics-server-7cd5fcb6b7-tvnps             1/1     Running   0          23h
longhorn-system   csi-attacher-76c9f797d7-2jg5w               1/1     Running   0          23h
longhorn-system   csi-attacher-76c9f797d7-qhs85               1/1     Running   0          23h
longhorn-system   csi-attacher-76c9f797d7-qn9pr               1/1     Running   0          23h
longhorn-system   csi-provisioner-b749dbdf9-chjs9             1/1     Running   0          23h
longhorn-system   csi-provisioner-b749dbdf9-hbwx2             1/1     Running   0          23h
Tabbed Interface with Table