injection

package
v0.0.0-...-a7fd9b1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 18, 2024 License: Apache-2.0 Imports: 16 Imported by: 5,338

README

Knative Dependency Injection

This library supports the production of controller processes with minimal boilerplate outside of the reconciler implementation.

Building Controllers

To adopt this model of controller construction, implementations should start with the following controller constructor:

import (
	"context"

	"knative.dev/pkg/configmap"
	"knative.dev/pkg/controller"
	"knative.dev/pkg/logging"
	kindreconciler "knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<resource>"
)

func NewController(ctx context.Context, cmw configmap.Watcher) *controller.Impl {
	logger := logging.FromContext(ctx)

	// TODO(you): Access informers

	r := &Reconciler{
		// TODO(you): Pass listers, clients, and other stuff.
	}
	impl := kindreconciler.NewImpl(ctx, r)

	// TODO(you): Set up event handlers.

	return impl
}
Generated Reconcilers

A code generator is available for simple subset of reconciliation requirements. A label above the API type will signal to the injection code generator to generate a strongly typed reconciler. Use +genreconciler to generate the reconcilers.

// +genclient
// +genreconciler
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

type ExampleType struct {
	...
}

+genreconciler will produce a helper method to get a controller impl.

Update NewController as follows:

"knative.dev/pkg/controller"
...
impl := controller.NewContext(ctx, c, controller.ControllerOptions{
	Logger: logger,
	WorkQueueName: "NameOfController",
})

becomes

kindreconciler "knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<resource>"
...
impl := kindreconciler.NewImpl(ctx, c)

See Generated Reconciler Responsibilities for more information.

Implementing Reconcilers

Type Reconciler is expected to implement Reconcile:

func (r *Reconciler) Reconcile(ctx context.Context, key string) error {
	...
}
Generated Reconcilers

If generated reconcilers are used, Type Reconciler is expected to implement ReconcileKind:

func (r *Reconciler) ReconcileKind(ctx context.Context, o *samplesv1alpha1.AddressableService) reconciler.Event {
    ...
}

And if finalizers are required,

func (r *Reconciler) FinalizeKind(ctx context.Context, o *samplesv1alpha1.AddressableService) reconciler.Event {
    ...
}

See Generated Reconciler Responsibilities for more information.

Consuming Informers

Knative controllers use "informers" to set up the various event hooks needed to queue work, and pass the "listers" fed by the informers' caches to the nested "Reconciler" for accessing objects.

Our controller constructor is passed a context.Context onto which we inject any informers we access. The accessors for these informers are in little stub libraries, which we have hand rolled for Kubernetes (more on how to generate these below).

import (
	// These are how you access a client or informer off of the "ctx" passed
	// to set up the controller.
	"knative.dev/pkg/client/injection/kube/client"
	svcinformer "knative.dev/pkg/client/injection/kube/informers/core/v1/service"

	// Other imports ...
)

func NewController(ctx context.Context, cmw configmap.Watcher) *controller.Impl {
	logger := logging.FromContext(ctx)

	// Access informers
	svcInformer := svcinformer.Get(ctx)

	c := &Reconciler{
		// Pass the lister and client to the Reconciler.
		Client:        kubeclient.Get(ctx),
		ServiceLister: svcInformer.Lister(),
	}
	logger = logger.Named("NameOfController")
	impl := controller.NewContext(ctx, c, controller.ControllerOptions{
		Logger: logger,
		WorkQueueName: "NameOfController",
	})

	// Set up event handlers.
	svcInformer.Informer().AddEventHandler(...)

	return impl
}

How it works: by importing the accessor for a client or informer we link it and trigger the init() method for its package to run at startup. Each of these libraries registers themselves similar to our init() and controller processes can leverage this to setup and inject all of the registered things onto a context to pass to your NewController().

Testing Controllers

Similar to injection.Default, we also have injection.Fake. While linking the normal accessors sets up the former, linking their fakes set up the latter.

