Kubernetes Error Codes: SchemaError

{{text-cta}}

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:

current-context: awards-context
apiVersion: v1
clusters:
- cluster:
    api-version: v1
    server: http://oscar.org:8080
  name: oscar-cluster
- cluster:
    certificate-authority: path/to/my/cafile
    server: https://grammy.org:4443
  name: grammy-cluster
- cluster:
    insecure-skip-tls-verify: true
    server: https://tony.org:443
  name: tony-cluster
contexts:
- context:
    cluster: grammy-cluster
    namespace: vegas-ns
    user: grammy-user
  name: awards-context
- context:
    cluster: tony-cluster
    namespace: awt-ns
    user: tony-user
  name: play-context
kind: Config
preferences:
  colors: true
users:
- name: oscar-user
  user:
    token: oscar-token
- name: grammy-user
  user:
    client-certificate: path/to/my/client/cert
    client-key: path/to/my/client/key

`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:

$ kubectl cluster-info

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:

error: SchemaError(io.k8s.api.core.v1.ServiceSpec): invalid object doesn't have additional properties

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.

Resolving SchemaErrors

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:

$ kubectl version
Client Version: version.Info{Major:"1", Minor:"10", GitVersion:"v1.10.11", GitCommit:"637c7e288581ee40ab4ca210618a89a555b6e7e9", GitTreeState:"clean", BuildDate:"2018-11-26T14:38:32Z", GoVersion:"go1.9.3", Compiler:"gc", Platform:"darwin/amd64"}

Server Version: version.Info{Major:"1", Minor:"17", GitVersion:"v1.17.0", GitCommit:"70132b0f130acc0bed193d9ba59dd186f0e634cf", GitTreeState:"clean", BuildDate:"2019-12-07T21:12:17Z", GoVersion:"go1.13.4", Compiler:"gc", Platform:"linux/amd64"}

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.

{{text-cta}}

Mac Users

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:

$ brew install kubernetes-cli

For Mac users who installed the `kubectl` binary, your upgrade path involves grabbing the latest release:

*Intel-based Macs:*

$ curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

*Apple-silicon Macs:*

$ curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

You’ll need to add the executable flag to the binary, then move the binary into your system PATH as well:

$ chmod +x ./kubectl
$ chmod +x ./kubectl
$ sudo chown root: /usr/local/bin/kubectl

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:

$ rm /usr/local/bin/kubectl
$ brew link --overwrite kubernetes-cli
$ brew link --overwrite --dry-run kubernetes-cli.

Linux Users

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:

$ curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

Then, configure and place the binary in the system PATH:

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Windows Users

Windows users have the option of installing the latest binary by downloading it with the following command:

$ curl -LO "https://dl.k8s.io/release/v1.23.0/bin/windows/amd64/kubectl.exe"

Users who use [Chocolatey](https://chocolatey.org/) as their package manager can also install the latest version:

choco install kubernetes-cli

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:

kubectl cluster-info

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.

Final Thoughts

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.