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

+#!/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

+#!/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

+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

+/*
+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

+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

+/*
+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

+/*
+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

+/*
+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"`
+}

staging/src/k8s.io/apiextensions-apiserver/test/integration/client-go_test.go

-/*
-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 integration
-
-import (
-	"context"
-	"testing"
-
-	apiv1 "k8s.io/api/core/v1"
-	"k8s.io/apiextensions-apiserver/test/integration/testserver"
-	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-
-	examplecrv1 "k8s.io/apiextensions-apiserver/examples/client-go/apis/cr/v1"
-	exampleclient "k8s.io/apiextensions-apiserver/examples/client-go/client"
-	examplecontroller "k8s.io/apiextensions-apiserver/examples/client-go/controller"
-)
-
-func TestClientGoCustomResourceExample(t *testing.T) {
-	t.Logf("Creating apiextensions apiserver")
-	config, err := testserver.DefaultServerConfig()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	stopCh, apiExtensionClient, _, err := testserver.StartServer(config)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	defer close(stopCh)
-
-	t.Logf("Creating CustomResourceDefinition")
-	crd, err := exampleclient.CreateCustomResourceDefinition(apiExtensionClient)
-	if err != nil {
-		t.Fatalf("unexpected error creating the CustomResourceDefinition: %v", err)
-	}
-	defer apiExtensionClient.ApiextensionsV1beta1().CustomResourceDefinitions().Delete(crd.Name, nil)
-
-	exampleClient, exampleScheme, err := exampleclient.NewClient(config.GenericConfig.LoopbackClientConfig)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	t.Logf("Starting a controller on instances of custom resource %q", examplecrv1.ExampleResourcePlural)
-	controller := examplecontroller.ExampleController{
-		ExampleClient: exampleClient,
-		ExampleScheme: exampleScheme,
-	}
-
-	ctx, cancelFunc := context.WithCancel(context.Background())
-	defer cancelFunc()
-	go controller.Run(ctx)
-
-	// Create an instance of our custom resource
-	t.Logf("Creating custom resource instance")
-	example := &examplecrv1.Example{
-		ObjectMeta: metav1.ObjectMeta{
-			Name: "example1",
-		},
-		Spec: examplecrv1.ExampleSpec{
-			Foo: "hello",
-			Bar: true,
-		},
-		Status: examplecrv1.ExampleStatus{
-			State:   examplecrv1.ExampleStateCreated,
-			Message: "Created, not processed yet",
-		},
-	}
-	var result examplecrv1.Example
-	err = exampleClient.Post().
-		Resource(examplecrv1.ExampleResourcePlural).
-		Namespace(apiv1.NamespaceDefault).
-		Body(example).
-		Do().Into(&result)
-	if err != nil {
-		t.Fatalf("Failed to create an instance of the custom resource: %v", err)
-	}
-
-	t.Logf("Waiting instance to be processed by the controller")
-	if err := exampleclient.WaitForExampleInstanceProcessed(exampleClient, "example1"); err != nil {
-		t.Fatalf("Instance was not processed correctly: %v", err)
-	}
-	t.Logf("Instance is processed")
-}

staging/src/k8s.io/sample-controller/pkg/apis/samplecontroller/v1alpha1/register.go

@@ -17,7 +17,6 @@ limitations under the License.
 package v1alpha1
 
 import (
-	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/runtime/schema"
 
@@ -27,31 +26,26 @@ import (
 // SchemeGroupVersion is group version used to register these objects
 var SchemeGroupVersion = schema.GroupVersion{Group: samplecontroller.GroupName, Version: "v1alpha1"}
 
+// 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 (
-	// localSchemeBuilder and AddToScheme will stay in k8s.io/kubernetes.
-	SchemeBuilder      runtime.SchemeBuilder
-	localSchemeBuilder = &SchemeBuilder
-	AddToScheme        = localSchemeBuilder.AddToScheme
+	SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
+	AddToScheme   = SchemeBuilder.AddToScheme
 )
 
-func init() {
-	// We only register manually written functions here. The registration of the
-	// generated functions takes place in the generated files. The separation
-	// makes the code compile even when the generated files are missing.
-	localSchemeBuilder.Register(addKnownTypes)
-}
-
-// Adds the list of known types to api.Scheme.
+// Adds the list of known types to Scheme.
 func addKnownTypes(scheme *runtime.Scheme) error {
 	scheme.AddKnownTypes(SchemeGroupVersion,
 		&Foo{},
 		&FooList{},
 	)
-	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
 	return nil
 }

staging/src/k8s.io/sample-controller/pkg/apis/samplecontroller/v1alpha1/types.go

@@ -23,7 +23,6 @@ import (
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-// +resource:path=foo
 
 // Foo is a specification for a Foo resource
 type Foo struct {
@@ -46,7 +45,6 @@ type FooStatus struct {
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-// +resource:path=foos
 
 // FooList is a list of Foo resources
 type FooList struct {