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 Kubernetes 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)

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Select Create Namespace to create one or more Kubernetes namespaces.
    FieldDescription
    NamespacesEnter one or more namespace names, separated by commas.
    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

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: Configure Sensitive Data Using Kubernetes Secrets (Optional)

Starting with Gateway 22.0.0, the NextGen Gateway Helm chart supports retrieving sensitive configuration values from Kubernetes Secrets. This helps secure gateway registration and proxy credentials without storing them in plaintext in Helm values files, Git repositories, or deployment pipelines.

Benefits

  • Protects sensitive credentials from being exposed in Helm chart values files.
  • Reduces the risk of exposing credentials through deployment commands and configuration reviews.
  • Allows sensitive configuration to be managed separately from the Helm chart.
  • Maintains compatibility with existing Helm-based deployments.

Supported Secret Keys

The NextGen Gateway Helm chart supports the following secret keys:

SettingSecret KeyDescription
Gateway registrationAPI_SERVEROpsRamp API server URL
Gateway registrationACTIVATION_KEYGateway activation key
ProxyPROXY_IPProxy server IP address
ProxyPROXY_PORTProxy server port
ProxyPROXY_USERNAMEProxy user name
ProxyPROXY_PASSWORDProxy password
ProxyPROXY_PROTOCOLProxy protocol
ProxyPROXY_CONNECTION_TYPEProxy connection type

Prerequisites

Before installing the Helm chart:

  • Create the target Kubernetes namespace.
  • Create the Kubernetes Secret that contains the sensitive values.
  • Ensure the Secret exists in the same namespace where you deploy the Gateway.

Create a Kubernetes Secret

Create a Secret containing the Gateway registration and proxy configuration values. Replace the placeholders with values from your environment.

kubectl create secret generic gw-credentials \
  --from-literal=API_SERVER=<api-server-url> \
  --from-literal=ACTIVATION_KEY=<activation-key> \
  --from-literal=PROXY_IP=<proxy-ip> \
  --from-literal=PROXY_PORT=<proxy-port> \
  --from-literal=PROXY_USERNAME=<proxy-username> \
  --from-literal=PROXY_PASSWORD=<proxy-password> \
  --from-literal=PROXY_PROTOCOL=<proxy-protocol> \
  --from-literal=PROXY_CONNECTION_TYPE=<connection-type> \
  -n <namespace>

Configure Image Pull Secrets for Private Registries

When container images are stored in a private registry, configure Kubernetes image pull Secrets.

Create an Image Pull Secret
kubectl create secret docker-registry <secret-name> \
  --docker-server=<registry-url> \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <namespace>
Reference the Image Pull Secret During Installation
helm install <release-name> <chart-path> \
  --set imagePullSecrets[0].name=<secret-name> \
  -n <namespace>

The Helm chart uses the specified image pull Secret to authenticate with the container registry before pulling Gateway images.

Security Considerations

OpsRamp recommends using Kubernetes Secrets for production deployments. Secrets help avoid storing sensitive credentials in source control, prevent sensitive values from appearing in Helm installation commands, and improve alignment with organizational security and compliance requirements.

Step 3: Install and Register NextGen Gateway

  1. Run the following command to open the Terminal UI:
    opsramp-collector-start terminal-ui
  2. Select Install Gateway to deploy and register an OpsRamp Gateway.
    FieldDescription
    (Required) OpsRamp API ServerOpsRamp platform URL.
    (Required) Activation TokenRegistration token.
    Gateway VersionGateway version to deploy.
    RepositoryContainer image repository.
    Repo UserRepository username.
    Repo PasswordRepository password.
    Read Repopass From FileReads repository password from a file.
    Proxy ProtocolProxy protocol.
    Proxy IPProxy server IP address.
    Proxy PortProxy server port.
    Proxy UsernameProxy username.
    Proxy PasswordProxy password.
    Storage ClassKubernetes storage class.
    Cluster NameKubernetes cluster name.
    Gateway NameGateway instance name.
    Cloud ProviderCloud platform identifier.
    Credentials SecretKubernetes secret containing credentials.
    Registration ConfigRegistration configuration.
    ConfigAdditional configuration parameters.
    Webprobe VersionWebprobe version.
    Squid ProxyEnables Squid proxy during installation.
    Third Party AppEnables third-party application integration.
    Skip PrechecksSkips installation prechecks.
    Select Execute to save the entered information.
  3. Press ESC to close the Terminal UI.

Step 4: 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

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 ---namespace {NAMESPACE NAME}

Available Flags

FlagsDescription
--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

Sample Response:

root@opsram-gateway:/home/gateway-admin# opsramp-collector-start uninstall
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.