Installation using Helm
Overview Copied
This guide takes you through the deployment process of deploying Geneos containers in Kubernetes and OpenShift environments using Helm.
Helm is a package manager for Kubernetes. Helm uses a packaging format called charts. A chart is a collection of files that describe a related set of Kubernetes resources.
Charts are created as files laid out in a particular directory tree. They can be packaged into versioned archives to be deployed. ITRS provides updated Helm charts with each Geneos release.
For more information about Helm, see the Official Helm docs.
Helm prerequisites Copied
This section provides the prerequisites for installing using Helm, you must also ensure your system meets the general prerequisites for installation in a orchestrated environment.
For more info, see Data collection in an orchestrated environment.
Add the ITRS repository Copied
To add the ITRS repository, run the following command:
helm repo add itrs https://helm.itrsgroup.com
Create a registry secret Copied
Before deploying Helm charts, you must add a registry secret so that you can use the ITRS Docker repository. To do this, use the following command:
kubectl create secret docker-registry itrsdocker \
--docker-server=https://docker.itrsgroup.com \
--docker-username=USERNAME \
--docker-password=PASSWORD \
-n NAMESPACE
Kubernetes monitoring Copied
To perform Kubernetes log monitoring, you must have a Docker container configured with JSON logging.
Kubernetes Role-Based Acess Control requirements for Netprobe Copied
The Netprobe runs using a service account that requires certain Role-Based Access Control (RBAC) permissions in order to collect metrics. The required service account, roles, and role bindings are automatically created during installation. The Netprobe Helm chart will automatically create the ClusterRole
and ClusterRoleBinding
with get/list/watch
access to node
and node/proxy
resources. However, it is possible to disable the automatic creation of a service account and supply your own service account and roles.
The Netprobe Helm chart will also create the following resources depending on Netprobe configuration:
- If the Netprobe is configured to collect metrics for all namespaces, the
ClusterRole
will also haveget/list/watch
access todeployments
,daemonsets
,statefulsets
,pods
,resourcequotas
,replicasets
,jobs
andevents
resources in all namespaces. - If the Netprobe is configured to collect metrics for a specific namespace only, a
Role
andRoleBinding
withget/list/watch
access todeployments
,daemonsets
,statefulsets
,pods
,resourcequotas
,replicasets
,jobs
andevents
resources will be created in each of the target namespaces.
Helm deployments Copied
This section provides general information that applies to all Helm deployments of Geneos components.
Create a namespace Copied
To create the geneos
namespace, use the following command:
kubectl create namespace geneos
Install a Helm chart Copied
To install the chart, use the following command:
helm install -f <configuration_filename> -n <namespace> <release_name> itrs/<chart_name>
For example:
helm install -f config.yaml -n geneos netprobe itrs/netprobe
Note
Helm automatically creates the service accounts and roles. For more information, see Kubernetes RBAC Requirements.
Netprobe deployments Copied
This section provides information specific to Netprobe deployments.
One Netprobe or Collection Agent chart can be configured to connect to multiple Gateways and run in the same cluster.
Starting Geneos 6.3.x, the Helm chart now determines which collection image version is used during installation based on the configuration settings. By default, the image tag in the YAML file is blank, and the Collection Agent runs an unprivileged image as a non-root user.
agent:
image:
repository: docker.itrsgroup.com/collection/collection-agent
tag: ""
pullPolicy: IfNotPresent
To use an image with elevated file permissions, enable either log collection or persistence, or both, in the YAML file. This will start a Collection Agent image that has elevated file permissions. The word privileged
in the image name indicates this. For example:
collection-agent:
Container ID: docker://c73f663032997adada3f8a66d8c7b626639afa43d65f1aece4edec7e44ff3ea1
Image: docker.itrsgroup.com/collection/collection-agent:3.3.1-jre11-privileged-r0
If log collection and persistence are disabled, the default unprivileged
image will be used.
Currently, the following configurations are supported:
To fetch a list of all possible configuration options, run:
helm show values itrs/netprobe
You can construct a config.yaml
file using these options to fit your use case. The sections below provide minimal examples that you can adapt.
DaemonSet deployment Copied
You can deploy Netprobe as a DaemonSet to all matching nodes. Each DaemonSet pod collects metrics and logs for the pods on that node only. An additional StatefulSet is launched to collect metrics and events that are not node-specific, such as ResourceQuotas
. This is the only mode that supports log collection and is the default deployment mode.
To install a Netprobe to monitor full metrics and events in all namespaces, using a DaemonSet, use the following config.yaml
file:
cluster: myCluster
gateways:
- host: "10.1.1.1"
port: 7039
netprobe:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
agent:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
Non-DaemonSet deployment Copied
You can deploy a Netprobe in one pod and collect metrics for the entire cluster. However, log collection is not supported in this mode.
To install a Netprobe to monitor full metrics and events in all namespaces, without using a DaemonSet, use the following config.yaml
file:
mode: StatefulSet
cluster: myCluster
gateways:
- host: "10.1.1.1"
port: 7039
netprobe:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
agent:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
Monitor specific namespaces Copied
By default, metrics are collected for all namespaces but you can configure your Netprobe deployment to monitor specific namespaces.
To install a DaemonSet with full metrics, events, and log collection for specific namespaces, use the following config.yaml
file:
mode: DaemonSet
cluster: myCluster
gateways:
- host: "10.1.1.1"
port: 7039
namespaces:
- ns1
- ns2
netprobe:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
agent:
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
Gateway deployments Copied
This section provides information specific to Gateway deployments.
To fetch list of all possible configuration options, run:
helm show values itrs/gateway
You can construct a config.yaml
file using these options to fit your use case. The sections below provide minimal examples that you can adapt.
Insecure installation Copied
To install a Gateway in your cluster, without TLS security, use the following config.yaml
file:
licenceDaemon:
host: localhost
port: 7041
secure: false
persistence:
enabled: true
size: 1Gi
tls:
enabled: false
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "768Mi"
Secure installation Copied
To install a Gateway in your cluster, with TLS security, perform the following steps:
-
Add your
tls.key
andtls.cert
files to your secrets by running:kubectl create secret tls gw-tls --key="tls.key" --cert="tls.crt"
-
Deploy the Gateway, to a specified namespace, by running
helm install -f config.yaml -n <namespace> gateway itrs/gateway
using the followingconfig.yaml
file:licenceDaemon: host: localhost port: 7041 secure: false persistence: enabled: true size: 1Gi tls: enabled: true secret: "gw-tls" resources: limits: cpu: "1" memory: "1Gi" requests: cpu: "500m" memory: "768Mi"
Installation with a setup file Copied
To install a Gateway in your cluster with an initial setup file, use the following command:
helm install -f <configuration_filename> --set-file setup.file=<setup_file> -n <namespace> <release_name> itrs/gateway
For example:
helm install -f config.yaml --set-file setup.file=gateway.setup.xml -n geneos gateway itrs/gateway
Note
If
persistence.enabled
is set totrue
and there is a saved setup file in the persistent volume, the saved setup file will be used instead of the specified setup file.The setup file should not define the Gateway name.
Connecting to Obcerv Copied
To install a Gateway that connects to Obcerv, follow these steps:
-
Go to the Gateway directory and generate an API key file by runnning the following command:
./gateway2.linux_64 -store-app-key app-key.txt <client_id> <client_secret> obcerv
-
Create a
secret
containing your API key file by running:kubectl create secret generic app-key --from-file=app-key=app-key.txt -n geneos
-
In the Helm configuration file, set
setup.appKeySecret
to the name of thesecret
containing the API key file andsetup.obcerv.url
to the Obcerv URL. For example:licenceDaemon: host: localhost port: 7041 secure: false persistence: enabled: true size: 1Gi tls: enabled: false resources: limits: cpu: "1" memory: "1Gi" requests: cpu: "500m" memory: "768Mi" setup: appKeySecret: app-key obcerv: url: https://obcerv.example.com
-
Deploy the Gateway to a specified namespace by running:
helm install -f <configuration_filename> -n <namespace> gateway itrs/gateway
Helpful commands Copied
Check liveness endpoint Copied
Kubernetes has a mechanism to check the liveness of the component using the following command:
curl http://<np host>:<np port>/liveness
The command uses an http
protocol if the port is insecure, and an https
protocol if the port is secure.
If the component is alive, the command above will return a 200
code. Otherwise, it will return a 503
code, and will restart the container running the component.
List configuration options Copied
To see the complete list of available configuration options, run:
helm show values itrs/<chart_name>
Check chart information Copied
To check the status and version of your Helm charts, run:
helm ls
The output will look similar to:
ubuntu@ip-192-168-18-189:~$ helm ls
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
netprobe default 1 2021-08-26 18:55:28.328483978 +0800 PST deployed netprobe-5.7.6 5.7.2
To check detailed chart information, run:
helm show chart itrs/<chart_name>
The output will look similar to:
apiVersion: v2
appVersion: 5.10.0
description: ITRS Geneos Gateway
name: gateway
type: application
version: 5.10.0-beta.5