Using Namespaces and Selectors With the Kubernetes Java API

1. Introduction

In this tutorial, we’ll explore different ways to filter resources using the Kubernetes Java API.

In our previous articles covering the Kubernetes Java API, we’ve focused on the available methods to query, manipulate, and monitor cluster resources.

Those examples assumed that we were either looking for resources of a specific kind or targeting a single resource. In practice, however, most applications need a way to locate resources based on some criteria.

Kubernetes’ API supports three ways to limit the scope of those searches:

• Namespaces: scope limited to a given Kubernetes namespace
• Field Selectors: scope limited to resources having matching field values
• Label Selectors: scope limited to resources having matching labels

Moreover, we can combine those methods in a single query. This gives us a lot of flexibility to address even complex requirements.

Now, let’s see each method in more detail.

2. Using Namespaces

Using namespaces is the most basic way to limit the scope of a query. As the name implies, a namespaced query only returns items within the specified namespace.

In the Java API, namespaced query methods follow the pattern listNamespacedXXX(). For instance, to list pods in a specific namespace, we’d use listNamespacedPod():

ApiClient client  = Config.defaultClient();
CoreV1Api api = new CoreV1Api(client);
String ns = "ns1";
V1PodList items = api.listNamespacedPod(ns,null, null, null, null, null, null, null, null, 10, false);
items.getItems()
  .stream()
  .map((pod) -> pod.getMetadata().getName() )
  .forEach((name) -> System.out.println("name=" + name));

Here, ApliClient and CoreV1Api  are used to perform actual access to the Kubernetes API server. We use ns1 as the namespace to filter resources. We also use the remaining arguments similar to the ones in the non-namespaced method.

As expected, namespaced queries also have call variants, thus allowing us to create Watches using the same techniques described before. Asynchronous calls and paging also work in the same way as their non-namespaced versions.

3. Using Field Selectors

Namespaced API calls are simple to use but have some limitations:

• It’s all-or-nothing, meaning we can’t select more than one (but not all) namespaces
• No way to filter based on resource properties
• Using a different method for each scenario leads to more complex/verbose client code

Field selectors provide a way to select resources based on the value of one of its fields. A field in Kubernetes parlance is just the JSON path associated with a given value in a resource’s YAML or JSON document. For instance, this is a typical Kubernetes YAML for a pod running an Apache HTTP server:

apiVersion: v1
kind: Pod
metadata:
  labels:
    app: httpd
  name: httpd-6976bbc66c-4lbdp
  namespace: ns1
spec:
  ... fields omitted
status:
  ... fields omitted
  phase: Running

The field status.phase contains the status of an existing Pod. The corresponding field selector expression is simply the field name followed by an operator and value. Now, let’s code a query that returns all running pods in all namespaces:

String fs = "status.phase=Running";        
V1PodList items = api.listPodForAllNamespaces(null, null, fs, null, null, null, null, null, 10, false);
// ... process items

A field selector expression supports only the equality (‘=’ or ‘==’) and inequality (‘!=’) operators. Also, we can pass multiple comma-separated expressions in the same call. In this case, the net effect is that they’ll be ANDed together to produce the final result:

String fs = "metadata.namespace=ns1,status.phase=Running";        
V1PodList items = api.listPodForAllNamespaces(null, null, fs, null, null, null, null, null, 10, false);
// ... process items

Be aware: field values are case-sensitive! In the previous query, using “running” instead of “Running” (capital “R”) would yield an empty result set.

An important limitation of field selectors is that they are resource-dependent. Only metadata.name and metadata.namespace fields are supported across all resource kinds.

Nevertheless, field selectors are especially useful when used with dynamic fields. An example is the status.phase in the previous example. Using a field selector together with a Watch, we can easily create a monitoring application that gets notified when pods terminate.

4. Using Label Selectors

Labels are special fields that contain arbitrary key/value pairs that we can add to any Kubernetes resource as part of its creation. Label selectors are similar to field selector, as they essentially allow filtering a resource list based on its values, but offers more flexibility:

• Support for additional operators: in/notin/exists/not exists
• Consistent usage across resource types when compared to field selectors

Going back to the Java API, we use label selectors by constructing a string with the desired criteria and passing it in as an argument to the desired resource API listXXX call. Filtering for a specific label value using equality and/or inequality uses the same syntax used by field selectors.

Let’s see the code that looks for all pods that have a label “app” with the value “httpd”:

String ls = "app=httpd";        
V1PodList items = api.listPodForAllNamespaces(null, null, null, ls, null, null, null, null, 10, false);
// ... process items

The in operator resembles its SQL counterpart and allows us to create some OR logic in queries:

String ls = "app in ( httpd, test )";        
V1PodList items = api.listPodForAllNamespaces(null, null, null, ls, null, null, null, null, 10, false);

Also, we can check for the presence or absence of a field using the labelname or !labelname syntax:

String ls = "app";
V1PodList items = api.listPodForAllNamespaces(null, null, null, ls, null, null, null, null, 10, false);

Finally, we can chain multiple expressions in a single API call. The resulting items list contains only resources that satisfy all expressions:

String ls = "app in ( httpd, test ),version=1,foo";
V1PodList items = api.listPodForAllNamespaces(null, null, null, ls, null, null, null, null, 10, false);

5. Conclusion

In this article, we’ve covered different ways to filter resources using the Java Kubernetes API client.