TCG Kubernetes Connector

The GroundWork TCG Kubernetes connector lets you use the metrics API in Kubernetes clusters to monitor key metrics exposed on the metrics endpoint.

Requirements

The basic requirement is for a Kubernetes cluster to monitor. If you are new to Kubernetes, you will likely be testing on a cloud-based or similarly controlled environment. This is useful for learning kubectl commands, and setting up monitoring of Kubernetes with GroundWork will require some familiarity with this command-line tool.

You will need administrative privileges over any cluster you want to monitor. This is because you must install the Metrics server, and make changes to its accessibility from the GroundWork server (or at least from TCG).

You will need to authenticate to the cluster. You have four options, and you only need to configure one:

Run TCG inside the cluster as a service (experimental)
Use username/password authentication to the cluster
Use a Kubernetes authentication bearer token (recommended)
Use a Kubernetes config file that contains the authentication information

There are many possible configurations of Kubernetes, so it's not possible to describe all the variations in this document. The Kubernetes documentation and also Related Resources below provides examples to work from. In general, you can generate a bearer token with the command:

kubectl describe secrets

CODE

This should allow you to display the bearer token and copy and paste it in for that authentication method.

You should be able to generate a yaml file with the command:

kubectl get serviceaccounts -o yaml

CODE

this will give you output you can pipe to a file and then transfer to your workstation, and hence upload to the GroundWork UI.

Setting Up TCG

The easiest way to run the TCG instance that handles the connection to Kubernetes is to run it as a container under docker-compose on a GroundWork server. Of course, TCG is just a Go program and it's possible to deploy it differently, so it's up to you. Here's how to set it up as a container:

Edit the docker-compose.override.yml file in the gw8 directory of your GroundWork server. In the services: section, add:

  tcg-kubernetes:
    image: groundworkdevelopment/tcg:${TAG}
    entrypoint: ["/app/docker_cmd.sh", "kubernetes-connector"]
    volumes:
      - tcg-var:/tcg

CODE

At the bottom of the file, under the volumes: section, make sure that volumes: is uncommented, and that tcg-var: is listed as a volume, for example:
```
volumes:
  tcg-var:
```
Pay close attention to the indenting as you are editing a YAML file and it is sensitive to order and to white space.

Restart your GroundWork server:

docker-compose down
docker-compose up -d

CODE

Setting Up the Connector

Sign in to your GroundWork server as an administrative user.
Go to Configuration > Connectors.
Click the Add icon and select the Kubernetes connector from the menu.
Enter the following information:
- Connector Name: Provide a unique name
- Depending on your chosen authentication method, select the radio button for the method and fill in the credentials (if needed).
  - Kubernetes TCG Host Address: Enter tcg-kubernetes:8099, unless you have changed where TCG is running with a custom configuration.
  - Interval: Set a polling Interval, Timeout, and Retries as desired.
    
    You can set an interval as fast as once per minute. Depending on the metrics you gather, the faster the interval, the more overhead involved.
Click Create.
After a few moments, you will see new hostgroups appear in Status. This will contain hosts and several services representing the performance of your Kubernetes services.
Drilling down into any services in a Warning or Critical state will give you a message about the issues detected.

While the thresholds are all defaulted off (-1), you can set them in the Metrics tab. You can also override them in the Status Summary. The following metrics are supported by default:

Metric	Default Threshold	Description
cpu.allocated	none	Total CPU space allocated
cpu.cores	none	Number of cores available in the system
memory.allocated	none	Total memory space allocated
memory.capacity	none	Memory capacity available in the system
cpu	none	Total CPU space allocated
memory	none	Total memory space allocated

Related Resources

Here's some useful information about Kubernetes relating to topics in this article:

Example: Connecting from outside of a cluster with authentication: https://github.com/kubernetes/client-go/blob/master/examples/out-of-cluster-client-configuration/main.go
Example: Connecting In-Cluster no authentication: https://github.com/kubernetes/client-go/tree/master/examples/in-cluster-client-configuration
How to generate a Bearer Token: https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#without-kubectl-proxy

Other TCG connectors:

Page:

Application Performance Monitoring
Page:

Elasticsearch Monitoring
Page:

Microsoft 365 Monitoring
Page:

SNMP Monitoring