K8s.Selector (k8s v2.8.0)

Builds label selectors and field selectors for K8s.Operations

Examples

Parse from a YAML map

iex> deployment = %{
...>   "kind" => "Deployment",
...>   "metadata" => %{
...>     "name" => "nginx",
...>     "labels" => %{
...>       "app" => "nginx",
...>       "tier" => "backend"
...>     }
...>   },
...>   "spec" => %{
...>     "selector" => %{
...>       "matchLabels" => %{
...>         "app" => "nginx"
...>       }
...>     },
...>     "template" => %{
...>       "metadata" => %{
...>         "labels" => %{
...>           "app" => "nginx",
...>           "tier" => "backend"
...>         }
...>       }
...>     }
...>   }
...> }
...> K8s.Selector.parse(deployment)
%K8s.Selector{match_labels: %{"app" => "nginx"}}

Provides a composable interface for building label selectors

iex> {"component", "redis"}
...> |> K8s.Selector.label()
...> |> K8s.Selector.label_not({"foo", "bar"})
...> |> K8s.Selector.label_in({"tier", "cache"})
...> |> K8s.Selector.label_not_in({"environment", "dev"})
...> |> K8s.Selector.label_exists("foo")
...> |> K8s.Selector.label_does_not_exist("bar")
%K8s.Selector{
  match_labels: %{"component" => {"=", "redis"}, "foo" => {"!=", "bar"}},
  match_expressions: [
    %{"key" => "bar", "operator" => "DoesNotExist"},
    %{"key" => "foo", "operator" => "Exists"},
    %{"key" => "environment", "operator" => "NotIn", "values" => ["dev"]},
    %{"key" => "tier", "operator" => "In", "values" => ["cache"]}
  ]
}

Provides a composable interface for adding selectors to K8s.Operations.

iex> K8s.Client.get("v1", :pods)
...> |> K8s.Selector.label({"app", "nginx"})
...> |> K8s.Selector.label_not(%{"tier" => "backend"})
...> |> K8s.Selector.label_in({"environment", ["qa", "prod"]})
%K8s.Operation{data: nil, api_version: "v1", query_params: [labelSelector: %K8s.Selector{match_expressions: [%{"key" => "environment", "operator" => "In", "values" => ["qa", "prod"]}], match_labels: %{"app" => {"=", "nginx"}, "tier" => {"!=", "backend"}}}], method: :get, name: :pods, path_params: [], verb: :get}

Summary

Types

selector_or_operation_t()

t()

Functions

field(fields)

fieldSelector helper that creates a composable K8s.Selector.

field(selector_or_operation, fields)

field_not(fields)

fieldSelector helper that creates a composable K8s.Selector.

field_not(selector_or_operation, fields)

fields_to_s(selector)

Serializes a K8s.Selector to a fieldSelector query string.

label(labels)

matchLabels helper that creates a composable K8s.Selector.

label(selector_or_operation, labels)

matchLabels helper that creates a composable K8s.Selector.

label_does_not_exist(key)

DoesNotExist expression helper that creates a composable K8s.Selector.

label_does_not_exist(selector_or_operation, key)

label_exists(key)

Exists expression helper that creates a composable K8s.Selector.

label_exists(selector_or_operation, key)

label_in(expr)

In expression helper that creates a composable K8s.Selector.

label_in(selector_or_operation, arg)

label_not(labels)

matchLabels helper that creates a composable K8s.Selector.

label_not(selector_or_operation, labels)

matchLabels helper that creates a composable K8s.Selector.

label_not_in(expr)

NotIn expression helper that creates a composable K8s.Selector.

label_not_in(selector_or_operation, arg)

labels_to_s(selector)

Serializes a K8s.Selector to a labelSelector query string.

match_expression?(resource, arg2)

Checks whether a resource matches a single selector matchExpressions

match_expressions?(resource, exprs)

Checks if a K8s.Resource matches all matchExpressions using a logical AND

match_label?(resource, key, value)

Checks if a K8s.Resource matches a single label

match_labels?(resource, labels)

Checks if a K8s.Resource matches all matchLabels using a logcal AND

parse(arg1)

Parses a "selector" map of "matchLabels" and "matchExpressions"

serialize_match(fields)

Returns a fieldSelector query string value for a set of field selectors.

serialize_match_expressions(exps)

