clientgo/examples: add ToC for examples

hack/.linted_packages

@@ -384,8 +384,8 @@ staging/src/k8s.io/apiserver/plugin/pkg/authenticator/password/allow
 staging/src/k8s.io/apiserver/plugin/pkg/authenticator/request/basicauth
 staging/src/k8s.io/client-go/discovery
 staging/src/k8s.io/client-go/examples/create-update-delete-deployment
-staging/src/k8s.io/client-go/examples/in-cluster
-staging/src/k8s.io/client-go/examples/out-of-cluster
+staging/src/k8s.io/client-go/examples/in-cluster-client-configuration
+staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration
 staging/src/k8s.io/client-go/examples/third-party-resources-deprecated
 staging/src/k8s.io/client-go/informers
 staging/src/k8s.io/client-go/informers/admissionregistration

hack/verify-staging-imports.sh

@@ -80,7 +80,7 @@ if grep -rq '// import "k8s.io/kubernetes/' 'staging/'; then
 	exit 1
 fi
 
-for EXAMPLE in vendor/k8s.io/client-go/examples/{in-cluster,out-of-cluster,third-party-resources-deprecated} vendor/k8s.io/apiextensions-apiserver/examples ; do
+for EXAMPLE in vendor/k8s.io/client-go/examples/{in-cluster-client-configuration,out-of-cluster-client-configuration,third-party-resources-deprecated} vendor/k8s.io/apiextensions-apiserver/examples ; do
 	test -d "${EXAMPLE}" # make sure example is still there
 	if go list -f '{{ join .Deps "\n" }}' "./${EXAMPLE}/..." | sort | uniq | grep -q k8s.io/client-go/plugin; then
 		echo "${EXAMPLE} imports client-go plugins by default, but shouldn't."

staging/src/k8s.io/client-go/examples/README.md

@@ -0,0 +1,28 @@
+# client-go Examples
+
+This directory contains examples that cover various use cases and functionality
+for client-go.
+
+### Configuration
+
+- [**Authenticate in cluster**](./in-cluster-client-configuration): Configure a
+  client while running inside the Kubernetes cluster.
+- [**Authenticate out of cluster**](./out-of-cluster-client-configuration):
+  Configure a client to access a Kubernetes cluster from outside.
+
+### Basics
+
+- [**Managing resources with API**](./create-update-delete-deployment): Create,
+  get, update, delete a Deployment resource.
+
+### Advanced Concepts
+
+- [**Work queues**](./workqueue): Create a hotloop-free controller with the
+  rate-limited workqueue and the [informer framework][informer].
+- [**Third-party resources (deprecated)**](./third-party-resources-deprecated):
+  Register a custom resource type with the API, create/update/query this custom
+  type, and write a controller drives the cluster state based on the changes to
+  the custom resources.
+
+[informer]: https://godoc.org/k8s.io/client-go/tools/cache#NewInformer
+

staging/src/k8s.io/client-go/examples/in-cluster/BUILD → staging/src/k8s.io/client-go/examples/in-cluster-client-configuration/BUILD

@@ -9,7 +9,7 @@ load(
 )
 
 go_binary(
-    name = "in-cluster",
+    name = "in-cluster-client-configuration",
     library = ":go_default_library",
     tags = ["automanaged"],
 )

staging/src/k8s.io/client-go/examples/in-cluster/README.md → staging/src/k8s.io/client-go/examples/in-cluster-client-configuration/README.md

@@ -1,7 +1,7 @@
 # Authenticating inside the cluster
 
-This example shows you how you can write an application that authenticates to
-the Kubernetes API while it is running on a Kubernetes cluster.
+This example shows you how to configure a client with client-go to authenticate
+to the Kubernetes API from an application running inside the Kubernetes cluster.
 
 client-go uses the [Service Account token][sa] mounted inside the Pod at the
 `/var/run/secrets/kubernetes.io/serviceaccount` path when the
@@ -11,7 +11,7 @@ client-go uses the [Service Account token][sa] mounted inside the Pod at the
 
 First compile the application for Linux:
 
-    cd in-cluster
+    cd in-cluster-client-configuration
     GOOS=linux go build -o ./app .
 
 Then package it to a docker image using the provided Dockerfile to run it on

staging/src/k8s.io/client-go/examples/out-of-cluster/BUILD → staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/BUILD

@@ -9,7 +9,7 @@ load(
 )
 
 go_binary(
-    name = "out-of-cluster",
+    name = "out-of-cluster-client-configuration",
     library = ":go_default_library",
     tags = ["automanaged"],
 )

staging/src/k8s.io/client-go/examples/out-of-cluster/README.md → staging/src/k8s.io/client-go/examples/out-of-cluster-client-configuration/README.md

@@ -1,7 +1,8 @@
 # Authenticating outside the cluster
 
-This example shows you how to authenticate to the Kubernetes API from an
-application running outside the Kubernetes cluster with client-go.
+This example shows you how to configure a client with client-go to authenticate
+to the Kubernetes API from an application running outside the Kubernetes
+cluster.
 
 You can use your kubeconfig file that contains the context information
 of your cluster to initialize a client. The kubeconfig file is also used
@@ -14,7 +15,7 @@ Make sure your `kubectl` is configured and pointed to a cluster. Run
 
 Run this application with:
 
-    cd out-of-cluster
+    cd out-of-cluster-client-configuration
     go build -o app .
     ./app