Better docs for pkg/client

This lays out package docs for the client package, clarifies that
client.New creates a new direct-to-API client, and adds an example
for indexers.

Author: DirectXMan12

pkg/client/client.go

@@ -41,6 +41,15 @@ type Options struct {
 }
 
 // New returns a new Client using the provided config and Options.
+// The returned client reads *and* writes directly from the server
+// (it doesn't use object caches).  It understands how to work with
+// normal types (both custom resources and aggregated/built-in resources),
+// as well as unstructured types.
+//
+// In the case of normal types, the scheme will be used to look up the
+// corresponding group, version, and kind for the given type.  In the
+// case of unstrctured types, the group, version, and kind will be extracted
+// from the corresponding fields on the object.
 func New(config *rest.Config, options Options) (Client, error) {
 	if config == nil {
 		return nil, fmt.Errorf("must provide non-nil rest.Config to client.New")

pkg/client/doc.go

@@ -0,0 +1,49 @@
+/*
+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 client contains functionality for interacting with Kubernetes API
+// servers.
+//
+// Clients
+//
+// Clients are split into two interfaces -- Readers and Writers.   Readers
+// get and list, while writers create, update, and delete.
+//
+// The New function can be used to create a new client that talks directly
+// to the API server.
+//
+// A common pattern in Kubernetes to read from a cache and write to the API
+// server.  This pattern is covered by the DelegatingClient type, which can
+// be used to have a client whose Reader is different from the Writer.
+//
+// Options
+//
+// Many client operations in Kubernetes support options.  These options are
+// represented as variadic arguments at the end of a given method call.
+// For instance, to use a label selector on list, you can call
+//  err := someReader.List(context.Background(), &podList, client.MatchingLabels(someLabelMap))
+//
+// Indexing
+//
+// Indexes may be added to caches using a FieldIndexer.  This allows you to easily
+// and efficiently look up objects with certain properties.  You can then make
+// use of the index by specifying a field selector on calls to List on the Reader
+// corresponding to the given Cache.
+//
+// For instance, a Secret controller might have an index on the
+// `.spec.volumes.secret.secretName` field in Pod objects, so that it could
+// easily look up all pods that reference a given secret.
+package client

pkg/client/example_test.go

@@ -25,12 +25,14 @@ import (
 	"k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/apimachinery/pkg/runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 	"sigs.k8s.io/controller-runtime/pkg/client/config"
 )
 
 var (
 	c client.Client
+	someIndexer client.FieldIndexer
 )
 
 func ExampleNew() {
@@ -196,3 +198,24 @@ func ExampleClient_delete() {
 	})
 	_ = c.Delete(context.Background(), u)
 }
+
+// This example shows how to set up and consume a field select over a pod's volumes' secretName field.
+func ExampleFieldIndexer_secretName() {
+	// someIndexer is a FieldIndexer over a Cache
+	_ = someIndexer.IndexField(&corev1.Pod{}, "spec.volumes.secret.secretName", func(o runtime.Object) []string {
+		var res []string
+		for _, vol := range o.(*corev1.Pod).Spec.Volumes {
+			if vol.Secret == nil {
+				continue
+			}
+			// just return the raw field value -- the indexer will take care of dealing with namespaces for us
+			res = append(res, vol.Secret.SecretName)
+		}
+		return res
+	})
+
+	// elsewhere (e.g. in your reconciler)
+	mySecretName := "someSecret"  // derived from the reconcile.Request, for instance
+	var podsWithSecrets corev1.PodList
+	_ = c.List(context.Background(), &podsWithSecrets, client.MatchingField("spec.volumes.secret.secretName", mySecretName))
+}

pkg/client/interfaces.go

@@ -100,6 +100,8 @@ type FieldIndexer interface {
 	// compatibility with the Kubernetes API server, only return one key, and only use
 	// fields that the API server supports.  Otherwise, you can return multiple keys,
 	// and "equality" in the field selector means that at least one key matches the value.
+	// The FieldIndexer will automatically take care of indexing over namespace
+	// and supporting efficient all-namespace queries.
 	IndexField(obj runtime.Object, field string, extractValue IndexerFunc) error
 }