whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import from Container Engine docs, addition of Tabs functionality, various link fixes

Browse Source
This commit is contained in:
johndmulhausen
2016-03-16 15:54:34 -07:00
parent 3a2026677d
commit c8dd8b8831
56 changed files with 1974 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide/debugging-pods-and-replication-controllers.md
+105
View File
@@ -0,0 +1,105 @@
---
---
* TOC
{:toc}
## Debugging pods
The first step in debugging a pod is taking a look at it. Check the current
state of the pod and recent events with the following command:
$ kubectl describe pods ${POD_NAME}
Look at the state of the containers in the pod. Are they all `Running`? Have
there been recent restarts?
Continue debugging depending on the state of the pods.
### My pod stays pending
If a pod is stuck in `Pending` it means that it can not be scheduled onto a
node. Generally this is because there are insufficient resources of one type or
another that prevent scheduling. Look at the output of the `kubectl describe
...` command above. There should be messages from the scheduler about why it
can not schedule your pod. Reasons include:
#### Insufficient resources
You may have exhausted the supply of CPU or Memory in your cluster. In this
case you can try several things:
* [Add more nodes](/docs/admin/cluster-management/#resizing-a-cluster) to the cluster.
* [Terminate unneeded pods](/docs/user-guide/pods/single-container/#deleting_a_pod)
to make room for pending pods.
* Check that the pod is not larger than your nodes. For example, if all
nodes have a capacity of `cpu:1`, then a pod with a limit of `cpu: 1.1`
will never be scheduled.
You can check node capacities with the `kubectl get nodes -o <format>`
command. Here are some example command lines that extract just the necessary
information:
kubectl get nodes -o yaml | grep '\sname\|cpu\|memory'
kubectl get nodes -o json | jq '.items[] | {name: .metadata.name, cap: .status.capacity}'
The [resource quota](/docs/admin/resource-quota/)
feature can be configured to limit the total amount of
resources that can be consumed. If used in conjunction with namespaces, it can
prevent one team from hogging all the resources.
#### Using hostPort
When you bind a pod to a `hostPort` there are a limited number of places that
the pod can be scheduled. In most cases, `hostPort` is unnecessary; try using a
service object to expose your pod. If you do require `hostPort` then you can
only schedule as many pods as there are nodes in your container cluster.
### My pod stays waiting
If a pod is stuck in the `Waiting` state, then it has been scheduled to a
worker node, but it can't run on that machine. Again, the information from
`kubectl describe ...` should be informative. The most common cause of
`Waiting` pods is a failure to pull the image. There are three things to check:
* Make sure that you have the name of the image correct.
* Have you pushed the image to the repository?
* Run a manual `docker pull <image>` on your machine to see if the image can be
pulled.
### My pod is crashing or otherwise unhealthy
First, take a look at the logs of the current container:
$ kubectl logs ${POD_NAME} ${CONTAINER_NAME}
If your container has previously crashed, you can access the previous
container's crash log with:
$ kubectl logs --previous ${POD_NAME} ${CONTAINER_NAME}
Alternately, you can run commands inside that container with `exec`:
$ kubectl exec ${POD_NAME} -c ${CONTAINER_NAME} -- ${CMD} ${ARG1} ${ARG2} ... ${ARGN}
Note that `-c ${CONTAINER_NAME}` is optional and can be omitted for pods that
only contain a single container.
As an example, to look at the logs from a running Cassandra pod, you might run:
$ kubectl exec cassandra -- cat /var/log/cassandra/system.log
If none of these approaches work, you can find the host machine that the pod is
running on and SSH into that host.
## Debugging Replication Controllers
Replication controllers are fairly straightforward. They can either create pods
or they can't. If they can't create pods, then please refer to the
[instructions above](#debugging_pods) to debug your pods.
You can also use `kubectl describe rc ${CONTROLLER_NAME}` to inspect events
related to the replication controller.
docs/user-guide/debugging-services.md
+60 -1
View File
@@ -9,7 +9,6 @@ This document will hopefully help you to figure out what's going wrong.
* TOC
{:toc}
## Conventions
Throughout this doc you will see various commands that you can run. Some
@@ -506,6 +505,66 @@ Setting endpoints for default/hostnames:default to [10.244.0.5:9376 10.244.0.6:9
If you don't see those, try restarting `kube-proxy` with the `-V` flag set to 4, and
then look at the logs again.
Services provide load balancing across a set of pods. There are several common
problems that can make services not work properly. The following instructions
should help debug service problems.
First, verify that there are endpoints for the service. For every service
object, the apiserver makes an `endpoints` resource available.
You can view this resource with:
$ kubectl get endpoints ${SERVICE_NAME}
Make sure that the endpoints match up with the number of containers that you
expect to be a member of your service. For example, if your service is for an
nginx container with 3 replicas, you would expect to see three different IP
addresses in the service's endpoints.
### My service is missing endpoints
If you are missing endpoints, try listing pods using the labels that service
uses. Imagine that you have a service where the labels are:
...
spec:
- selector:
name: nginx
type: frontend
You can use:
$ kubectl get pods --selector=name=nginx,type=frontend
to list pods that match this selector. Verify that the list matches the pods
that you expect to provide your service.
If the list of pods matches expectations, but your endpoints are still empty,
it's possible that you don't have the right ports exposed. If your service has
a `containerPort` specified, but the pods that are selected don't have that
port listed, then they won't be added to the endpoints list.
Verify that the pod's `containerPort` matches up with the service's
`containerPort`.
### Network traffic is not forwarded
If you can connect to the service, but the connection is immediately dropped,
and there are endpoints in the endpoints list, it's likely that the proxy can't
contact your pods.
There are three things to check:
* Are your pods working correctly? Look for restart count, and
[debug pods](#debugging_pods).
* Can you connect to your pods directly? Get the IP address for the pod, and
try to connect directly to that IP.
* Is your application serving on the port that you configured? Container
Engine doesn't do port remapping, so if your application serves on 8080,
the `containerPort` field needs to be 8080.
## Seek help
If you get this far, something very strange is happening. Your `Service` is
docs/user-guide/load-balancer.md
+73
View File
@@ -0,0 +1,73 @@
---
---
* TOC
{:toc}
## Overview
When creating a service, you have the option of automatically creating a
network load balancer. This provides an
externally-accessible IP address that sends traffic to the correct port on your
cluster nodes.
## Configuration file
To create an external load balancer, add the following line to your
[service configuration file](/docs/services/operations/#service-configuration-file):
"type": "LoadBalancer"
Your configuration file might look like:
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "example-service"
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376,
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
## Using kubectl
You can alternatively create the service with the `kubectl expose` command and
its `--type=LoadBalancer` flag:
$ kubectl expose rc example --port=8765 --target-port=9376 \
--name=example-service --type=LoadBalancer
This command creates a new service using the same selectors as the referenced
resource (in the case of the example above, a replication controller named
`example`.)
For more information, including optional flags, refer to the
[`kubectl expose` reference](/docs/user-guide/kubectl/kubectl_expose/).
## Finding your IP address
You can find the IP address created for your service by getting the service
information through `kubectl`:
$ kubectl describe services example-service
Name: example-service
Selector: app=example
Type: LoadBalancer
IP: 10.67.252.103
LoadBalancer Ingress: 123.45.678.9
Port: <unnamed> 80/TCP
NodePort: <unnamed> 32445/TCP
Endpoints: 10.64.0.4:80,10.64.1.5:80,10.64.2.4:80
Session Affinity: None
No events.
The IP address is listed next to `LoadBalancer Ingress`.
docs/user-guide/pods/_viewing-a-pod.md
+58
View File
@@ -0,0 +1,58 @@
To view a specific pod, use the `kubectl get` command:
```shell
$ kubectl get pod NAME
NAME READY STATUS RESTARTS AGE
example 1/1 Running 0 2d
```
To return the name of the node on which the pod is scheduled, use the `-o wide`
option:
```shell
$ kubectl get pod NAME -o wide
NAME READY STATUS RESTARTS AGE NODE
example 1/1 Running 0 2d gke-example-c6a38-node-xij3
```
For more details about a pod, including events, use `describe` in place of
`get`:
```shell
$ kubectl describe pod NAME
Name: example
Namespace: default
Image(s): kubernetes/example-php-redis:v2
Node: gke-example-c6a38461-node-xij3/10.240.34.183
Labels: name=frontend
Status: Running
Reason:
Message:
IP: 10.188.2.10
Replication Controllers: example (5/5 replicas created)
Containers:
php-redis:
Image: kubernetes/example-php-redis:v2
Limits:
cpu: 100m
State: Running
Started: Tue, 04 Aug 2015 09:02:46 -0700
Ready: True
Restart Count: 0
Conditions:
Type Status
Ready True
Events:
FirstSeen LastSeen Coun From SubobjectPath Reason Message
Thu, 06 Aug 2015 11:49:44 -0700 Thu, 06 Aug 2015 11:49:44 -0700 1 {kubelet gke-example-c6a38461-node-xij3} spec.containers{example} started Started with docker id 5705bffa65e2
```
To list all pods running on a cluster:
```shell
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
example-xypvc 1/1 Running 0 1m
frontend-7kdod 1/1 Running 0 1d
```
docs/user-guide/pods.md → docs/user-guide/pods/index.md
View File
docs/user-guide/pods/multi-container.md
+175
View File
@@ -0,0 +1,175 @@
---
---
* TOC
{:toc}
A pod is a group of containers that are scheduled
onto the same host. Pods serve as units of scheduling, deployment, and
horizontal scaling/replication. Pods share fate, and share some resources, such
as storage volumes and IP addresses.
## Creating a pod
Multi-container pods must be created with the `create` command. Properties
are passed to the command as a YAML- or JSON-formatted configuration file.
The `create` command can be used to create a pod directly, or it can create
a pod or pods through a replication controller. It is highly recommended that
you use a
[replication controller](/docs/user-guide/replication-controller/)
to create your pods. The controller watches for failed pods and will start up
new pods as required to maintain the specified number.
For instructions on creating pods with a replication controller, refer to
[Creating replication controllers](/docs/user-guide/replication-controller/operations/).
If you don't want a replication controller to monitor your pod (e.g. your pod
is writing non-persistent data which won't survive a restart, or your pod is
intended to be very short-lived), you can create a pod directly with the
`create` command.
### Using `create`
Note: We recommend using a
[replication controller](/docs/user-guide/replication-controller/)
to create pods. You should use the instructions below only if you don't want
to create a replication controller.
If your pod will contain more than one container, or if you don't want to
create a replication controller to manage your pod, use the
`kubectl create` command and pass a pod specification as a JSON- or
YAML-formatted configuration file.
```shell
$ kubectl create -f FILE
```
Where:
* `-f FILE` or `--filename FILE` is the name of a
[pod configuration file](#pod-configuration-file) in either JSON or YAML
format.
A successful create request returns the pod name. Use the
[`kubectl get`](#viewing_a_pod) command to view status after creation.
### Pod configuration file
A pod configuration file specifies required information about the pod.
It can be formatted as YAML or as JSON, and supports the following fields:
{% capture tabspec %}configfiles
JSON,json,pod-config.json,/docs/user-guide/pods/pod-config.json
YAML,yaml,pod-config.yaml,/docs/user-guide/pods/pod-config.yaml{% endcapture %}
{% include tabs.html %}
Required fields are:
* `kind`: Always `Pod`.
* `apiVersion`: Currently `v1`.
* `metadata`: An object containing:
* `name`: Required if `generateName` is not specified. The name of this pod.
It must be an
[RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be
unique within the namespace.
* `labels`: Optional. Labels are arbitrary key:value pairs that can be used
by
[replication controllers](/docs/user-guide/replication-controller)
and [services](/docs/user-guide/services/) for grouping and targeting
pods.
* `generateName`: Required if `name` is not set. A prefix to use to generate
a unique name. Has the same validation rules as `name`.
* `namespace`: Required. The namespace of the pod.
* `annotations`: Optional. A map of string keys and values that can be used
by external tooling to store and retrieve arbitrary metadata about
objects.
* `spec`: The pod specification. See [The `spec` schema](#the_spec_schema) for
details.
### The `spec` schema
A full description of the `spec` schema is contained in the
[Kubernetes API reference](/docs/api-reference/v1/definitions/#_v1_podspec).
The following fields are required or commonly used in the `spec` schema:
{% capture tabspec %}specfiles
JSON,json,pod-spec-common.json,/docs/user-guide/pods/pod-spec-common.json
YAML,yaml,pod-spec-common.yaml,/docs/user-guide/pods/pod-spec-common.yaml{% endcapture %}
{% include tabs.html %}
#### `containers[]`
A list of containers belonging to the pod. Containers cannot be added or removed once the pod is created, and there must be at least one container in a pod.
The `containers` object **must contain**:
* `name`: Name of the container. It must be a DNS_LABEL and be unique within the pod. Cannot be updated.
* `image`: Docker image name.
The `containers` object **commonly contains** the following optional properties:
* `command[]`: The entrypoint array. Commands are not executed within a shell. The docker image's entrypoint is used if this is not provided. Cannot be updated.
* `args[]`: A command array containing arguments to the entrypoint. The docker image's `cmd` is used if this is not provided. Cannot be updated.
* `env[]`: A list of environment variables in key:value format to set in the container. Cannot be updated.
* `name`: The name of the environment variable; must be a `C_IDENTIFIER`.
* `value`: The value of the environment variable. Defaults to empty string.
* `imagePullPolicy`: The image pull policy. Accepted values are:
* `Always`
* `Never`
* `IfNotPresent`Defaults to `Always` if `:latest` tag is specified, or `IfNotPresent` otherwise. Cannot be updated.
* `ports[]`: A list of ports to expose from the container. Cannot be updated.
* `containerPort`: The port number to expose on the pod's IP address.
* `name`: The name for the port that can be referred to by services. Must be a `DNS_LABEL` and be unique without the pod.
* `protocol`: Protocol for the port. Must be UDP or TCP. Default is TCP.
* `resources`: The Compute resources required by this container. Contains:
* `cpu`: CPUs to reserve for each container. Default is whole CPUs; scale suffixes (e.g. `100m` for one hundred milli-CPUs) are supported. If the host does not have enough available resources, your pod will not be scheduled.
* `memory`: Memory to reserve for each container. Default is bytes; [binary scale suffixes](http://en.wikipedia.org/wiki/Binary_prefix) (e.g. `100Mi` for one hundred mebibytes) are supported. If the host does not have enough available resources, your pod will not be scheduled.Cannot be updated.
#### `restartPolicy`
Restart policy for all containers within the pod. Options are:
* `Always`
* `OnFailure`
* `Never`
#### `volumes[]`
A list of volumes that can be mounted by containers belonging to the pod. You must specify a `name` and a source for each volume. The container must also include a `volumeMount` with matching `name`. Source is one of:
* `emptyDir`: A temporary directory that shares a pod's lifetime. Contains:
* `medium`: The type of storage used to back the volume. Must be an empty string (default) or `Memory`.
* `hostPath`: A pre-existing host file or directory. This is generally used for privileged system daemons or other agents tied to the host. Contains:
* `path`: The path of the directory on the host.
* `secret`: Secret to populate volume. Secrets are used to hold sensitive information, such as passwords, OAuth tokens, and SSH keys. Learn more from [the docs on secrets](/docs/user-guide/secrets/). Contains:
* `secretName`: The name of a secret in the pod's namespace.
The `name` must be a DNS_LABEL and unique within the pod.
### Sample file
For example, the following configuration file creates two containers: a
`redis` key-value store image, and a `django` frontend image.
{% capture tabspec %}samplefiles
JSON,json,pod-sample.json,/docs/user-guide/pods/pod-sample.json
YAML,yaml,pod-sample.yaml,/docs/user-guide/pods/pod-sample.yaml{% endcapture %}
{% include tabs.html %}
## Viewing a pod
{% include_relative _viewing-a-pod.md %}
## Deleting a pod
If you created your pod directly with `kubectl create`, use `kubectl delete`:
```shell
$ kubectl delete pod NAME
```
A successful delete request returns the name of the deleted pod.
docs/user-guide/pods/pod-config.json
+18
View File
@@ -0,0 +1,18 @@
{
"kind": "Pod",
"apiVersion": "v1",
"metadata": {
"name": "",
"labels": {
"name": ""
},
"generateName": "",
"namespace": "",
"annotations": []
},
"spec": {
// See 'The spec schema' for details.
}
}
docs/user-guide/pods/pod-config.yaml
+12
View File
@@ -0,0 +1,12 @@
apiVersion: v1
kind: Pod
metadata:
name: ""
labels:
name: ""
namespace: ""
annotations: []
generateName: ""
spec:
? "// See 'The spec schema' for details."
: ~
docs/user-guide/pods/pod-sample.json
+32
View File
@@ -0,0 +1,32 @@
{
"kind": "Pod",
"apiVersion": "v1",
"metadata": {
"name": "redis-django",
"labels": {
"app": "webapp"
}
},
"spec": {
"containers": [
{
"name": "key-value-store",
"image": "redis",
"ports": [
{
"containerPort": 6379,
}
]
},
{
"name": "frontend",
"image": "django",
"ports": [
{
"containerPort": 8000,
}
]
}
]
}
}
docs/user-guide/pods/pod-sample.yaml
+16
View File
@@ -0,0 +1,16 @@
apiVersion: v1
kind: Pod
metadata:
name: redis-django
labels:
app: web
spec:
containers:
- name: key-value-store
image: redis
ports:
- containerPort: 6379
- name: frontend
image: django
ports:
- containerPort: 8000
docs/user-guide/pods/pod-spec-common.json
+44
View File
@@ -0,0 +1,44 @@
"spec": {
"containers": [
{
"name": "",
"image": "",
"command": [
""
],
"args": [
""
],
"env": [
{
"name": "",
"value": ""
}
],
"imagePullPolicy": "",
"ports": [
{
"containerPort": 0,
"name": "",
"protocol": ""
}
],
"resources": {
"cpu": ""
"memory": ""
}
}
],
"restartPolicy": "",
"volumes": [
{
"name": "",
"emptyDir": {
"medium": ""
},
"secret": {
"secretName": ""
}
}
]
}
docs/user-guide/pods/pod-spec-common.yaml
+31
View File
@@ -0,0 +1,31 @@
spec:
containers:
-
args:
- ""
command:
- ""
env:
-
name: ""
value: ""
image: ""
imagePullPolicy: ""
name: ""
ports:
-
containerPort: 0
name: ""
protocol: ""
resources:
cpu: ""
memory: ""
restartPolicy: ""
volumes:
-
emptyDir:
medium: ""
name: ""
secret:
secretName: ""
docs/user-guide/pods/single-container.md
+88
View File
@@ -0,0 +1,88 @@
---
---
* TOC
{:toc}
A pod is a group of containers that are scheduled
onto the same host. Pods serve as units of scheduling, deployment, and
horizontal scaling/replication. Pods share fate, and share some resources, such
as storage volumes and IP addresses.
## Creating a pod
Single-container pods can be created with the `run` command. The
pod's properties are specified with flags on the command line.
The `run` command creates a replication controller to monitor the pod(s).
The controller watches for failed pods and will start up new pods as required
to maintain the specified number.
Note: If you don't want a replication controller to monitor your pod (e.g. your pod
is writing non-persistent data which won't survive a restart, or your pod is
intended to be very short-lived), you can
[create a pod directly with the `create` command](/docs/user-guide/pods/multi-container/).
To create a pod using the `run` command:
```shell
$ kubectl run NAME
--image=image
[--port=port]
[--replicas=replicas]
[--labels=key=value,key=value,...]
```
Where:
* `NAME` (required) is the name of the container to create. This value is also
applied as the name of the replication controller, and as the prefix of the
pod name. For example:
```shell
$ kubectl run example --image=nginx
replicationcontroller "example" created
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
example-xypvc 1/1 Running 0 13s
```
* `--image=IMAGE` (required) is the Docker container image to use for this
container.
* `--port=PORT` is the port to expose on the container.
* `--replicas=NUM` is the number of replicated pods to create. If not specified,
one pod will be created.
* `--labels=key=value` specifies one or more labels to attach to the pod. In
addition to any labels specified here, `run` attaches a label of
the format `run=NAME`. This is used by the replication controller
to target the pods created by the command.
There are additional flags that can be specified. For a complete list, run:
$ kubectl run --help
## Viewing a pod
{% include_relative _viewing-a-pod.md %}
## Deleting a pod
If your pod was created using the `run` command, kubernetes creates a
[replication controller](/docs/user-guide/replication-controller/)
to manage the pod. Pods managed by a replication controller are rescheduled if
they go away, including being deleted by `kubectl delete pod`. To permanently
delete the pod, delete its replication controller.
First, find the controller's name:
```shell
$ kubectl get rc
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
example example busybox run=example 1
```
Then, `delete` the controller:
```shell
$ kubectl delete rc CONTROLLER_NAME
```
docs/user-guide/replication-controller.md → docs/user-guide/replication-controller/index.md
+6 -2
View File
@@ -92,8 +92,8 @@ A Replication Controller also needs a [`.spec` section](https://github.com/kuber
The `.spec.template` is the only required field of the `.spec`.
The `.spec.template` is a [pod template](/docs/user-guide/replication-controller/#pod-template). It has exactly
the same schema as a [pod](pods.md), except it is nested and does not have an `apiVersion` or
The `.spec.template` is a [pod template](#pod-template). It has exactly
the same schema as a [pod](/docs/user-guide/pods/), except it is nested and does not have an `apiVersion` or
`kind`.
In addition to required fields for a Pod, a pod template in a job must specify appropriate
@@ -241,3 +241,7 @@ Use a [DaemonSet](/docs/admin/daemons/) instead of a replication controller for
machine-level function, such as machine monitoring or machine logging. These pods have a lifetime is tied
to machine lifetime: the pod needs to be running on the machine before other pods start, and are
safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
## For more information
Read [Replication Controller Operations](/docs/user-guide/replication-controller/operations/).
docs/user-guide/replication-controller/operations.md
+226
View File
@@ -0,0 +1,226 @@
---
---
* TOC
{:toc}
A replication controller ensures that a specified number of pod "replicas" are
running at any one time. If there are too many, it will kill some. If there are
too few, it will start more.
## Creating a replication controller
Replication controllers are created with `kubectl create`:
```shell
$ kubectl create -f FILE
```
Where:
* `-f FILE` or `--filename FILE` is a relative path to a
[configuration file](#replication_controller_configuration_file) in
either JSON or YAML format.
You can use the [sample file](#sample_file) below to try a create request.
A successful create request returns the name of the replication controller. To
view more details about the controller, see
[Viewing replication controllers](#viewing_replication_controllers) below.
### Replication controller configuration file
When creating a replication controller, you must point to a configuration file
as the value of the `-f` flag. The configuration
file can be formatted as YAML or as JSON, and supports the following fields:
```json
{
"apiVersion": "v1",
"kind": "ReplicationController",
"metadata": {
"name": "",
"labels": "",
"namespace": ""
},
"spec": {
"replicas": int,
"selector": {
"":""
},
"template": {
"metadata": {
"labels": {
"":""
}
},
"spec": {
// See 'The spec schema' below
}
}
}
}
```
Required fields are:
* `kind`: Always `ReplicationController`.
* `apiVersion`: Currently `v1`.
* `metadata`: An object containing:
* `name`: Required if `generateName` is not specified. The name of this
replication controller. It must be an
[RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be
unique within the namespace.
* `labels`: Optional. Labels are arbitrary key:value pairs that can be used
for grouping and targeting by other resources and services.
* `generateName`: Required if `name` is not set. A prefix to use to generate
a unique name. Has the same validation rules as `name`.
* `namespace`: Optional. The namespace of the replication controller.
* `annotations`: Optional. A map of string keys and values that can be used
by external tooling to store and retrieve arbitrary metadata about
objects.
* `spec`: The configuration for this replication controller. It must
contain:
* `replicas`: The number of pods to create and maintain.
* `selector`: A map of key:value pairs assigned to the set of pods that
this replication controller is responsible for managing. **This must**
**match the key:value pairs in the `template`'s `labels` field**.
* `template` contains:
* A `metadata` object with `labels` for the pod.
* The [`spec` schema](#the_spec_schema) that defines the pod
configuration.
### The `spec` schema
The `spec` schema (that is a child of `template`) is described in the locations
below:
* The [`spec` schema](/docs/user-guide/pods/multi-container/#the_spec_schema)
section of the Creating Multi-Container Pods page covers required and
frequently-used fields.
* The entire `spec` schema is documented in the
[Kubernetes API reference](/docs/api-reference/v1/definitions/#_v1_podspec).
### Sample file
The following sample file creates 2 pods, each containing a single container
using the `redis` image. Port 80 on each container is opened. The replication
controller is tagged with the `serving` label. The pods are given the label
`frontend` and the `selector` is set to `frontend`, to indicate that the
controller should manage pods with the `frontend` label.
```json
{
"kind": "ReplicationController",
"apiVersion": "v1",
"metadata": {
"name": "frontend-controller",
"labels": {
"state": "serving"
}
},
"spec": {
"replicas": 2,
"selector": {
"app": "frontend"
},
"template": {
"metadata": {
"labels": {
"app": "frontend"
}
},
"spec": {
"volumes": null,
"containers": [
{
"name": "php-redis",
"image": "redis",
"ports": [
{
"containerPort": 80,
"protocol": "TCP"
}
],
"imagePullPolicy": "IfNotPresent"
}
],
"restartPolicy": "Always",
"dnsPolicy": "ClusterFirst"
}
}
}
}
```
## Updating replication controller pods
See [Rolling Updates](/docs/user-guide/rolling-updates/).
## Resizing a replication controller
See
[Resizing a replication controller](/docs/user-guide/resizing-a-replication-controller/).
## Viewing replication controllers
To list replication controllers on a cluster, use the `kubectl get` command:
```shell
$ kubectl get rc
```
A successful get command returns all replication controllers on the cluster in
the specified or default namespace. For example:
```shell
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
frontend php-redis redis name=frontend 2
```
You can also use `get rc NAME` to return information about a specific
replication controller.
To view detailed information about a specific replication controller, use the
`kubectl describe` command:
```shell
$ kubectl describe rc NAME
```
A successful describe request returns details about the replication controller
including number and status of pods managed, and recent events:
```conf
Name: frontend
Namespace: default
Image(s): gcr.io/google_samples/gb-frontend:v3
Selector: name=frontend
Labels: name=frontend
Replicas: 2 current / 2 desired
Pods Status: 2 Running / 0 Waiting / 0 Succeeded / 0 Failed
Events:
FirstSeen LastSeen Count From SubobjectPath Reason Message
Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-gyx2h
Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-vc9w4
```
## Deleting replication controllers
To delete a replication controller as well as the pods that it controls, use
`kubectl delete`:
```shell
$ kubectl delete rc NAME
```
By default, `kubectl delete rc` will resize the controller to zero (effectively
deleting all pods) before deleting it.
To delete a replication controller without deleting its pods, use
`kubectl delete` and specify `--cascade=false`:
```shell
$ kubectl delete rc NAME --cascade=false
```
A successful delete request returns the name of the deleted resource.
docs/user-guide/replication.yaml → docs/user-guide/replication-controller/replication.yaml
View File
docs/user-guide/resizing-a-replication-controller.md
+33
View File
@@ -0,0 +1,33 @@
---
---
To increase or decrease the number of pods under a replication controller's
control, use the `kubectl scale` command:
$ kubectl scale rc NAME --replicas=COUNT \
[--current-replicas=COUNT] \
[--resource-version=VERSION]
Tip: You can use the `rc` alias in your commands in place of
`replicationcontroller`.
Required fields are:
* `NAME`: The name of the replication controller to update.
* `--replicas=COUNT`: The desired number of replicas.
Optional fields are:
* `--current-replicas=COUNT`: A precondition for current size. If specified,
the resize will only take place if the current number of replicas matches
this value.
* `--resource-version=VERSION`: A precondition for resource version. If
specified, the resize will only take place if the current replication
controller version matches this value. Versions are specified in the
`labels` field of the replication controller's configuration file, as a
key:value pair with a key of `version`. For example,
`--resource-version test` matches:
"labels": {
"version": "test"
}
docs/user-guide/rolling-updates.md
+127
View File
@@ -0,0 +1,127 @@
---
---
* TOC
{:toc}
## Overview
A rolling update applies changes to the configuration of pods being managed by
a replication controller. The changes can be passed as a new replication
controller configuration file; or, if only updating the image, a new container
image can be specified directly.
A rolling update works by:
1. Creating a new replication controller with the updated configuration.
2. Increasing/decreasing the replica count on the new and old controllers until
the correct number of replicas is reached.
3. Deleting the original replication controller.
Rolling updates are initiated with the `kubectl rolling-update` command:
$ kubectl rolling-update NAME \
([NEW_NAME] --image=IMAGE | -f FILE)
## Passing a configuration file
To initiate a rolling update using a configuration file, pass the new file to
`kubectl rolling-update`:
$ kubectl rolling-update NAME -f FILE
The configuration file must:
* Specify a different `metadata.name` value.
* Overwrite at least one common label in its `spec.selector` field.
* Use the same `metadata.namespace`.
Replication controller configuration files are described in
[Creating Replication Controllers](/docs/user-guide/replication-controller/operations/).
### Examples
// Update pods of frontend-v1 using new replication controller data in frontend-v2.json.
$ kubectl rolling-update frontend-v1 -f frontend-v2.json
// Update pods of frontend-v1 using JSON data passed into stdin.
$ cat frontend-v2.json | kubectl rolling-update frontend-v1 -f -
## Updating the container image
To update only the container image, pass a new image name and tag with the
`--image` flag and (optionally) a new controller name:
$ kubectl rolling-update NAME [NEW_NAME] --image=IMAGE:TAG
The `--image` flag is only supported for single-container pods. Specifying
`--image` with multi-container pods returns an error.
If no `NEW_NAME` is specified, a new replication controller is created with
a temporary name. Once the rollout is complete, the old controller is deleted,
and the new controller is updated to use the original name.
The update will fail if `IMAGE:TAG` is identical to the
current value. For this reason, we recommend the use of versioned tags as
opposed to values such as `:latest`. Doing a rolling update from `image:latest`
to a new `image:latest` will fail, even if the image at that tag has changed.
### Examples
// Update the pods of frontend-v1 to frontend-v2
$ kubectl rolling-update frontend-v1 frontend-v2 --image=image:v2
// Update the pods of frontend, keeping the replication controller name
$ kubectl rolling-update frontend --image=image:v2
## Required and optional fields
Required fields are:
* `NAME`: The name of the replication controller to update.
as well as either:
* `-f FILE`: A replication controller configuration file, in either JSON or
YAML format. The configuration file must specify a new top-level `id` value
and include at least one of the existing `spec.selector` key:value pairs.
See the
[Replication Controller Operations](/docs/user-guide/replication-controller/operations#replication-controller-configuration-file)
page for details.
<br>
<br>
or:
<br>
<br>
* `--image IMAGE:TAG`: The name and tag of the image to update to. Must be
different than the current image:tag currently specified.
Optional fields are:
* `NEW_NAME`: Only used in conjunction with `--image` (not with `-f FILE`). The
name to assign to the new replication controller.
* `--poll-interval DURATION`: The time between polling the controller status
after update. Valid units are `ns` (nanoseconds), `us` or `µs` (microseconds),
`ms` (milliseconds), `s` (seconds), `m` (minutes), or `h` (hours). Units can
be combined (e.g. `1m30s`). The default is `3s`.
* `--timeout DURATION`: The maximum time to wait for the controller to update a
pod before exiting. Default is `5m0s`. Valid units are as described for
`--poll-interval` above.
* `--update-period DURATION`: The time to wait between updating pods. Default
is `1m0s`. Valid units are as described for `--poll-interval` above.
Additional information about the `kubectl rolling-update` command is available
from the [`kubectl` reference](/docs/user-guide/kubectl/kubectl_rolling-update/).
## Troubleshooting
If the `timeout` duration is reached during a rolling update, the operation will
fail with some pods belonging to the new replication controller, and some to the
original controller.
To continue the update from where it failed, retry using the same command.
To roll back to the original state before the attempted update, append the
`--rollback=true` flag to the original command. This will revert all changes.
docs/user-guide/services.md → docs/user-guide/services/index.md
+4
View File
@@ -569,3 +569,7 @@ through a load-balancer, though in those cases the client IP does get altered.
Service is a top-level resource in the kubernetes REST API. More details about the
API object can be found at: [Service API
object](/docs/api-reference/v1/definitions/#_v1_service).
## For More Information
Read [Service Operations](/docs/user-guide/services/operations/).
docs/user-guide/services/load-balancer-sample.json
+17
View File
@@ -0,0 +1,17 @@
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "myapp"
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
},
"type": "LoadBalancer"
}
}
docs/user-guide/services/load-balancer-sample.yaml
+12
View File
@@ -0,0 +1,12 @@
apiVersion: v1
kind: Service
metadata:
name: myapp
spec:
ports:
-
port: 8765
targetPort: 9376
selector:
app: example
type: LoadBalancer
docs/user-guide/services/operations.md
+161
View File
@@ -0,0 +1,161 @@
---
---
* TOC
{:toc}
Services map a port on each cluster node to ports on one or more pods.
The mapping uses a `selector` key:value pair in the service, and the
`labels` property of pods. Any pods whose labels match the service selector
are made accessible through the service's port.
For more information, see the
[Services Overview](/docs/user-guide/services/).
## Create a service
Services are created by passing a configuration file to the `kubectl create`
command:
```shell
$ kubectl create -f FILE
```
Where:
* `-f FILE` or `--filename FILE` is a relative path to a
[service configuration file](#service-configuration-file) in either JSON
or YAML format.
A successful service create request returns the service name. You can use
a [sample file](#sample_files) below to try a create request.
### Service configuration file
When creating a service, you must point to a service configuration file as the
value of the `-f` flag. The configuration file can be formatted as
YAML or as JSON, and supports the following fields:
```json
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": string
},
"spec": {
"ports": [{
"port": int,
"targetPort": int
}],
"selector": {
string: string
},
"type": "LoadBalancer"
}
}
```
Required fields are:
* `kind`: Always `Service`.
* `apiVersion`: Currently `v1`.
* `metadata`: Contains:
* `name`: The name to give to this service.
* `spec`: Contains:
* `ports`: The ports to map. `port` is the service port to expose on the
cluster IP. `targetPort` is the port to target on the pods that are part
of this service.
* `selector`: The label key:value pair that defines the pods to
target.
* `type`: Optional. If the type is `LoadBalancer`, sets up a [network load balancer](/docs/user-guide/load-balancer/)
for your service. This provides an externally-accessible IP address that
sends traffic to the correct port on your cluster nodes.
For the full `service` schema see the
[Kubernetes api reference](/docs/api-reference/v1/definitions/#_v1_service).
### Sample files
The following service configuration files assume that you have a set of pods
that expose port 9376 and carry the label `app=example`.
Both files create a new service named `myapp` which resolves to TCP port 9376
on any pod with the `app=example` label.
The difference in the files is in how the service is accessed. The first file
does not create an external load balancer; the service can be accessed through
port 8765 on any of the nodes' IP addresses.
{% capture tabspec %}servicesample
JSON,json,service-sample.json,/docs/user-guide/services/service-sample.json
YAML,yaml,service-sample.yaml,/docs/user-guide/services/service-sample.yaml{% endcapture %}
{% include tabs.html %}
The second file uses
[network load balancing](/docs/user-guide/load-balancer/) to create a
single IP address that spreads traffic to all of the nodes in
your cluster. This option is specified with the
`"type": "LoadBalancer"` property.
{% capture tabspec %}loadbalancesample
JSON,json,load-balancer-sample.json,/docs/user-guide/services/load-balancer-sample.json
YAML,yaml,load-balancer-sample.yaml,/docs/user-guide/services/load-balancer-sample.yaml{% endcapture %}
{% include tabs.html %}
To access the service, a client connects to the external IP address, which
forwards to port 8765 on a node in the cluster, which in turn accesses
port 9376 on the pod. See the
[Service configuration file](#service-configuration-file) section of this doc
for directions on finding the external IP address.
## View a service
To list all services on a cluster, use the
`kubectl get` command:
```shell
$ kubectl get services
```
A successful get request returns all services that exist on the specified
cluster:
```shell
NAME LABELS SELECTOR IP PORT
myapp <none> app=MyApp 10.123.255.83 8765/TCP
```
To return information about a specific service, use the
`kubectl describe` command:
```shell
$ kubectl describe service NAME
```
Details about the specific service are returned:
```conf
Name: myapp
Labels: <none>
Selector: app=MyApp
IP: 10.123.255.83
Port: <unnamed> 8765/TCP
NodePort: <unnamed> 31474/TCP
Endpoints: <none>
Session Affinity: None
No events.
```
To return information about a service when event information is not required,
substitute `get` for `describe`.
## Delete a service
To delete a service, use the `kubectl delete` command:
```shell
$ kubectl delete service NAME
```
A successful delete request returns the deleted service's name.
docs/user-guide/services/service-sample.json
+16
View File
@@ -0,0 +1,16 @@
{
"kind": "Service",
"apiVersion": "v1",
"metadata": {
"name": "myapp"
},
"spec": {
"ports": [{
"port": 8765,
"targetPort": 9376
}],
"selector": {
"app": "example"
}
}
}
docs/user-guide/services/service-sample.yaml
+11
View File
@@ -0,0 +1,11 @@
apiVersion: v1
kind: Service
metadata:
name: myapp
spec:
ports:
-
port: 8765
targetPort: 9376
selector:
app: example