wait

Documentation

Overview

Package wait contains functionality for getting the statuses of a list of kubernetes resources. Unlike the status package, the functions exposed in the wait package will talk to a live kubernetes cluster to get the latest state of resources and provides functionality for polling the cluster until the resources reach the Current status.

FetchAndResolve will fetch resources from a cluster, compute the status for each of them and then return the results. The list of resources is defined as a slice of ResourceIdentifier, which is an interface that is implemented by the Unstructured type. It only requires functions for getting the apiVersion, kind, name and namespace of a resource.

import (
  "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
  "k8s.io/apimachinery/pkg/types"
  "sigs.k8s.io/kustomize/kstatus/wait"
)

key := types.NamespacedName{Name: "name", Namespace: "namespace"}
deployment := &unstructured.Unstructured{
  Object: map[string]interface{}{
    "apiVersion": "apps/v1",
    "kind":       "Deployment",
  },
}
client.Get(context.Background(), key, deployment)
resourceIdentifiers := []wait.ResourceIdentifier{deployment}

resolver := wait.NewResolver(client)
results := resolver.FetchAndResolve(context.Background(), resourceIdentifiers)

WaitForStatus also looks up status for a list of resources, but it will block until all the provided resources has reached the Current status or the wait is cancelled through the passed-in context. The function returns a channel that will provide updates as the status of the different resources change.

import (
  "sigs.k8s.io/kustomize/kstatus/wait"
)

resolver := wait.NewResolver(client)
eventsChan := resolver.WaitForStatus(context.Background(), resourceIdentifiers, 2 * time.Second)
for {
  select {
  case event, ok := <-eventsChan:
    if !ok {
      return
    }
    fmt.Printf(event) // do something useful here.
  }
}

Index

• type Event
• type EventResource
• type EventType
• type KubernetesObject
• type Resolver
  • func NewResolver(client client.Reader, mapper meta.RESTMapper, pollInterval time.Duration) *Resolver
  • func (r *Resolver) FetchAndResolve(ctx context.Context, resourceIDs []ResourceIdentifier) []ResourceResult
  • func (r *Resolver) FetchAndResolveObjects(ctx context.Context, objects []KubernetesObject) []ResourceResult
  • func (r *Resolver) WaitForStatus(ctx context.Context, resources []ResourceIdentifier) <-chan Event
  • func (r *Resolver) WaitForStatusOfObjects(ctx context.Context, objects []KubernetesObject) <-chan Event
• type ResourceIdentifier
  • func (r ResourceIdentifier) Equals(other ResourceIdentifier) bool
• type ResourceResult

Types

type Event

type Event struct {
	// Type defines which type of event this is.
	Type EventType

	// AggregateStatus is the aggregated status for all the provided resources.
	AggregateStatus status.Status

	// EventResource is information about the event to which this event pertains.
	// This is only populated for ResourceUpdate events.
	EventResource *EventResource
}

Event is returned through the channel returned after a call to WaitForStatus. It contains an update to either an individual resource or to the aggregate status for the set of resources.

type EventResource

type EventResource struct {
	// Identifier contains information that identifies which resource
	// this information is about.
	ResourceIdentifier ResourceIdentifier

	// Status is the latest status for the given resource.
	Status status.Status

	// Message is more details about the status.
	Message string

	// Error is set if there was a problem identifying the status
	// of the resource. For example, if polling the cluster for information
	// about the resource failed.
	Error error
}

EventResource contains information about the resource for which a specific Event pertains.

type EventType

type EventType string

const (
	// The status/message for a resource has changed. This also means the
	// aggregate status might have changed.
	ResourceUpdate EventType = "ResourceUpdate"

	// All resources have reached the current status.
	Completed EventType = "Completed"

	// The wait was stopped before all resources could reach the
	// Current status.
	Aborted EventType = "Aborted"
)

type KubernetesObject

type KubernetesObject interface {
	GetName() string
	GetNamespace() string
	GroupVersionKind() schema.GroupVersionKind
}

ResourceIdentifier defines the functions needed to identify a resource in a cluster. This interface is implemented by both unstructured.Unstructured and the standard Kubernetes types.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver provides the functions for resolving status of a list of resources.

func NewResolver

func NewResolver(client client.Reader, mapper meta.RESTMapper, pollInterval time.Duration) *Resolver

NewResolver creates a new resolver with the provided client. Fetching and polling of resources will be done using the provided client.

func (*Resolver) FetchAndResolve

func (r *Resolver) FetchAndResolve(ctx context.Context, resourceIDs []ResourceIdentifier) []ResourceResult

FetchAndResolve returns the status for a list of ResourceIdentifiers. It will return the status for each of them individually.

func (*Resolver) FetchAndResolveObjects

func (r *Resolver) FetchAndResolveObjects(ctx context.Context, objects []KubernetesObject) []ResourceResult

FetchAndResolveObjects returns the status for a list of kubernetes objects. These can be provided either as Unstructured resources or the specific resource types. It will return the status for each of them individually. The provided resources will only be used to get the information needed to fetch the updated state of the resources from the cluster.

func (*Resolver) WaitForStatus

func (r *Resolver) WaitForStatus(ctx context.Context, resources []ResourceIdentifier) <-chan Event

WaitForStatus polls all the resources references by the provided ResourceIdentifiers until all of them have reached the Current status or the timeout specified through the context is reached. Updates on the status of individual resources and the aggregate status is provided through the Event channel.

func (*Resolver) WaitForStatusOfObjects

func (r *Resolver) WaitForStatusOfObjects(ctx context.Context, objects []KubernetesObject) <-chan Event

WaitForStatus polls all the provided resources until all of them have reached the Current status or the timeout specified through the context is reached. Updates on the status of individual resources and the aggregate status is provided through the Event channel.

type ResourceIdentifier

type ResourceIdentifier struct {
	Name      string
	Namespace string
	GroupKind schema.GroupKind
}

ResourceIdentifier contains the information needed to uniquely identify a resource in a cluster.

func (ResourceIdentifier) Equals

func (r ResourceIdentifier) Equals(other ResourceIdentifier) bool

Equals compares two ResourceIdentifiers and returns true if they refer to the same resource. Special handling is needed for namespace since an empty namespace for a namespace-scoped resource is defaulted to the "default" namespace.

type ResourceResult

type ResourceResult struct {
	Result *status.Result

	ResourceIdentifier ResourceIdentifier

	Error error
}

ResourceResult is the status result for a given resource. It provides information about the resource if the request was successful and an error if something went wrong.