Merge pull request #1354 from yue9944882/doc/kubectl

Doc: Kubectl Equivalence in Java

Author: k8s-ci-robot

docs/kubectl-equivalence-in-java.md

@@ -0,0 +1,248 @@
+#Kubectl Equivalence in Java
+
+__TL;DR__: Used to kubectl? Now our kubernetes Java client library has released a set of 
+helpful client utilities which has the similar input argument interface as the kubectl binary.
+Especially the developers who're already familiar with kubectl commands, after reading this 
+document, you will know how to build programs that interact with Kubernetes as easily as kubectl.
+
+
+### What is Java Kubectl
+
+The Java Kubectl is not only a more user-friendly wrapper for our direct HTTP kubernetes client,
+but also contains implementation of commonly-used kubectl advanced commands. All these kubectl 
+equivalences are accessible as a group of static helper functions under `io.kubernetes.client.extended.kubectl.Kubectl` 
+class. You can import them by adding the following dependency to your project:
+
+```xml
+<dependency>
+	<groupId>io.kubernetes</groupId>
+	<artifactId>client-java-extended</artifactId>
+	<version>${latest project version}</version>
+</dependency>
+```
+
+Now you're all set, invoke the kubectl commands as Java static functions wherever you like in 
+your project.
+
+#### (Optional) Setting a Global Client-Config
+
+Kubectl static helpers don't know its client-config (or kubeconfig if the name makes more sense to 
+you) unless you set it when your application starts. You can either specifies the client-config upon 
+invoking kubectl helpers or simply set a global config at the start of your application:
+
+```java
+Configuration.setDefaultApiClient(ClientBuilder.defaultClient());
+```
+
+This will create a client on either a client, or a container in Kubernetes.
+
+### Manifest of Supported Commands 
+
+
+#### Kubectl get
+
+You can either query a single resource or list multiple resources using the `Kubectl#get` helper depending
+on whether you're passing `name()` in the flow. Here is a few illustrative examples for querying pod 
+resources:
+
+```java
+// kubectl get -n default pod foo
+V1Pod pod = Kubectl.get(V1Pod.class)
+                .namespace("default")
+                .name("foo")
+                .execute();
+// kubectl get -n default pod
+List<V1Pod> pods = Kubectl.get(V1Pod.class)
+                .namespace("default")
+                .execute();
+// kubectl get pod --all-namespaces
+List<V1Pod> pods = Kubectl.get(V1Pod.class)
+                .execute();
+```
+
+#### Kubectl create
+
+Currently the `Kubectl#create` helper only accepts a desired instance of resource object, you need to do the 
+deserialization of a resource object or manually craft an instance of the resource.
+
+```java
+// kubectl create -f <file>
+V1Pod creatingPod = /* load it from file or else */;
+V1Pod createdPod = Kubectl.create(V1Pod.class)
+                .resource(creatingPod)
+                .execute();
+```
+
+#### Kubectl delete
+
+`Kubectl#delete` works the same as `kubectl delete` command.
+
+```java
+// kubectl delete -n default pod foo
+V1Pod deletedPod = Kubectl.delete(V1Pod.class)
+                .namespace("default")
+                .name("foo")
+                .execute();
+```
+
+#### Kubectl patch
+
+`Kubectl#patch` works the same as `kubectl patch` command.
+
+```java
+// kubectl patch --type='strategic' --patch="{\"metadata\":{\"labels\":{\"foo\":\"bar\"}}"
+V1Pod patchedPod = Kubectl.patch(V1Pod.class)
+                .patchType(V1Patch.PATCH_FORMAT_STRATEGIC_MERGE_PATCH)
+                .patchContent(new V1Patch("{\"metadata\":{\"labels\":{\"foo\":\"bar\"}}"))
+                .execute();
+```
+
+#### Kubectl apply
+
+Note that for now only server-side apply is supported, so your apiserver version is required to
+be greater than or equal to 1.18.0. `Kubectl#apply` works the same as `kubectl apply --server-side=true`.
+
+```java
+// kubectl apply --server-side=true --field-manager=java-kubectl --force-conflict=true -f <file>
+V1Pod applyingPod = /* load it from file or else */;
+V1Pod appliedPod = Kubectl.apply(V1Pod.class)
+                .fieldManager("java-kubectl")
+                .forceConflict(true)
+                .resource(applyingPod)
+                .execute();
+```
+
+#### Kubectl scale
+
+```java
+// kubectl scale -n default rs foo --replicas=2
+V1ReplicaSet scaledRs = Kubectl.scale(V1ReplicaSet.class)
+                .namespace("default")
+                .name("foo")
+                .replicas(2)
+                .execute();
+```
+
+
+#### Kubectl drain
+
+```java
+// kubectl drain node1
+V1Node drainedNode = Kubectl.drain()
+                .name("node1")
+                .execute();
+```
+
+
+#### Kubectl cordon/uncordon
+
+```java
+// kubectl cordon node1
+V1Node cordondNode = Kubectl.cordon()
+                .name("node1")
+                .execute();
+// kubectl uncordon node1
+V1Node uncordondNode = Kubectl.uncordon()
+                .name("node1")
+                .execute();
+```
+
+#### Kubectl taint
+
+```java
+// kubectl taint nodes foo dedicated:NoSchedule
+V1Node taintedNode = Kubectl.taint()
+                .addTaint("dedicated", "NoSchedule")
+                .execute()
+// kubectl taint nodes foo dedicated=special-user:NoSchedule
+V1Node taintedNode = Kubectl.taint()
+                .addTaint("dedicated", "special-user", "NoSchedule")
+                .execute()
+// kubectl taint nodes foo dedicated:NoSchedule-
+V1Node taintedNode = Kubectl.taint()
+                .removeTaint("dedicated", "NoSchedule")
+                .execute()
+```
+
+
+
+#### Kubectl label/annotate
+
+```java
+// kubectl label -n default pod foo key1=value1 key2=value2
+V1Pod labelledPod = Kubectl.label(V1Pod)
+                .addLabel("key1", "value1")
+                .addLabel("key2", "value2")
+                .namespace("default")
+                .name("foo")
+                .execute();
+// kubectl annotate -n default pod foo key1=value1 key2=value2
+V1Pod annotatedPod = Kubectl.annotate(V1Pod)
+                .addLabel("key1", "value1")
+                .addLabel("key2", "value2")
+                .namespace("default")
+                .name("foo")
+                .execute();
+```
+
+#### Kubectl api-resources
+
+```java
+// kubectl api-resources
+Set<Discovery.APIResource> apiResourceSet = Kubectl.apiResources()
+                .execute()
+```
+
+#### Kubectl exec
+
+```java
+// kubectl exec -n default foo -c test-container echo test
+int retCode = Kubectl.exec()
+                .namespace("default")
+                .name("foo")
+                .container("test-container")
+                .command(new String[]{"echo","test"})
+                .execute();
+```
+
+
+#### Kubectl logs
+
+```java
+// kubectl logs -n default foo -c test-container
+InputStream logStream = Kubectl.log()
+                .namespace("default")
+                .name("foo")
+                .container("test-container")
+                .execute();
+```
+
+#### Kubectl top
+
+```java
+// kubectl top node
+List<Pair<V1Node, NodeMetrics>> metrics = Kubectl.top(V1Node.class, NodeMetrics.class)
+                .metric("cpu")
+                .execute();
+```
+
+### Advanced Tips
+
+#### API Discovery for custom models
+
+Kubernetes allows you to extend new kubernetes API types by either [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
+or [APIServerAggregation](https://kubernetes.io/docs/tasks/extend-kubernetes/setup-extension-api-server/),
+and api-discovery is basically a process of discovering new kubernetes resources types from the client-side. 
+The java client is managing all the api-discovery information at `io.kubernetes.client.util.ModelMapper`.
+In order to make the java client know the connection between new kubernetes api and custom Java models, you're 
+supposed to manually set up the mappings for them by:
+
+```java
+ModelMapper.addModelMap(
+  "example.io",  // api-group
+  "v1",          // api-version
+  "Foo",         // kind name -- camel-case'd singular resource name.
+  "foos",        // resource name -- lowercase plural resource name
+  true,          // is namespace-scoped
+  Foo.class);    // java model class
+```

extended/src/main/java/io/kubernetes/client/extended/kubectl/KubectlPatch.java

@@ -12,17 +12,16 @@
 */
 package io.kubernetes.client.extended.kubectl;
 
-import io.kubernetes.client.common.KubernetesListObject;
 import io.kubernetes.client.common.KubernetesObject;
 import io.kubernetes.client.custom.V1Patch;
+import io.kubernetes.client.util.ModelMapper;
 import io.kubernetes.client.util.generic.GenericKubernetesApi;
 
 public class KubectlPatch<ApiType extends KubernetesObject>
     extends Kubectl.ResourceBuilder<ApiType, KubectlPatch<ApiType>>
     implements Kubectl.Executable<ApiType> {
 
-  private Class<ApiType> apiTypeClass;
-  private Class<KubernetesListObject> apiListTypeClass;
+  private String patchType;
   private V1Patch patchContent;
 
   KubectlPatch(Class<ApiType> apiTypeClass) {
@@ -34,9 +33,18 @@ public KubectlPatch patchContent(V1Patch patchContent) {
     return this;
   }
 
+  public KubectlPatch patchType(String patchType) {
+    this.patchType = patchType;
+    return this;
+  }
+
   @Override
   public ApiType execute() {
     GenericKubernetesApi genericKubernetesApi = getGenericApi();
-    return (ApiType) genericKubernetesApi.patch(namespace, name, patchContent);
+    if (ModelMapper.isNamespaced(apiTypeClass)) {
+      return (ApiType) genericKubernetesApi.patch(namespace, name, patchType, patchContent);
+    } else {
+      return (ApiType) genericKubernetesApi.patch(name, patchType, patchContent);
+    }
   }
 }