Skip to content

Commit

Permalink
Add more examples in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
aerfio committed Sep 18, 2023
1 parent f1c940e commit 77fdfc7
Show file tree
Hide file tree
Showing 4 changed files with 103 additions and 8 deletions.
84 changes: 82 additions & 2 deletions example_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,14 @@ import (

appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/types"

ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/handler"
"sigs.k8s.io/controller-runtime/pkg/reconcile"

// since we invoke tests with -ginkgo.junit-report we need to import ginkgo.
_ "github.com/onsi/ginkgo/v2"
Expand All @@ -38,7 +44,7 @@ import (
//
// * Start the application.
func Example() {
var log = ctrl.Log.WithName("builder-examples")
log := ctrl.Log.WithName("builder-examples")

manager, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{})
if err != nil {
Expand All @@ -62,6 +68,80 @@ func Example() {
}
}

type ExampleCRDWithConfigMapRef struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
ConfigMapRef corev1.LocalObjectReference `json:"configMapRef"`
}

// DeepCopyObject implements client.Object.
func (*ExampleCRDWithConfigMapRef) DeepCopyObject() runtime.Object {
panic("unimplemented")
}

type ExampleCRDWithConfigMapRefList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []ExampleCRDWithConfigMapRef `json:"items"`
}

// DeepCopyObject implements client.ObjectList.
func (*ExampleCRDWithConfigMapRefList) DeepCopyObject() runtime.Object {
panic("unimplemented")
}

// This example creates a simple application Controller that is configured for ExampleCRDWithConfigMapRef CRD.
// Any change in the configMap referenced in this Custom Resource will cause the re-reconcile of the parent ExampleCRDWithConfigMapRef
// due to the implementation of the .Watches method of "sigs.k8s.io/controller-runtime/pkg/builder".Builder.
func Example_watches() {
log := ctrl.Log.WithName("builder-examples")

manager, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{})
if err != nil {
log.Error(err, "could not create manager")
os.Exit(1)
}

err = ctrl.
NewControllerManagedBy(manager).
For(&ExampleCRDWithConfigMapRef{}).
Watches(&corev1.ConfigMap{}, handler.EnqueueRequestsFromMapFunc(func(ctx context.Context, cm client.Object) []ctrl.Request {
// map a change to referenced configMap to ExampleCRDWithConfigMapRef, which causes its re-reconcile
crList := &ExampleCRDWithConfigMapRefList{}
if err := manager.GetClient().List(ctx, crList); err != nil {
manager.GetLogger().Error(err, "while listing ExampleCRDWithConfigMapRefs")
return nil
}

reqs := make([]ctrl.Request, 0, len(crList.Items))
for _, item := range crList.Items {
if item.ConfigMapRef.Name == cm.GetName() {
reqs = append(reqs, ctrl.Request{
NamespacedName: types.NamespacedName{
Namespace: item.GetNamespace(),
Name: item.GetName(),
},
})
}
}

return reqs
})).
Complete(reconcile.Func(func(ctx context.Context, r reconcile.Request) (reconcile.Result, error) {
// Your business logic to implement the API by creating, updating, deleting objects goes here.
return reconcile.Result{}, nil
}))
if err != nil {
log.Error(err, "could not create controller")
os.Exit(1)
}

if err := manager.Start(ctrl.SetupSignalHandler()); err != nil {
log.Error(err, "could not start manager")
os.Exit(1)
}
}

// This example creates a simple application Controller that is configured for ReplicaSets and Pods.
// This application controller will be running leader election with the provided configuration in the manager options.
// If leader election configuration is not provided, controller runs leader election with default values.
Expand All @@ -75,7 +155,7 @@ func Example() {
//
// * Start the application.
func Example_updateLeaderElectionDurations() {
var log = ctrl.Log.WithName("builder-examples")
log := ctrl.Log.WithName("builder-examples")
leaseDuration := 100 * time.Second
renewDeadline := 80 * time.Second
retryPeriod := 20 * time.Second
Expand Down
4 changes: 2 additions & 2 deletions pkg/builder/example_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ import (
func ExampleBuilder_metadata_only() {
logf.SetLogger(zap.New())

var log = logf.Log.WithName("builder-examples")
log := logf.Log.WithName("builder-examples")

mgr, err := manager.New(config.GetConfigOrDie(), manager.Options{})
if err != nil {
Expand Down Expand Up @@ -95,7 +95,7 @@ func ExampleBuilder_metadata_only() {
func ExampleBuilder() {
logf.SetLogger(zap.New())

var log = logf.Log.WithName("builder-examples")
log := logf.Log.WithName("builder-examples")

mgr, err := manager.New(config.GetConfigOrDie(), manager.Options{})
if err != nil {
Expand Down
17 changes: 15 additions & 2 deletions pkg/client/example_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,14 @@ import (
corev1 "k8s.io/api/core/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/runtime/schema"
"k8s.io/apimachinery/pkg/types"
corev1ac "k8s.io/client-go/applyconfigurations/core/v1"

"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/client/config"
"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
)

var (
Expand Down Expand Up @@ -159,7 +162,7 @@ func ExampleClient_update() {
Namespace: "namespace",
Name: "name",
}, pod)
pod.SetFinalizers(append(pod.GetFinalizers(), "new-finalizer"))
controllerutil.AddFinalizer(pod, "new-finalizer")
_ = c.Update(context.Background(), pod)

// Using a unstructured object.
Expand All @@ -173,7 +176,7 @@ func ExampleClient_update() {
Namespace: "namespace",
Name: "name",
}, u)
u.SetFinalizers(append(u.GetFinalizers(), "new-finalizer"))
controllerutil.AddFinalizer(u, "new-finalizer")
_ = c.Update(context.Background(), u)
}

Expand All @@ -188,6 +191,16 @@ func ExampleClient_patch() {
}, client.RawPatch(types.StrategicMergePatchType, patch))
}

// This example shows how to use the client with unstructured objects to create/patch objects using Server Side Apply,
func ExampleClient_apply() {
// Using a typed object.
configMap := corev1ac.ConfigMap("name", "namespace").WithData(map[string]string{"key": "value"})
// c is a created client.
u := &unstructured.Unstructured{}
u.Object, _ = runtime.DefaultUnstructuredConverter.ToUnstructured(configMap)
_ = c.Patch(context.Background(), u, client.Apply, client.ForceOwnership, client.FieldOwner("field-owner"))
}

// This example shows how to use the client with typed and unstructured objects to patch objects' status.
func ExampleClient_patchStatus() {
u := &unstructured.Unstructured{}
Expand Down
6 changes: 4 additions & 2 deletions pkg/handler/example_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,10 @@ import (
"sigs.k8s.io/controller-runtime/pkg/source"
)

var mgr manager.Manager
var c controller.Controller
var (
mgr manager.Manager
c controller.Controller
)

// This example watches Pods and enqueues Requests with the Name and Namespace of the Pod from
// the Event (i.e. change caused by a Create, Update, Delete).
Expand Down

0 comments on commit 77fdfc7

Please sign in to comment.