Photo by Ross Sneddon on Unsplash

Want to understand Kubernetes Source Code? This is how you can start exploring.

In this Byte size post, we will explore few important files and directories of K8’s source code that serve as a good starting point to understand all the magic that Kubernetes does!

Kubernetes source code is a treasure chest for golang developers. But when I first started browsing the source code, it felt more like a Pandora’s Box to me. With lots of components that constitute a Kubernetes ecosystem and mind boggling lines of code for each component, it is one of the toughest code base to understand. Honestly I don’t think I will be able to understand it in my life time but I would certainly make an attempt to do so.

I was so hesitant to understand the internal workings that I started browsing the files and directories directly on Kubernetes Github repository and continued to do so for few days. But I was finding it difficult to map package dependencies in my mind and sometimes I had 20 –30 Github tabs ( each tab pointing to a file of a certain package ) open in my browser and I kept on switching between these tabs.

Finally I decided to clone the Kubernetes repository on my system (yes, I was so impatient that I forgot this basic step). To do that, we need to have git client installed on our system(refer the docs to install one). Choose an appropriate directory on your system and then execute the git clone command:

git clone

( If you are a Golang programmer, it’s more likely that you will use the command go get” )

You would also need a good IDE to browse through the directories. I use VisualStudio code which is suitable for both programmers and non programmers.

Root level files and directories

Kubernetes is written in Golang and a go program maintains all its dependent modules in a file called go.mod. If you want to know what are modules that Kubernetes depends on, you should check this file available at the root directory.

(Note: In Golang, a package is something that consists of one or more *.go files. A collection packages is called as a Module. Check this doc for more information.)


Every Go project follows as specific directory structure (though it is not mandatory but following this structure makes the code more readable and maintainable. Check this doc for more information.) and the same is applicable for Kubernetes project. Among the many directories at root level, there are 2 important directories cmd and pkg.

Every programming language has an entry point and based on this entry point the compiler knows from where it should start executing the program. Example: For a Java program, the entry point is:

public static void main(String[] args) {…}

For a go program, the entry point is the func main(){…} located in <filename>.go that declares itself as the main package.

func main()

Next, if you browse the cmd directory of Kubernetes project, you will find the source code of all the applications (or components), used by Kubernetes to perform container orchestration (or say the magic).


This is the best place to start exploring the different applications. For instance you can start with the kube-apiserver application. If you expand kube-apiserver directory you will notice that it contains a file with name apiserver.go that contains the func main().

The main func calls the function NewAPIServerCommand() from the package


If you expand the app directory there will be a file server.go which contains NewAPIServerCommand() function which is called inside func main().

NewAPIServerCommand (Cobra CLI Framework)

Hmm. Looks like we have found out how to start looking for things inside the code.

Lets take a look in the kube-controller-manager directory. Everything inside the directory looks similar to kube-apiserver. The file controller-manager.go contains the func main() which again calls NewControllerManagerCommand() from


You can now continue to trace the function calls one by one and in parallel try to understand the interfaces and custom types that each component uses. To make things easier pick a simple component like kube-apiserver and try to understand its internals before moving on to next component. Certainly this isn’t a easy task and you may not be able to figure it out in the first instance.

So what’s inside the pkg directory? Most of the directory names under pkg looks similar to the ones under cmd directory but you won’t find any files that are part of main package and there is a reason for that.

pkg directory

In a go project, pkg directory usually contains code that can be used by external applications. For Kubernetes project, most of the code could be found inside the pkg directory and is imported by the components available under the cmd directory. For example, in below screen shot, aggregator.go of kube-apiserver imports the package that’s inside the pkg directory.

kube-apiserver imports package

The developer’s have done a lot of work to keep the code clean and have also included lot’s of comments in most part of the code to make it more understandable.

It’s also worth mentioning that Kubernetes uses the Cobra framework for creating the command line interface. Once you have understood how this framework works, it will be easy for you to understand each component under the cmd directory.

With that, I will let you go so that you can start exploring the bazillion lines of Kubernetes code.

Hope this helps someone like me who has just begun to understand the internals of Kubernetes.

Let me know if I missed to mention something.Your feed backs are always welcome.

Note: CloudLego is providing free training’s on Kubernetes, Terraform, Azure Devops and Azure Cloud. If you or any of your acquaintances are interested please drop an email to and mention your interested topic in the subject line. You will then receive an email with training details. We are doing this particularly for people who are affected by current situation of Software industry but anyone who has an interest to learn is also welcome!

I work on cloud and containerization technologies and interested in coding, problem solving and writing philosophical and motivational quotes.