1.2 additions for getting-started-guides/ and new non-Markdown files for user-guides

2016-03-06 17:55:12 +00:00
parent 97c728d343
commit a6f6fd01cd
78 changed files with 2314 additions and 975 deletions
@@ -14,12 +14,90 @@ We still have [a bunch of work](http://issue.k8s.io/8262) to do to make the expe

 - Note that for rkt version later than v0.7.0, `metadata service` is not required for running pods in private networks. So now rkt pods will not register the metadata service be default.

+- Since release [v1.2.0-alpha.5](https://github.com/kubernetes/kubernetes/releases/tag/v1.2.0-alpha.5),
+the [rkt API service](https://github.com/coreos/rkt/blob/master/api/v1alpha/README.md)
+must be running on the node.
+
+### Network Setup
+
+rkt uses the [Container Network Interface (CNI)](https://github.com/appc/cni)
+to manage container networking. By default, all pods attempt to join a network
+called `rkt.kubernetes.io`, which is currently defined [in `rkt.go`]
+(https://github.com/kubernetes/kubernetes/blob/v1.2.0-alpha.6/pkg/kubelet/rkt/rkt.go#L91).
+In order for pods to get correct IP addresses, the CNI config file must be
+edited to add this `rkt.kubernetes.io` network:
+
+#### Using flannel
+
+In addition to the basic prerequisites above, each node must be running
+a [flannel](https://github.com/coreos/flannel) daemon. This implies
+that a flannel-supporting etcd service must be available to the cluster
+as well, apart from the Kubernetes etcd, which will not yet be
+available at flannel configuration time. Once it's running, flannel can
+be set up with a CNI config like:
+
+```shell
+$ cat <<EOF >/etc/rkt/net.d/k8s_cluster.conf
+{
+    "name": "rkt.kubernetes.io",
+    "type": "flannel"
+}
+EOF
+```
+
+While `k8s_cluster.conf` is a rather arbitrary name for the config file itself,
+and can be adjusted to suit local conventions, the keys and values should be exactly
+as shown above. `name` must be `rkt.kubernetes.io` and `type` should be `flannel`.
+More details about the flannel CNI plugin can be found
+[in the CNI documentation](https://github.com/appc/cni/blob/master/Documentation/flannel.md).
+
+#### On GCE
+
+Each VM on GCE has an additional 256 IP addresses routed to it, so
+it is possible to forego flannel in smaller clusters. This makes the
+necessary CNI config file a bit more verbose:
+
+```shell
+$ cat <<EOF >/etc/rkt/net.d/k8s_cluster.conf
+{
+    "name": "rkt.kubernetes.io",
+    "type": "bridge",
+    "bridge": "cbr0",
+    "isGateway": true,
+    "ipam": {
+        "type": "host-local",
+        "subnet": "10.255.228.1/24",
+        "gateway": "10.255.228.1"
+    },
+    "routes": [
+      { "dst": "0.0.0.0/0" }
+    ]
+}
+EOF
+```
+
+This example creates a `bridge` plugin configuration for the CNI network, specifying
+the bridge name `cbr0`. It also specifies the CIDR, in the `ipam` field.
+
+Creating these files for any moderately-sized cluster is at best inconvenient.
+Work is in progress to
+[enable Kubernetes to use the CNI by default]
+(https://github.com/kubernetes/kubernetes/pull/18795/files).
+As that work matures, such manual CNI config munging will become unnecessary
+for primary use cases. For early adopters, an initial example shows one way to
+[automatically generate these CNI configurations]
+(https://gist.github.com/yifan-gu/fbb911db83d785915543)
+for rkt.
+
 ### Local cluster

-To use rkt as the container runtime, we need to supply `--container-runtime=rkt` and `--rkt-path=$PATH_TO_RKT_BINARY` to kubelet. Additionally we can provide `--rkt-stage1-image` flag
-as well to select which [stage1 image](https://github.com/coreos/rkt/blob/master/Documentation/running-lkvm-stage1.md) we want to use.
+To use rkt as the container runtime, we need to supply the following flags to kubelet:

-If you are using the [hack/local-up-cluster.sh](https://releases.k8s.io/{{page.githubbranch}}/hack/local-up-cluster.sh) script to launch the local cluster, then you can edit the environment variable `CONTAINER_RUNTIME`, `RKT_PATH` and `RKT_STAGE1_IMAGE` to
+- `--container-runtime=rkt` chooses the container runtime to use. Possible values: 'docker', 'rkt'. Default: 'docker'.
+- `--rkt-path=$PATH_TO_RKT_BINARY` sets the path of rkt binary. Leave empty to use the first rkt in $PATH.
+- `--rkt-stage1-image` sets the path of the stage1 image. Local paths and http/https URLs are supported. Leave empty to use the 'stage1.aci' that locates in the same directory as the rkt binary.
+
+If you are using the [hack/local-up-cluster.sh](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/hack/local-up-cluster.sh) script to launch the local cluster, then you can edit the environment variable `CONTAINER_RUNTIME`, `RKT_PATH` and `RKT_STAGE1_IMAGE` to
 set these flags:

 ```shell
@@ -40,21 +118,21 @@ To use rkt as the container runtime for your CoreOS cluster on GCE, you need to

 ```shell
 $ export KUBE_OS_DISTRIBUTION=coreos
-$ export KUBE_GCE_MINION_IMAGE=<image_id>
-$ export KUBE_GCE_MINION_PROJECT=coreos-cloud
+$ export KUBE_GCE_NODE_IMAGE=<image_id>
+$ export KUBE_GCE_NODE_PROJECT=coreos-cloud
 $ export KUBE_CONTAINER_RUNTIME=rkt
 ```

 You can optionally choose the version of rkt used by setting `KUBE_RKT_VERSION`:

 ```shell
-$ export KUBE_RKT_VERSION=0.8.0
+$ export KUBE_RKT_VERSION=0.15.0
 ```

 Then you can launch the cluster by:

 ```shell
-$ kube-up.sh
+$ cluster/kube-up.sh
 ```

 Note that we are still working on making all containerized the master components run smoothly in rkt. Before that we are not able to run the master node with rkt yet.
@@ -96,16 +174,19 @@ See [a simple nginx example](/docs/user-guide/simple-nginx) to try out your new

 For more complete applications, please look in the [examples directory](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/).

+### Different UX with rkt container runtime
+
+rkt and Docker have very different designs, as well as ACI and Docker image format. Users might experience some different experience when switching from one to the other. More information can be found [here](/docs/getting-started-guides/rkt/notes/).

 ### Debugging

-Here are severals tips for you when you run into any issues.
+Here are several tips for you when you run into any issues.

 ##### Check logs

 By default, the log verbose level is 2. In order to see more logs related to rkt, we can set the verbose level to 4.
 For local cluster, we can set the environment variable: `LOG_LEVEL=4`.
-If the cluster is using salt, we can edit the [logging.sls](https://releases.k8s.io/{{page.githubbranch}}/cluster/saltbase/pillar/logging.sls) in the saltbase.
+If the cluster is using salt, we can edit the [logging.sls](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/cluster/saltbase/pillar/logging.sls) in the saltbase.

 ##### Check rkt pod status

@@ -0,0 +1,99 @@
+---
+---
+
+# Notes on Different UX with rkt container runtime
+
+### Doesn't support ENTRYPOINT + CMD feature
+
+To run a Docker image, rkt will convert it into [App Container Image (ACI) format](https://github.com/appc/spec/blob/master/SPEC.md) first.
+However, during the conversion, the `ENTRYPOINT` and `CMD` are concatentated to construct ACI's `Exec` field.
+This means after the conversion, we are not able to replace only `ENTRYPOINT` or `CMD` without touching the other part.
+So for now, users are recommended to specify the **executable path** in `Command` and **arguments** in `Args`.
+(This has the same effect if users specify the **executable path + arguments** in `Command` or `Args` alone).
+
+For example:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+  labels:
+    name: nginx
+spec:
+  containers:
+  - name: nginx
+    image: nginx
+    ports:
+    - containerPort: 80
+```
+
+The above pod yaml file is valid as it's not specifying `Command` or `Args`, so the default `ENTRYPOINT` and `CMD` of the image will be used.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+  labels:
+    name: busybox
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    command:
+    - /bin/sleep
+    - 1000
+```
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+  labels:
+    name: busybox
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    command:
+    - /bin/sleep
+    args:
+    - 1000
+```
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+  labels:
+    name: busybox
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    args:
+    - /bin/sleep
+    - 1000
+```
+
+All the three examples above are valid as they contain both the executable path and the arguments.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+  labels:
+    name: busybox
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    args:
+    - 1000
+```
+
+The last example is invalid, as we cannot override just the `CMD` of the image alone.