How to use Kubectl Patch

The kubectl command line utility offers a lot of functionality to users to help them manage their Kubernetes resources. One such command exposed by this utility is the kubectl patch command, which allows you to change running configurations immediately.

In this guide, you will see how you can use the kubectl patch command to manipulate your Kubernetes resources, and you’ll learn the different options presented to you by this command. You will then learn some best practices that you can follow to ensure that your usage of this command is as sustainable as possible.

Why do you need Kubectl Patch?

Kubectl gives you several different ways to update running configurations. The main ways are the apply, edit, and patch commands. There are some nuances between each of these commands that will be touched on later, but the focus of this guide is on the patch command. If you need to update API objects in place, kubectl patch is one of the commands available to you that you will likely want to consider using.

The patch command lets you apply a change to your running configuration by specifying only the bit that you wish to change and then using one of three different patch types to apply this change. The three patch types each vary slightly in how they apply the change, and as such, each is suitable for different use cases. Applying small changes like this can be useful if you want to test configuration changes or perform some small experiments, but don’t want to update the whole configuration file. However, if you decide to keep the changes, it’s generally a good idea to codify these changes into your base configuration, as patches can become burdensome to maintain in the long run.

Introducing Kubectl Patch

The best way to learn how to use the patch command is by using it. If you want to follow along with the examples in this article, you will need a Kubernetes cluster to experiment with. You can either create one with a cloud provider such as GKE, or set up a local cluster using one of the various tools available to do so.

If you are using Mac or Windows, you can get a simple single-node cluster via Docker Desktop. If you are running a Linux-based OS, there are several options available to you, such as minikube and MicroK8s.

For the purposes of following along with this article, any type of Kubernetes cluster should be sufficient.

Using Kubectl Patch

To experiment with the patch command, you first need some resources to work with. The following configuration file will create a simple deployment with a single replica, which has a single pod:

To run this configuration from your terminal, execute the following command:

This will create your resources—the deployment and the pod—which you can verify by running kubectl get pods. That will give you the following response:

The first way to use patch is by running the command with your patch object inline. In this case, if you wanted to patch the deployment to have two replicas, it would look something like this:

If you run kubectl get pods again, you will see two replicas, where previously there was only one. This approach can be useful for small changes or cases where repeatability isn’t a key consideration. One very real use case for doing your patches inline is that sometimes when trying to delete a PersistentVolume, it will seemingly hang indefinitely. You can easily resolve this issue by running inline patches as follows:

In many instances, however, it is a good idea to apply your patches from a patch file, which is a partial YAML file saved to your disk. If you were to do this with the above example of increasing the replicas in your deployment to two, you would first need to create a new file called something like patch-file.yaml, which would contain your patch object:

From the terminal, you can now patch your deployment by providing the file, instead of the object itself:

This ultimately has the same effect, but is more convenient than doing it all inline, especially for larger patch objects and things that you might want to iterate on.

Different patch types

A few different types of patch can be performed when applying configs with the patch command. In the above examples, kubectl uses the strategic merge type by default. The available types are:

• <terminal inline bold>json<terminal inline bold>: A JSON patch allows you to provide an operation or operations to carry out on the object.
• <terminal inline bold>json merge<terminal inline bold>: A JSON merge patch allows you to naively override keys in an object.
• <terminal inline bold>strategic<terminal inline bold>: A strategic merge patch will either replace or merge values based on the object’s patchStrategy as defined in the Kubernetes source code. This is the default patch type.

You can change which type is used by specifying the type parameter when you call the patch command:

There are some important differences between each of the types. Notably, a JSON patch uses a slightly more complicated syntax, whereby you specify a sequence of atomic operations that are executed one after another. For the above example of setting the number of replicas, it might look something like this:

The key difference with JSON patches is that instead of specifying a partial fragment of the config that you wish to combine with the existing config, you simply specify instructions to carry out. This type of patch is good for more granular operations, as you can specify each atomic change individually. You can also perform multiple operations together. If you wanted to add a Redis container to your pod, and a new corresponding label, you could perform a JSON patch with the following:

The conceptually simpler JSON merge patch is good for small replacement operations, but has some limitations. If you want to update a list, you need to specify the entire new list, not just new items. Additionally, you can delete a key by setting its value to null, but as a result, it is not possible to update a value to have a null literal value. Similar to the above example, if you wanted to add a Redis container and label using this patch strategy, it would look something like this:

Best practices

When using the patch command, it’s easy to get carried away and potentially create a bit of a mess, where your running configs don’t match what you have on disk, and you aren’t sure what has changed. To avoid this kind of scenario, there are some best practices that you can follow to keep things nice and tidy.

Prefer patch files

Inline patching can be useful if you’re just trying something out, or if you are making a throwaway change that you don’t care about. When working with resources that you care about, though, it’s often wise to use patch files for a few reasons:

• Keeping patch files can give you an idea of the changes that your resources have gone through without requiring you to inspect the running configuration.
• There’s a chance that your patch might not be exactly right and could require some tweaks. In this case, updating and reapplying the patch file is more convenient than doing multiple inline patches.

When to use Kubectl Patch

There are multiple different ways that you can update configurations in Kubernetes. In addition to patch, there is also kubectl apply and kubectl edit. Suppose you create and manage your resources using apply. In that case, it is generally a good idea to use this when updating your configurations, as apply keeps track of the previously applied configuration via annotation. This annotation is not updated by patch, so you miss some functionality there.

Use Kubectl Patch sparingly

The patch command can be very useful for testing and experimentation. Still, even with patch files, it is generally a good idea to encode changes you’ll be keeping into your base config files. This is because when you recreate your resources by applying your config, your patches will not be automatically reapplied. This can be inconvenient, especially if you have multiple patches you need to apply. Reflecting changes you wish to keep in your base configs makes future maintainability much easier.

Final thoughts

In this guide, you learned about the kubectl patch command: what it is, how to use it, and its different modes of operation.

The patch command is a useful tool to be familiar with, and can ease the debugging and experimentation process significantly. However, it’s important to know when to use it and whether there’s a better alternative available. kubectl gives you several options for updating configurations. They each have use cases where they’re most suitable, so while it’s important to be familiar with the patch command to use it effectively, it’s just as important to know when it is time to reach for a different tool.

If you're looking to build workflows that help you debug your applications in a streamlined and easy manner, then consider using Airplane. Airplane is the code-first platform for building internal tools. The basic building blocks of Airplane are Tasks, which are single or multi-step functions that anyone can use. Airplane also offers Views, a React-based platform for building custom UIs.

With Airplane, you can build a custom UI to monitor your applications and debug issues that arise. It's easy to get started with a pre-built component library and template library.

To try it out and build your first internal UI or workflow to debug issues quickly, sign up for a free account or book a demo.