Returns a labelSelector query string value for a set of label expressions.

serialize_match_labels(labels) deprecated

See K8s.Selector.serialize_match/1.

to_s(selector)

Serializes a K8s.Selector to a labelSelector query string.

Types

selector_or_operation_t()

@type selector_or_operation_t() :: t() | K8s.Operation.t()

t()

@type t() :: %K8s.Selector{
  match_expressions: [map()],
  match_fields: map(),
  match_labels: map()
}

Functions

field(fields)

@spec field({binary() | atom(), binary()} | map()) :: t()

fieldSelector helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.field({"metadata.namespace", "default"})
%K8s.Selector{match_fields: %{"metadata.namespace" => {"=", "default"}}}

iex> K8s.Selector.field(%{"metadata.namespace" => "default", "status.phase" => "Running"})
%K8s.Selector{match_fields: %{"metadata.namespace" => {"=", "default"}, "status.phase" => {"=", "Running"}}}

field(selector_or_operation, fields)

@spec field(selector_or_operation_t(), {binary() | atom(), binary()} | map()) ::
  selector_or_operation_t()

field_not(fields)

@spec field_not({binary() | atom(), binary()} | map()) :: t()

fieldSelector helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.field_not({"metadata.namespace", "default"})
%K8s.Selector{match_fields: %{"metadata.namespace" => {"!=", "default"}}}

iex> K8s.Selector.field(%{"metadata.namespace" => "default", "status.phase" => "Running"})
%K8s.Selector{match_fields: %{"metadata.namespace" => {"=", "default"}, "status.phase" => {"=", "Running"}}}

field_not(selector_or_operation, fields)

@spec field_not(
  selector_or_operation_t(),
  {binary() | atom(), binary()}
) :: selector_or_operation_t()

fields_to_s(selector)

@spec fields_to_s(t()) :: binary()

Serializes a K8s.Selector to a fieldSelector query string.

Examples

iex> selector = K8s.Selector.field({"status.phase", "Running"})
...> K8s.Selector.fields_to_s(selector)
"status.phase=Running"

label(labels)

@spec label({binary() | atom(), binary()} | map()) :: t()

matchLabels helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label({"component", "redis"})
%K8s.Selector{match_labels: %{"component" => {"=", "redis"}}}

iex> K8s.Selector.label(%{"component" => "redis", "env" => "prod"})
%K8s.Selector{match_labels: %{"component" => {"=", "redis"}, "env" => {"=", "prod"}}}

label(selector_or_operation, labels)

@spec label(selector_or_operation_t(), {binary() | atom(), binary()} | map()) ::
  selector_or_operation_t()

matchLabels helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label({"component", "redis"})
...> |> K8s.Selector.label({"environment", "dev"})
%K8s.Selector{match_labels: %{"component" => {"=", "redis"}, "environment" => {"=", "dev"}}}

label_does_not_exist(key)

@spec label_does_not_exist(binary()) :: t()

DoesNotExist expression helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_does_not_exist("environment")
%K8s.Selector{match_expressions: [%{"key" => "environment", "operator" => "DoesNotExist"}]}

label_does_not_exist(selector_or_operation, key)

@spec label_does_not_exist(selector_or_operation_t(), binary()) ::
  selector_or_operation_t()

label_exists(key)

@spec label_exists(binary()) :: t()

Exists expression helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_exists("environment")
%K8s.Selector{match_expressions: [%{"key" => "environment", "operator" => "Exists"}]}

label_exists(selector_or_operation, key)

@spec label_exists(selector_or_operation_t(), binary()) :: selector_or_operation_t()

label_in(expr)

@spec label_in({binary(), binary() | [binary()]}) :: t()

In expression helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_in({"component", "redis"})
%K8s.Selector{match_expressions: [%{"key" => "component", "operator" => "In", "values" => ["redis"]}]}

label_in(selector_or_operation, arg)

@spec label_in(
  selector_or_operation_t(),
  {binary(), binary() | [binary()]}
) :: selector_or_operation_t()

label_not(labels)

@spec label_not({binary() | atom(), binary()} | map()) :: t()

matchLabels helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_not({"component", "redis"})
%K8s.Selector{match_labels: %{"component" => {"!=", "redis"}}}

