Geneos containers
Overview Copied
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 Copied
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 Copied
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 Copied
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 Copied
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.
Customize containers Copied
By default, the Geneos containers are packaged with the minimum base image and do not include Perl and Python, which are required to run action and command scripts triggered by Gateway or Netprobe.
The following steps demonstrate how to customize the Geneos Gateway container to include Perl:
-
Access the ITRS Docker registry:
docker login docker.itrsgroup.com
-
Pull the Gateway or the Netprobe image:
docker pull docker.itrsgroup.com/gateway
-
Create a Docker file:
FROM docker.itrsgroup.com/gateway:latest USER root RUN \ yum -y update && \ yum -y install perl
-
Build the Docker file to create the custom image:
docker build -t gateway:6.2-custom .
-
Test the Docker image:
docker run -d --rm --name my_gateway -p 7039:7039 gateway:6.2-custom
Configure Copied
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 Copied
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 is45
. If the environment variableREQUIRE_HUB
is set toTRUE
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 Copied
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 Copied
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 Netprobe Overview and Netprobe setup.
Alternative configuration and setup files Copied
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/{*}config{*}/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 -e NETPROBE_CONFIG="-ssl-certificate /gateway/tls/security.pem -secure" -p 7036:7036 docker.itrsgroup.com/netprobe:<version>
Centrally configured Gateways Copied
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.
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 Copied
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 ub 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>