resource

Documentation

Overview

Package resource defines interfaces that may be implemented by types -- e.g. pkg/apis/GROUP/VERSION/types.go

Index

• func AddToScheme(objs ...Object) func(s *runtime.Scheme) error
• type ArbitrarySubResource
• type ConnectorSubResource
• type GetterUpdaterSubResource
• type MultiVersionObject
• type Object
• type ObjectList
• type ObjectWithArbitrarySubResource
• type ObjectWithScaleSubResource
• type ObjectWithStatusSubResource
• type QueryParameterObject
• type StatusSubResource
• type SubResource

Examples

• Object
• Object (WithHandler)
• Object (WithStrategy)

Functions

func AddToScheme

func AddToScheme(objs ...Object) func(s *runtime.Scheme) error

AddToScheme returns a function to add the Objects to the scheme.

AddToScheme will register the objects returned by New and NewList under the GroupVersion for each object. AddToScheme will also register the objects under the "__internal" group version for each object that returns true for IsInternalVersion. AddToScheme will register the defaulting function if it implements the Defaulter inteface.

Types

type ArbitrarySubResource

type ArbitrarySubResource interface {
	SubResource
	rest.Storage
}

ArbitrarySubResource defines required methods for extending a new custom subresource.

type ConnectorSubResource

type ConnectorSubResource interface {
	ArbitrarySubResource
	resourcerest.Connecter
}

ConnectorSubResource defines required methods for implementing a connector subresource.

type GetterUpdaterSubResource

type GetterUpdaterSubResource interface {
	ArbitrarySubResource
	resourcerest.Getter
	resourcerest.Updater
}

GetterUpdaterSubResource defines required methods for implementing a subresource that allows getting & updating.

type MultiVersionObject

type MultiVersionObject interface {
	// NewStorageVersionObject returns a new empty instance of storage version.
	NewStorageVersionObject() runtime.Object

	// ConvertToStorageVersion receives an new instance of storage version object as the conversion target
	// and overwrites it to the equal form of the current resource version.
	ConvertToStorageVersion(storageObj runtime.Object) error

	// ConvertFromStorageVersion receives an instance of storage version as the conversion source and
	// in-place mutates the current object to the equal form of the storage version object.
	ConvertFromStorageVersion(storageObj runtime.Object) error
}

MultiVersionObject should be implemented if the resource is not storage version and has multiple versions serving at the server.

type Object

type Object interface {
	// Object allows the apiserver libraries to operate on the Object
	runtime.Object

	// GetObjectMeta returns the object meta reference.
	GetObjectMeta() *metav1.ObjectMeta

	// Scoper is used to qualify the resource as either namespace scoped or non-namespace scoped.
	rest.Scoper

	// New returns a new instance of the resource -- e.g. &v1.Deployment{}
	New() runtime.Object

	// NewList return a new list instance of the resource -- e.g. &v1.DeploymentList{}
	NewList() runtime.Object

	// GetGroupVersionResource returns the GroupVersionResource for this resource.  The resource should
	// be the all lowercase and pluralized kind.s
	GetGroupVersionResource() schema.GroupVersionResource

	// IsStorageVersion returns true if the object is also the internal version -- i.e. is the type defined
	// for the API group an alias to this object.
	// If false, the resource is expected to implement MultiVersionObject interface.
	IsStorageVersion() bool
}

Object must be implemented by all resources served by the apiserver.

Example

package main

import (
	"github.com/pluralsh/apiserver-runtime/pkg/builder"
	"github.com/pluralsh/apiserver-runtime/pkg/builder/resource"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
)

func main() {
	// register this resource using the default etcd storage under
	// https://APISERVER_HOST:APISERVER_PORT/apis/sample.k8s.com/v1alpha1/namespaces/NAMESPACE/examples/NAME
	builder.APIServer.WithResource(&ExampleResource{})
}

var (
	// register the APIs in this package under the sample.k8s.com group and v1alpha1 version
	SchemeGroupVersion = schema.GroupVersion{Group: "sample.k8s.com", Version: "v1alpha1"}
	// AddToScheme is required for generated clients to compile
	// nolint:unused
	AddToScheme = resource.AddToScheme(&ExampleResource{})
)

type ExampleResource struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
}

type ExampleResourceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

	Items []ExampleResource `json:"items" protobuf:"bytes,2,rep,name=items"`
}

// DeepCopyObject is required by apimachinery and implemented by deepcopy-gen
func (e ExampleResource) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	panic("implement me")
}