iex> K8s.Selector.label_not(%{"component" => "redis", "env" => "prod"})
%K8s.Selector{match_labels: %{"component" => {"!=", "redis"}, "env" => {"!=", "prod"}}}

label_not(selector_or_operation, labels)

@spec label_not(selector_or_operation_t(), {binary() | atom(), binary()} | map()) ::
  selector_or_operation_t()

matchLabels helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_not({"component", "redis"})
...> |> K8s.Selector.label_not({"environment", "dev"})
%K8s.Selector{match_labels: %{"component" => {"!=", "redis"}, "environment" => {"!=", "dev"}}}

label_not_in(expr)

@spec label_not_in({binary(), binary() | [binary()]}) :: t()

NotIn expression helper that creates a composable K8s.Selector.

Examples

iex> K8s.Selector.label_not_in({"component", "redis"})
%K8s.Selector{match_expressions: [%{"key" => "component", "operator" => "NotIn", "values" => ["redis"]}]}

label_not_in(selector_or_operation, arg)

@spec label_not_in(
  selector_or_operation_t(),
  {binary(), binary() | [binary()]}
) :: selector_or_operation_t()

labels_to_s(selector)

@spec labels_to_s(t()) :: binary()

Serializes a K8s.Selector to a labelSelector query string.

Examples

iex> selector = K8s.Selector.label({"component", "redis"})
...> K8s.Selector.labels_to_s(selector)
"component=redis"

match_expression?(resource, arg2)

@spec match_expression?(map(), map()) :: boolean()

Checks whether a resource matches a single selector matchExpressions

Examples

When an In expression matches

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "prod"}}}
...> expr = %{"operator" => "In", "key" => "env", "values" => ["prod", "qa"]}
...> K8s.Selector.match_expression?(resource, expr)
true

When an In expression doesnt match

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "In", "key" => "env", "values" => ["prod", "qa"]}
...> K8s.Selector.match_expression?(resource, expr)
false

When an NotIn expression matches

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "NotIn", "key" => "env", "values" => ["prod"]}
...> K8s.Selector.match_expression?(resource, expr)
true

When an NotIn expression doesnt match

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "NotIn", "key" => "env", "values" => ["dev"]}
...> K8s.Selector.match_expression?(resource, expr)
false

When an Exists expression matches

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "Exists", "key" => "env"}
...> K8s.Selector.match_expression?(resource, expr)
true

When an Exists expression doesnt match

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "Exists", "key" => "tier"}
...> K8s.Selector.match_expression?(resource, expr)
false

When an DoesNotExist expression matches

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "DoesNotExist", "key" => "tier"}
...> K8s.Selector.match_expression?(resource, expr)
true

When an DoesNotExist expression doesnt match

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "dev"}}}
...> expr = %{"operator" => "DoesNotExist", "key" => "env"}
...> K8s.Selector.match_expression?(resource, expr)
false

match_expressions?(resource, exprs)

@spec match_expressions?(map(), [map()] | t()) :: boolean()

Checks if a K8s.Resource matches all matchExpressions using a logical AND

Examples

Accepts K8s.Selectors:

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "prod", "tier" => "frontend"}}}
...> expr1 = %{"operator" => "In", "key" => "env", "values" => ["prod", "qa"]}
...> expr2 = %{"operator" => "Exists", "key" => "tier"}
...> selector = %K8s.Selector{match_expressions: [expr1, expr2]}
...> K8s.Selector.match_expressions?(resource, selector)
true

Accepts maps:

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "prod", "tier" => "frontend"}}}
...> expr1 = %{"operator" => "In", "key" => "env", "values" => ["prod", "qa"]}
...> expr2 = %{"operator" => "Exists", "key" => "tier"}
...> K8s.Selector.match_expressions?(resource, [expr1, expr2])
true

Returns false when not matching all expressions:

iex> resource = %{"kind" => "Node", "metadata" => %{"labels" => %{"env" => "prod", "tier" => "frontend"}}}
...> expr1 = %{"operator" => "In", "key" => "env", "values" => ["prod", "qa"]}
...> expr2 = %{"operator" => "Exists", "key" => "foo"}
...> K8s.Selector.match_expressions?(resource, [expr1, expr2])
false

match_label?(resource, key, value)

@spec match_label?(map(), binary(), binary()) :: boolean()

Checks if a K8s.Resource matches a single label

match_labels?(resource, labels)

