v1

README

Composable SDK

Kubernetes object specifications often require constant values for their fields. When deploying an entire application with many different resources, this limitation often results in the need for staged deployments, because some resources have to be deployed first in order to determine what data to provide for the specifications of dependent resources. This undermines the declarative nature of Kubernetes object specification and requires workflows, manual step-by-step instructions and/or brittle automated scripts for the deployment of applications as a whole.

The Composable SDK can be used to add cross-resource references to any existing CRD, so that values no longer need to be hardwired. This feature allows dynamic configuration of a resource, meaning that its fields can be resolved after it has been deployed.

See this tutorial, in which we add cross-references to the memcached-operator (provided as a sample for operator-sdk) using the Composable SDK.

Installation

To install, run:

go get github.com/ibm/composable/sdk

Types

The Composable SDK offers the following types.

type ObjectRef struct {
	GetValueFrom ComposableGetValueFrom `json:"getValueFrom"`
}

type ComposableGetValueFrom struct {
	Kind               string   `json:"kind"`
	APIVersion         string   `json:"apiVersion,omitempty"`
	Name               string   `json:"name,omitempty"`
	Labels             []string `json:"labels,omitempty"`
	Namespace          string   `json:"namespace,omitempty"`
	Path               string   `json:"path"`
	FormatTransformers []string `json:"format-transformers,omitempty"`
}

An ObjectRef can be used to specify the type of any field of a CRD definition, allowing the value to be determined dynamically. For a detailed explanation of how to specify an object reference according to this schema, see here.

Functions

The Composable SDK offers the following function for resolving the value of cross-resource references.

func ResolveObject(r client.Client, config *rest.Config, object interface{}, resolved interface{}, composableNamespace string) *ComposableError 

The function ResolveObject takes a Kubernetes client and configuration, and object to resolve, and a blank object resolved that will contain the result, as well as a namespace. The namespace is the default used when references do not specify one. This function will cast the result to the type of the resolved object, provided that appropriate data transforms have been included in the reference definitions (see tutorial for an example).

The ResolveObject function uses caching for looking up object kinds, as well as for the objects themselves, in order to ensure that a consistent view of the data is obtained. If any data is not available at the time of the lookup, it returns an error. So this function either resolves the entire object or it doesn't -- there are no partial results.

The return value is a ComposableError:

type ComposableError struct {
	Error error
	// This indicates that the consuming Reconcile function should return this error
	ShouldBeReturned bool
}

The type ComposableError contains the error, if any, and a boolean ShouldBeReturned to indicate whether the calling reconciler should return this error or not. This is used to distinguish errors that are minor and could be fixed by immediately retrying from errors that may indicate a stronger failure, such as an ill-formed yaml (in which case there is no need to retry right away).

Documentation

Index

• Constants
• func Array2CSStringTransformer(intValue interface{}) (interface{}, error)
• func Base642StringTransformer(value interface{}) (interface{}, error)
• func CompoundTransformer(value interface{}, transformers ...Transformer) (interface{}, error)
• func CompoundTransformerNames(value interface{}, transNames ...string) (interface{}, error)
• func GetNamespace(obj map[string]interface{}) (string, error)
• func IsIllFormedRef(err error) bool
• func IsKindNotFound(err error) bool
• func IsObjectNotFound(err error) bool
• func IsRefNotFound(err error) bool
• func IsValueNotFound(err error) bool
• func JSONToObjectTransformer(value interface{}) (interface{}, error)
• func NameMatchesResource(kind string, resource metav1.APIResource, resGroup string) bool
• func ObjectToJSONTransformer(value interface{}) (interface{}, error)
• func String2Base64Transformer(value interface{}) (interface{}, error)
• func String2BoolTransformer(value interface{}) (interface{}, error)
• func String2FloatTransformer(value interface{}) (interface{}, error)
• func String2Int32Transformer(value interface{}) (interface{}, error)
• func String2IntTransformer(value interface{}) (interface{}, error)
• func ToStringTransformer(value interface{}) (interface{}, error)
• type ComposableCache
• type ComposableGetValueFrom
  • func (in *ComposableGetValueFrom) DeepCopy() *ComposableGetValueFrom
  • func (in *ComposableGetValueFrom) DeepCopyInto(out *ComposableGetValueFrom)
• type KubernetesResourceResolver
  • func (k KubernetesResourceResolver) ResolveObject(ctx context.Context, object interface{}, resolved interface{}) error
• type ObjectRef
  • func (in *ObjectRef) DeepCopy() *ObjectRef
  • func (in *ObjectRef) DeepCopyInto(out *ObjectRef)
• type ResolveObject
• type Transformer

Constants

const (
	Metadata     = "metadata"
	Namespace    = "namespace"
	GetValueFrom = "getValueFrom"

	Name         = "name"
	Labels       = "labels"
	Transformers = "format-transformers"
)

String constants

const (
	// Base64ToString - name of the base64 to string transformer
	Base64ToString = "Base64ToString"

	// StringToBase64 - name of the string to base64 transformer
	StringToBase64 = "StringToBase64"

	// StringToInt - name of the string to integer transformer
	StringToInt = "StringToInt"

	// StringToInt32 - name of the string to integer32 transformer
	StringToInt32 = "StringToInt32"

	// StringToFloat - name of the string to float transformer
	StringToFloat = "StringToFloat"

	// StringToBool - name of the string to boolean transformer
	StringToBool = "StringToBool"

	// ArrayToCSString - name of the array to Comma Separated String (CSS) transformer
	ArrayToCSString = "ArrayToCSString"

	// JSONToObject - name of the JSON to object transformer
	JSONToObject = "JsonToObject"

	// ObjectToJSON - name of the object to JSON transformer
	ObjectToJSON = "ObjectToJson"

	// ToString - name of the transformer, that transforms any object to its native string representation
	ToString = "ToString"
)