// GetObjectMeta returns the ObjectMeta for the object
func (e ExampleResource) GetObjectMeta() *metav1.ObjectMeta {
	return &e.ObjectMeta
}

// NamespaceScoped returns true to register ExampleResource as a namespaced resource
func (e ExampleResource) NamespaceScoped() bool {
	return true
}

// New returns a new instance of the object for this resource.
func (e ExampleResource) New() runtime.Object {
	return &ExampleResource{}
}

// NewList returns a new instance of the list object for this resource.
func (e ExampleResource) NewList() runtime.Object {
	return &ExampleResourceList{}
}

// GetGroupVersionResource returns the GroupVersionResource for this type.
func (e ExampleResource) GetGroupVersionResource() schema.GroupVersionResource {
	return SchemeGroupVersion.WithResource("exampleresources")
}

// IsStorageVersion returns true for the resource version used as the storage version.
func (e ExampleResource) IsStorageVersion() bool {
	return true
}

// DeepCopyObject is required by apimachinery and generated by deepcopy-gen.
func (e *ExampleResourceList) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	return e
}

Example (WithHandler)

package main

import (
	"context"

	"github.com/pluralsh/apiserver-runtime/pkg/builder"
	"github.com/pluralsh/apiserver-runtime/pkg/builder/resource/resourcerest"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"k8s.io/apiserver/pkg/registry/rest"
)

func main() {
	// register this resource using the object itself to handle the requests and only exposes
	// endpoints that are implemented by the object (create, update, patch).
	// https://APISERVER_HOST:APISERVER_PORT/apis/sample.k8s.com/v1alpha1/namespaces/NAMESPACE/examples/NAME
	builder.APIServer.WithResource(&ExampleResourceWithHandler{})
}

// ExampleResourceWithHandler defines a resource and implements its request handler functions
type ExampleResourceWithHandler struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
}

// Create is invoked when creating a resource -- e.g. for POST calls
func (e ExampleResourceWithHandler) Create(
	ctx context.Context, obj runtime.Object, createValidation rest.ValidateObjectFunc, options *metav1.CreateOptions) (
	runtime.Object, error) {
	panic("implement me")
}

// Update is invoked when updating a resource -- e.g. for PUT and PATCH calls
func (e ExampleResourceWithHandler) Update(ctx context.Context, name string, objInfo rest.UpdatedObjectInfo,
	createValidation rest.ValidateObjectFunc, updateValidation rest.ValidateObjectUpdateFunc,
	forceAllowCreate bool, options *metav1.UpdateOptions) (runtime.Object, bool, error) {
	panic("implement me")
}

// ExampleResourceWithHandlerList contains a list of ExampleResourceWithHandler objects
type ExampleResourceWithHandlerList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

	Items []ExampleResourceWithHandler `json:"items" protobuf:"bytes,2,rep,name=items"`
}

var _ resourcerest.CreaterUpdater = &ExampleResourceWithHandler{}

// ExampleResourceWithHandler is required by apimachinery and implemented by deepcopy-gen
func (e ExampleResourceWithHandler) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	panic("implement me")
}

// GetObjectMeta returns the ObjectMeta for the object
func (e ExampleResourceWithHandler) GetObjectMeta() *metav1.ObjectMeta {
	return &e.ObjectMeta
}

// NamespaceScoped returns true to register ExampleResource as a namespaced resource
func (e ExampleResourceWithHandler) NamespaceScoped() bool {
	return true
}

// New returns a new instance of the object for this resource.
func (e ExampleResourceWithHandler) New() runtime.Object {
	return &ExampleResource{}
}

// NewList returns a new instance of the list object for this resource.
func (e ExampleResourceWithHandler) NewList() runtime.Object {
	return &ExampleResourceList{}
}

// GetGroupVersionResource returns the GroupVersionResource for this type.
func (e ExampleResourceWithHandler) GetGroupVersionResource() schema.GroupVersionResource {
	return SchemeGroupVersion.WithResource("examplewithhandlers")
}

// IsStorageVersion returns true for the resource version used as the storage version.
func (e ExampleResourceWithHandler) IsStorageVersion() bool {
	return true
}

// DeepCopyObject is required by apimachinery and generated by deepcopy-gen.
func (e *ExampleResourceWithHandlerList) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	return e
}

Example (WithStrategy)

package main

import (
	"context"

	"github.com/pluralsh/apiserver-runtime/pkg/builder"
	"github.com/pluralsh/apiserver-runtime/pkg/builder/resource/resourcestrategy"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	"k8s.io/apimachinery/pkg/runtime/schema"
	"k8s.io/apimachinery/pkg/util/validation/field"
)