@spec match_labels?(map(), map() | t()) :: boolean()

Checks if a K8s.Resource matches all matchLabels using a logcal AND

Examples

Accepts K8s.Selectors:

iex> labels = %{"env" => "prod", "tier" => "frontend"}
...> selector = %K8s.Selector{match_labels: labels}
...> resource = K8s.Resource.build("v1", "Pod", "default", "test", labels)
...> K8s.Selector.match_labels?(resource, selector)
true

Accepts maps:

iex> labels = %{"env" => "prod", "tier" => "frontend"}
...> resource = K8s.Resource.build("v1", "Pod", "default", "test", labels)
...> K8s.Selector.match_labels?(resource, labels)
true

Returns false when not matching all labels:

iex> not_a_match = %{"env" => "prod", "tier" => "frontend", "nope" => "not-a-match"}
...> resource = K8s.Resource.build("v1", "Pod", "default", "test", %{"env" => "prod", "tier" => "frontend"})
...> K8s.Selector.match_labels?(resource, not_a_match)
false

parse(arg1)

@spec parse(map()) :: t()

Parses a "selector" map of "matchLabels" and "matchExpressions"

Examples

iex> selector = %{
...>   "matchLabels" => %{"component" => "redis"},
...>   "matchExpressions" => [
...>     %{"operator" => "In", "key" => "tier", "values" => ["cache"]},
...>     %{"operator" => "NotIn", "key" => "environment", "values" => ["dev"]}
...>   ]
...> }
...> K8s.Selector.parse(selector)
%K8s.Selector{match_labels: %{"component" => "redis"}, match_expressions: [%{"operator" => "In", "key" => "tier", "values" => ["cache"]},%{"operator" => "NotIn", "key" => "environment", "values" => ["dev"]}]}

serialize_match(fields)

@spec serialize_match(map()) :: [binary()]

Returns a fieldSelector query string value for a set of field selectors.

Examples

Builds a query string for a single field (kubectl get pods --field-selector status.phase=Running):

iex> K8s.Selector.serialize_match(%{"status.phase" => {"=", "Running"}})
["status.phase=Running"]

Builds a query string for multiple fields (kubectl get pods --field-selector status.phase=Running,metadata.namespace!=default):

iex> K8s.Selector.serialize_match(%{"metadata.namespace" => {"!=", "default"}, "status.phase" => {"=", "Running"}})
["metadata.namespace!=default", "status.phase=Running"]

serialize_match_expressions(exps)

@spec serialize_match_expressions([map()]) :: [binary()]

Returns a labelSelector query string value for a set of label expressions.

For != matches, use a NotIn set-based expression.

Examples

Builds a query string for In expressions (kubectl get pods -l 'environment in (production,qa),tier in (frontend)):

iex> expressions = [
...>   %{"operator" => "In", "key" => "environment", "values" => ["production", "qa"]},
...>   %{"operator" => "In", "key" => "tier", "values" => ["frontend"]},
...> ]
...> K8s.Selector.serialize_match_expressions(expressions)
["environment in (production,qa)", "tier in (frontend)"]

Builds a query string for NotIn expressions (kubectl get pods -l 'environment notin (frontend)):

iex> expressions = [
...>   %{"operator" => "NotIn", "key" => "environment", "values" => ["frontend"]}
...> ]
...> K8s.Selector.serialize_match_expressions(expressions)
["environment notin (frontend)"]

Builds a query string for Exists expressions (kubectl get pods -l 'environment'):

iex> expressions = [
...>   %{"operator" => "Exists", "key" => "environment"}
...> ]
...> K8s.Selector.serialize_match_expressions(expressions)
["environment"]

Builds a query string for DoesNotExist expressions (kubectl get pods -l '!environment'):

iex> expressions = [
...>   %{"operator" => "DoesNotExist", "key" => "environment"}
...> ]
...> K8s.Selector.serialize_match_expressions(expressions)
["!environment"]

serialize_match_labels(labels)

This function is deprecated. Use serialize_match/1.

See K8s.Selector.serialize_match/1.

to_s(selector)

@spec to_s(t()) :: binary()

Serializes a K8s.Selector to a labelSelector query string.

Examples

iex> selector = K8s.Selector.label({"component", "redis"}) ...> K8s.Selector.to_s(selector) "component=redis"