Kubernetes is arguably the world’s leading container orchestration engine. When Kubernetes functions as expected, deploying containerized applications is quick, and upgrading and scaling applications is easy.
Unfortunately, there are times when your containerized applications “misbehave” and require your attention. Other times, it’s the Kubernetes cluster itself that experiences an issue. In either case, Kubernetes provides you with a number of exit and error codes that indicate the types of problems your cluster is experiencing.
If you’re a cloud engineer or site reliability engineer with Kubernetes responsibilities, then understanding error codes is important for you to know what’s going on with your cluster, debug it quickly, and prevent errors in the future.
The problem is, the exit and error codes offered by Kubernetes are often cryptic, leaving you digging through Stack Overflow responses for answers. The SchemaError in Kubernetes is no exception.
In this article, you’ll learn about the SchemaError that is often encountered when you’re operating on resources using `kubectl` in Kubernetes. You’ll also learn how to resolve the SchemaError should you ever receive it.
What Is a SchemaError?
To better understand what a SchemaError is, let’s briefly discuss two things: the Kubernetes API and the `kubectl` command.
The Kubernetes API server is at the heart of Kubernetes. It provides HTTP API access to various portions of your Kubernetes cluster, including components like namespaces, pods, ConfigMaps, and deployments. Developers have the opportunity to directly interface with the Kubernetes API using REST calls, though most of the functions that the Kubernetes API exposes are accessible via a command-line tool called `kubectl`.
Under the covers, the `kubectl` command is making API calls to the Kubernetes API to access your Kubernetes clusters. In order to work with your Kubernetes cluster, `kubectl` must be configured using a file named `config` that is located inside the `$HOME/.kube` directory called the `kubeconfig` file.
`kubectl` uses `kubeconfig` files to configure access to your Kubernetes cluster. Here’s a quick example of what a `kubeconfig` file configured to work with multiple Kubernetes clusters looks like:
`kubectl` depends on this file to determine how and where to authenticate with your cluster(s). As in the example above, you can configure your `kubeconfig` file to give the `kubectl` tool the ability to connect to multiple Kubernetes clusters.
You can also validate that your file is properly configured by running the following command:
If your `kubeconfig` file is configured properly, a detailed response about the Kubernetes cluster you are currently connected to should be displayed.
For instance, if you were attempting to use `kubectl` to interface with Kubernetes resources, you may encounter the SchemaError that looks like this:
At first glance, this error appears to offer detailed information. However, taking a closer look, you can see that the error output only offers a cryptic “invalid object” message.
Coupled with the cryptic “invalid object” message, the SchemaError above refers to a version mismatch between the client (i.e., the `kubectl` tool) and the server (i.e., the Kubernetes API server you’re accessing).
You can check this by taking a look at the client and server versions you’re currently using by running the `kubectl version` command:
Notice that the versions are mismatched; the client version is compatible with the **1.10** version of Kubernetes, but the version of Kubernetes that is currently in use is **1.17**. Simply put, your Kubernetes cluster is using a newer version of Kubernetes that the `kubectl` command-line tool isn’t *new* enough to interact with.
The solution? Upgrade `kubectl`.
The operating system that you’re currently using will determine your upgrade path.
For Mac users who installed `kubectl` with the [Homebrew](https://brew.sh/) package manager, using the `brew install` command grabs the latest version of the tool:
For Mac users who installed the `kubectl` binary, your upgrade path involves grabbing the latest release:
You’ll need to add the executable flag to the binary, then move the binary into your system PATH as well:
Important Note for Docker/Homebrew macOS Users
If you’ve installed [Docker](https://www.docker.com/), the `kubectl` command-line tool is also installed. If you installed `kubectl` using the Homebrew package manager, then there’s one final step. To ensure that you’re using your newly installed `kubectl` (not the instance provided with Docker), run the following commands:
Linux users will use a similar upgrade path for `kubectl` because its installation/upgrade method is very similar to macOS.
You’ll grab the latest release:
Then, configure and place the binary in the system PATH:
Windows users have the option of installing the latest binary by downloading it with the following command:
Users who use [Chocolatey](https://chocolatey.org/) as their package manager can also install the latest version:
Once you’ve successfully installed the latest version of the `kubectl` command-line tool, you can once again verify that your installed version is compatible with your version of Kubernetes with the following command:
Note: The `kubectl` command line tool is compatible with versions of Kubernetes that are no more than one minor release away. For example, the 1.21 client would be compatible with Kubernetes versions 1.21, 1.22, and 1.20.
In this article, you learned that the Kubernetes API is at the center of accessing, configuring, and maintaining your Kubernetes cluster. You also learned that your Kubernetes cluster can be accessed using REST API calls, but in most cases, administrators often leverage the `kubectl` command-line tool to interface with Kubernetes components.
Most importantly, you learned that the SchemaError reminds us that updated versions of `kubectl` are best to use with later versions of Kubernetes. Specifically, the `kubectl` version you’re required to use with your Kubernetes clusters must be no more than one minor release away from the version of your Kubernetes cluster.