Functions

func Array2CSStringTransformer

func Array2CSStringTransformer(intValue interface{}) (interface{}, error)

Array2CSStringTransformer ...

func Base642StringTransformer

func Base642StringTransformer(value interface{}) (interface{}, error)

Base642StringTransformer ...

func CompoundTransformer

func CompoundTransformer(value interface{}, transformers ...Transformer) (interface{}, error)

CompoundTransformer - the function that combines several transformers

func CompoundTransformerNames

func CompoundTransformerNames(value interface{}, transNames ...string) (interface{}, error)

CompoundTransformerNames returns names of the given transformers

func GetNamespace

func GetNamespace(obj map[string]interface{}) (string, error)

GetNamespace gets the namespace out of a map

func IsIllFormedRef

func IsIllFormedRef(err error) bool

IsIllFormedRef can be used to determine if an error returned by the ResolveObject method is illFormedRef

func IsKindNotFound

func IsKindNotFound(err error) bool

IsKindNotFound can be used to determine if an error returned by the ResolveObject method is kindNotFound

func IsObjectNotFound

func IsObjectNotFound(err error) bool

IsObjectNotFound can be used to determine if an error returned by the ResolveObject method is objectNotFound

func IsRefNotFound

func IsRefNotFound(err error) bool

IsRefNotFound can be used to determine if an error returned by the ResolvedObject method is due to the reference not being found

func IsValueNotFound

func IsValueNotFound(err error) bool

IsValueNotFound can be used to determine if an error returned by the ResolveObject method is valueNotFound

func JSONToObjectTransformer

func JSONToObjectTransformer(value interface{}) (interface{}, error)

JSONToObjectTransformer ...

func NameMatchesResource

func NameMatchesResource(kind string, resource metav1.APIResource, resGroup string) bool

NameMatchesResource checks if the given resource name/kind matches with API resource and its group

func ObjectToJSONTransformer

func ObjectToJSONTransformer(value interface{}) (interface{}, error)

ObjectToJSONTransformer ...

func String2Base64Transformer

func String2Base64Transformer(value interface{}) (interface{}, error)

String2Base64Transformer ...

func String2BoolTransformer

func String2BoolTransformer(value interface{}) (interface{}, error)

String2BoolTransformer ...

func String2FloatTransformer

func String2FloatTransformer(value interface{}) (interface{}, error)

String2FloatTransformer ...

func String2Int32Transformer

func String2Int32Transformer(value interface{}) (interface{}, error)

String2Int32Transformer ...

func String2IntTransformer

func String2IntTransformer(value interface{}) (interface{}, error)

String2IntTransformer ...

func ToStringTransformer

func ToStringTransformer(value interface{}) (interface{}, error)

ToStringTransformer ...

Types

type ComposableCache

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

ComposableCache caches objects that have been read so far in a reconcile cycle

type ComposableGetValueFrom

type ComposableGetValueFrom struct {
	Kind               string   `json:"kind"`
	APIVersion         string   `json:"apiVersion,omitempty"`
	Name               string   `json:"name,omitempty"`
	Labels             []string `json:"labels,omitempty"`
	Namespace          string   `json:"namespace,omitempty"`
	Path               string   `json:"path"`
	FormatTransformers []string `json:"format-transformers,omitempty"`
}

ComposableGetValueFrom specifies a reference to a Kubernetes object +kubebuilder:object:generate=true

func (*ComposableGetValueFrom) DeepCopy

func (in *ComposableGetValueFrom) DeepCopy() *ComposableGetValueFrom

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ComposableGetValueFrom.

func (*ComposableGetValueFrom) DeepCopyInto

func (in *ComposableGetValueFrom) DeepCopyInto(out *ComposableGetValueFrom)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type KubernetesResourceResolver

type KubernetesResourceResolver struct {
	Client          client.Client
	ResourcesClient discovery.ServerResourcesInterface
}

KubernetesResourceResolver implements the ResolveObject interface

func (KubernetesResourceResolver) ResolveObject

func (k KubernetesResourceResolver) ResolveObject(ctx context.Context, object interface{}, resolved interface{}) error

ResolveObject resolves the object into resolved

type ObjectRef

type ObjectRef struct {
	GetValueFrom ComposableGetValueFrom `json:"getValueFrom"`
}

ObjectRef is the type that can be used for cross-resource references +kubebuilder:object:generate=true

func (*ObjectRef) DeepCopy

func (in *ObjectRef) DeepCopy() *ObjectRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObjectRef.

func (*ObjectRef) DeepCopyInto

func (in *ObjectRef) DeepCopyInto(out *ObjectRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ResolveObject

type ResolveObject interface {
	// ResolveObject resolves object references. It uses a context for cancellation.
	ResolveObject(ctx context.Context, in, out interface{}) error
}

ResolveObject interface

type Transformer

type Transformer func(interface{}) (interface{}, error)

Transformer - the base transformer function