Documenting Your Kubernetes Infrastructure for IT Professionals


Dominique St-Amand


5 min

IT application systems are complex, and as business requirements evolve, they get more convoluted over time. In today’s day and age, those systems are often built using a microservice architecture, with countless pieces. As IT professionals, it is your duty to document not only the cloud architecture but also the infrastructure of the IT application systems you are building or maintaining.

Have you ever been given the task to document the current state of your cloud infrastructure? You may be wondering where to start. Which components are connected to each other or why have they logically separated the way they are?

But what if you are using a container orchestrator such as Kubernetes (k8s). It can be even more daunting to document all the interconnections. As you get deeper into your Kubernetes infrastructure, you may ask yourself multiple questions such as:

    • How many pods are deployed?
    • Are there containers within the pods? In what namespaces are they living?
    • What are the services setup that exposes those pods?
    • What are the replication policies (replica sets)?
    • Are there any daemon sets?

Proper cloud infrastructure documentation, like the ones Cloudockit generates, can help you greatly in your obstacles as an IT professional.

Azure Kubernetes documentation and diagram generated by Cloudockit

Documentation for a Developer or Tech Lead

Documentation, as a developer, is useful when onboarding a project. It will help you tie all of the components together and visualize your overall cloud architecture. After all, seeing how all of the components work together will enable you to better understand your project. Proper Kubernetes documentation is also important when you are planning enhancements for the task/section you were given.

As a team lead, documentation can also be useful to understand how environments are set up. In some cases, your development environment, QA environment, and pre-production environments could differ from one another and be logically separated with namespaces.

Finally, having updated documentation will help you trace a request when debugging. You will easily find where the bug originated and see the trajectory it should go through to get to a pod or a container within it. If you need to debug an environment, having a clear landscape will help you minimize making certain mistakes.

Documentation for a Cloud Architect

As an architect, documentation plays a crucial role when you want to evolve your cloud architecture. For example, you may want to add pieces; a microservice, a database, a cache system, a service bus, a load balancer, or anything that is included in your architecture. You might also want to tweak the system’s overall performance from the existing pieces in place. Having strong documentation can also help you with the following.

    • Visualize migrations from legacy systems to a more modern system architecture using containers and Kubernetes
    • See if your team is respecting your naming convention
    • Present and defend your architecture when you are doing a proof of concept (POCs)
    • Easy cost management

Cloudockit’s document generation tool can help you be a more productive cloud architect. As shown in the example below, easily track your cloud spending, get details of your Kubernetes containers, and receive an overview of your best practices.

Azure Kubernetes documentation

Documentation for a System Administrator

As a system administrator, documenting the networking inflows and outflows is a very important part of your job. You might ask yourself the following questions.

      • Which ports are open?
      • Which types of protocols are the services using; HTTPS, HTTP, TCP, UDP, etc.?
      • Are you running out of IP address with your space?
      • How many resources are attributed to each pod?As a system administrator, documenting the networking inflows and outflows is a very important part of your job. You might ask yourself the following questions.

Aside from documenting the networking inflows and outflows, going through many services and rules across various environments can be extremely long. Therefore, up-to-date documentation will help you save time.

It can also be interesting to see how many roles exist within the k8s cluster; knowing which groups and users are associated with roles (role binding). Finally, having a document ready to be read can ease your manager’s worries.

Documentation for a Site Reliability Engineer (SRE)

As an SRE engineer, you are most likely responsible for coordinating deployments and making sure releases run as smoothly as possible. You may also be the first responder in case of emergencies. Additionally, before deployment, you may want to discuss strategy and get the proper authorizations from other teams. Having proper visuals such as an updated diagram that shows the interactions between components (interconnections) and the overall architecture will help you greatly in your task.

Cloudockit offers auto-generated Visio diagrams of your Kubernetes clusters. Use it as a starting point to add extra pods and switch things around. You can then show your team members the before and after.

If you are experiencing issues within your Kubernetes cluster components like your pods or ingresses, use your latest generated diagram to understand the architecture before changing components. If you have an overall view, it is easier to avoid mistakes.

Azure Kubernetes global diagram

One tool to rule them all

AWS Amazon Web Services
Microsoft Azure
Microsoft Hyper-V