Table of Contents
You’ve spent weeks researching Kubernetes and its concepts, from clusters to control planes to pods to ConfigMap. Against all odds, you have finally launched a testing cluster on AWS. As a developer, this is all uncharted territory for you. Because Kubernetes is part of the “new” full-stack your organization has embraced, you need to learn a new way of deploying code.
Eventually, you write the Kubernetes manifest that defines your deployment, type out:
An error.
Do you know what the error means?
For a while now, we have been building Monokle - an open-source visual tool, a Kubernetes manifest IDE to help YAML experts and newbies alike to edit, debug and manage manifests easier and better.
What is a Kubernetes YAML Manifest?
A Kubernetes manifest is a YAML file that describes each component or resource of your deployment and the state you want your cluster to be in once applied.
Here is an example for a ReplicaSet and three Nginx pods:
Once you’ve created a Deployment, you can always edit your manifest file and re-apply it using `kubectl apply…` to declare a new state, scale the number of pods, or clean up your cluster.
Where Kubernetes manifests meet Helm and Kustomize
If you’ve spent time in the Kubernetes ecosystem, you’ve probably heard about tools such as Helm and Kustomize. Both extend manifests to improve the developer experience around Kubernetes.
Let’s be clear about what they are:
- Helm: A package manager for Kubernetes that uses Charts, which are Go-based templates that ultimately generate YAML-based manifests for deployments.
- Kustomize: A configuration management tool for customizing Kubernetes objects. With Kustomize, you can take an existing manifest and apply overrides without touching the original YAML file.
While these tools can help avoid some errors, by either delivering community-validated manifests or narrowing the changes you make on existing manifests, unfortunately they don’t help you to validate your manifests, suggest fixes nor to display relationships across the resources.
Why are Kubernetes manifest errors hard to find?
Some manifest-related errors show up right away, like in the scenario that kicked this piece off.
A few common Kubernetes manifest errors
To help you solve some errors you might already have on your plate, let’s jump into some of the most common, why they happen, and how to solve them.
1. Indentation
As a configuration language, YAML uses maps and arrays to understand how the resources in your manifest are related to one another.
Both lists and maps are defined in YAML using indentation. So, your resources and configurations must be correctly associated.
YAML is quite relaxed with the rules around indentation, not forcing any number of spaces per line, so the important rules are to use spaces and be consistent with indentation throughout your manifests.
2. Maps vs. arrays
In YAML, maps are key-value dictionaries, while arrays are essentially lists, and they have unique syntaxes.
To borrow from our example manifest above, this is a map:
And here’s a list:
The difference? Lists are set off by hyphens (-).
Maps are used when there’s a single value for a given key.
Arrays define a list of similar objects, like several containers that should deploy in conjunction.
Often the reasons for using one versus the other in a manifest aren’t clear, and only make sense once you’ve dove into documentation.
3. `invalid type for…` or `got "string", expected "integer"`, aka expected vs. received values
4. Typos
5. Invalid references between resources
Manifest will likely reference other resources, such as ConfigMaps, secrets defined elsewhere in the file, or a separate file entirely.
References must be right for a deployment to work. Typos or changed resource labels will often prompt this error if references elsewhere in the manifest(s) haven’t been updated.
6. Invalid output from Helm charts and Kustomize
One downside to these useful tools is that they can abstract away too much, especially for developers who are still getting comfortable with manifests.
For example, when you run Kustomize, it returns a big YAML file or multiple smaller files.
Your only options for double-checking the output are
- reading through it with a fine-toothed comb,
- running each portion through external validation tools, or
- jumping into the deploy-troubleshoot-deploy cycle right away.
The same goes for Helm. It’s a helpful resource for getting started, but because you’re not working on the YAML “by hand,” you don’t know what’s happening inside the files.
So, just because a manifest comes from Helm doesn’t mean it’s error-free or doesn’t need some customization on your part.
Using built-in tools for testing Kubernetes manifest errors
Kubernetes comes with a few methods of simplifying how you identify errors in manifests.
While these can help you catch errors a little faster once you’ve started a deployment, they’re still too late.
Pre-test for Kubernetes manifest errors with a manifest IDE
So far, we’ve covered the state of manifest testing and some tips on common manifest mistakes.
One problem remains: : How do you make the process of editing and managing manifests more efficient?
The status quo—a cycle of deploying and failing and fixing ad infinitum—means you’re still engineering YAML files, not developing new features for your application and team .
Enter Monokle, an open-source visual tool that simplifies everyday tasks around Kubernetes to help developers be more productive without tedious YAML-engineering. It uses built-in intelligence and syntax checking, giving a comprehensive view of manifests integrity spoting errors before you deployments.
As a result, you can be effective in Kubernetes on day one without looking up a single YAML syntax rule.
Monokle's basic components are:
File Explorer
Monokle’s File Explorer helps you find all your relevant manifest files, which is particularly useful for those complex deployments.
Navigator
The Navigator converts the complex relationships between Kubernetes resources into easily-understood workloads, networks, and access controls and even gives you visual syntax or reference error alerts, including their number and severity.
Editor
And the Editor, which can also switch to a form-fill mode for less YAML-engineering, highlights errors with a detailed explanation and a suggested fix.
Monokle also lets you:
- Debug and validate the output of Kustomizations and Helm charts,
- View diffs between local and remote resources, and
- Navigating between resource relationships and dependencies.
Finishing Up
Monokle has everything needed to end a cycle of hunting manifest errors. Download it directly from GitHub or check out our documentation. It’s a desktop application that works on macOS, Linux, and Windows.
We’d love to hear from you. Please join us on Discord!
