The NextGen Gateway can be deployed using multiple approaches depending on your infrastructure requirements. You can either use the OpsRamp-provided ISO or OVA for a simplified deployment experience, or deploy the gateway on an existing Kubernetes cluster or a custom Kubernetes environment created using the OpsRamp Bootstrap Tool.
This document provides guidance for deploying the NextGen Gateway when you choose a Kubernetes-based setup instead of the ISO or OVA method.

OpsRamp Collector Bootstrap Tool Overview

The OpsRamp Collector Bootstrap tool is a lightweight and flexible utility designed to simplify and automate the initial (day-0) deployment of OpsRamp’s collector technologies, including the Agent and Gateway across diverse IT environments. It supports a wide range of infrastructure types, such as bare-metal, virtual machines, and cloud-native environments, running on various Linux distributions, whether on-premises or in the public cloud.

Prerequisites

  • Ensure the K3s and Helm installed before registration.
  • Ensure these prerequisites are met before starting the gateway registration process.
  • Have network access to the OpsRamp SaaS platform, either directly or via your proxy.
  • Ensure you have the OpsRamp Bootstrap Tool installed and configured on your system.
  • For proxy connections, verify that the proxy server details and credentials are correct and accessible.

To get started, you must first download the appropriate binary for your operating system - Linux, macOS, or Windows. Using a straightforward command-line interface (CLI), you can initiate the installation process with a single command.

Download the Collector Bootstrap Tool

You can download the Collector Bootstrap Tool to any machine (such as your laptop) for convenience. However, for successful installation and registration, you must execute the tool on the same host where the collector will ultimately run.

Click here to view the steps for downloading the Collector Bootstrap Tool.
  1. In the OpsRamp portal, select your client from All Clients.
  2. Navigate to Setup > Account > Collector Profile.
  3. On the COLLECTOR PROFILES page, click + ADD.


  1. On the configuration page, enter the following details:

    • Profile Name: Provide a name for the profile you are creating.
    • Profile Type: Select either Standard or Elastic. By default, Standard is selected.
      To enable the Elastic option, please contact OpsRamp Support Team. For more information on this feature, refer to the Elastic Collector Profile document.
    • Description: Add a short description for the profile. (Optional)
    • Gateway Collector: Select the CLOUD-NATIVE APPLICATION (INSTALLER) NEXTGEN tile.


  2. Click NEXT. The instructions page appears.


  1. Login to your Cloud-Native Application (installer) host.
  2. Select the Architecture from below:
    • Linux ARM
    • Linux AMD
    • Mac ARM
    • Mac AMD
    • Windows AMD
  3. Run the wget command provided on the instruction page to download the Gateway. The command varies based on the selected architecture.
  4. Run the commands provided on the instruction page to register the Gateway.
  5. Use the following command to check the bootstrap tool version.
    opsramp-collector-start --version
    Sample Response:
    root@node1:/home/gateway-admin# opsramp-collector-start --version
opsramp-collector-start version 19.0.0

Available Commands

CommandsDescription
installDownload and register the collector (agent, gateway)
uninstallUnregister and delete the collector
setupSetup kubernetes and high availability

Create a Namespace(optional)

You can create the required namespace by running the following command:

kubectl create namespace <namespace-name>
Example:
kubectl create namespace gateway1
Verify that the namespace was created successfully:
kubectl get namespaces

Note: The above step is optional. If you don’t want to create a custom namespace, you can skip it. If you don’t specify a namespace, the Gateway will be installed in the default namespace.

Installation and Registration Steps

Step 1: Get the activation token

To find the Activation Token, navigate to Setup > Account > Collector Profiles.


Step 2: Install and Register NextGen Gateway

There are multiple options to install NextGen Gateway, as mentioned below.

Option 1: Registering the NextGen Gateway with direct connection

View details. Use the OpsRamp Bootstrap Tool for registration. The basic command format is:
opsramp-collector-start install --environment k8s --url {OpsRamp Server URL} --key {Gateway unique authentication token}

Sample Response

