Merge pull request #9821 from erictune/api-conv

Added document on using resources.

docs/api-conventions.md

@@ -3,6 +3,10 @@ API Conventions
 
 Updated: 4/16/2015
 
+*This document is oriented at users who want a deeper understanding of the kubernetes
+API structure, and developers wanting to extend the kubernetes API.  An introduction to
+using resources with kubectl can be found in (working_with_resources.md).*
+
 The conventions of the [Kubernetes API](api.md) (and related APIs in the ecosystem) are intended to ease client development and ensure that configuration mechanisms can be implemented that work across a diverse set of use cases consistently.
 
 The general style of the Kubernetes API is RESTful - clients create, update, delete, or retrieve a description of an object via the standard HTTP verbs (POST, PUT, DELETE, and GET) - and those APIs preferentially accept and return JSON. Kubernetes also exposes additional endpoints for non-standard verbs and allows alternative content types. All of the JSON accepted and returned by the server has a schema, identified by the "kind" and "apiVersion" fields. Where relevant HTTP header fields exist, they should mirror the content of JSON fields, but the information should not be represented only in the HTTP header.

docs/working_with_resources.md

@@ -0,0 +1,61 @@
+# Working with Resources
+
+*This document is aimed at users who have worked through some of the examples,
+and who want to learn more about using kubectl to manage resources such
+as pods and services.  Users who want to access the REST API directly,
+and developers who want to extend the kubernetes API should 
+refer to the [api conventions](api-conventions.md) and
+the [api document](api.md).*
+
+## Resources are Automatically Modified
+When you create a resource such as pod, and then retrieve the created
+resource, a number of the fields of the resource are added.
+You can see this at work in the following example:
+```
+$ cat > original.yaml <<EOF
+apiVersion: v1
+kind: Pod
+metadata:
+  name: foo
+spec:
+  containers:
+    - name: foo
+      image: busybox
+  restartPolicy: Never
+EOF
+$ kubectl create -f original.yaml
+pods/original
+$ kubectl get pods/original -o yaml > current.yaml
+pods/original
+$ wc -l original.yaml current.yaml
+      51 current.yaml
+       9 original.yaml
+      60 total
+```
+The resource we posted had only 9 lines, but the one we got back had 51 lines. 
+If you `diff original.yaml current.yaml`, you can see the fields added to the pod.
+The system adds fields in several ways:
+  - Some fields are added synchronously with creation of the resource and some are set asynchronously.
+    - For example: `metadata.uid` is set synchronously.  (Read more about [metadata](api-conventions.md#metadata)).
+    - For example, `status.hostIP` is set only after the pod has been scheduled.  This often happens fast, but you may notice pods which do not have this set yet.  This is called Late Initialization.  (Read mode about [status](api-conventions.md#spec-and-status) and [late initialization](api-conventions.md#late-initialization) ).
+  - Some fields are set to default values.  Some defaults vary by cluster and some are fixed for the API at a certain version.  (Read more about [defaulting](api-conventions.md#defaulting)).
+    - For example, `spec.containers.imagePullPolicy` always defaults to `IfNotPresent` in api v1.
+    - For example, `spec.containers.resources.limits.cpu` may be defaulted to  `100m` on some clusters, to some other value on others, and not defaulted at all on others.
+The API will generally not modify fields that you have set; it just sets ones which were unspecified.
+
+## <a name="finding_schema_docs"></a>Finding Documentation on Resource Fields
+You can browse auto-generated API documentation at the [project website](http://kubernetes.io/third_party/swagger-ui/) or directly from your cluster, like this:
+  - Run `kubectl proxy --api-prefix=/`
+  - Go to `http://localhost:8001/swagger-ui` in your browser.
+  - It should say "swagger" at the top-left.
+
+Once there:
+  - Click on "v1" and wait for it to expand.
+  - Search for "pods", "services", "replicationcontrollers" or some other resource.
+  - Click on that POST row for the matching resource.
+  - Click on the words "Model".
+  - You should see a list of all possible resource fields, starting with `v1.pods {...}`
+
+
+
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/working_with_resources.md?pixel)]()