typed client: add tags and script for code generation

hack/.golint_failures

@@ -454,9 +454,14 @@ staging/src/k8s.io/api/scheduling/v1alpha1
 staging/src/k8s.io/api/settings/v1alpha1
 staging/src/k8s.io/api/storage/v1
 staging/src/k8s.io/api/storage/v1beta1
-staging/src/k8s.io/apiextensions-apiserver/examples/client-go/apis/cr/v1
-staging/src/k8s.io/apiextensions-apiserver/examples/client-go/client
-staging/src/k8s.io/apiextensions-apiserver/examples/client-go/controller
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/clientset/versioned
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/clientset/versioned/fake
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/clientset/versioned/scheme
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/clientset/versioned/typed/cr/v1
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/clientset/versioned/typed/cr/v1/fake
+staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/client/informers/externalversions/internalinterfaces
 staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions
 staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1
 staging/src/k8s.io/apiextensions-apiserver/pkg/apiserver

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

@@ -2,18 +2,29 @@
 
 **Note:** CustomResourceDefinition is the successor of the deprecated ThirdPartyResource.
 
-This particular example demonstrates how to perform basic operations such as:
+This particular example demonstrates how to generate a client for CustomResources using [`k8s.io/code-generator`](https://github.com/kubernetes/code-generator). The clientset can
+be generated using the `./hack/update-codegen.sh` script.
 
-* How to register a new custom resource (custom resource type) using a CustomResourceDefinition
-* How to create/get/list instances of your new resource type (update/delete/etc work as well but are not demonstrated)
-* How to setup a controller on resource handling create/update/delete events
+The `update-codegen` script will automatically generate the following files and
+directories:
 
-## Running
+* `pkg/apis/cr/v1/zz_generated.deepcopy.go`
+* `pkg/client/`
 
-```
-# assumes you have a working kubeconfig, not required if operating in-cluster
-go run *.go -kubeconfig=$HOME/.kube/config
-```
+The following code-generators are used:
+
+* `deepcopy-gen` - creates a method `func (t* T) DeepCopy() *T` for each type T
+* `client-gen` - creates typed clientsets for CustomResource APIGroups
+* `informer-gen` - creates informers for CustomResources which offer an event based
+interface to react on changes of CustomResources on the server
+* `lister-gen` - creates listers for CustomResources which offer a read-only caching layer for GET and LIST requests.
+
+Changes should not be made to these files manually, and when creating your own
+controller based off of this implementation you should not copy these files and
+instead run the `update-codegen` script to generate your own.
+
+Please see [`k8s.io/sample-controller`](https://github.com/kubernetes/sample-controller) for an example
+controller for CustomResources using the generated client.
 
 ## Use Cases
 
@@ -44,9 +55,3 @@ type User struct {
 	Password string `json:"password"`
 }
 ```
-
-## Cleanup
-
-Successfully running this program will clean the created artifacts. If you terminate the program without completing, you can clean up the created CustomResourceDefinition with:
-
-    kubectl delete crd examples.cr.client-go.k8s.io

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/hack/update-codegen.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# Copyright 2017 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.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+SCRIPT_ROOT=$(dirname ${BASH_SOURCE})/..
+CODEGEN_PKG=${CODEGEN_PKG:-$(cd ${SCRIPT_ROOT}; ls -d -1 ./vendor/k8s.io/code-generator 2>/dev/null || echo ../code-generator)}
+
+# generate the code with:
+# --output-base    because this script should also be able to run inside the vendor dir of
+#                  k8s.io/kubernetes. The output-base is needed for the generators to output into the vendor dir
+#                  instead of the $GOPATH directly. For normal projects this can be dropped.
+${CODEGEN_PKG}/generate-groups.sh all \
+  k8s.io/apiextensions-apiserver/examples/client-go/pkg/client k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis \
+  cr:v1 \
+  --output-base "$(dirname ${BASH_SOURCE})/../../../../.."
+
+# To use your own boilerplate text append:
+#   --go-header-file ${SCRIPT_ROOT}/hack/custom-boilerplate.go.txt

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/hack/verify-codegen.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Copyright 2017 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.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..
+
+DIFFROOT="${SCRIPT_ROOT}/pkg"
+TMP_DIFFROOT="${SCRIPT_ROOT}/_tmp/pkg"
+_tmp="${SCRIPT_ROOT}/_tmp"
+
+cleanup() {
+  rm -rf "${_tmp}"
+}
+trap "cleanup" EXIT SIGINT
+
+cleanup
+
+mkdir -p "${TMP_DIFFROOT}"
+cp -a "${DIFFROOT}"/* "${TMP_DIFFROOT}"
+
+"${SCRIPT_ROOT}/hack/update-codegen.sh"
+echo "diffing ${DIFFROOT} against freshly generated codegen"
+ret=0
+diff -Naupr "${DIFFROOT}" "${TMP_DIFFROOT}" || ret=$?
+cp -a "${TMP_DIFFROOT}"/* "${DIFFROOT}"
+if [[ $ret -eq 0 ]]
+then
+  echo "${DIFFROOT} up to date."
+else
+  echo "${DIFFROOT} is out of date. Please run hack/update-codegen.sh"
+  exit 1
+fi

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/BUILD

@@ -0,0 +1,25 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "go_default_library",
+    srcs = ["register.go"],
+    importpath = "k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr",
+    visibility = ["//visibility:public"],
+)
+
+filegroup(
+    name = "package-srcs",
+    srcs = glob(["**"]),
+    tags = ["automanaged"],
+    visibility = ["//visibility:private"],
+)
+
+filegroup(
+    name = "all-srcs",
+    srcs = [
+        ":package-srcs",
+        "//staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1:all-srcs",
+    ],
+    tags = ["automanaged"],
+    visibility = ["//visibility:public"],
+)

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/register.go

@@ -0,0 +1,21 @@
+/*
+Copyright 2017 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 cr
+
+const (
+	GroupName = "cr.example.apiextensions.k8s.io"
+)

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1/BUILD

@@ -0,0 +1,54 @@
+package(default_visibility = ["//visibility:public"])
+
+load(
+    "@io_bazel_rules_go//go:def.bzl",
+    "go_library",
+    "go_test",
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = ["roundtrip_test.go"],
+    importpath = "k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1",
+    library = ":go_default_library",
+    deps = [
+        "//vendor/github.com/google/gofuzz:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/api/testing/fuzzer:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/api/testing/roundtrip:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/apis/meta/fuzzer:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/apis/meta/v1:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/runtime:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/runtime/serializer:go_default_library",
+    ],
+)
+
+go_library(
+    name = "go_default_library",
+    srcs = [
+        "doc.go",
+        "register.go",
+        "types.go",
+        "zz_generated.deepcopy.go",
+    ],
+    importpath = "k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1",
+    deps = [
+        "//vendor/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/apis/meta/v1:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/conversion:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/runtime:go_default_library",
+        "//vendor/k8s.io/apimachinery/pkg/runtime/schema:go_default_library",
+    ],
+)
+
+filegroup(
+    name = "package-srcs",
+    srcs = glob(["**"]),
+    tags = ["automanaged"],
+    visibility = ["//visibility:private"],
+)
+
+filegroup(
+    name = "all-srcs",
+    srcs = [":package-srcs"],
+    tags = ["automanaged"],
+)

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1/doc.go

@@ -0,0 +1,21 @@
+/*
+Copyright 2017 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.
+*/
+
+// +k8s:deepcopy-gen=package,register
+
+// Package v1 is the v1 version of the API.
+// +groupName=cr.example.apiextensions.k8s.io
+package v1

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1/register.go

@@ -0,0 +1,51 @@
+/*
+Copyright 2017 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 v1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+
+	cr "k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr"
+)
+
+// SchemeGroupVersion is group version used to register these objects
+var SchemeGroupVersion = schema.GroupVersion{Group: cr.GroupName, Version: "v1"}
+
+// Kind takes an unqualified kind and returns back a Group qualified GroupKind
+func Kind(kind string) schema.GroupKind {
+	return SchemeGroupVersion.WithKind(kind).GroupKind()
+}
+
+// Resource takes an unqualified resource and returns a Group qualified GroupResource
+func Resource(resource string) schema.GroupResource {
+	return SchemeGroupVersion.WithResource(resource).GroupResource()
+}
+
+var (
+	SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
+	AddToScheme   = SchemeBuilder.AddToScheme
+)
+
+// Adds the list of known types to Scheme.
+func addKnownTypes(scheme *runtime.Scheme) error {
+	scheme.AddKnownTypes(SchemeGroupVersion,
+		&Example{},
+		&ExampleList{},
+	)
+	return nil
+}

staging/src/k8s.io/apiextensions-apiserver/examples/client-go/pkg/apis/cr/v1/types.go

@@ -0,0 +1,63 @@
+/*
+Copyright 2017 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 v1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// +genclient
+// +genclient:noStatus
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// Example is a specification for an Example resource
+type Example struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata"`
+
+	Spec   ExampleSpec   `json:"spec"`
+	Status ExampleStatus `json:"status,omitempty"`
+}
+
+// ExampleSpec is the spec for an Example resource
+type ExampleSpec struct {
+	Foo string `json:"foo"`
+	Bar bool   `json:"bar"`
+}
+
+// ExampleStatus is the status for an Example resource
+type ExampleStatus struct {
+	State   ExampleState `json:"state,omitempty"`
+	Message string       `json:"message,omitempty"`
+}
+
+type ExampleState string
+
+const (
+	ExampleStateCreated   ExampleState = "Created"
+	ExampleStateProcessed ExampleState = "Processed"
+)
+
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// ExampleList is a list of Example resources
+type ExampleList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata"`
+
+	Items []Example `json:"items"`
+}