Kubernetes is a powerful container management platform that can be used to manage multiple containers and their associated resources. However, managing Kubernetes can be difficult if you do not have the appropriate tools and annotations. In this article, we will discuss how to use Kubernetes annotations to manage your cluster. First, let’s create an annotation for our application: kubeconfig –namespace my-app – annotation “com.example” This annotation will add a namespace to our application and will define the com.example class as the object type for that namespace. Next, we need to create a file in our my-app namespace called kubeconfig . This file contains the configuration for our cluster:
kubeconfig # … # annotations { “com.example” : { “name” : “MyApp”, “type” : “application/json” } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
Here are the differences between the three concepts, what they’re designed for, and how you can use them to manage your resources.
Annotations
The Kubernetes documentation defines annotations as “arbitrary non-identifying metadata” which you add to your objects. Their status as “non-identifying” means they aren’t used internally by Kubernetes as part of its object selection system.
This means annotations are best used for data that’s independent of the object and its role in your cluster. You could use them to add information about the tool that created an object, define who’s responsible for its management, or add tags to be picked up by external tools.
There’s no restrictions on what you use annotations for. As long as your data can be expressed as a key-value pair, you can create an annotation that encapsulates it. The model lets you store useful data directly alongside your objects, instead of having to refer to external documentation or databases.
Setting Annotations
Annotations are defined as part of a resource’s metadata field. They’re simple key-value pairs. The key needs to be 63 characters or less and can include alphanumeric characters, dashes, underscores, and dots. It must start and end with an alphanumeric character.
Keys also support an optional prefix which must be a valid DNS subdomain. Prefixes are used to namespace your annotation keys, avoiding collisions between common annotations like name and version. When a prefix is used, a slash character separates it from the key.
This example demonstrates both prefixed and unprefixed annotations.
You can retrieve the annotations that have been set on an object using Kubectl. There’s no built-in command so you need to get the JSON or YAML definition of the object, then extract the value of the annotations field. Here’s an example that displays the annotations associated with the Pod shown above:
Labels
Labels are another form of metadata which you can attach to your resources. The documentation describes the role of labels as “identifying attributes of objects that are meaningful and relevant to users” but independent of the properties of the core system.
Whereas annotations are intentionally purposeless, capable of representing any arbitrary data, labels are meant for more formal situations. They’re commonly used to represent processes and organizational structures. You might use labels to denote a resource’s release status (such as beta or stable) or the development stage it maps to (build or qa).
Labels can be used as selectors when referencing objects. This is a key difference compared to annotations which aren’t supported as selectors. Here’s a Pod which selects Nodes that have the node-environment: production label:
Setting Labels
Labels are attached to objects in the same way as annotations. Add a labels field to the object’s metadata, then populate it with key-value pairs. Labels possess the same constraints around key names and prefixes.
You can retrieve an object’s labels using Kubectl with the same technique as shown earlier. Get the object’s JSON representation, then extract the labels field:
Kubectl also supports a –show-labels flag to include labels in human-readable output tables:
Selectors
Selectors are used within Kubernetes object definitions to reference other objects. Different types of selectors are available to pull in objects that possess certain characteristics.
In the example above, we used a selector to identify Nodes with a particular label. Here’s a Deployment object that uses an explicit label selector to identify the Pods it should manage:
The Deployment’s template will create Pods that have the cloudsavvyit.com/app label set. These will be matched by the selector so they become part of the Deployment.
Selectors in Kubectl
You can use a form of selector to filter the objects that are returned by Kubectl:
Label-based queries support several kinds of comparison operator. These include equality-based and set-based comparisons:
= – The label value is equal to a given value. == – The label value is strictly equal to a given value. != – The label value is not equal to a given value. in – The label value is one of a set of given values. notin – The label value is not in a set of given values. exists – The label exists on the object.
Here’s an example of using the in operator to query objects that are in the staging or production environments:
Summary
Annotations and Labels are two ways to add metadata to your Kubernetes objects. Annotations are for non-identifying data that won’t be referenced by Kubernetes. Labels are used to identify objects so that they can be selected by other Kubernetes resources.
It’s best to use an annotation if you won’t be querying for objects with the key-value pair. Use a label if you’ll be referencing it within another resource or using it to filter Kubectl output in your terminal.
When working with labels, several forms of selector are available to help you access the data you need. Annotations are a little trickier to access as they’re not meant to be queried but you can still list them by viewing the JSON representation of a Kubernetes object.