import (
	"testing"

	// Link the fakes for any informers our controller accesses.
	_ "knative.dev/pkg/client/injection/kube/informers/core/v1/service/fake"

	"k8s.io/client-go/rest"
	"knative.dev/pkg/injection"
	logtesting "knative.dev/pkg/logging/testing"
)

func TestFoo(t *testing.T) {
	ctx := logtesting.TestContextWithLogger(t)

	// Setup a context from all of the injected fakes.
	ctx, _ = injection.Fake.SetupInformers(ctx, &rest.Config{})
	cmw := configmap.NewStaticWatcher(...)
	ctrl := NewController(ctx, cmw)

	// Test the controller process.
}

The fake clients also support manually setting up contexts seeded with objects:

import (
	"testing"

	fakekubeclient "knative.dev/pkg/client/injection/kube/client/fake"

	"k8s.io/client-go/rest"
	"knative.dev/pkg/injection"
	logtesting "knative.dev/pkg/logging/testing"
)

func TestFoo(t *testing.T) {
	ctx := logtesting.TestContextWithLogger(t)

	objs := []runtime.Object{
		// Some list of initial objects in the client.
	}

	ctx, kubeClient := fakekubeclient.With(ctx, objs...)

	// The fake clients returned by our library are the actual fake type,
	// which enables us to access test-specific methods, e.g.
	kubeClient.AppendReactor(...)

	c := &Reconciler{
		Client: kubeClient,
	}

	// Test the reconciler...
}

Starting controllers

All we do is import the controller packages and pass their constructors along with a component name (single word) to our shared main. Then our shared main method sets it all up and runs our controllers.

package main

import (
	// The set of controllers this process will run.
	"github.com/knative/foo/pkg/reconciler/bar"
	"github.com/knative/baz/pkg/reconciler/blah"

	// This defines the shared main for injected controllers.
	"knative.dev/pkg/injection/sharedmain"
)

func main() {
	sharedmain.Main("componentname",
       bar.NewController,
       blah.NewController,
    )
}

Generating Injection Stubs.

To make generating stubs simple, we have harnessed the Kubernetes code-generation tooling to produce injection-gen. Similar to how you might ordinarily run the other foo-gen processed:

CODEGEN_PKG=${CODEGEN_PKG:-$(cd ${REPO_ROOT}; ls -d -1 ./vendor/k8s.io/code-generator 2>/dev/null || echo ../code-generator)}