root@node1:/home/gateway-admin# opsramp-collector-start install --environment k8s --url uat.opsramp.net --key 28128ba2-72de-4f92-8c79-362c778d1a6e 
System requirements check passed ✔ 
Repository check passed ✔
Coredns status check passed ✔
Opsramp cloud checks passed ✔ 
Gateway registration pre-checks passed ✔ 
Installing Agent
Pulled: us-docker.pkg.dev/opsramp-registry/gateway-cluster-charts/opsramp-nextgen-agent:2.0.0
Digest: sha256:3a445c9d58d4571c03483b1f8bdc85bf0526f21b1774c9554e3d4660a44ceafe
NAME: opsramp-nextgen-agent
LAST DEPLOYED: Thu Apr 24 10:33:30 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
Pulled: us-docker.pkg.dev/opsramp-registry/gateway-cluster-charts/nextgen-gw:19.0.0
Digest: sha256:2c4d4fa75d2cbaecc442613b3c9a6cecab2162680cd17d3e01c5ecbd27c5143e
NAME: nextgen-gw
LAST DEPLOYED: Thu Apr 24 10:33:34 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
OpsRamp gateway installed successfully

Option 2: Registering NextGen Gateway with proxy connection

View details. For security reasons, you might not be allowed to permit direct outbound connections from your internal network. Instead, you can configure proxy servers within your environment to control and monitor external access.
  • All third-party tools and users, including OpsRamp Gateways, must connect to the internet through these proxies.
  • Because OpsRamp Gateways are deployed within your environment, any communication with the OpsRamp Cloud must go through the proxy. If you have a proxy in place, use the appropriate command to register the Gateway via the proxy during installation.
  • The examples below show how you can register a Gateway using a proxy. Once installed, the opsramp-collector-start tool will attempt to register the Gateway through your specified proxy server.
  • The tool supports registration using a proxy with or without authentication credentials, as shown in the examples.

Register through proxy with credentials

opsramp-collector-start install --environment {Environment} --url {OpsRamp Server URL} --key {Gateway unique authentication token} --proxy-protocol {Proxy Protocol http/https} --proxy-ip {Proxy IP Address} --proxy-port {Proxy Port} --proxy-username {Proxy Username} --proxy-password {Proxy Password}

Register through proxy without credentials

opsramp-collector-start install --environment {Environment} --url {OpsRamp Server URL} --key {Gateway unique authentication token} --proxy-protocol {Proxy Protocol http/https} --proxy-ip {Proxy IP Address} --proxy-port {Proxy Port}

Option 3: Registering NextGen Gateway using yaml config file

View details. Specifying multiple flags during Gateway registration can be cumbersome, especially if your environment requires complex configurations.

To simplify this process, you can register the NextGen Gateway using a YAML configuration file. This approach lets you define all required registration parameters in a single file, eliminating the need to pass multiple command-line flags.

With the YAML method, you can:

  • Set memory limits for the Gateway pod
  • Provide SNMP trap v3 credentials
  • Customize other environment-specific settings

To complete the registration process using the YAML method, follow these steps:

  1. Create a YAML file using the sample provided below, incorporating the necessary modifications as required.
    Sample YAML

    config:
squid-proxy: disable
third-party-app: disable
 
proxy:
  proxy-protocol:
  proxy-ip:
  proxy-port:
  proxy-username:
  proxy-password:
 
helmchart-version: 1.6.0
 
repo:
  repository:
  repo-user:
  repo-password:
  read-repopass-from-file:
 
gateway-name:
storage-class:

#Pass the snmp_v3 credentials in below format. Put 2 spaces under the "snmp_trap_v3_credentials" and pass the keys after those spaces (spaces are for yaml intonations)
#snmp_trap_v3_credentials: |-
#  key1
#  key2
#  key3
# Refer https://docs.opsramp.com/platform-features/feature-guides/monitoring-using-snmp-traps/#configure-snmp-v3-traps for more details on configuring SNMP credentials.
 
snmp_trap_v3_credentials: |-
 
