✨ clean up builder package and UX

- Rename Builder functions
- Encourage providing the manager to the Builder factory
- Deprecate discouraged functions
- Add alias.go with short cuts for common functions to reduce import line bloat
- Fix issue with GetConfigOrDie not exiting
- Update examples
- Add example at package root

alias.go

@@ -0,0 +1,135 @@
+/*
+Copyright 2018 The Kubernetes 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.
+*/
+
+// Package controllerruntime alias' common functions and types to improve discoverability and reduce
+// the number of imports for simple Controllers.
+package controllerruntime
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/builder"
+	"sigs.k8s.io/controller-runtime/pkg/client/config"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+	"sigs.k8s.io/controller-runtime/pkg/manager"
+	"sigs.k8s.io/controller-runtime/pkg/reconcile"
+	"sigs.k8s.io/controller-runtime/pkg/runtime/log"
+	"sigs.k8s.io/controller-runtime/pkg/runtime/scheme"
+	"sigs.k8s.io/controller-runtime/pkg/runtime/signals"
+)
+
+// Builder builds an Application ControllerManagedBy (e.g. Operator) and returns a manager.Manager to start it.
+type Builder = builder.Builder
+
+// Request contains the information necessary to reconcile a Kubernetes object.  This includes the
+// information to uniquely identify the object - its Name and Namespace.  It does NOT contain information about
+// any specific Event or the object contents itself.
+type Request = reconcile.Request
+
+// Result contains the result of a Reconciler invocation.
+type Result = reconcile.Result
+
+// Manager initializes shared dependencies such as Caches and Clients, and provides them to Runnables.
+// A Manager is required to create Controllers.
+type Manager = manager.Manager
+
+// Options are the arguments for creating a new Manager
+type Options = manager.Options
+
+// Builder builds a new Scheme for mapping go types to Kubernetes GroupVersionKinds.
+type SchemeBuilder = scheme.Builder
+
+// GroupVersion contains the "group" and the "version", which uniquely identifies the API.
+type GroupVersion = schema.GroupVersion
+
+// GroupResource specifies a Group and a Resource, but does not force a version.  This is useful for identifying
+// concepts during lookup stages without having partially valid types
+type GroupResource = schema.GroupResource
+
+// TypeMeta describes an individual object in an API response or request
+// with strings representing the type of the object and its API schema version.
+// Structures that are versioned or persisted should inline TypeMeta.
+//
+// +k8s:deepcopy-gen=false
+type TypeMeta = metav1.TypeMeta
+
+// ObjectMeta is metadata that all persisted resources must have, which includes all objects
+// users must create.
+type ObjectMeta = metav1.ObjectMeta
+
+var (
+	// GetConfigOrDie creates a *rest.Config for talking to a Kubernetes apiserver.
+	// If --kubeconfig is set, will use the kubeconfig file at that location.  Otherwise will assume running
+	// in cluster and use the cluster provided kubeconfig.
+	//
+	// Will log an error and exit if there is an error creating the rest.Config.
+	GetConfigOrDie = config.GetConfigOrDie
+
+	// GetConfig creates a *rest.Config for talking to a Kubernetes apiserver.
+	// If --kubeconfig is set, will use the kubeconfig file at that location.  Otherwise will assume running
+	// in cluster and use the cluster provided kubeconfig.
+	//
+	// Config precedence
+	//
+	// * --kubeconfig flag pointing at a file
+	//
+	// * KUBECONFIG environment variable pointing at a file
+	//
+	// * In-cluster config if running in cluster
+	//
+	// * $HOME/.kube/config if exists
+	GetConfig = config.GetConfig
+
+	// NewControllerManagedBy returns a new controller builder that will be started by the provided Manager
+	NewControllerManagedBy = builder.ControllerManagedBy
+
+	// NewManager returns a new Manager for creating Controllers.
+	NewManager = manager.New
+
+	// CreateOrUpdate creates or updates the given object obj in the Kubernetes
+	// cluster. The object's desired state should be reconciled with the existing
+	// state using the passed in ReconcileFn. obj must be a struct pointer so that
+	// obj can be updated with the content returned by the Server.
+	//
+	// It returns the executed operation and an error.
+	CreateOrUpdate = controllerutil.CreateOrUpdate
+
+	// SetControllerReference sets owner as a Controller OwnerReference on owned.
+	// This is used for garbage collection of the owned object and for
+	// reconciling the owner object on changes to owned (with a Watch + EnqueueRequestForOwner).
+	// Since only one OwnerReference can be a controller, it returns an error if
+	// there is another OwnerReference with Controller flag set.
+	SetControllerReference = controllerutil.SetControllerReference
+
+	// SetupSignalHandler registered for SIGTERM and SIGINT. A stop channel is returned
+	// which is closed on one of these signals. If a second signal is caught, the program
+	// is terminated with exit code 1.
+	SetupSignalHandler = signals.SetupSignalHandler
+
+	// Log is the base logger used by controller-runtime.  It delegates
+	// to another logr.Logger.  You *must* call SetLogger to
+	// get any actual logging.
+	Log = log.Log
+
+	// SetLogger sets a concrete logging implementation for all deferred Loggers.
+	SetLogger = log.SetLogger
+
+	// ZapLogger is a Logger implementation.
+	// If development is true, a Zap development config will be used
+	// (stacktraces on warnings, no sampling), otherwise a Zap production
+	// config will be used (stacktraces on errors, sampling).
+	ZapLogger = log.ZapLogger
+)

