Geneos ["Geneos"]
You are currently viewing an older version of the documentation. You can find the latest documentation here.
["Geneos > Gateway"]["User Guide"]

Geneos containers

Overview

Gateways or Netprobes are available as Docker images to run as containers.

This is especially useful for deploying Geneos in orchestrated environments. For information about running Gateway in Kubernetes, see the Deploying Gateway into Kubernetes GitHub page.

Intended audience

Users of Geneos containers should be familiar with configuring docker containers and managing orchestrated environments.

You must ensure that containers are started with access to all ports required for the Gateway or Netprobe features you want to use. Additionally, you may need to mount directories on the host system to provide configuration files.

Please consult the official Docker or Kubernetes documentation if you require more information about managing containers.

Prerequisites

To run the Geneos containers, you must have either of the following installed:

  • Docker
  • Kubernetes

In addition, you must ensure all Geneos components have network access to each other. When using multiple containers together this may require configuring a network bridge.

Install

To run Geneos containers, you must download the container image from the ITRS docker registry.

To access the ITRS docker registry, run:

docker login docker.itrsgroup.com

This prompts you to provide login details, these are the same as the credentials you have been provided to access the ITRS website.

If you do not have login credentials, you can request these from the ITRS Registration page.

Available versions

The container images for Gateway and Netprobe are available beginning Geneos 5.4.x and newer released versions. The image names use the format <product>:<version>. You can pull the most recent version by using <product>:latest. For example:

  • gateway:5.4.0, gateway:5.5.0, gateway:5.5.1, gateway:latest, and so on.

  • netprobe:5.4.0, netprobe:5.5.0, netprobe:5.5.1, netprobe:latest, and so on.

Configure

You can mount directories on the host machine to provide configuration files for Geneos containers. You must ensure any directories you want to mount exist before starting containers.

Gateway configuration

Gateway is configured at startup by reading a gateway.gci file. By default, the Gateway container will use an example configuration stored at /gateway/config/gateway.gci in the container. The gateway.gci file sets the location the Gateway looks for setup files and data. By default, these are /gateway/persist/setup and /gateway/persist/data respectively.

Note the following special conditions when configuring Gateway in Docker:

  • If a Gateway Hub location is specified in the gateway.gci file, the Gateway container will attempt to fetch its setup files using centralised configuration. For more information, see Obtain Gateway setup from Gateway Hub in Centralised Gateways User Guide.
  • If a Gateway container is configured to connect to Gateway Hub, it will wait for a connection to be established before starting the Gateway. The timeout duration is set, in seconds, by the WAIT_TIME environment variable. The default value is 45. If the environment variable REQUIRE_HUB is set to TRUE then a timeout will terminate the process, otherwise after the timeout Gateway will start without Gateway Hub.
  • If centralised configuration is required, then Gateway startup will fail if Gateway Hub is not available.
  • The Gateway container does not create log files. Logging is performed using Docker and to read the Gateway log, run docker logs <container_name>.
  • If you are mounting local directories, you can add --user $(id -u):$(id -g) as an option when starting the container so that files are created and edited using your user ID.
  • If you are using script commands, by default Gateway will check the /gateway directory for available scripts. You must specify an absolute path to use scripts from a mounted directory. For more information about script commands, see Configuration in Gateway Commands.
  • If you want to use the hot standby feature you must use two Gateway containers. You cannot use this feature with a mixture of Gateway containers and regular Gateways.

For more information about Gateways, see Gateway Introduction and Gateway Installation Guide.

Alternative configuration and setup files

You can mount directories on the host machine to provide alternative configuration or setup files. This is a standard Docker feature.

For example, to start the Gateway container with an alternate setup directory run:

docker run -d --rm --name itrs_gw -v $(pwd)/setup:/gateway/persist/setup -p 7038:7038 docker.itrsgroup.com/gateway:<version>

You can also provide an alternative gateway.gci configuration file by setting the GATEWAY_CONFIG environment variable in the container with the contents of the alternate gateway.gci file.

For example, to start the Gateway with a gateway.gci configuration file as follows:

-resources-dir /opt/gateway/resources -demo -setup /gateway/persist/setup/gateway.setup.xml -gateway-hub https://hub.itrsgroup.com:8081