vprobe:
  resources:
    limits:
      memory: "5096Mi"
 
nativebridge:
  resources:
    limits:
      memory: "500Mi"
 
squid:
  resources:
    limits:
      memory: "500Mi"
       
postgres:
  resources:
    limits:
      memory: "1024Mi"
#Add service types based the requirement and if the servicetype is not passed then by default gateway will use LoadBalancer serviceType.
#Use either LoadBalancer or Cluster-IP types.
squidproxy-servicetype: "LoadBalancer"
gateway-servicetype: "LoadBalancer"
trafficDirectorMode: disable
webprobeVersion: 21.0.0

  2. Save above YAML file with ‘registration.yaml’.

  3. Specify the path to the ‘registration.yaml’ file in the following command to complete the Gateway registration.

    opsramp-collector-start install --url {OpsRamp Server URL} --key {Gateway unique authentication token} --registration-config {registration.yaml file path}

Example

opsramp-collector-start install --url uat.opsramp.net --key 2e245f6b-0056-4ad3-84e7-1553f42af1be --registration-config /home/gateway-admin/registration.yaml

The install commands in the above options performs several key tasks:

  • Validates the host environment where the collector will run.
  • Automates previously manual steps like authentication and registration with the OpsRamp cloud platform.
  • Customizing resource settings, such as memory limits for the Gateway pod.
  • Optionally, it can also trigger automatic infrastructure discovery, with no extra configuration needed on the cloud side.

By consolidating setup steps into a single command, the Bootstrap tool streamlines the onboarding process, saving time and reducing the chance of errors.

Available Flags

View details.
FlagsDescription
--cloud-providerSpecifies the cloud provider for the gateway installation. Supported values: AWS, GCP, AZURE, OCI.
--cluster-nameSpecifies the name of the Kubernetes cluster. This name will be displayed in the gateway interface.
--config (-c)Specifies the initial discovery configuration file for the Gateway installation.
--debugEnables debug logging for troubleshooting purposes. Default is false.
--environment (-e)Specifies the environment for Gateway installation. Supported values: k8s (Kubernetes) or docker. Default is k8s.
--gateway-name (-N)Specifies the display name for the Gateway in the management profile.
--helmchart-version (-V)Specifies the version of the Helm chart to deploy in the Kubernetes environment.
--help (-h)Displays help information for installation.
--key (-k)Specifies the unique authentication token required for Gateway registration.
--namespace (-n)Specifies the Kubernetes namespace for Gateway deployment. Default is default.
--proxy-ip (-i)Specifies the IP address of the proxy server used for Gateway registration and communication.
--proxy-password (-P)Specifies the password for the proxy server used during Gateway registration and communication.
--proxy-port (-p)Specifies the port number of the proxy server used for Gateway registration and communication.
--proxy-protocol (-r)Specifies the protocol used by the proxy server for Gateway registration and communication.
--proxy-username (-U)Specifies the username for authenticating with the proxy server during Gateway registration and communication.
--read-repopass-from-file (-f)Specifies a file path from which to read the repository password for authentication during Gateway installation.
--registration-config (-F)Specifies the path to a YAML configuration file containing registration parameters for the Gateway installation.
--repo-password (-s)Specifies the password for authenticating with the custom repository during Gateway installation.
--repo-user (-a)Specifies the username for authenticating with the custom repository during Gateway installation.
--repository (-R)Specifies the custom repository URL from which to pull Helm charts and container images during Gateway installation.
--skip-prechecksSkips environment and system prechecks during Gateway registration. Accepts true or false. Default is false.
--squid-proxy (-S)Enables or disables the Squid proxy service for Gateway registration. Supported values: enable or disable.
--storage-class (-C)Specifies the Kubernetes storage class to use for dynamic provisioning of persistent volumes required by the Gateway.
--third-party-app (-t)Enables or disables integration with third-party applications during Gateway installation. Supported values: enable or disable.
--url (-u)Specifies the OpsRamp SaaS platform URL for Gateway registration and communication.
--webprobe-version (-w)Specifies the version of the Synthetics (WebProbe) component to deploy in the Kubernetes environment.

