TeamCity Kubernetes Support Plugin

Posted on by Yegor Naumov

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!

Comments below can no longer be edited.

8 Responses to TeamCity Kubernetes Support Plugin

  1. Omer says:

    December 15, 2017

    I believe there is a bug with the plugin for Token based authentication.
    I get this error message when I enter a token: “The password is too long. Entered password length is 120 characters. Please shorten the password”

    • Pavel Sher says:

      December 17, 2017

      Could you please submit a bug report in our tracker?

      • Ren says:

        January 20, 2018

        how do i file a bug for this?

  2. Ren says:

    January 19, 2018

    There is definitely a bug on token auth. I am getting an error password is too long when I upload my token.

    • Pavel Sher says:

      January 22, 2018

      Please see my comment above.

  3. Ren says:

    January 19, 2018

    I am also getting this error when I tried using Username and Password. PKIX path building failed: unable to find valid certification path to requested target.

  4. Wes says:

    February 7, 2018

    Anyone testing this locally should consider using kubectl proxy to run an HTTP proxy and work around any self-signed certificate issues with TeamCity accessing the k8s API. kubectl proxy will transparently handle auth, and you can setup TeamCity to use http & unauthorized auth strategy. In production or a remote system you can deal with configuring auth properly but don’t beat your head against the wall locally in a dev environment.

    Just be careful that you don’t open your HTTP proxy to the world thus exposing your k8s API to the world.

    Read more here:


Subscribe for updates