Class LabelSelector<TItem>

Implements a Kubernetes compatible general purpose label-based selector mechanism that can select a set of items from a collection based on the set of labels assigned to each item. This class supports some simple fixed query methods as well as a simple text-based query language.

This is suitable for operations like selecting Kubernetes related items by labels or annotations.

Inheritance

object

LabelSelector<TItem>

Namespace: Neon.Common

Assembly: Neon.Common.dll

Syntax

public class LabelSelector<TItem> where TItem : ILabeled

Type Parameters

Name	Description
TItem	The underlying item type.

Remarks

This class supports Kubernetes style label selectors:

Kubernetes: Labels and Selectors

For this to work, your TItem type will need to implement the ILabeled interface and its GetLabels() which returns a string/string dictionary holding that items labels. Then you can construct a selector instance via LabelSelector<TItem>, passing your set of labeled items. Then you can call GetItemsWith(string), GetItemsWithout(string), and Select(string) to select items based on their labels and one ore more label conditions to be satisified.

note

Kubernetes labels are key/value pairs. Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

If the prefix is omitted, the label Key is presumed to be private to the user. Automated system components (e.g. kube-scheduler, kube-controller-manager, kube-apiserver, kubectl, or other third-party automation) which add labels to end-user objects must specify a prefix.

The kubernetes.io/ and k8s.io/ prefixes are reserved for Kubernetes core components.

Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

Label Names: must conform to the Kubernetes standard and will be treated as case sensitive or insensitive based on how the underlying dictionary returned was constructed. Generally though, labels are considered to be case insensitive so you should probably use InvariantCultureIgnoreCase when constructing the dictionaries returned by your item's GetLabels() method.

Label names must conform to the Kubernetes conventions by default but this can be relaxed by passing an option to the constructor.

note

Label Values: are considered to be case senstive by default but this can be customized via the constructor.

note

See Select(string) for a description of the label selector language.

note

You may use the static ValidateLabelKey(string) and ValidateLabelValue(string) methods to explicity confirm that label keys and values satisfy the Kubernetes conventions.

Constructors

LabelSelector(IEnumerable<TItem>, LabelSelectorOptions)

Constructor.

Declaration

public LabelSelector(IEnumerable<TItem> items, LabelSelectorOptions options = LabelSelectorOptions.None)

Parameters

Type	Name	Description
IEnumerable<TItem>	items	The set of items to be queries. null will treated as an empty set.
LabelSelectorOptions	options	Optionally customize selector case sensitivity and other behaviors.

Methods

GetItemsWith(string)

Returns the set of items including a specific label.

Declaration

public IEnumerable<TItem> GetItemsWith(string labelKey)

Parameters

Type	Name	Description
string	labelKey	The desired label key.

Returns

Type	Description
IEnumerable<TItem>	The set of items with the label.

GetItemsWithout(string)

Returns the set of items that do not include the label.

Declaration

public IEnumerable<TItem> GetItemsWithout(string labelKey)

Parameters

Type	Name	Description
string	labelKey	The undesired label key.

Returns

Type	Description
IEnumerable<TItem>	The set of items without the label.

Select(string)

Returns the set of items that satisfy a label selector.

Declaration

public IEnumerable<TItem> Select(string labelSelector)

Parameters

Type	Name	Description
string	labelSelector	The label selector condistions(s).

Returns

Type	Description
IEnumerable<TItem>	The set of items whose meet the query requirements.

Remarks

This class supports Kubernetes style label selectors:

Kubernetes: Labels and Selectors

Label selectors must include zero or more label conditions separated by commas. All label conditions must be satisfied for an item to be selected. The conditions are essentially AND-ed together. We'll support two basic types of label conditions: equality/inequality and set based.

note

A null or empty labelSelector simply returns all items.

equality/inequality conditions:

[label] = [value]
[label] == [value]
[label] != [value]

The first two examples two compare label value equality and the last compares for inequality. Note that it is not currently possible to compare an empty or null string.

set conditions:

[label] in ([value1], [value2],,...)
notin([value1], [value2],...)
[label]
![label]

The first example selects items if they have a label with any of the values listed and the second selects items that have the label that doesn't have any of the values. The last two examples select items when they have or don't have a label, regardless of its value.

note

The in and notin operators both require that the item have the target label for a match.

note

Case Sensitivity: Label name lookups are actually determined by the dictionary returned by each item. .NET string dictionaries are typically case sensitive by default but you can change this behavior by having your item implementations construct case insenstive dictionaries. By default, this class performs case insensitive comparisions for label values. You can override this by passing CaseInsensitiveValues to the LabelSelector(IEnumerable<TItem>, LabelSelectorOptions) constructor.

note

Label Name Constraints: Label keys are checked to ensure that they match Kubernetes conventions by default. You can override this by passing UnConstraintedLabels to the LabelSelector(IEnumerable<TItem>, LabelSelectorOptions) constructor.

Label Value Constraints: Label values are also checked to ensure that they match Kubernetes conventions by default. This behavior can also be overriden by passing to the constructor.

Exceptions

Type	Condition
FormatException	Thrown when the label selector is not valid.