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!

Comments below can no longer be edited.

8 Responses to TeamCity Kubernetes Support Plugin

  1. Avatar

    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”

    • Avatar

      Pavel Sher says:

      December 17, 2017

      Could you please submit a bug report in our tracker?

      • Avatar

        Ren says:

        January 20, 2018

        how do i file a bug for this?

  2. Avatar

    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.

    • Avatar

      Pavel Sher says:

      January 22, 2018

      Please see my comment above.

  3. Avatar

    Ren says:

    January 19, 2018

    I am also getting this error when I tried using Username and Password.

    sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.

  4. Avatar

    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: https://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/

Discover more