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. 


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

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

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:

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

        image: groundworkdevelopment/tcg:${TAG}
        entrypoint: ["/app/", "kubernetes-connector"]
          - tcg-var:/tcg
  2. 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: 


    Pay close attention to the indenting as you are editing a YAML file and it is sensitive to order and to white space. 

  3. Restart your GroundWork server: 

    docker-compose down
    docker-compose up -d

Setting Up the Connector

  1. Sign in to your GroundWork server as an administrative user.
  2. Go to Configuration > Connectors.
  3. Click the Add icon and select the Kubernetes connector from the menu.
  4. 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. 

  5. Click Create.
  6. 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. 
  7. Drilling down into any services in a Warning or Critical state will give you a message about the issues detected.
  8. 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:

    MetricDefault ThresholdDescription
    cpu.allocatednoneTotal CPU space allocated
    cpu.coresnoneNumber of cores available in the system
    memory.allocatednoneTotal memory space allocated
    memory.capacitynoneMemory capacity available in the system
    cpunoneTotal CPU space allocated
    memorynoneTotal memory space allocated

Related Resources

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

Other TCG connectors: