add client-go examples;

update README

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

@@ -18,7 +18,17 @@ client-go has the same release cycle as the Kubernetes main repository. For exam
 
 ### How to get it
 
-You can `go get` a release of client-go, e.g., `go get k8s.io/client-go/1.4/...` for the whole thing or `go get k8s.io/client-go/1.4/kubernetes` if you just need the clientset.
+You can `go get` to get a release of client-go, e.g., `go get k8s.io/client-go/1.4/...` or `go get k8s.io/client-go/1.4/kubernetes`.
+
+### How to use it
+
+If your application runs in a Pod in the cluster, please refer to the in-cluster [example](examples/in-cluster/main.go), otherwise please refer to the out-of-cluster [example](examples/out-of-cluster/main.go).
+
+### Dependency management
+
+If your application depends on a package that client-go depends on, and you let the Go compiler find the dependency in `GOPATH`, you will end up with duplicated dependencies: one copy from the `GOPATH`, and one from the vendor folder of client-go. This will cause unexpected runtime error like flag redefinition, since the go compiler ends up importing both packages separately, even if they are exactly the same thing. If this happens, you can either
+* run `godep restore` ([godep](https://github.com/tools/godep)) in the client-go/1.4 folder, then remove the vendor folder of client-go. Then the packages in your GOPATH will be the only copy
+* or run `godep save` in your application folder to flatten all dependencies.
 
 ### Reporting bugs
 

staging/src/k8s.io/client-go/examples/in-cluster/main.go

@@ -0,0 +1,47 @@
+/*
+Copyright 2016 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 main
+
+import (
+	"fmt"
+	"time"
+
+	"k8s.io/client-go/1.4/kubernetes"
+	"k8s.io/client-go/1.4/pkg/api"
+	"k8s.io/client-go/1.4/rest"
+)
+
+func main() {
+	// creates the in-cluster config
+	config, err := rest.InClusterConfig()
+	if err != nil {
+		panic(err.Error())
+	}
+	// creates the clientset
+	clientset, err := kubernetes.NewForConfig(config)
+	if err != nil {
+		panic(err.Error())
+	}
+	for {
+		pods, err := clientset.Core().Pods("").List(api.ListOptions{})
+		if err != nil {
+			panic(err.Error())
+		}
+		fmt.Printf("There are %d pods in the cluster\n", len(pods.Items))
+		time.Sleep(10 * time.Second)
+	}
+}

staging/src/k8s.io/client-go/examples/out-of-cluster/main.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2016 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 main
+
+import (
+	"flag"
+	"fmt"
+	"time"
+
+	"k8s.io/client-go/1.4/kubernetes"
+	"k8s.io/client-go/1.4/pkg/api"
+	"k8s.io/client-go/1.4/tools/clientcmd"
+)
+
+var (
+	kubeconfig = flag.String("kubeconfig", "./config", "absolute path to the kubeconfig file")
+)
+
+func main() {
+	flag.Parse()
+	// uses the current context in kubeconfig
+	config, err := clientcmd.BuildConfigFromFlags("", *kubeconfig)
+	if err != nil {
+		panic(err.Error())
+	}
+	// creates the clientset
+	clientset, err := kubernetes.NewForConfig(config)
+	if err != nil {
+		panic(err.Error())
+	}
+	for {
+		pods, err := clientset.Core().Pods("").List(api.ListOptions{})
+		if err != nil {
+			panic(err.Error())
+		}
+		fmt.Printf("There are %d pods in the cluster\n", len(pods.Items))
+		time.Sleep(10 * time.Second)
+	}
+}