reference

Documentation

Overview

Package reference is based on https://github.com/operator-framework/operator-lib/blob/8c3d48f55639528bcee4432b570bc6671900b75d/handler/enqueue_annotation.go Main changes are about allowing to store multiple values of a given annotation as comma-separated list.

Copyright 2020 The Operator-SDK Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• func Add(owner types.NamespacedName, object client.Object) error
• func AddRefMarker(object client.Object, key, value, hash string)
• func CreateRefMarker(session, ref string) string
• func Get(object client.Object) []types.NamespacedName
• func GetRefMarker(object client.Object, key string) (value, hash string)
• func RefMarkerMatch(session string) client.ListOption
• func Remove(owner types.NamespacedName, object client.Object) error
• func RemoveRefMarker(object client.Object, session string)
• type EnqueueRequestForAnnotation
  • func (e *EnqueueRequestForAnnotation) Create(evt event.CreateEvent, q workqueue.RateLimitingInterface)
  • func (e *EnqueueRequestForAnnotation) Delete(evt event.DeleteEvent, q workqueue.RateLimitingInterface)
  • func (e *EnqueueRequestForAnnotation) Generic(evt event.GenericEvent, q workqueue.RateLimitingInterface)
  • func (e *EnqueueRequestForAnnotation) Update(evt event.UpdateEvent, q workqueue.RateLimitingInterface)

Constants

const (
	// NamespacedNameAnnotation is an annotation whose value encodes the name and namespace of a resource to
	// reconcile when a resource containing this annotation changes. Valid values are of the form
	// `<namespace>/<name>` for namespace-scoped owners and `<name>` for cluster-scoped owners.
	NamespacedNameAnnotation = "maistra.io/istio-workspaces"
)

Functions

func Add

func Add(owner types.NamespacedName, object client.Object) error

Add helps in adding 'NamespacedNameAnnotation' to object based on the NamespaceName. The object gets the annotations from owner's namespace, name, group and kind. In other terms, object can be said to be the dependent having annotations from the owner. When a watch is set on the object, the annotations help to identify the owner and trigger reconciliation. Annotations are accumulated as a comma-separated list.

func AddRefMarker

func AddRefMarker(object client.Object, key, value, hash string)

AddRefMarker sets session specific label on a given object.

func CreateRefMarker

func CreateRefMarker(session, ref string) string

func Get

func Get(object client.Object) []types.NamespacedName

Get converts annotations defined for NamespacedNameAnnotation as comma-separated list to a slice.

func GetRefMarker

func GetRefMarker(object client.Object, key string) (value, hash string)

GetRefMarker returns value of a label specific to a given session.

func RefMarkerMatch

func RefMarkerMatch(session string) client.ListOption

RefMarkerMatch filters the list operation checking if the set of session specific labels exists without checking their values.

func Remove

func Remove(owner types.NamespacedName, object client.Object) error

Remove helps in removing 'NamespacedNameAnnotation' from object based on the NamespaceName. The object gets the annotations from owner's namespace, name, group and kind. Annotations are accumulated as a comma-separated list, thus removal will change the content of the list.

func RemoveRefMarker

func RemoveRefMarker(object client.Object, session string)

RemoveRefMarker removes label for a specific session. If label does not exists RemoveRefMarker is no-op.

Types

type EnqueueRequestForAnnotation

type EnqueueRequestForAnnotation struct {
	Type schema.GroupKind
}

EnqueueRequestForAnnotation enqueues Request containing the Name and Namespace specified in the annotations of the object that is the source of the Event. The source of the event triggers reconciliation of the parent resource which is identified by annotations. `NamespacedNameAnnotation` uniquely identify an owner resource to reconcile.

handler.EnqueueRequestForAnnotation can be used to trigger reconciliation of resources which are cross-referenced. This allows a namespace-scoped dependent to trigger reconciliation of an owner which is in a different namespace, and a cluster-scoped dependent can trigger the reconciliation of a namespace(scoped)-owner.

As an example, consider the case where we would like to watch virtualservices based on which we reconcile Istio Workspace Sessions. We rely on using annotations as a way of tracking the resources that we manipulate to avoid running into the built-in garbage collection included with OwnerRef. Using this approach we could implement the following:

if err := c.Watch(&source.Kind{
	// Watch VirtualService
	Type: &istio.VirtualService{}},

	// Enqueue ReplicaSet reconcile requests using the namespacedName annotation value in the request.
	&handler.EnqueueRequestForAnnotation{schema.GroupKind{Group:"istio.io", Kind:"VirtualService"}}); err != nil {
		entryLog.Error(err, "unable to watch ClusterRole")
		os.Exit(1)
	}
}

With this watch, the Istio Workspace controller would receive a request to reconcile "namespace/session1,session2" based on a change to a VirtualService that has the following annotations:

annotations:
	maistra.io/istio-workspaces: "namespace/session1,session2"

Note: multiple sessions can manipulate the same resource, therefore the annotation is a list defined as comma-separated values.

Though an annotation-based watch handler removes the boundaries set by native owner reference implementation, the garbage collector still respects the scope restrictions. For example, if a parent creates a child resource across scopes not supported by owner references, it becomes the responsibility of the reconciler to clean up the child resource. Hence, the resource utilizing this handler SHOULD ALWAYS BE IMPLEMENTED WITH A FINALIZER.

func (*EnqueueRequestForAnnotation) Create

func (e *EnqueueRequestForAnnotation) Create(evt event.CreateEvent, q workqueue.RateLimitingInterface)

Create reacts to create event and schedules reconcile.

func (*EnqueueRequestForAnnotation) Delete

func (e *EnqueueRequestForAnnotation) Delete(evt event.DeleteEvent, q workqueue.RateLimitingInterface)

Delete reacts to delete event and schedules reconcile.

func (*EnqueueRequestForAnnotation) Generic

func (e *EnqueueRequestForAnnotation) Generic(evt event.GenericEvent, q workqueue.RateLimitingInterface)

Generic reacts to any other event (e.g. reconcile Autoscaling, or a Webhook) and schedules reconcile.

func (*EnqueueRequestForAnnotation) Update

func (e *EnqueueRequestForAnnotation) Update(evt event.UpdateEvent, q workqueue.RateLimitingInterface)

Update reacts to update event and schedules reconcile.