Features FYI How-To's

TeamCity Kubernetes Support Plugin

Kubernetes nowadays is quite a popular way to run Docker containers. A number of teams and organizations already have a Kubernetes cluster configured and used in production.

Now with the help of the TeamCity Kubernetes Support plugin, it is possible to use the same infrastructure to run TeamCity build agents.

The plugin is compatible with TeamCity 2017.1.x and later.

First, download the plugin and install it on the TeamCity server as usual.

Then you can start by configuring a cloud profile in a project:


Specify the URL of the Kubernetes API server (aka Kubernetes master), select the appropriate namespace.

Select one of the Kubernetes API authentication options:


The next step after connecting to the Kubernetes API is creating a cloud image.


There are two options available:

  • Simply run single container: good choice for those who don’t know about all the powerful Kubernetes features but want to simply run its container;
  • Use pod template from deployment: will handle all the possible advanced scenarios of configuring workload to a Kubernetes cluster like multi-container pods, node/pod affinity and toleration, etc.

When the “Simply run single container” mode is selected, users can specify the name of the Docker image with the build agent they want to use.

In our setup, we are using the official TeamCity Build Agent image which is supported by the plugin. You can also create your own image.

Other options like Docker command, Docker arguments, and image pull policy, will be useful as well.


Another cloud image option is ‘Use pod template from deployment’.

Here you simply specify a deployment name: remember to check that the deployment belongs to the same namespace you’ve provided in the cloud profile. You can either use the official TeamCity Build Agent image in your deployment like in the example below, or your own image.


There is a small trick here. When given a deployment name, the plugin will not actually use it as deployment, but it will extract the PodTemplateSpec section from its definition and use it to create the plugin’s own pods. The plugin’s own pods means that the pods will not be connected to deployment anyhow. The Kubernetes deployments feature will not be used to manage the pods’ lifecycle. The TeamCity server will take care of those pods on its own. Deployment will be used as a container of PodTemplateSpec which can be referenced by name.

After a cloud profile is created and saved, you will be able to start TeamCity agents running in containers in the scope of the pods on the Kubernetes cluster. TeamCity will mark every started pod with a set of specific labels.


Using those labeled pods, you can always determine which TeamCity server started a particular pod, which cloud profile and cloud image are affected.

Feel free to download the plugin, try it, and share your feedback with us!

Or you can TestDrive it in the cloud.

Happy building with TeamCity!

image description