func main() {
	// register this resource using the default etcd storage under
	// https://APISERVER_HOST:APISERVER_PORT/apis/sample.k8s.com/v1alpha1/namespaces/NAMESPACE/examples/NAME,
	// invoking the strategy functions before handling or storing the object.
	builder.APIServer.WithResource(&ExampleResourceWithStrategy{})
}

// ExampleResourceWithHandler defines a resource and implements its request handler functions
type ExampleResourceWithStrategy struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
}

// ExampleResourceWithHandlerList contains a list of ExampleResourceWithHandler objects
type ExampleResourceWithStrategyList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

	Items []ExampleResourceWithStrategy `json:"items" protobuf:"bytes,2,rep,name=items"`
}

var _ resourcestrategy.Defaulter = &ExampleResourceWithStrategy{}

func (e ExampleResourceWithStrategy) Default() {
	// set defaults here
}

var _ resourcestrategy.Validater = &ExampleResourceWithStrategy{}
var _ resourcestrategy.ValidateUpdater = &ExampleResourceWithStrategy{}

func (e ExampleResourceWithStrategy) Validate(ctx context.Context) field.ErrorList {
	// implement validation here
	return nil
}

func (e ExampleResourceWithStrategy) ValidateUpdate(ctx context.Context, obj runtime.Object) field.ErrorList {
	// implement validation here
	return nil
}

// ExampleResourceWithHandler is required by apimachinery and implemented by deepcopy-gen
func (e ExampleResourceWithStrategy) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	panic("implement me")
}

// GetObjectMeta returns the ObjectMeta for the object
func (e ExampleResourceWithStrategy) GetObjectMeta() *metav1.ObjectMeta {
	return &e.ObjectMeta
}

// NamespaceScoped returns true to register ExampleResource as a namespaced resource
func (e ExampleResourceWithStrategy) NamespaceScoped() bool {
	return true
}

// New returns a new instance of the object for this resource.
func (e ExampleResourceWithStrategy) New() runtime.Object {
	return &ExampleResource{}
}

// NewList returns a new instance of the list object for this resource.
func (e ExampleResourceWithStrategy) NewList() runtime.Object {
	return &ExampleResourceList{}
}

// GetGroupVersionResource returns the GroupVersionResource for this type.
func (e ExampleResourceWithStrategy) GetGroupVersionResource() schema.GroupVersionResource {
	return SchemeGroupVersion.WithResource("examplewithstrategies")
}

// IsStorageVersion returns true for the resource version used as the storage version.
func (e ExampleResourceWithStrategy) IsStorageVersion() bool {
	return true
}

// DeepCopyObject is required by apimachinery and generated by deepcopy-gen.
func (e *ExampleResourceWithStrategyList) DeepCopyObject() runtime.Object {
	// generated by deepcopy-gen
	return e
}

type ObjectList

type ObjectList interface {
	// Object allows the apiserver libraries to operate on the Object
	runtime.Object

	// GetListMeta returns the list meta reference.
	GetListMeta() *metav1.ListMeta
}

ObjectList must be implemented by all resources' list object.

type ObjectWithArbitrarySubResource

type ObjectWithArbitrarySubResource interface {
	Object
	GetArbitrarySubResources() []ArbitrarySubResource
}

ObjectWithArbitrarySubResource defines an interface for plumbing arbitrary sub-resources for a resource.

type ObjectWithScaleSubResource

type ObjectWithScaleSubResource interface {
	Object
	SetScale(scaleSubResource *autoscalingv1.Scale)
	GetScale() (scaleSubResource *autoscalingv1.Scale)
}

ObjectWithScaleSubResource defines an interface for getting and setting the scale sub-resource for a resource.

type ObjectWithStatusSubResource

type ObjectWithStatusSubResource interface {
	Object
	GetStatus() (statusSubResource StatusSubResource)
}

ObjectWithStatusSubResource defines an interface for getting and setting the status sub-resource for a resource.

type QueryParameterObject

type QueryParameterObject interface {
	ConvertFromUrlValues(values *url.Values) error
}

QueryParameterObject allows the object to be casted to url.Values. It's specifically for Connector subresource.

type StatusSubResource

type StatusSubResource interface {
	SubResource
	// CopyTo copies the content of the status subresource to a parent resource.
	CopyTo(parent ObjectWithStatusSubResource)
}

StatusSubResource defines required methods for implementing a status subresource.

type SubResource

type SubResource interface {
	SubResourceName() string
}

SubResource defines interface for registering arbitrary subresource to the parent resource.