diff --git a/.gitignore b/.gitignore index 460a88c521..efdcc2a53e 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,4 @@ Session.vim tags kubernetes.github.io.iml +_redirects diff --git a/.travis.yml b/.travis.yml index e527e16dbc..09a28b78cb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,6 +13,7 @@ install: - rm $GOPATH/src/k8s.io/kubernetes/vendor/k8s.io/apimachinery - rm $GOPATH/src/k8s.io/kubernetes/vendor/k8s.io/apiserver - rm $GOPATH/src/k8s.io/kubernetes/vendor/k8s.io/client-go +- rm $GOPATH/src/k8s.io/kubernetes/vendor/k8s.io/sample-apiserver - cp -r $GOPATH/src/k8s.io/kubernetes/vendor/* $GOPATH/src/ - rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/* - cp -r $GOPATH/src/k8s.io/kubernetes/staging/src/* $GOPATH/src/ diff --git a/Makefile b/Makefile index 3657cb577a..36a4842840 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: all build build-preview help serve +.PHONY: all build build-preview generate-redirects help serve help: ## Show this help. @awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {sub("\\\\n",sprintf("\n%22c"," "), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) @@ -11,5 +11,8 @@ build: ## Build site with production settings and put deliverables in _site. build-preview: ## Build site with drafts and future posts enabled. jekyll build --drafts --future +generate-redirects: ## Generate a redirects file and copy it into the _site directory. + mkdir -p _site && REDIRECTS_PATH=_site/_redirects ruby redirects.rb + serve: ## Boot the development server. jekyll serve diff --git a/_data/concepts.yml b/_data/concepts.yml index 4f41c2c818..4227231cc1 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -9,12 +9,14 @@ toc: - docs/concepts/tools/kubectl/object-management-using-imperative-commands.md - docs/concepts/tools/kubectl/object-management-using-imperative-config.md - docs/concepts/tools/kubectl/object-management-using-declarative-config.md - + - title: Kubernetes Objects section: - docs/concepts/abstractions/overview.md - - docs/concepts/abstractions/pod.md - + - title: Pods + section: + - docs/concepts/abstractions/pod.md + - docs/concepts/abstractions/init-containers.md - title: Controllers section: - docs/concepts/abstractions/controllers/statefulsets.md diff --git a/_data/tasks.yml b/_data/tasks.yml index de066c9ed2..cb61b1a05a 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -3,6 +3,10 @@ abstract: "Step-by-step instructions for performing operations with Kubernetes." toc: - docs/tasks/index.md +- title: Using the Kubectl Command-Line + section: + - docs/tasks/kubectl/list-all-running-container-images.md + - title: Configuring Pods and Containers section: - docs/tasks/configure-pod-container/define-environment-variable-container.md @@ -10,6 +14,7 @@ toc: - docs/tasks/configure-pod-container/assign-cpu-ram-container.md - docs/tasks/configure-pod-container/configure-volume-storage.md - docs/tasks/configure-pod-container/configure-persistent-volume-storage.md + - docs/tasks/configure-pod-container/environment-variable-expose-pod-information.md - docs/tasks/configure-pod-container/distribute-credentials-secure.md - docs/tasks/configure-pod-container/pull-image-private-registry.md - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md diff --git a/_includes/1-5-beta.md b/_includes/1-5-beta.md new file mode 100644 index 0000000000..abccaa303c --- /dev/null +++ b/_includes/1-5-beta.md @@ -0,0 +1 @@ +***NOTE: This feature is beta in Kubernetes 1.5.*** \ No newline at end of file diff --git a/_includes/v1.5/v1-definitions.html b/_includes/v1.5/v1-definitions.html index faaa0e847d..16858392bc 100755 --- a/_includes/v1.5/v1-definitions.html +++ b/_includes/v1.5/v1-definitions.html @@ -8146,7 +8146,7 @@ The resulting set of endpoints can be viewed as:

unschedulable

-

Unschedulable controls node schedulability of new pods. By default, node is schedulable. More info: http://releases.k8s.io/HEAD/docs/admin/node.md#manual-node-administration"

+

Unschedulable controls node schedulability of new pods. By default, node is schedulable. More info: http://releases.k8s.io/HEAD/docs/admin/node.md#manual-node-administration

false

boolean

false

@@ -8263,4 +8263,4 @@ Last updated 2016-11-17 06:26:10 UTC - \ No newline at end of file + diff --git a/_sass/_base.sass b/_sass/_base.sass index 3ad4f81dc5..72557bb983 100644 --- a/_sass/_base.sass +++ b/_sass/_base.sass @@ -856,6 +856,7 @@ dd display: block margin: 20px 0 padding: 15px + position: relative overflow-x: auto h1 code, h2 code, h3 code, h4 code, h5 code, h6 code diff --git a/docs/admin/addons.md b/docs/admin/addons.md index aeee68cc30..fc1c4ec83c 100644 --- a/docs/admin/addons.md +++ b/docs/admin/addons.md @@ -14,6 +14,7 @@ Add-ons in each section are sorted alphabetically - the ordering does not imply * [Calico](http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/) is a secure L3 networking and network policy provider. * [Canal](https://github.com/tigera/canal/tree/master/k8s-install/kubeadm) unites Flannel and Calico, providing networking and network policy. +* [Contiv](http://contiv.github.io) provides configurable networking (native L3 using BGP, overlay using vxlan, classic L2, and Cisco-SDN/ACI) for various use cases and a rich policy framework. Contiv project is fully [open sourced](http://github.com/contiv). The [installer](http://github.com/contiv/install) provides both kubeadm and non-kubeadm based installation options. * [Flannel](https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml) is an overlay network provider that can be used with Kubernetes. * [Romana](http://romana.io) is a Layer 3 networking solution for pod networks that also supports the [NetworkPolicy API](/docs/user-guide/networkpolicies/). Kubeadm add-on installation details available [here](https://github.com/romana/romana/tree/master/containerize). * [Weave Net](https://www.weave.works/docs/net/latest/kube-addon/) provides networking and network policy, will carry on working on both sides of a network partition, and does not require an external database. diff --git a/docs/admin/authorization.md b/docs/admin/authorization.md index d398bba2c8..e5c091b772 100644 --- a/docs/admin/authorization.md +++ b/docs/admin/authorization.md @@ -221,20 +221,20 @@ don't already have even when the RBAC authorizer it disabled__. If "user-1" does not have the ability to read secrets in "namespace-a", they cannot create a binding that would grant that permission to themselves or any other user. -For bootstrapping the first roles, it becomes necessary for someone to get -around these limitations. For the alpha release of RBAC, an API Server flag was -added to allow one user to step around all RBAC authorization and privilege -escalation checks. NOTE: _This is subject to change with future releases._ +When bootstrapping, superuser credentials should include the `system:masters` +group, for example by creating a client cert with `/O=system:masters`. This +gives those credentials full access to the API and allows an admin to then set +up bindings for other users. + +In Kubernetes versions 1.4 and 1.5, there was a similar flag that gave a user +full access: ``` --authorization-rbac-super-user=admin ``` -Once set the specified super user, in this case "admin", can be used to create -the roles and role bindings to initialize the system. - -This flag is optional and once the initial bootstrapping is performed can be -unset. +__This flag will be removed in 1.6__. Admins should prefer the `system:masters` +group when setting up clusters. ### Roles, RolesBindings, ClusterRoles, and ClusterRoleBindings @@ -445,6 +445,7 @@ subjects: ``` For all authenticated users: + ```yaml subjects: - kind: Group @@ -452,6 +453,7 @@ subjects: ``` For all unauthenticated users: + ```yaml subjects: - kind: Group @@ -459,6 +461,7 @@ subjects: ``` For all users: + ```yaml subjects: - kind: Group diff --git a/docs/admin/federation/kubefed.md b/docs/admin/federation/kubefed.md index 9685271b85..695edf7bee 100644 --- a/docs/admin/federation/kubefed.md +++ b/docs/admin/federation/kubefed.md @@ -36,7 +36,7 @@ in your `$PATH` and set the executable permission on those binaries. Note: The URL in the curl command below downloads the binaries for Linux amd64. If you are on a different platform, please use the URL for the binaries appropriate for your platform. You can find the list -of available binaries on the [release page](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#client-binaries-3) +of available binaries on the [release page](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#client-binaries-3). ```shell diff --git a/docs/admin/kubeadm.md b/docs/admin/kubeadm.md index 1014ee1ab6..edf9c87a7d 100644 --- a/docs/admin/kubeadm.md +++ b/docs/admin/kubeadm.md @@ -191,6 +191,7 @@ available as configuration file options. externalDNSNames: - - + authorizationMode: cloudProvider: discovery: bindPort: diff --git a/docs/admin/kubelet.md b/docs/admin/kubelet.md index 258db1e3aa..4a57e00d60 100644 --- a/docs/admin/kubelet.md +++ b/docs/admin/kubelet.md @@ -96,7 +96,7 @@ StreamingProxyRedirects=true|false (ALPHA - default=false) --google-json-key string The Google Cloud Platform Service Account JSON Key to use for authentication. --hairpin-mode string How should the kubelet setup hairpin NAT. This allows endpoints of a Service to loadbalance back to themselves if they should try to access their own Service. Valid values are "promiscuous-bridge", "hairpin-veth" and "none". (default "promiscuous-bridge") --healthz-bind-address ip The IP address for the healthz server to serve on, defaulting to 127.0.0.1 (set to 0.0.0.0 for all interfaces) (default 127.0.0.1) - --healthz-port int32 The port of the localhost healthz endpoint (default 10248) + --healthz-port int32 (Deprecated) The port of the localhost healthz endpoint (default 10248) --host-ipc-sources stringSlice Comma-separated list of sources from which the Kubelet allows pods to use the host ipc namespace. [default="*"] (default [*]) --host-network-sources stringSlice Comma-separated list of sources from which the Kubelet allows pods to use of host network. [default="*"] (default [*]) --host-pid-sources stringSlice Comma-separated list of sources from which the Kubelet allows pods to use the host pid namespace. [default="*"] (default [*]) @@ -137,7 +137,7 @@ StreamingProxyRedirects=true|false (ALPHA - default=false) --pods-per-core int32 Number of Pods per core that can run on this Kubelet. The total number of Pods on this Kubelet cannot exceed max-pods, so max-pods will be used if this calculation results in a larger number of Pods allowed on the Kubelet. A value of 0 disables this limit. --port int32 The port for the Kubelet to serve on. (default 10250) --protect-kernel-defaults Default kubelet behaviour for kernel tuning. If set, kubelet errors if any of kernel tunables is different than kubelet defaults. - --read-only-port int32 The read-only port for the Kubelet to serve on with no authentication/authorization (set to 0 to disable) (default 10255) + --read-only-port int32 The read-only port for the Kubelet to serve on with no authentication/authorization, and for localhost healthz endpoint (set to 0 to disable) (default 10255) --really-crash-for-testing If true, when panics occur crash. Intended for testing. --register-node Register the node with the apiserver (defaults to true if --api-servers is set) (default true) --register-schedulable Register the node as schedulable. Won't have any effect if register-node is false. [default=true] (default true) diff --git a/docs/admin/limitrange/index.md b/docs/admin/limitrange/index.md index 3a31b9e732..82bed781f1 100644 --- a/docs/admin/limitrange/index.md +++ b/docs/admin/limitrange/index.md @@ -30,7 +30,7 @@ This example demonstrates how limits can be applied to a Kubernetes [namespace]( min/max resource limits per pod. In addition, this example demonstrates how you can apply default resource limits to pods in the absence of an end-user specified value. -See [LimitRange design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/admission_control_limit_range.md) for more information. For a detailed description of the Kubernetes resource model, see [Resources](/docs/user-guide/compute-resources/) +See [LimitRange design doc](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/admission_control_limit_range.md) for more information. For a detailed description of the Kubernetes resource model, see [Resources](/docs/user-guide/compute-resources/) ## Step 0: Prerequisites diff --git a/docs/admin/multiple-schedulers.md b/docs/admin/multiple-schedulers.md index bf7386e492..3e3b4d270b 100644 --- a/docs/admin/multiple-schedulers.md +++ b/docs/admin/multiple-schedulers.md @@ -61,7 +61,7 @@ config. Save it as `my-scheduler.yaml`: {% include code.html language="yaml" file="multiple-schedulers/my-scheduler.yaml" ghlink="/docs/admin/multiple-schedulers/my-scheduler.yaml" %} An important thing to note here is that the name of the scheduler specified as an -argument to the scheduler command in the container spec should be unique. This is the name that is matched against the value of the optional `scheduler.alpha.kubernetes.io/name` annotation on pods, to determine whether this scheduler is responsible for scheduling a particular pod. +argument to the scheduler command in the container spec should be unique. This is the name that is matched against the value of the optional `spec.schedulername` on pods, to determine whether this scheduler is responsible for scheduling a particular pod. Please see the [kube-scheduler documentation](/docs/admin/kube-scheduler/) for @@ -92,14 +92,14 @@ pod in this list. ### 4. Specify schedulers for pods Now that our second scheduler is running, let's create some pods, and direct them to be scheduled by either the default scheduler or the one we just deployed. In order to schedule a given pod using a specific scheduler, we specify the name of the -scheduler as an annotation in that pod spec. Let's look at three examples. +scheduler in that pod spec. Let's look at three examples. -1. Pod spec without any scheduler annotation +1. Pod spec without any scheduler name {% include code.html language="yaml" file="multiple-schedulers/pod1.yaml" ghlink="/docs/admin/multiple-schedulers/pod1.yaml" %} - When no scheduler annotation is supplied, the pod is automatically scheduled using the + When no scheduler name is supplied, the pod is automatically scheduled using the default-scheduler. Save this file as `pod1.yaml` and submit it to the Kubernetes cluster. @@ -108,12 +108,11 @@ scheduler as an annotation in that pod spec. Let's look at three examples. kubectl create -f pod1.yaml ``` -2. Pod spec with `default-scheduler` annotation +2. Pod spec with `default-scheduler` {% include code.html language="yaml" file="multiple-schedulers/pod2.yaml" ghlink="/docs/admin/multiple-schedulers/pod2.yaml" %} - A scheduler is specified by supplying the scheduler name as a value to the annotation - with key `scheduler.alpha.kubernetes.io/name`. In this case, we supply the name of the + A scheduler is specified by supplying the scheduler name as a value to `spec.schedulername`. In this case, we supply the name of the default scheduler which is `default-scheduler`. Save this file as `pod2.yaml` and submit it to the Kubernetes cluster. @@ -122,13 +121,12 @@ scheduler as an annotation in that pod spec. Let's look at three examples. kubectl create -f pod2.yaml ``` -3. Pod spec with `my-scheduler` annotation +3. Pod spec with `my-scheduler` {% include code.html language="yaml" file="multiple-schedulers/pod3.yaml" ghlink="/docs/admin/multiple-schedulers/pod3.yaml" %} In this case, we specify that this pod should be scheduled using the scheduler that we - deployed - `my-scheduler`. Note that the value of the annotation with key - `scheduler.alpha.kubernetes.io/name` should match the name supplied to the scheduler + deployed - `my-scheduler`. Note that the value of `spec.schedulername` should match the name supplied to the scheduler command as an argument in the deployment config for the scheduler. Save this file as `pod3.yaml` and submit it to the Kubernetes cluster. @@ -149,9 +147,9 @@ In order to make it easier to work through these examples, we did not verify tha pods were actually scheduled using the desired schedulers. We can verify that by changing the order of pod and deployment config submissions above. If we submit all the pod configs to a Kubernetes cluster before submitting the scheduler deployment config, -we see that the pod `annotation-second-scheduler` remains in "Pending" state forever +we see that the pod `second-scheduler` remains in "Pending" state forever while the other two pods get scheduled. Once we submit the scheduler deployment config -and our new scheduler starts running, the `annotation-second-scheduler` pod gets +and our new scheduler starts running, the `second-scheduler` pod gets scheduled as well. Alternatively, one could just look at the "Scheduled" entries in the event logs to diff --git a/docs/admin/multiple-schedulers/pod2.yaml b/docs/admin/multiple-schedulers/pod2.yaml index 2f9fdf9875..26b0376967 100644 --- a/docs/admin/multiple-schedulers/pod2.yaml +++ b/docs/admin/multiple-schedulers/pod2.yaml @@ -2,11 +2,10 @@ apiVersion: v1 kind: Pod metadata: name: annotation-default-scheduler - annotations: - scheduler.alpha.kubernetes.io/name: default-scheduler labels: name: multischeduler-example spec: + schedulername: default-scheduler containers: - name: pod-with-default-annotation-container image: gcr.io/google_containers/pause:2.0 \ No newline at end of file diff --git a/docs/admin/multiple-schedulers/pod3.yaml b/docs/admin/multiple-schedulers/pod3.yaml index 52276df5f6..e64070abfa 100644 --- a/docs/admin/multiple-schedulers/pod3.yaml +++ b/docs/admin/multiple-schedulers/pod3.yaml @@ -2,11 +2,10 @@ apiVersion: v1 kind: Pod metadata: name: annotation-second-scheduler - annotations: - scheduler.alpha.kubernetes.io/name: my-scheduler labels: name: multischeduler-example spec: + schedulername: my-scheduler containers: - name: pod-with-second-annotation-container image: gcr.io/google_containers/pause:2.0 \ No newline at end of file diff --git a/docs/concepts/abstractions/init-containers.md b/docs/concepts/abstractions/init-containers.md new file mode 100644 index 0000000000..1bea00b3a2 --- /dev/null +++ b/docs/concepts/abstractions/init-containers.md @@ -0,0 +1,184 @@ +--- +assignees: +- erictune +title: Init Containers +--- + +{% capture overview %} +This page provides an overview of Init Containers, which are specialized +Containers that run before app Containers and can contain utilities or setup +scripts not present in an app image. +{% endcapture %} + +{:toc} + +{% include 1-5-beta.md %} + +**Once the feature exits beta, Init Containers will be specified in the PodSpec +alongside the app `containers` array.** + +{% capture body %} +## Understanding Init Containers + +A [Pod](/docs/concepts/abstractions/pod/) can have multiple Containers running +apps within it, but it can also have one or more Init Containers, which are run +before the app Containers are started. + +Init Containers are exactly like regular Containers, except: + +* They always run to completion. +* Each one must complete successfully before the next one is started. + +If an Init Container fails for a Pod, Kubernetes restarts the Pod repeatedly until the Init +Container succeeds. However, if the Pod has a `restartPolicy` of Never, it is not restarted. + +To specify a Container as an Init Container, add the `annotations` key +`pod.beta.kubernetes.io/init-containers`. Its value should be a +JSON array of objects of type +[Container](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_container). + +The status of an Init Container is returned as another annotation, +`pod.beta.kubernetes.io/init-container-statuses`, which is an array of +container statuses similar to the `status.containerStatuses` field. + +### Differences from regular Containers + +Init Containers support all the fields and features of app Containers, +including resource limits, volumes, and security settings. However, the +resource requests and limits for an Init Container are handled slightly +differently, which are documented in [Resources](#resources) below. Also, Init Containers do not +support readiness probes because they must run to completion before the Pod can +be ready. + +If multiple Init Containers are specified for a Pod, those Containers are run +one at a time in sequential order. Each must succeed before the next can run. +When all of the Init Containers have run to completion, Kubernetes initializes +the Pod and runs the application Containers as usual. + +## What can Init Containers be used for? + +Because Init Containers have separate images from app Containers, they +have some advantages for start-up related code: + +* They can contain and run utilities that are not desirable to include in the + app Container image for security reasons. +* They can contain utilities or custom code for setup that is not present in an app + image. For example, there is no need to make an image `FROM` another image just to use a tool like + `sed`, `awk`, `python`, or `dig` during setup. +* The application image builder and deployer roles can work independently without + the need to jointly build a single app image. +* They use Linux namespaces so they have a different filesystem view from app Containers. + Consequently, they can be given access to Secrets that app Containers are not able to + access. +* They run to completion before any app Containers start, whereas app + Containers run in parallel, so Init Containers provide an easy way to block or + delay the startup of app Containers until some set of preconditions are met. + +### Examples +Here are some ideas for how to use Init Containers: + +* Wait for a service to be created with a shell command like: + + for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; exit 1 + +* Register this Pod with a remote server from the downward API with a command like: + + curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d 'instance=$()&ip=$()' + +* Wait for some time before starting the app Container with a command like `sleep 60`. +* Clone a git repository into a volume. +* Place values into a configuration file and run a template tool to dynamically + generate a configuration file for the the main app Container. For example, + place the POD_IP value in a configuration and generate the main app + configuration file using Jinja. + +More detailed usage examples can be found in the [StatefulSets documentation](/docs/concepts/abstractions/controllers/statefulsets/) +and the [Production Pods guide](/docs/user-guide/production-pods.md#handling-initialization). + +## Detailed behavior + +During the startup of a Pod, the Init Containers are started in order, after the +network and volumes are initialized. Each Container must exit successfully before +the next is started. If a Container fails to start due to the runtime or +exits with failure, it is retried according to the Pod `restartPolicy`. However, +if the Pod `restartPolicy` is set to Always, the Init Containers use +`RestartPolicy` OnFailure. + +A Pod cannot be `Ready` until all Init Containers have succeeded. The ports on an +Init Container are not aggregated under a service. A Pod that is initializing +is in the `Pending` state but should have a condition `Initializing` set to true. + +If the Pod is [restarted](#pod-restart-reasons), all Init Containers must +execute again. + +Changes to the Init Container spec are limited to the container image field. +Altering an Init Container image field is equivalent to restarting the Pod. + +Because Init Containers can be restarted, retried, or re-executed, Init Container +code should be idempotent. In particular, code that writes to files on `EmptyDirs` +should be prepared for the possibility that an output file already exists. + +Init Containers have all of the fields of an app Container. However, Kubernetes +prohibits `readinessProbe` from being used because Init Containers cannot +define readiness distinct from completion. This is enforced during validation. + +Use `activeDeadlineSeconds` on the Pod and `livenessProbe` on the Container to +prevent Init Containers from failing forever. The active deadline includes Init +Containers. + +The name of each app and Init Container in a Pod must be unique; a +validation error is thrown for any Container sharing a name with another. + +### Resources + +Given the ordering and execution for Init Containers, the following rules +for resource usage apply: + +* The highest of any particular resource request or limit defined on all Init + Containers is the *effective init request/limit* +* The Pod's *effective request/limit* for a resource is the higher of: + * the sum of all app Containers request/limit for a resource + * the effective init request/limit for a resource +* Scheduling is done based on effective requests/limits, which means + Init Containers can reserve resources for initialization that are not used + during the life of the Pod. +* QoS tier of the Pod's *effective QoS tier* is the QoS tier for Init Containers + and app containers alike. + +Quota and limits are applied based on the effective Pod request and +limit. + +Pod level cgroups are based on the effective Pod request and limit, the +same as the scheduler. + + +### Pod restart reasons + +A Pod can restart, causing re-execution of Init Containers, for the following +reasons: + +* A user updates the PodSpec causing the Init Container image to change. + App Container image changes only restart the app Container. +* The Pod infrastructure container is restarted. This is uncommon and would + have to be done by someone with root access to nodes. +* All containers in a Pod are terminated while `restartPolicy` is set to Always, + forcing a restart, and the Init Container completion record has been lost due + to garbage collection. + +## Support and compatibility + +A cluster with Kubelet and Apiserver version 1.4.0 or greater supports Init +Containers with the beta annotations. Support varies for other combinations of +Kubelet and Apiserver versions; see the [release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md) for details. + +{% endcapture %} + + +{% capture whatsnext %} + +* [Creating a Pod that has an Init Container](/docs/tasks/configure-pod-container/configure-pod-initialization/#creating-a-pod-that-has-an-init-container) + +{% endcapture %} + + +{% include templates/concept.md %} \ No newline at end of file diff --git a/docs/concepts/abstractions/pod.md b/docs/concepts/abstractions/pod.md index 07f0d18934..f8b9cf2f72 100644 --- a/docs/concepts/abstractions/pod.md +++ b/docs/concepts/abstractions/pod.md @@ -41,7 +41,7 @@ Pods provide two kinds of shared resources for their constituent containers: *ne #### Networking -Each Pod is assigned a unique IP address. Every the container in a Pod shares the network namespace, including the IP address and network ports. Containers *inside a Pod* can communicate with one another using `localhost`. When containers in a Pod communicate with entities *outside the Pod*, they must coordinate how they use the shared network resources (such as ports). +Each Pod is assigned a unique IP address. Every container in a Pod shares the network namespace, including the IP address and network ports. Containers *inside a Pod* can communicate with one another using `localhost`. When containers in a Pod communicate with entities *outside the Pod*, they must coordinate how they use the shared network resources (such as ports). #### Storage diff --git a/docs/concepts/configuration/container-command-args.md b/docs/concepts/configuration/container-command-args.md index 54fe3afcb9..25d555f702 100644 --- a/docs/concepts/configuration/container-command-args.md +++ b/docs/concepts/configuration/container-command-args.md @@ -13,7 +13,7 @@ fields to override the default Entrypoint and Cmd of the the Container's image. ## Container entry points and arguments -The configuration file for a Container has an `image` field that specifies the +The configuration file for a Container has an `image` field that specifies the Docker image to be run in the Container. A Docker image has metadata that includes a default Entrypoint and a default Cmd. diff --git a/docs/concepts/tools/kubectl/object-management-using-declarative-config.md b/docs/concepts/tools/kubectl/object-management-using-declarative-config.md index 5033bbac8c..6c8dfbd250 100644 --- a/docs/concepts/tools/kubectl/object-management-using-declarative-config.md +++ b/docs/concepts/tools/kubectl/object-management-using-declarative-config.md @@ -382,7 +382,7 @@ is used to identify fields that have been removed from the configuration file and need to be cleared from the live configuration. Here are the steps used to caluculate which fields should be deleted or set: -1. Calculate the fields to delete. Thes are the fields present in `last-applied-configuration` and missing from the configuration file. +1. Calculate the fields to delete. These are the fields present in `last-applied-configuration` and missing from the configuration file. 2. Calculate the fields to add or set. These are the fields present in the configuration file whose values don't match the live configuration. Here's an example. Suppose this is the configuration file for a Deployment object: diff --git a/docs/contribute/stage-documentation-changes.md b/docs/contribute/stage-documentation-changes.md index 452c38170c..48d28aad15 100644 --- a/docs/contribute/stage-documentation-changes.md +++ b/docs/contribute/stage-documentation-changes.md @@ -90,6 +90,14 @@ web server: 1. View your staged content at [http://localhost:4000](http://localhost:4000){: target="_blank"}. +NOTE: If you do not want Jekyll to interfere with your other globally installed gems, you can use `bundler`: + + gem install bundler + bundle install + bundler exec jekyll serve + + Regardless of whether you use `bundler` or not, your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000) + {% endcapture %} {% capture whatsnext %} diff --git a/docs/getting-started-guides/kubeadm.md b/docs/getting-started-guides/kubeadm.md index a005ed0c56..a4e5679ffb 100644 --- a/docs/getting-started-guides/kubeadm.md +++ b/docs/getting-started-guides/kubeadm.md @@ -357,6 +357,6 @@ Please note: `kubeadm` is a work in progress and these limitations will be addre 1. If you are using VirtualBox (directly or via Vagrant), you will need to ensure that `hostname -i` returns a routable IP address (i.e. one on the second network interface, not the first one). By default, it doesn't do this and kubelet ends-up using first non-loopback network interface, which is usually NATed. - Workaround: Modify `/etc/hosts`, take a look at this [`Vagrantfile`][ubuntu-vagrantfile] for how you this can be achieved. + Workaround: Modify `/etc/hosts`, take a look at this [`Vagrantfile`][ubuntu-vagrantfile] for how this can be achieved. [ubuntu-vagrantfile]: https://github.com/errordeveloper/k8s-playground/blob/22dd39dfc06111235620e6c4404a96ae146f26fd/Vagrantfile#L11), diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index 4f4a432185..e0e79364cf 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -40,7 +40,7 @@ See the installation instructions for the [latest release](https://github.com/ku ## Quickstart Here's a brief demo of minikube usage. -If you want to change the VM driver add the appropriate `--vm-driver=xxx` flag to `minikube start`. Minikube Supports +If you want to change the VM driver add the appropriate `--vm-driver=xxx` flag to `minikube start`. Minikube supports the following drivers: * virtualbox @@ -106,7 +106,7 @@ plugins, if required. When using a single VM of Kubernetes, it's really handy to reuse the minikube's built-in Docker daemon; as this means you don't have to build a docker registry on your host machine and push the image into it - you can just build inside the same docker daemon as minikube which speeds up local experiments. Just make sure you tag your Docker image with something other than 'latest' and use that tag while you pull the image. Otherwise, if you do not specify version of your image, it will be assumed as `:latest`, with pull image policy of `Always` correspondingly, which may eventually result in `ErrImagePull` as you may not have any versions of your Docker image out there in the default docker registry (usually DockerHub) yet. -To be able to work with the docker daemon on your mac/linux host use the [docker-env command](./docs/minikube_docker-env.md) in your shell: +To be able to work with the docker daemon on your mac/linux host use the [docker-env command](https://github.com/kubernetes/minikube/blob/master/docs/minikube_docker-env.md) in your shell: ``` eval $(minikube docker-env) diff --git a/docs/getting-started-guides/ubuntu/backups.md b/docs/getting-started-guides/ubuntu/backups.md index 9c0c741d9b..b839cafee4 100644 --- a/docs/getting-started-guides/ubuntu/backups.md +++ b/docs/getting-started-guides/ubuntu/backups.md @@ -3,7 +3,7 @@ title: Backups --- {% capture overview %} -This pages shows you how to backup and restore data from the different deployed services in a given cluster. +This page shows you how to backup and restore data from the different deployed services in a given cluster. {% endcapture %} {% capture prerequisites %} diff --git a/docs/getting-started-guides/vsphere.md b/docs/getting-started-guides/vsphere.md index ba07d14890..61ea733bf3 100644 --- a/docs/getting-started-guides/vsphere.md +++ b/docs/getting-started-guides/vsphere.md @@ -69,6 +69,7 @@ Sample Config: datacenter = datastore = working-dir = + vm-uuid = [Disk] scsicontrollertype = pvscsi ``` diff --git a/docs/tasks/configure-pod-container/assign-cpu-ram-container.md b/docs/tasks/configure-pod-container/assign-cpu-ram-container.md index 24cca3eca5..fc62af79d9 100644 --- a/docs/tasks/configure-pod-container/assign-cpu-ram-container.md +++ b/docs/tasks/configure-pod-container/assign-cpu-ram-container.md @@ -4,7 +4,7 @@ title: Assigning CPU and RAM Resources to a Container {% capture overview %} -This page shows how assign CPU and RAM resources to containers running +This page shows how to assign CPU and RAM resources to containers running in a Kubernetes Pod. {% endcapture %} diff --git a/docs/tasks/configure-pod-container/dapi-envars-container.yaml b/docs/tasks/configure-pod-container/dapi-envars-container.yaml new file mode 100644 index 0000000000..8b3b3a39d3 --- /dev/null +++ b/docs/tasks/configure-pod-container/dapi-envars-container.yaml @@ -0,0 +1,45 @@ +apiVersion: v1 +kind: Pod +metadata: + name: dapi-envars-resourcefieldref +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox:1.24 + command: [ "sh", "-c"] + args: + - while true; do + echo -en '\n'; + printenv MY_CPU_REQUEST MY_CPU_LIMIT; + printenv MY_MEM_REQUEST MY_MEM_LIMIT; + sleep 10; + done; + resources: + requests: + memory: "32Mi" + cpu: "125m" + limits: + memory: "64Mi" + cpu: "250m" + env: + - name: MY_CPU_REQUEST + valueFrom: + resourceFieldRef: + containerName: test-container + resource: requests.cpu + - name: MY_CPU_LIMIT + valueFrom: + resourceFieldRef: + containerName: test-container + resource: limits.cpu + - name: MY_MEM_REQUEST + valueFrom: + resourceFieldRef: + containerName: test-container + resource: requests.memory + - name: MY_MEM_LIMIT + valueFrom: + resourceFieldRef: + containerName: test-container + resource: limits.memory + restartPolicy: Never diff --git a/docs/tasks/configure-pod-container/dapi-envars-pod.yaml b/docs/tasks/configure-pod-container/dapi-envars-pod.yaml new file mode 100644 index 0000000000..00762373b3 --- /dev/null +++ b/docs/tasks/configure-pod-container/dapi-envars-pod.yaml @@ -0,0 +1,38 @@ +apiVersion: v1 +kind: Pod +metadata: + name: dapi-envars-fieldref +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "sh", "-c"] + args: + - while true; do + echo -en '\n'; + printenv MY_NODE_NAME MY_POD_NAME MY_POD_NAMESPACE; + printenv MY_POD_IP MY_POD_SERVICE_ACCOUNT; + sleep 10; + done; + env: + - name: MY_NODE_NAME + valueFrom: + fieldRef: + fieldPath: spec.nodeName + - name: MY_POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: MY_POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: MY_POD_IP + valueFrom: + fieldRef: + fieldPath: status.podIP + - name: MY_POD_SERVICE_ACCOUNT + valueFrom: + fieldRef: + fieldPath: spec.serviceAccountName + restartPolicy: Never diff --git a/docs/tasks/configure-pod-container/environment-variable-expose-pod-information.md b/docs/tasks/configure-pod-container/environment-variable-expose-pod-information.md new file mode 100644 index 0000000000..1390727000 --- /dev/null +++ b/docs/tasks/configure-pod-container/environment-variable-expose-pod-information.md @@ -0,0 +1,163 @@ +--- +title: Exposing Pod Information to Containers Through Environment Variables +--- + +{% capture overview %} + +This page shows how a Pod can use environment variables to expose information +about itself to Containers running in the Pod. Environment variables can expose +Pod fields and Container fields. + +There are two ways to expose Pod and Container fields to a running Container: +environment variables and +[DownwardAPIVolumeFiles](/docs/resources-reference/v1.5/#downwardapivolumefile-v1). +Together, these two ways of exposing Pod and Container fields are called the +*Downward API*. + +{% endcapture %} + + +{% capture prerequisites %} + +{% include task-tutorial-prereqs.md %} + +{% endcapture %} + + +{% capture steps %} + +## Using Pod fields as values for environment variables + +In this exercise, you create a Pod that has one Container. Here is the +configuration file for the Pod: + +{% include code.html language="yaml" file="dapi-envars-pod.yaml" ghlink="/docs/tasks/configure-pod-container/dapi-envars-pod.yaml" %} + +In the configuration file, you can see five environment variables. The `env` +field is an array of +[EnvVars](/docs/resources-reference/v1.5/#envvar-v1). +The first element in the array specifies that the `MY_NODE_NAME` environment +variable gets its value from the Pod's `spec.nodeName` field. Similarly, the +other environment variables get their names from Pod fields. + +**Note**: The fields in this example are Pod fields. They are not fields of the +Container in the Pod. + +Create the Pod: + +```shell +kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/dapi-envars-pod.yaml +``` + +Verify that the Container in the Pod is running: + +``` +kubectl get pods +``` + +View the Container's logs: + +``` +kubectl logs dapi-envars-fieldref +``` + +The output shows the values of selected environment variables: + +``` +minikube +dapi-envars-fieldref +default +172.17.0.4 +default +``` + +To see why these values are in the log, look at the `command` and `args` fields +in the configuration file. When the Container starts, it writes the values of +five environment variables to stdout. It repeats this every ten seconds. + +Next, get a shell into the Container that is running in your Pod: + +``` +kubectl exec -it dapi-envars-fieldref -- sh +``` + +In your shell, view the environment variables: + +``` +/# printenv +``` + +The output shows that certain environment variables have been assigned the +values of Pod fields: + +``` +MY_POD_SERVICE_ACCOUNT=default +... +MY_POD_NAMESPACE=default +MY_POD_IP=172.17.0.4 +... +MY_NODE_NAME=minikube +... +MY_POD_NAME=dapi-envars-fieldref +``` + +## Using Container fields as values for environment variables + +In the preceding exercise, you used Pod fields as the values for environment +variables. In this next exercise, you use Container fields as the values for +environment variables. Here is the configuration file for a Pod that has one +container: + +{% include code.html language="yaml" file="dapi-envars-container.yaml" ghlink="/docs/tasks/configure-pod-container/dapi-envars-container.yaml" %} + +In the configuration file, you can see four environment variables. The `env` +field is an array of +[EnvVars](/docs/resources-reference/v1.5/#envvar-v1). +The first element in the array specifies that the `MY_CPU_REQUEST` environment +variable gets its value from the `requests.cpu` field of a Container named +`test-container`. Similarly, the other environment variables get their values +from Container fields. + +Create the Pod: + +```shell +kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/dapi-envars-container.yaml +``` + +Verify that the Container in the Pod is running: + +``` +kubectl get pods +``` + +View the Container's logs: + +``` +kubectl logs dapi-envars-resourcefieldref +``` + +The output shows the values of selected environment variables: + +``` +1 +1 +33554432 +67108864 +``` + +{% endcapture %} + +{% capture whatsnext %} + +* [Defining Environment Variables for a Container](/docs/tasks/configure-pod-container/define-environment-variable-container/) +* [PodSpec](/docs/resources-reference/v1.5/#podspec-v1) +* [Container](/docs/resources-reference/v1.5/#container-v1) +* [EnvVar](/docs/resources-reference/v1.5/#envvar-v1) +* [EnvVarSource](/docs/resources-reference/v1.5/#envvarsource-v1) +* [ObjectFieldSelector](/docs/resources-reference/v1.5/#objectfieldselector-v1) +* [ResourceFieldSelector](/docs/resources-reference/v1.5/#resourcefieldselector-v1) + +{% endcapture %} + + +{% include templates/task.md %} diff --git a/docs/tasks/kubectl/list-all-running-container-images.md b/docs/tasks/kubectl/list-all-running-container-images.md new file mode 100644 index 0000000000..4fb64ee442 --- /dev/null +++ b/docs/tasks/kubectl/list-all-running-container-images.md @@ -0,0 +1,122 @@ +--- +title: Listing all Container images running in the cluster +--- + +{% capture overview %} + +This page shows how to use kubectl to list all of the Container images +for Pods running in a cluster. + +{% endcapture %} + +{% capture prerequisites %} + +{% include task-tutorial-prereqs.md %} + +{% endcapture %} + +{% capture steps %} + +In this exercise you will use kubectl to fetch all of the Pods +running in a cluster, and format the output to pull out the list +of Containers for each. + +## List all Containers in all namespaces + +- Fetch all Pods in all namespaces using `kubectl get pods --all-namespaces` +- Format the output to include only the list of Container image names + using `-o jsonpath={..image}`. This will recursively parse out the + `image` field from the returned json. + - See the [jsonpath reference](/docs/user-guide/jsonpath/) + for further information on how to use jsonpath. +- Format the output using standard tools: `tr`, `sort`, `uniq` + - Use `tr` to replace spaces with newlines + - Use `sort` to sort the results + - Use `uniq` to aggregate image counts + +```sh +kubectl get pods --all-namespaces -o jsonpath="{..image}" |\ +tr -s '[[:space:]]' '\n' |\ +sort |\ +uniq -c +``` + +The above command will recursively return all fields named `image` +for all items returned. + +As an alternative, it is possible to use the absolute path to the image +field within the Pod. This ensures the correct field is retrieved +in the even the field name is repeated, +e.g. many fields are called `name` within a given item: + +```sh +kubectl get pods --all-namespaces -o jsonpath="{.items[*].spec.containers[*].image}" +``` + +The jsonpath is interpreted as follows: + +- `.items[*]`: for each returned value +- `.spec`: get the spec +- `.containers[*]`: for each container +- `.image`: get the image + +**Note:** When fetching a single Pod by name, e.g. `kubect get pod nginx`, +the `.items[*]` portion of the path should be omitted because a single +Pod is returned instead of a list of items. + +## List Containers by Pod + +The formatting can be controlled further by using the `range` operation to +iterate over elements individually. + +```sh +kubectl get pods --all-namespaces -o=jsonpath='{range .items[*]}{"\n"}{.metadata.name}{":\t"}{range .spec.containers[*]}{.image}{", "}{end}{end}' |\ +sort +``` + +## List Containers filtering by Pod label + +To target only Pods matching a specific label, use the -l flag. The +following matches only Pods with labels matching `app=nginx`. + +```sh +kubectl get pods --all-namespaces -o=jsonpath="{..image}" -l app=nginx +``` + +## List Containers filtering by Pod namespace + +To target only pods in a specific namespace, use the namespace flag. The +following matches only Pods in the `kube-system` namespace. + +```sh +kubectl get pods --namespace kube-system -o jsonpath="{..image}" +``` + +## List Containers using a go-template instead of jsonpath + +As an alternative to jsonpath, Kubectl supports using [go-templates](https://golang.org/pkg/text/template/) +for formatting the output: + +{% raw %} +```sh +kubectl get pods --all-namespaces -o go-template --template="{{range .items}}{{range .spec.containers}}{{.image}} {{end}}{{end}}" +``` +{% endraw %} + + +{% endcapture %} + +{% capture discussion %} + +{% endcapture %} + +{% capture whatsnext %} + +### Reference + +* [Jsonpath](/docs/user-guide/jsonpath/) reference guide +* [Go template](https://golang.org/pkg/text/template/) reference guide + +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tutorials/stateless-application/deployment-scale.yaml b/docs/tutorials/stateless-application/deployment-scale.yaml index 2968b88360..7259c97603 100644 --- a/docs/tutorials/stateless-application/deployment-scale.yaml +++ b/docs/tutorials/stateless-application/deployment-scale.yaml @@ -3,7 +3,7 @@ kind: Deployment metadata: name: nginx-deployment spec: - replicas: 4 + replicas: 4 # Update the replicas from 2 to 4 template: metadata: labels: @@ -11,6 +11,6 @@ spec: spec: containers: - name: nginx - image: nginx:1.8 # Update the version of nginx from 1.7.9 to 1.8 + image: nginx:1.8 ports: - containerPort: 80 diff --git a/docs/user-guide/accessing-the-cluster.md b/docs/user-guide/accessing-the-cluster.md index 8fb9e6b0b4..1f5a65aa61 100644 --- a/docs/user-guide/accessing-the-cluster.md +++ b/docs/user-guide/accessing-the-cluster.md @@ -1,10 +1,10 @@ ---- -assignees: -- lavalamp -- mikedanese -title: Accessing Clusters ---- - +--- +assignees: +- lavalamp +- mikedanese +title: Accessing Clusters +--- + * TOC {:toc} @@ -125,6 +125,7 @@ with future high-availability support. The Kubernetes project-supported Go client library is at [https://github.com/kubernetes/client-go](https://github.com/kubernetes/client-go). To use it, + * To get the library, run the following command: `go get k8s.io/client-go//kubernetes` See [https://github.com/kubernetes/client-go](https://github.com/kubernetes/client-go) to see which versions are supported. * Write an application atop of the client-go clients. Note that client-go defines its own API objects, so if needed, please import API definitions from client-go rather than from the main repository, e.g., `import "k8s.io/client-go/1.4/pkg/api/v1"` is correct. diff --git a/docs/user-guide/debugging-services.md b/docs/user-guide/debugging-services.md index de9cec5c3f..6a1a692e8a 100644 --- a/docs/user-guide/debugging-services.md +++ b/docs/user-guide/debugging-services.md @@ -352,7 +352,7 @@ they are running fine and not crashing. The `-l app=hostnames` argument is a label selector - just like our `Service` has. Inside the Kubernetes system is a control loop which evaluates the -selector of every `Service` and save the results into an `Endpoints` object. +selector of every `Service` and saves the results into an `Endpoints` object. ```shell $ kubectl get endpoints hostnames diff --git a/docs/user-guide/deploying-applications.md b/docs/user-guide/deploying-applications.md index 9bbcd34282..a1c04e1003 100644 --- a/docs/user-guide/deploying-applications.md +++ b/docs/user-guide/deploying-applications.md @@ -6,96 +6,6 @@ assignees: title: Deploying Applications --- -* TOC -{:toc} +{% include user-guide-content-moved.md %} -## Launching a set of replicas using a configuration file - -Kubernetes creates and manages sets of replicated containers (actually, replicated [Pods](/docs/user-guide/pods)) using [*Deployments*](/docs/user-guide/deployments). - -A Deployment simply 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. It's analogous to Google Compute Engine's [Instance Group Manager](https://cloud.google.com/compute/docs/instance-groups/manager/) or AWS's [Auto-scaling Group](http://docs.aws.amazon.com/AutoScaling/latest/DeveloperGuide/AutoScalingGroup.html) (with no scaling policies). - -The Deployment created to run nginx by `kubectl run` in the [Quick start](/docs/user-guide/quick-start) could be specified using YAML as follows: - -{% include code.html language="yaml" file="run-my-nginx.yaml" ghlink="/docs/user-guide/run-my-nginx.yaml" %} - -Some differences compared to specifying just a pod are that the `kind` is `Deployment`, the number of `replicas` desired is specified, and the pod specification is under the `template` field. The names of the pods don't need to be specified explicitly because they are generated from the name of the Deployment. -View the [Deployment API -object](/docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_deployment) -to view the list of supported fields. - -This Deployment can be created using `create`, just as with pods: - -```shell -$ kubectl create -f ./run-my-nginx.yaml -deployment "my-nginx" created -``` - -Unlike in the case where you directly create pods, a Deployment replaces pods that are deleted or terminated for any reason, such as in the case of node failure. For this reason, we recommend that you use a Deployment for a continuously running application even if your application requires only a single pod, in which case you can omit `replicas` and it will default to a single replica. - -## Viewing Deployment status - -You can view the Deployment you created using `get`: - -```shell -$ kubectl get deployment -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -my-nginx 2 2 2 2 6s -``` - -This tells you that your Deployment will ensure that you have two nginx replicas (desired replicas = 2). - -You can see those replicas using `get`, just as with pods you created directly: - -```shell -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -my-nginx-3800858182-9hk43 1/1 Running 0 8m -my-nginx-3800858182-e529s 1/1 Running 0 8m -``` - -## Deleting Deployments - -When you want to kill your application, delete your Deployment, as in the [Quick start](/docs/user-guide/quick-start): - -```shell -$ kubectl delete deployment/my-nginx -deployment "my-nginx" deleted -``` - -By default, this will also cause the pods managed by the Deployment to be deleted. If there were a large number of pods, this may take a while to complete. If you want to leave the pods running instead, specify `--cascade=false`. - -If you try to delete the pods before deleting the Deployments, it will just replace them, as it is supposed to do. - -## Labels - -Kubernetes uses user-defined key-value attributes called [*labels*](/docs/user-guide/labels) to categorize and identify sets of resources, such as pods and Deployments. The example above specified a single label in the pod template, with key `run` and value `my-nginx`. All pods created carry that label, which can be viewed using `-L`: - -```shell -$ kubectl get pods -L run -NAME READY STATUS RESTARTS AGE RUN -my-nginx-3800858182-1v53o 1/1 Running 0 46s my-nginx -my-nginx-3800858182-2ds1q 1/1 Running 0 46s my-nginx -``` - -The labels from the pod template are copied to the Deployment's labels by default, as well -- all resources in Kubernetes support labels: - -```shell -$ kubectl get deployment/my-nginx -L run -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE RUN -my-nginx 2 2 2 2 2m my-nginx -``` - -More importantly, the pod template's labels are used to create a [`selector`](/docs/user-guide/labels/#label-selectors) that will match pods carrying those labels. You can see this field by requesting it using the [Go template output format of `kubectl get`](/docs/user-guide/kubectl/kubectl_get): - -```shell{% raw %} -$ kubectl get deployment/my-nginx -o template --template="{{.spec.selector}}" -map[matchLabels:map[run:my-nginx]]{% endraw %} -``` - -You could also specify the `selector` explicitly, such as if you wanted to specify labels in the pod template that you didn't want to select on, but you should ensure that the selector will match the labels of the pods created from the pod template, and that it won't match pods created by other Deployments. The most straightforward way to ensure the latter is to create a unique label value for the Deployment, and to specify it in both the pod template's labels and in the selector's -matchLabels. - -## What's next? - -[Learn about exposing applications to users and clients, and connecting tiers of your application together.](/docs/user-guide/connecting-applications) +[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/) diff --git a/docs/user-guide/federation/index.md b/docs/user-guide/federation/index.md index 7ba0ca9c60..10cea0ad6e 100644 --- a/docs/user-guide/federation/index.md +++ b/docs/user-guide/federation/index.md @@ -43,7 +43,7 @@ why you might want multiple clusters are: [Multi cluster guide](/docs/admin/multi-cluster) has more details on this. * Scalability: There are scalability limits to a single kubernetes cluster (this should not be the case for most users. For more details: - https://github.com/kubernetes/community/blob/master/sig-scalability/goals.md). + [Kubernetes Scaling and Performance Goals](https://github.com/kubernetes/community/blob/master/sig-scalability/goals.md)). * Hybrid cloud: You can have multiple clusters on different cloud providers or on-premises data centers. @@ -53,7 +53,7 @@ why you might want multiple clusters are: While there are a lot of attractive use cases for federation, there are also some caveats. -* Increased network bandwidth and cost: The dederation control plane watches all +* Increased network bandwidth and cost: The federation control plane watches all clusters to ensure that the current state is as expected. This can lead to significant network cost if the clusters are running in different regions on a cloud provider or on different cloud providers. @@ -93,15 +93,15 @@ Once we have the control plane setup, we can start creating federation API resources. The following guides explain some of the resources in detail: -* [ConfigMap](/docs/user-guide/federation/configmap/) -* [DaemonSets](/docs/user-guide/federation/daemonsets/) -* [Deployment](/docs/user-guide/federation/deployment/) -* [Events](/docs/user-guide/federation/events/) -* [Ingress](/docs/user-guide/federation/federated-ingress/) -* [Namespaces](/docs/user-guide/federation/namespaces/) -* [ReplicaSets](/docs/user-guide/federation/replicasets/) -* [Secrets](/docs/user-guide/federation/secrets/) -* [Services](/docs/user-guide/federation/federated-services/) +* [ConfigMap](https://kubernetes.io/docs/user-guide/federation/configmap/) +* [DaemonSets](https://kubernetes.io/docs/user-guide/federation/daemonsets/) +* [Deployment](https://kubernetes.io/docs/user-guide/federation/deployment/) +* [Events](https://kubernetes.io/docs/user-guide/federation/events/) +* [Ingress](https://kubernetes.io/docs/user-guide/federation/federated-ingress/) +* [Namespaces](https://kubernetes.io/docs/user-guide/federation/namespaces/) +* [ReplicaSets](https://kubernetes.io/docs/user-guide/federation/replicasets/) +* [Secrets](https://kubernetes.io/docs/user-guide/federation/secrets/) +* [Services](https://kubernetes.io/docs/user-guide/federation/federated-services/) [API reference docs](/docs/federation/api-reference/) lists all the resources supported by federation apiserver. @@ -119,12 +119,12 @@ federation control plane. The following Federated resources are affected by cascading deletion: -* Ingress -* Namespace -* ReplicaSet -* Secret -* Deployment -* DaemonSet +* [Ingress](https://kubernetes.io/docs/user-guide/federation/federated-ingress/) +* [Namespaces](https://kubernetes.io/docs/user-guide/federation/namespaces/) +* [ReplicaSets](https://kubernetes.io/docs/user-guide/federation/replicasets/) +* [Secrets](https://kubernetes.io/docs/user-guide/federation/secrets/) +* [Deployment](https://kubernetes.io/docs/user-guide/federation/deployment/) +* [DaemonSets](https://kubernetes.io/docs/user-guide/federation/daemonsets/) Note: By default, deleting a resource from federation control plane does not delete the corresponding resources from underlying clusters. @@ -133,5 +133,5 @@ delete the corresponding resources from underlying clusters. ## For more information * [Federation - proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/federation.md) + proposal](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation.md) * [Kubecon2016 talk on federation](https://www.youtube.com/watch?v=pq9lbkmxpS8) diff --git a/docs/user-guide/jobs/work-queue-1/index.md b/docs/user-guide/jobs/work-queue-1/index.md index b2b68cff23..4ce1ffb667 100644 --- a/docs/user-guide/jobs/work-queue-1/index.md +++ b/docs/user-guide/jobs/work-queue-1/index.md @@ -101,7 +101,7 @@ Next we will verify we can create a queue, and publish and consume messages. # In the next line, rabbitmq-service is the hostname where the rabbitmq-service # can be reached. 5672 is the standard port for rabbitmq. -root@temp-loe07:/# BROKER_URL=amqp://guest:guest@rabbitmq-service:5672 +root@temp-loe07:/# export BROKER_URL=amqp://guest:guest@rabbitmq-service:5672 # If you could not resolve "rabbitmq-service" in the previous step, # then use this command instead: # root@temp-loe07:/# BROKER_URL=amqp://guest:guest@$RABBITMQ_SERVICE_SERVICE_HOST:5672 diff --git a/docs/user-guide/persistent-volumes/index.md b/docs/user-guide/persistent-volumes/index.md index d6245e8198..3ecc8ea99f 100644 --- a/docs/user-guide/persistent-volumes/index.md +++ b/docs/user-guide/persistent-volumes/index.md @@ -423,7 +423,7 @@ parameters: * `restuserkey` : Gluster REST service/Heketi user's password which will be used for authentication to the REST server. This parameter is deprecated in favor of `secretNamespace` + `secretName`. * `secretNamespace` + `secretName` : Identification of Secret instance that containes user password to use when talking to Gluster REST service. These parameters are optional, empty password will be used when both `secretNamespace` and `secretName` are omitted. The provided secret must have type "kubernetes.io/glusterfs", e.g. created in this way: ``` - $ kubectl create secret heketi-secret --type="kubernetes.io/glusterfs" --from-literal=key='opensesame' --namespace=default + $ kubectl create secret generic heketi-secret --type="kubernetes.io/glusterfs" --from-literal=key='opensesame' --namespace=default ``` #### OpenStack Cinder @@ -482,7 +482,7 @@ parameters: * `userId`: Ceph client ID that is used to map the RBD image. Default is the same as `adminId`. * `userSecretName`: The name of Ceph Secret for `userId` to map RBD image. It must exist in the same namespace as PVCs. This parameter is required. The provided secret must have type "kubernetes.io/rbd", e.g. created in this way: ``` - $ kubectl create secret ceph-secret --type="kubernetes.io/rbd" --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' --namespace=kube-system + $ kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' --namespace=kube-system ``` #### Quobyte @@ -509,7 +509,7 @@ parameters: * `adminSecretNamespace`: The namespace for `adminSecretName`. Default is "default". * `adminSecretName`: secret that holds information about the Quobyte user and the password to authenticate agains the API server. The provided secret must have type "kubernetes.io/quobyte", e.g. created in this way: ``` - $ kubectl create secret quobyte-admin-secret --type="kubernetes.io/quobyte" --from-literal=key='opensesame' --namespace=kube-system + $ kubectl create secret generic quobyte-admin-secret --type="kubernetes.io/quobyte" --from-literal=key='opensesame' --namespace=kube-system ``` * `user`: maps all access to this user. Default is "root". * `group`: maps all access to this group. Default is "nfsnobody". @@ -532,7 +532,7 @@ parameters: * `skuName`: Azure storage account Sku tier. Default is empty. * `location`: Azure storage account location. Default is empty. -* `storageAccount`: Azure storage account name. If storage account is not provided, all storage accounts associated with the resource group are searched to find one that matches `skuName` and `location`. If storage account is provided, `skuName` and `location` are ignored. +* `storageAccount`: Azure storage account name. If storage account is not provided, all storage accounts associated with the resource group are searched to find one that matches `skuName` and `location`. If storage account is provided, it must reside in the same resource group as the cluster, and `skuName` and `location` are ignored. ## Writing Portable Configuration diff --git a/docs/user-guide/pods/init-container.md b/docs/user-guide/pods/init-container.md index ce7679d40e..90a862ea02 100644 --- a/docs/user-guide/pods/init-container.md +++ b/docs/user-guide/pods/init-container.md @@ -1,168 +1,7 @@ --- -assignees: -- erictune title: Init Containers --- -* TOC -{:toc} - -In addition to having one or more main containers (or **app containers**), a -pod can also have one or more **init containers** which run before the app -containers. Init containers allow you to reduce and reorganize setup scripts -and "glue code". - -## Overview - -An init container is exactly like a regular container, except that it always -runs to completion and each init container must complete successfully before -the next one is started. If the init container fails, Kubernetes will restart -the pod until the init container succeeds. If a pod is marked as `RestartNever`, -the pod will fail if the init container fails. - -You specify a container as an init container by adding an annotation. -The annotation key is `pod.beta.kubernetes.io/init-containers`. The annotation -value is a JSON array of [objects of type `v1.Container` -](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_container) - -Once the feature exits beta, the init containers will be specified on the Pod -Spec alongside the app `containers` array. -The status of the init containers is returned as another annotation - -`pod.beta.kubernetes.io/init-container-statuses` -- as an array of the -container statuses (similar to the `status.containerStatuses` field). - -Init containers support all of the same features as normal containers, -including resource limits, volumes, and security settings. The resource -requests and limits for an init container are [handled slightly differently]( -#resources). Init containers do not support readiness probes since they will -run to completion before the pod can be ready. -An init container has all of the fields of an app container. - -If you specify multiple init containers for a pod, those containers run one at -a time in sequential order. Each must succeed before the next can run. Once all -init containers have run to completion, Kubernetes initializes the pod and runs -the application containers as usual. - -## What are Init Containers Good For? - -Because init containers have separate images from application containers, they -have some advantages for start-up related code. These include: - -* they can contain utilities that are not desirable to include in the app container - image for security reasons, -* they can contain utilities or custom code for setup that is not present in an app - image. (No need to make an image `FROM` another image just to use a tool like - `sed`, `awk`, `python`, `dig`, etc during setup). -* the application image builder and the deployer roles can work independently without - the need to jointly build a single app image. - -Because init containers have different filesystem view (Linux namespaces) from -app containers, they can be given access to Secrets that the app containers are -not able to access. - -Since init containers run to completion before any app containers start, and -since app containers run in parallel, they provide an easier way to block or -delay the startup of application containers until some precondition is met. - -Because init containers run in sequence and there can be multiple init containers, -they can be composed easily. - -Here are some ideas for how to use init containers: -- Wait for a service to be created with a shell command like: - `for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; exit 1` -- Register this pod with a remote server with a command like: - `curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d 'instance=$(POD_NAME)&ip=$(POD_IP)'` - using `POD_NAME` and `POD_IP` from the downward API. -- Wait for some time before starting the app container with a command like `sleep 60`. -- Clone a git repository into a volume -- Place values like a POD_IP into a configuration file, and run a template tool (e.g. jinja) - to generate a configuration file to be consumed by the main app contianer. - -Complete usage examples can be found in the [StatefulSets -documentation](/docs/concepts/abstractions/controllers/statefulsets/) and the [Production Pods -guide](/docs/user-guide/production-pods.md#handling-initialization). - - -## Detailed Behavior - -Each pod may have 0..N init containers defined along with the existing -1..M app containers. - -On startup of the pod, after the network and volumes are initialized, the init -containers are started in order. Each container must exit successfully before -the next is invoked. If a container fails to start (due to the runtime) or -exits with failure, it is retried according to the pod RestartPolicy, except -when the pod restart policy is RestartPolicyAlways, in which case just the init -containers use RestartPolicyOnFailure. - -A pod cannot be ready until all init containers have succeeded. The ports on an -init container are not aggregated under a service. A pod that is being -initialized is in the `Pending` phase but should has a condition `Initializing` -set to `true`. - -If the pod is [restarted](#pod-restart-reasons) all init containers must -execute again. - -Changes to the init container spec are limited to the container image field. -Altering an init container image field is equivalent to restarting the pod. - -Because init containers can be restarted, retried, or reexecuted, init container -code should be idempotent. In particular, code that writes to files on EmptyDirs -should be prepared for the possibility that an output file already exists. - -An init container has all of the fields of an app container. The following -fields are prohibited from being used on init containers by validation: - -* `readinessProbe` - init containers must exit for pod startup to continue, - are not included in rotation, and so cannot define readiness distinct from - completion. - -Init container authors may use `activeDeadlineSeconds` on the pod and -`livenessProbe` on the container to prevent init containers from failing -forever. The active deadline includes init containers. - -The name of each app and init container in a pod must be unique - it is a -validation error for any container to share a name. - -### Resources - -Given the ordering and execution for init containers, the following rules -for resource usage apply: - -* The highest of any particular resource request or limit defined on all init - containers is the **effective init request/limit** -* The pod's **effective request/limit** for a resource is the higher of: - * sum of all app containers request/limit for a resource - * effective init request/limit for a resource -* Scheduling is done based on effective requests/limits, which means - init containers can reserve resources for initialization that are not used - during the life of the pod. -* QoS tier of the pod's **effective QoS tier** is the QoS tier for init containers - and app containers alike. - -Quota and limits are applied based on the effective pod request and -limit. - -Pod level cGroups are based on the effective pod request and limit, the -same as the scheduler. - - -## Pod Restart Reasons - -A Pod may "restart", causing reexecution of init containers, for the following -reasons: - -* An init container image is changed by a user updating the Pod Spec. - * App container image changes only restart the app container. -* The pod infrastructure container is restarted. - * This is uncommon and would have to be done by someone with root access to nodes. -* All containers in a pod are terminated, requiring a restart (RestartPolicyAlways) AND the record of init container completion has been lost due to garbage collection. - -## Support and compatibility - -A cluster with Kubelet and Apiserver version 1.4.0 or greater supports init -containers with the beta annotations. Support varies for other combinations of -Kubelet and Apiserver version; see the [release notes -](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md) for details. - +{% include user-guide-content-moved.md %} +* [Init Containers](/docs/concepts/abstractions/init-containers/) \ No newline at end of file diff --git a/docs/user-guide/quick-start.md b/docs/user-guide/quick-start.md index 6cef04810d..67dfb1dc77 100644 --- a/docs/user-guide/quick-start.md +++ b/docs/user-guide/quick-start.md @@ -5,69 +5,6 @@ assignees: title: Launching, Exposing, and Killing Applications --- -This guide will help you get oriented to Kubernetes and running your first containers on the cluster. If you are already familiar with the docker-cli, you can also checkout the docker-cli to kubectl migration guide [here](/docs/user-guide/docker-cli-to-kubectl). +{% include user-guide-content-moved.md %} -* TOC -{:toc} - -## Launching a simple application, and exposing it to the Internet - -Once your application is packaged into a container and pushed to an image registry, you're ready to deploy it to Kubernetes. -Through integration with some cloud providers (for example Google Compute Engine, AWS EC2, and Azure ACS), Kubernetes also enables you to request it to provision a public IP address for your application. - -For example, [nginx](http://wiki.nginx.org/Main) is a popular HTTP server, with a [pre-built container on Docker hub](https://registry.hub.docker.com/_/nginx/). The [`kubectl run`](/docs/user-guide/kubectl/kubectl_run) commands below will create two nginx replicas, listening on port 80, and a public IP address for your application. - -```shell -$ kubectl run my-nginx --image=nginx --replicas=2 --port=80 -deployment "my-nginx" created -``` - -To expose your service to the public Internet, run: - -```shell -$ kubectl expose deployment my-nginx --target-port=80 --type=LoadBalancer -service "my-nginx" exposed -``` -Note: The type, LoadBalancer, is highly dependent upon the underlying platform that Kubernetes is running on. If your cloud provider doesn't have a load balancer implementation (e.g. OpenStack) for Kubernetes, you can simply use the allocated [NodePort](http://kubernetes.io/docs/user-guide/services/#type-nodeport) as a rudimentary form of load balancing across your endpoints. - -You can see that they are running by: - -```shell -$ kubectl get po -NAME READY STATUS RESTARTS AGE -my-nginx-3800858182-h9v8d 1/1 Running 0 1m -my-nginx-3800858182-wqafx 1/1 Running 0 1m -``` - -Kubernetes will ensure that your application keeps running, by automatically restarting containers that fail, spreading containers across nodes, and recreating containers on new nodes when nodes fail. - -To find the public IP address assigned to your application, execute: - -```shell -$ kubectl get service my-nginx -NAME CLUSTER_IP EXTERNAL_IP PORT(S) AGE -my-nginx 10.179.240.1 25.1.2.3 80/TCP 8s -``` - -You may need to wait for a minute or two for the external IP address to be provisioned. - -In order to access your nginx landing page, you also have to make sure that traffic from external IPs is allowed. Do this by opening a [firewall to allow traffic on port 80](/docs/user-guide/services-firewalls). - -If you're running on AWS, Kubernetes creates an ELB for you. ELBs use host -names, not IPs, so you will have to do `kubectl describe service/my-nginx` and look -for the `LoadBalancer Ingress` host name. Traffic from external IPs is allowed -automatically. - -## Killing the application - -To kill the application and delete its containers and public IP address, do: - -```shell -$ kubectl delete deployment,service my-nginx -deployment "my-nginx" deleted -service "my-nginx" deleted -``` - -## What's next? - -* [Learn about how to configure common container parameters, such as commands and environment variables.](/docs/user-guide/configuring-containers) +[Using a Service to Access an Application in a Cluster](https://kubernetes.io/docs/tutorials/stateless-application/expose-external-ip-address-service/) diff --git a/docs/user-guide/secrets/walkthrough.md b/docs/user-guide/secrets/walkthrough.md index 11ca7672df..a58364859f 100644 --- a/docs/user-guide/secrets/walkthrough.md +++ b/docs/user-guide/secrets/walkthrough.md @@ -1,61 +1,7 @@ --- -assignees: title: Secrets Walkthrough --- -Following this example, you will create a secret and a [pod](/docs/user-guide/pods/) that consumes that secret in a [volume](/docs/user-guide/volumes/). See [Secrets design document](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/secrets.md) for more information. +{% include user-guide-content-moved.md %} -## Step Zero: Prerequisites - -This example assumes you have a Kubernetes cluster installed and running, and that you have -installed the `kubectl` command line tool somewhere in your path. Please see the [getting -started](/docs/getting-started-guides/) for installation instructions for your platform. - -## Step One: Create the secret - -A secret contains a set of named byte arrays. - -Use the [`secret.yaml`](/docs/user-guide/secrets/secret.yaml) file to create a secret: - -```shell -$ kubectl create -f docs/user-guide/secrets/secret.yaml -``` - -You can use `kubectl` to see information about the secret: - -```shell -$ kubectl get secrets -NAME TYPE DATA -test-secret Opaque 2 - -$ kubectl describe secret test-secret -Name: test-secret -Labels: -Annotations: - -Type: Opaque - -Data -==== -data-1: 9 bytes -data-2: 11 bytes -``` - -## Step Two: Create a pod that consumes a secret - -Pods consume secrets in volumes. Now that you have created a secret, you can create a pod that -consumes it. - -Use the [`secret-pod.yaml`](/docs/user-guide/secrets/secret-pod.yaml) file to create a Pod that consumes the secret. - -```shell -$ kubectl create -f docs/user-guide/secrets/secret-pod.yaml -``` - -This pod runs a binary that displays the content of one of the pieces of secret data in the secret -volume: - -```shell -$ kubectl logs secret-test-pod -2015-04-29T21:17:24.712206409Z content of file "/etc/secret-volume/data-1": value-1 -``` \ No newline at end of file +[Distributing Credentials Securely](/docs/tasks/configure-pod-container/distribute-credentials-secure/) diff --git a/docs/user-guide/service-accounts.md b/docs/user-guide/service-accounts.md index d1129a1983..ad1c0a68bf 100644 --- a/docs/user-guide/service-accounts.md +++ b/docs/user-guide/service-accounts.md @@ -147,8 +147,18 @@ NAME TYPE DATA myregistrykey kubernetes.io/.dockerconfigjson 1 ``` -Next, read/modify/write the service account for the namespace to use this secret as an imagePullSecret +Next, read/modify/write the service account for the namespace to use this secret as an imagePullSecret. +Automated version using json and the jq utility: +```shell +kubectl get serviceaccounts default -o json | + jq 'del(.metadata.resourceVersion)'| + jq 'setpath(["imagePullSecrets"];[{"name":"myregistrykey"}])' | + kubectl replace serviceaccount default -f - + +``` + +Interactive version requiring manual edit: ```shell $ kubectl get serviceaccounts default -o yaml > ./sa.yaml $ cat sa.yaml diff --git a/docs/user-guide/ui.md b/docs/user-guide/ui.md index da2b2e611c..cb330f1f9b 100644 --- a/docs/user-guide/ui.md +++ b/docs/user-guide/ui.md @@ -97,7 +97,8 @@ track=stable - **Namespace**: Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called [namespaces](/docs/admin/namespaces/). They let you partition resources into logically named groups. - Dashboard offers all available namespaces in a dropdown list, and allows you to create a new namespace. The namespace name may contain a maximum of 63 alphanumeric characters and dashes (-). + Dashboard offers all available namespaces in a dropdown list, and allows you to create a new namespace. The namespace name may contain a maximum of 63 alphanumeric characters and dashes (-) but can not contain capital letters. + Namespace names should not consist of only numbers. If the name is set as a number, such as 10, the pod will be put in the default namespace. In case the creation of the namespace is successful, it is selected by default. If the creation fails, the first namespace is selected. @@ -147,7 +148,7 @@ Detail views for workloads show status and specification information and surface ![Deployment detail view](/images/docs/ui-dashboard-deployment-detail.png) #### Services and discovery -Services and discovery view shows Kubernetes resources that allow for exposing services to external world and discovering them within a cluster. For that reason, Service and Ingress views show Pods targeted by them, internal endpoints for cluster connections and endpoints for external users. +Services and discovery view shows Kubernetes resources that allow for exposing services to external world and discovering them within a cluster. For that reason, Service and Ingress views show Pods targeted by them, internal endpoints for cluster connections and external endpoints for external users. ![Service list partial view](/images/docs/ui-dashboard-service-list.png) diff --git a/docs/user-guide/working-with-resources.md b/docs/user-guide/working-with-resources.md index 07a9bd55b7..7b55db4e25 100644 --- a/docs/user-guide/working-with-resources.md +++ b/docs/user-guide/working-with-resources.md @@ -5,54 +5,6 @@ assignees: title: Using kubectl to Manage 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](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md) and -the [api document](/docs/api/).* +{% include user-guide-content-moved.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: - -```shell -$ cat > /tmp/original.yaml < /tmp/current.yaml -pods/original -$ wc -l /tmp/original.yaml /tmp/current.yaml - 51 /tmp/current.yaml - 9 /tmp/original.yaml - 60 total -``` - -The resource we posted had only 9 lines, but the one we got back had 51 lines. -If you `diff -u /tmp/original.yaml /tmp/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](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/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 more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/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](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#defaulting)). - - For example, `spec.containers[0].imagePullPolicy` always defaults to `IfNotPresent` in api v1. - - For example, `spec.containers[0].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. - -## Finding Documentation on Resource Fields - -You can browse auto-generated API documentation [here](/docs/api/). +[Kubernetes Object Management](/docs/concepts/tools/kubectl/object-management-overview/) diff --git a/index.html b/index.html index 5e860832d7..30cb9264b5 100644 --- a/index.html +++ b/index.html @@ -172,7 +172,6 @@ cid: home -{% include footer.html %}
diff --git a/netlify.toml b/netlify.toml index bac7e0b5ab..37e285cb2d 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,6 +1,6 @@ [build] - command = "make build" + command = "make build generate-redirects" publish = "_site" [context.deploy-preview] - command = "make build-preview" + command = "make build-preview generate-redirects" diff --git a/redirects.rb b/redirects.rb new file mode 100644 index 0000000000..4cb238a811 --- /dev/null +++ b/redirects.rb @@ -0,0 +1,72 @@ +# This script generates a redirects file that Netlify's CDN +# can use to forward visitor to the right content. +# +# You can read more details about this file in Netlify documentation: +# +# https://www.netlify.com/docs/redirects/ +# +# USAGE: +# +# Run this script with Ruby to generate the _redirects file in this repository. +# It works with any Ruby version higher than 1.8. +# +# ruby redirects.rb +# +# If you want to test a change without modifying the content of the current file, +# you can print the output of the script setting the DEBUG environment variable +# when you run the script: +# +# DEBUG=1 ruby redirects.rb +# +# You can test if the content generated is correct in this playground: +# +# https://play.netlify.com/redirects +# +# HOW TO ADD NEW RULES: +# +# This script is divided in two sections. +# +# The first section handles static redirects, +# those that you know the old path and the new path and never change. +# +# If you want to add one of these redirects, add the rule to the `fixed_redirects` variable, +# in a new line before the closing """. The format for basic 301 redirects is the following one, +# check Netlify's documentation linked above for other rules: +# +# /OLD_PATH /NEW_PATH_OR_URL +# +# The second section handles redirects that change depending on the branch that's deployed +# in the site. For instance, when you want to redirect a path to content in +# the kubernetes main repository but the content is specific to a branch that +# matches the deployed branch. +# +# If you want to add one of there redirects, add the old path to the `branch_redirects` list. For instance, +# when you deploy the branch release-1.5 on Netlify, this script will generate the following redirects: +# +# /examples/* https://github.com/kubernetes/kubernetes/tree/release-1.5/examples/:splat +# /cluster/* https://github.com/kubernetes/kubernetes/tree/release-1.5/cluster/:splat +# /docs/devel/* https://github.com/kubernetes/kubernetes/tree/release-1.5/docs/devel/:splat +# /docs/design/* https://github.com/kubernetes/kubernetes/tree/release-1.5/docs/design/:splat +# +REPO_TMPL = "https://github.com/kubernetes/kubernetes/tree/%s/%s/:splat" + +fixed_redirects = """# 301 redirects (301 is the default status when no other one is provided for each line) +/third_party/swagger-ui /kubernetes/third_party/swagger-ui/ +/resource-quota /docs/admin/resourcequota/ +/horizontal-pod-autoscaler /docs/user-guide/horizontal-pod-autoscaling/ +/docs/user-guide/overview /docs/whatisk8s/ +/docs/roadmap https://github.com/kubernetes/kubernetes/milestones/ +/api-ref https://github.com/kubernetes/kubernetes/milestones/ +""" + +branch_redirects = ["examples" , "cluster", "docs/devel", "docs/design"] + +branch_redirects.each do |name| + dest = REPO_TMPL % [ENV.fetch("HEAD", "master"), name] + rule = "\n/#{name}/* #{dest}" + + fixed_redirects << rule +end + +output = ENV["DEBUG"] ? STDOUT : File.open(ENV.fetch("REDIRECTS_PATH", "_redirects"), "w+") +output.puts fixed_redirects