example_test.go

@@ -0,0 +1,97 @@
+/*
+Copyright 2018 The Kubernetes 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.
+*/
+
+package controllerruntime_test
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	controllers "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// This example creates a simple application Controller that is configured for ReplicaSets and Pods.
+//
+// * Create a new application for ReplicaSets that manages Pods owned by the ReplicaSet and calls into
+// ReplicaSetReconciler.
+//
+// * Start the application.
+// TODO(pwittrock): Update this example when we have better dependency injection support
+func Example() {
+	var log = controllers.Log.WithName("builder-examples")
+
+	manager, err := controllers.NewManager(controllers.GetConfigOrDie(), controllers.Options{})
+	if err != nil {
+		log.Error(err, "could not create manager")
+		os.Exit(1)
+	}
+
+	err = controllers.
+		NewControllerManagedBy(manager). // Create the Controller
+		For(&appsv1.ReplicaSet{}).       // ReplicaSet is the Application API
+		Owns(&corev1.Pod{}).             // ReplicaSet owns Pods created by it
+		Complete(&ReplicaSetReconciler{Client: manager.GetClient()})
+	if err != nil {
+		log.Error(err, "could not create controller")
+		os.Exit(1)
+	}
+
+	if err := manager.Start(controllers.SetupSignalHandler()); err != nil {
+		log.Error(err, "could not start manager")
+		os.Exit(1)
+	}
+}
+
+// ReplicaSetReconciler is a simple Controller example implementation.
+type ReplicaSetReconciler struct {
+	client.Client
+}
+
+// Implement the business logic:
+// This function will be called when there is a change to a ReplicaSet or a Pod with an OwnerReference
+// to a ReplicaSet.
+//
+// * Read the ReplicaSet
+// * Read the Pods
+// * Set a Label on the ReplicaSet with the Pod count
+func (a *ReplicaSetReconciler) Reconcile(req controllers.Request) (controllers.Result, error) {
+	// Read the ReplicaSet
+	rs := &appsv1.ReplicaSet{}
+	err := a.Get(context.TODO(), req.NamespacedName, rs)
+	if err != nil {
+		return controllers.Result{}, err
+	}
+
+	// List the Pods matching the PodTemplate Labels
+	pods := &corev1.PodList{}
+	err = a.List(context.TODO(), client.InNamespace(req.Namespace).MatchingLabels(rs.Spec.Template.Labels), pods)
+	if err != nil {
+		return controllers.Result{}, err
+	}
+
+	// Update the ReplicaSet
+	rs.Labels["pod-count"] = fmt.Sprintf("%v", len(pods.Items))
+	err = a.Update(context.TODO(), rs)
+	if err != nil {
+		return controllers.Result{}, err
+	}
+
+	return controllers.Result{}, nil
+}