Set GATEWAY_CONFIG when running the container:

docker run -d --rm --name itrs_gw -e GATEWAY_CONFIG="-resources-dir /opt/gateway/resources -demo -setup /gateway/persist/setup/gateway.setup.xml -gateway-hub https://hub.itrsgroup.com:8081" -p 7038:7038 docker.itrsgroup.com/gateway:<version>

Netprobe configuration

Netprobes are configured at startup by reading a netprobe.gci file. By default, the Netprobe container will use an example configuration stored at /netprobe/config/netprobe.gci in the container. The netprobe.gci file sets the location the Netprobe looks for setup files, by default this is /netprobe/persist/setup.

Note the following special conditions when configuring a Netprobe in Docker:

  • Certain plugins require root access. For these plugins, you must add --user root as an option when starting the container.
  • The Netprobe container does not create log files. Logging is performed using Docker and to read the Netprobe log, run docker logs <container_name>.
  • If you are mounting local directories, you can add --user $(id -u):$(id -g) as an option when starting the container so that files are created and edited using your user ID.

For more information about Netprobes, see Introduction to Netprobe and Netprobe setup.

Alternative configuration and setup files

You can mount directories on the host machine to provide alternative configuration or setup files. This is a standard Docker feature.

For example, to start the Netprobe container with alternate configuration and setup directories run:

docker run -d --rm --name itrs_np -v $(pwd)/netprobe.gci:/netprobe/netprobe.gci -v $(pwd)/setup.xml:/netprobe/setup.xml -p 7036:7036 docker.itrsgroup.com/netprobe:<version>

You can also provide an alternative netprobe.gci configuration file by setting the NETPROBE_CONFIG environment variable in the container with the contents of the alternate netprobe.gci file.

For example, to start the Netprobe with a netprobe.gci configuration file as follows:

-ssl-certificate /gateway/tls/security.pem -secure

Set NETPROBE_CONFIG when running the container:

docker run -d --rm --name itrs_np NETPROBE_CONFIG="-ssl-certificate /gateway/tls/security.pem -secure" -p 7036:7036 docker.itrsgroup.com/netprobe:<version>

Centrally configured Gateways

You can start a Gateway container using a setup files provided by Gateway Hub central configuration. For more information about centralised configuration, see Centralised Gateways User Guide.

You must specify the Gateway Hub you wish to connect to in your gateway.gci file. An example file is provided below:

# Gateway2 Config File
-resources-dir /opt/gateway/resources
-gateway-name "Demo Gateway"
-gateway-hub https://<hub_hostname>:8081
-demo

To start a Gateway container using the a gateway.gci file on the host machine, run:

docker run --name itrs_gw --rm -v $(pwd)/gateway.gci:/gateway/config/gateway.gci -p 7039:7039 docker.itrsgroup.com/gateway:<version>

This will start the Gateway and attempt to fetch setup files from the specified Gateway Hub. If no setup files exist, a blank configuration will be created and added to the central store.

If your Gateway or Gateway Hub is using custom ports, ensure these are accessible by the host machine and the Gateway container.

Publish to Gateway Hub

You can publish metrics data from a Gateway container to Gateway Hub.

The Gateway must trust certificates provided by Gateway Hub. You will need to add the ca.crt file of the certificate authority that signs Gateway Hub certificates to Gateway's trusted list. For a default installation of Gateway Hub this file is located at /opt/hub/<hub_version>/tls/ca.crt.

To start a Gateway container using a ca.crt file on the host machine, run:

docker run --name itrs_gw --rm -v $(pwd)/ca.crt:/gateway/tls/ca.crt -p 7039:7039 docker.itrsgroup.com/gateway:<version>

To start publishing metrics to Gateway Hub you must configure this in the Gateway setup. You can do this using the Gateway Setup Editor following the instructions in Gateway Hub Quickstart.

Alternatively, you can add the following XML to your setup file:

<gatewayHub>
    <enabled>true</enabled>
    <publishingAddress>hub_hostname:9092</publishingAddress>
    <additionalSettings>kafka.security.protocol=ssl
	kafka.ssl.ca.location=/gateway/tls/ca.crt</additionalSettings>
</gatewayHub>