${CODEGEN_PKG}/generate-groups.sh "deepcopy,client,informer,lister" \
  github.com/knative/sample-controller/pkg/client github.com/knative/sample-controller/pkg/apis \
  "samples:v1alpha1" \
  --go-header-file ${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt

To run injection-gen you run the following (replacing the import path and api group):


KNATIVE_CODEGEN_PKG=${KNATIVE_CODEGEN_PKG:-$(cd ${REPO_ROOT}; ls -d -1 ./vendor/knative.dev/pkg 2>/dev/null || echo ../pkg)}

${KNATIVE_CODEGEN_PKG}/hack/generate-knative.sh "injection" \
  github.com/knative/sample-controller/pkg/client github.com/knative/sample-controller/pkg/apis \
  "samples:v1alpha1" \
  --go-header-file ${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt

To ensure the appropriate tooling is vendored, add the following to Gopkg.toml:

required = [
  "knative.dev/pkg/codegen/cmd/injection-gen",
]

# .. Constraints

# Keeps things like the generate-knative.sh script
[[prune.project]]
  name = "knative.dev/pkg"
  unused-packages = false
  non-go = false

Generated Reconciler Responsibilities

The goal of generating the reconcilers is to provide the controller implementer a strongly typed interface, and ensure correct reconciler behaviour around status updates, Kubernetes event creation, and queue management.

We have already helped the queue management with libraries in this repo. But there was a gap in support and standards around how status updates (and retries) are performed, and when Kubernetes events are created for the resource.

The general flow with generated reconcilers looks like the following:

[k8s] -> [watches] -> [reconciler enqeueue] -> [Reconcile(key)] -> [ReconcileKind(resource)]
            ^-- you set up.                          ^-- generated       ^-- stubbed and you customize

Optionally, support for finalizers:

[Reconcile(key)] -> <resource deleted?> - no -> [ReconcileKind(resource)]
                          `
                      (optional)
                            `- yes -> [FinalizeKind(resource)]
  • ReconcileKind is only called if the resource's deletion timestamp is empty.
  • FinalizeKind is optional, and if implemented by the reconciler will be called when the resource's deletion timestamp is set.

The responsibility and consequences of using the generated ReconcileKind(resource) method are as follows:

  • In NewController, set up watches and reconciler enqueue requests as before.
  • Implementing ReconcileKind(ctx, resource) to handle active resources.
  • Implementing FinalizeKind(ctx, resource) to finalize deleting active resources.
    • NOTE: Implementing FinalizeKind will result in the reconciler using finalizers on the resource.
  • Resulting changes from Reconcile calling ReconcileKind(ctx, resource):
    • DO NOT edit the spec of resource, it will be ignored.
    • DO NOT edit the metadata of resource, it will be ignored.
    • If resource.status is changed, Reconcile will synchronize it back to the API Server.
      • Note: the watches setup for resource.Kind will see the update to status and cause another reconciliation.
  • ReconcileKind(ctx, resource) returns a reconciler.Event results in:
  • If event is an error (reconciler.Event extends error internally), Reconciler will produce a Warning kubernetes event with reason InternalError and the body of the error as the message.
    • Additionally, the error will be returned from Reconciler and key will requeue back into the reconciler key queue.
  • If event is a reconciler.Event, Reconciler will log a typed and reasoned Kubernetes Event based on the contents of event.
    • event is not considered an error for requeue and nil is returned from Reconciler.
  • If additional events are required to be produced, an implementation can pull a recorder from the context: recorder := controller.GetEventRecorder(ctx).

Future features to be considered:

  • Document how we leverage configStore and specifically ctx = r.configStore.ToContext(ctx) inside Reconcile.
  • Adjust +genreconciler to allow for generated reconcilers to be made without annotating the type struct.
  • Add class-based annotation filtering.
ConfigStore

Config store is used to decorate the context with a snapshot of configmaps to be used in a reconciler method.

To add this feature to the generated reconciler, it will have to be passed in on reconciler<kind>.NewImpl like so:

kindreconciler "knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<resource>"
...
impl := kindreconciler.NewImpl(ctx, c, func(impl *controller.Impl) controller.Options {
	// Setup options that require access to a controller.Impl.
	configsToResync := []interface{}{
		&some.Config{},
	}
	resyncOnConfigChange := configmap.TypeFilter(configsToResync...)(func(string, interface{}) {
		impl.FilteredGlobalResync(myFilterFunc, kindInformer.Informer())
	})
	configStore := config.NewStore(c.Logger.Named("config-store"), resyncOnConfigChange)
	configStore.WatchConfigs(cmw)

	// Return the controller options.
	return controller.Options{
		ConfigStore: configStore,
	}
})
Filtering on controller promotion

The generated controllers implement the LeaderAwareFuncs interface to support HA controller deployments. When a generated controller is promoted, by default it will trigger a re-reconcile of every resource it manages. To filter which objects get reconciled, pass a PromoteFilterFunc to the controller's constructor:

kindreconciler "knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<resource>"
pkgreconciler "knative.dev/pkg/reconciler"
...
impl := kindreconciler.NewImpl(ctx, c, func(impl *controller.Impl) controller.Options {
	return controller.Options{
		PromoteFilterFunc: pkgreconciler.LabelFilterFunc("mylabel", "myvalue", false),
	}
})
Artifacts

The artifacts are targeted to the configured client/injection directory:

kindreconciler "knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<kind>"

Controller related artifacts:

  • NewImpl - gets an injection based client and lister for <kind>, sets up Kubernetes Event recorders, and delegates to controller.NewContext for queue management.
impl := reconciler.NewImpl(ctx, reconcilerInstance)

Reconciler related artifacts:

  • Interface - defines the strongly typed interfaces to be implemented by a controller reconciling <kind>.
// Check that our Reconciler implements Interface
var _ addressableservicereconciler.Interface = (*Reconciler)(nil)
  • Finalizer - defines the strongly typed interfaces to be implemented by a controller finalizing <kind>.
// Check that our Reconciler implements Interface
var _ addressableservicereconciler.Finalizer = (*Reconciler)(nil)
Annotation based class filters

Sometimes a reconciler only wants to reconcile a class of resource identified by a special annotation on the Custom Resource.

This behavior can be enabled in the generators by adding the annotation class key to the type struct:

// +genreconciler:class=example.com/filter.class

The genreconciler generator code will now have the addition of classValue string to NewImpl and NewReconciler (for tests):

NewImpl(ctx context.Context, r Interface, classValue string, optionsFns ...controller.OptionsFn) *controller.Impl

NewReconciler(ctx context.Context, logger *zap.SugaredLogger, client versioned.Interface, lister pubv1alpha1.BarLister, recorder record.EventRecorder, r Interface, classValue string, options ...controller.Options) controller.Reconciler

ReconcileKind and FinalizeKind will NOT be called for resources that DO NOT have the provided +genreconciler:class=<key> key annotation. Additionally the value of the <key> annotation on a resource must match the value provided to NewImpl (or NewReconcile) for ReconcileKind or FinalizeKind to be called for that resource.

Annotation based common logic

krshapedlogic=false may be used to omit common reconciler logic

Reconcilers can handle common logic for resources that conform to the KRShaped interface. This allows the generated code to automatically increment ObservedGeneration.

// +genreconciler

Setting this annotation will emit the following in the generated reconciler.

reconciler.PreProcessReconcile(ctx, resource)

reconcileEvent = r.reconciler.ReconcileKind(ctx, resource)

reconciler.PostProcessReconcile(ctx, resource, oldResource)
Stubs

To enable stubs generation, add the stubs flag:

// +genreconciler:stubs

Or with the class annotation:

// +genreconciler:class=example.com/filter.class,stubs

The stubs are intended to be used to get started, or to use as reference. It is intended to be copied out of the client dir.

knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<kind>/stubs/controller.go

  • A basic implementation of NewController.

knative.dev/<repo>/pkg/client/injection/reconciler/<clientgroup>/<version>/<kind>/stubs/reconciler.go

  • A basic implementation of type Reconciler struct {} and Reconciler.ReconcileKind.
  • A commented out example of a basic implementation of Reconciler.FinalizeKind.
  • An example reconciler.Event: newReconciledNormal
Examples

Please look at sample-controller or sample-source for working integrations of the generated geconciler code.

Documentation

Overview

Package injection defines the mechanisms through which clients, informers and shared informer factories are injected into a shared controller binary implementation.

There are two primary contexts where the usage of the injection package is interesting. The first is in the context of implementations of `controller.Reconciler` being wrapped in a `*controller.Impl`: 

import (
  // Simply linking this triggers the injection of the informer, which links
  // the factory triggering its injection, and which links the client,
  // triggering its injection.  All you need to know is that it works :)
  deployinformer "knative.dev/pkg/injection/informers/kubeinformers/appsv1/deployment"
  "knative.dev/pkg/injection"
)

func NewController(ctx context.Context) *controller.Impl {
  deploymentInformer := deployinformer.Get(ctx)
  // Pass deploymentInformer.Lister() to Reconciler
  ...
  // Set up events on deploymentInformer.Informer()
  ...
}

Then in `package main` the entire controller process can be set up via: 

package main

import (
	// The set of controllers this controller process runs.
   // Linking these will register their transitive dependencies, after
   // which the shared main can set up the rest.
	"github.com/knative/foo/pkg/reconciler/matt"
	"github.com/knative/foo/pkg/reconciler/scott"
	"github.com/knative/foo/pkg/reconciler/ville"
	"github.com/knative/foo/pkg/reconciler/dave"

	// This defines the shared main for injected controllers.
	"knative.dev/pkg/injection/sharedmain"
)

func main() {
	sharedmain.Main("mycomponent",
      // We pass in the list of controllers to construct, and that's it!
      // If we forget to add this, go will complain about the unused import.
      matt.NewController,
      scott.NewController,
      ville.NewController,
      dave.NewController,
   )
}

If you want to adapt the above to run the controller within a single namespace, you can instead do something like: 

package main

import (
	// The set of controllers this controller process runs.
   // Linking these will register their transitive dependencies, after
   // which the shared main can set up the rest.
	"github.com/knative/foo/pkg/reconciler/matt"
	"github.com/knative/foo/pkg/reconciler/scott"
	"github.com/knative/foo/pkg/reconciler/ville"
	"github.com/knative/foo/pkg/reconciler/dave"

	// This defines the shared main for injected controllers.
	"knative.dev/pkg/injection/sharedmain"

   // These are used to set up the context.
	"knative.dev/pkg/injection"
	"knative.dev/pkg/signals"
)

func main() {
   // Scope the shared informer factories to the provided namespace.
   ctx := injection.WithNamespace(signals.NewContext(), "the-namespace")

   // Use our initial context when setting up the controllers.
	sharedmain.MainWithContext(ctx, "mycomponent",
      // We pass in the list of controllers to construct, and that's it!
      // If we forget to add this, go will complain about the unused import.
      matt.NewController,
      scott.NewController,
      ville.NewController,
      dave.NewController,
   )
}

Index

Constants

View Source 
const HealthCheckDefaultPort = 8080

HealthCheckDefaultPort defines the default port number for health probes

Variables

This section is empty.

Functions

func AddLiveness 

func AddLiveness(ctx context.Context, handlerFunc http.HandlerFunc) context.Context

AddLiveness signals to probe setup logic to add a user provided probe handler

func AddReadiness 

func AddReadiness(ctx context.Context, handlerFunc http.HandlerFunc) context.Context

AddReadiness signals to probe setup logic to add a user provided probe handler

func EnableInjectionOrDie 

func EnableInjectionOrDie(ctx context.Context, cfg *rest.Config) (context.Context, func())

EnableInjectionOrDie enables Knative Client Injection, and provides a callback to start the informers. Both Context and Config are optional. Returns context with rest config set and a callback to start the informers after watches have been set.

Typical integration: ```go 

ctx, startInformers := injection.EnableInjectionOrDie(signals.NewContext(), nil)
... start watches with informers, if required ...
startInformers()

```

func GetConfig 

func GetConfig(ctx context.Context) *rest.Config

GetConfig gets the current config from the context.

func GetNamespaceScope 

func GetNamespaceScope(ctx context.Context) string

GetNamespaceScope accesses the namespace associated with the provided context. This should be called when the injection logic is setting up shared informer factories.

func GetRESTConfig 

func GetRESTConfig(serverURL, kubeconfig string) (*rest.Config, error)

GetRESTConfig returns a rest.Config to be used for kubernetes client creation. Deprecated: use environment.ClientConfig package

func GetResourceVersion 

func GetResourceVersion(ctx context.Context) string

GetResourceVersion gets the resource version associated with the context.

func HasNamespaceScope 

func HasNamespaceScope(ctx context.Context) bool

HasNamespaceScope determines whether the provided context has been scoped to a particular namespace.

func ParseAndGetRESTConfigOrDie 

func ParseAndGetRESTConfigOrDie() *rest.Config

ParseAndGetRESTConfigOrDie parses the rest config flags and creates a client or dies by calling log.Fatalf.

func ServeHealthProbes 

func ServeHealthProbes(ctx context.Context, port int) error

ServeHealthProbes sets up liveness and readiness probes. If user sets no probes explicitly via the context then defaults are added.

func WithConfig 

func WithConfig(ctx context.Context, cfg *rest.Config) context.Context

WithConfig associates a given config with the context.

func WithNamespaceScope 

func WithNamespaceScope(ctx context.Context, namespace string) context.Context

WithNamespaceScope associates a namespace scoping with the provided context, which will scope the informers produced by the downstream informer factories.

func WithResourceVersion 

func WithResourceVersion(ctx context.Context, resourceVersion string) context.Context

WithResourceVersion associates a resource version with the context.

Types

type ClientFetcher 

type ClientFetcher func(context.Context) interface{}

ClientFetcher holds the type of a callback that returns a particular client type from a context.

type ClientInjector 

type ClientInjector func(context.Context, *rest.Config) context.Context

ClientInjector holds the type of a callback that attaches a particular client type to a context.

type ControllerConstructor 

type ControllerConstructor func(context.Context, configmap.Watcher) *controller.Impl

type DuckFactoryInjector 

type DuckFactoryInjector func(context.Context) context.Context

DuckFactoryInjector holds the type of a callback that attaches a particular duck-type informer factory to a context.

type FilteredInformersInjector 

type FilteredInformersInjector func(context.Context) (context.Context, []controller.Informer)

FilteredInformersInjector holds the type of a callback that attaches a set of particular filtered informers type to a context.

type InformerFactoryInjector 

type InformerFactoryInjector func(context.Context) context.Context

InformerFactoryInjector holds the type of a callback that attaches a particular factory type to a context.

type InformerInjector 

type InformerInjector func(context.Context) (context.Context, controller.Informer)

InformerInjector holds the type of a callback that attaches a particular informer type to a context.

type Interface 

type Interface interface {
	// RegisterClient registers a new injector callback for associating
	// a new client with a context.
	RegisterClient(ClientInjector)

	// GetClients fetches all of the registered client injectors.
	GetClients() []ClientInjector

	// RegisterClientFetcher registers a new callback that fetches a client from
	// a given context.
	RegisterClientFetcher(ClientFetcher)

	// FetchAllClients returns all known clients from the given context.
	FetchAllClients(context.Context) []interface{}

	// RegisterInformerFactory registers a new injector callback for associating
	// a new informer factory with a context.
	RegisterInformerFactory(InformerFactoryInjector)

	// GetInformerFactories fetches all of the registered informer factory injectors.
	GetInformerFactories() []InformerFactoryInjector

	// RegisterDuck registers a new duck.InformerFactory for a particular type.
	RegisterDuck(ii DuckFactoryInjector)

	// GetDucks accesses the set of registered ducks.
	GetDucks() []DuckFactoryInjector

	// RegisterInformer registers a new injector callback for associating
	// a new informer with a context.
	RegisterInformer(InformerInjector)

	// RegisterFilteredInformers registers a new filtered informer injector callback for associating
	// a new set of informers with a context.
	RegisterFilteredInformers(FilteredInformersInjector)

	// GetInformers fetches all of the registered informer injectors.
	GetInformers() []InformerInjector

	// GetFilteredInformers fetches all of the registered filtered informer injectors.
	GetFilteredInformers() []FilteredInformersInjector

	// SetupInformers runs all of the injectors against a context, starting with
	// the clients and the given rest.Config.  The resulting context is returned
	// along with a list of the .Informer() for each of the injected informers,
	// which is suitable for passing to controller.StartInformers().
	// This does not setup or start any controllers.
	SetupInformers(context.Context, *rest.Config) (context.Context, []controller.Informer)
}

Interface is the interface for interacting with injection implementations, such as our Default and Fake below. 

var (

	// Default is the injection interface with which informers should register
	// to make themselves available to the controller process when reconcilers
	// are being run for real.
	Default Interface = &impl{}

	// Fake is the injection interface with which informers should register
	// to make themselves available to the controller process when it is being
	// unit tested.
	Fake Interface = &impl{}
)

type NamedControllerConstructor 

type NamedControllerConstructor struct {
	// Name is the name associated with the controller returned by ControllerConstructor.
	Name string
	// ControllerConstructor is a constructor for a controller.
	ControllerConstructor ControllerConstructor
}

NamedControllerConstructor is a ControllerConstructor with an associated name.

Source Files

View all Source files

Directories

Path Synopsis
clients
dynamicclient
dynamicclient/fake
namespacedkube/informers/core/v1/configmap
namespacedkube/informers/core/v1/configmap/fake
namespacedkube/informers/core/v1/secret
namespacedkube/informers/core/v1/secret/fake
namespacedkube/informers/factory
namespacedkube/informers/factory/fake

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.