Step 3: Verify for Successful Gateway Registration

After a successful deployment, the Gateway runs as one or more pods within the Kubernetes cluster. To check the status of the Gateway pod, run the following command:

kubectl get pods -n <namespace>

Sample Response

root@node1:/home/gateway-admin# kubectl get pods
NAME                        READY   STATUS    RESTARTS   AGE
nextgen-gw-0                3/3     Running   0          2m52s
nextgen-gw-redis-master-0   1/1     Running   0          2m52s
opsramp-agent-49dx4         1/1     Running   0          3m1s

Once the gateway-related pods are deployed in your Kubernetes cluster and all pods are in the Running and Ready state, the gateway establishes a secure connection to the OpsRamp Cloud. To verify the gateway connectivity status:

  1. Log in to the OpsRamp Portal.
  2. Navigate to Setup > Account > Collector Profiles.
  3. Confirm that your gateway is listed and shows as connected.



Use Bootstrap Tool to Uninstall the NextGen Gateway

To uninstall the NextGen Gateway using the OpsRamp Bootstrap Tool, run the following command.

sudo opsramp-collector-start uninstall --environment {Environment} ---namespace {NAMESPACE NAME}

Available Flags

FlagsDescription
--environment (-e)Specifies the environment for Gateway uninstallation. Supported values: k8s (Kubernetes) or docker. Default is k8s.
--namespace (-n)Specifies the Kubernetes namespace for Gateway uninstallation. Default is default. Required only for Kubernetes environments.
--debugEnables debug logging for troubleshooting purposes. Default is false.
--help (-h)Displays help information for uninstallation.

Example:

opsramp-collector-start uninstall --environment k8s

Sample Response:

root@opsram-gateway:/home/gateway-admin# opsramp-collector-start uninstall --environment k8s
Uninstalling the OpsRamp Gateway in K8S environment. Please wait...
release "nextgen-gw" uninstalled

Successfully Uninstalled OpsRamp Gateway in K8s environment.

Upon uninstallation:

  • The Gateway will be disconnected from the OpsRamp SaaS platform.
  • All Gateway related resources in the Kubernetes cluster - such as pods, config maps, secrets, and services will be cleaned up.

Once the CLI returns successfully, navigate to Setup > Account > Collector Profiles to check if the Gateway is de-registered successfully.


Troubleshooting

If you encounter errors during installation or registration using the OpsRamp Collector Bootstrap Tool, refer to the following common issues and their sample CLI outputs:

  • Incorrect OpsRamp Cloud API server URL
    If the provided URL is invalid or unreachable, you may see an error similar to:

    root@opsram-gateway:/home/gateway-admin# opsramp-collector-start install --url invalid-url.opsramp.com --key xxxxxxxxx
Get "https://invalid-url.opsramp.com/saregandlicdownload.do?action=registrationRequirements&activation_token=1688e815-20fb-4967-9357-107e73b89970": dial tcp: lookup invalid-url.opsramp.com on 127.0.0.53:53: no such host

  • Gateway already registered
    Attempting to re-register an already registered Gateway will result in:

    root@opsram-gateway:/home/gateway-admin# opsramp-collector-start install --url xxx.opsramp.com --key xxxxxxxxx
Gateway is already registered to cloud

  • Kubernetes server not reachable
    If the Kubernetes server is unreachable, the CLI will display:

    root@opsram-gateway:/home/gateway-admin# opsramp-collector-start install --url xxx.opsramp.com --key xxxxxxxxx
Unable to get helm status exit status 1: Error: Kubernetes cluster unreachable: Get "https://127.0.0.1:6443/version": dial tcp 127.0.0.1:6443: connect: connection refused

Additional Recommendations

  • Regularly update your Kubernetes and Helm versions to stay aligned with security patches and new features.
  • Validate your cluster networking and storage setup before installing the Gateway to avoid common deployment issues.

If you experience installation issues not covered in the Troubleshooting section above, consult your internal Kubernetes administrator for further assistance.