From 75f00dfc602cd4fd1ce2c37f77e0e70b9fa5c5cb Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Fri, 22 Jun 2018 11:20:04 -0700 Subject: [PATCH] Apply templates to all concepts and tasks to fix double bullets in TOC (#9149) * Apply concept template to fix double bullet issue. * Apply concept template * Apply templates to tasks --- .../concepts/architecture/cloud-controller.md | 11 +- .../architecture/master-node-communication.md | 12 +- .../en/docs/concepts/architecture/nodes.md | 13 +- .../concepts/cluster-administration/addons.md | 12 +- .../cluster-administration/certificates.md | 12 +- .../kubelet-garbage-collection.md | 15 +- .../cluster-administration/logging.md | 9 + .../manage-deployment.md | 13 +- .../cluster-administration/networking.md | 12 +- .../docs/concepts/overview/kubernetes-api.md | 11 + .../overview/working-with-objects/labels.md | 9 + .../overview/working-with-objects/names.md | 11 + .../working-with-objects/namespaces.md | 11 + .../concepts/policy/pod-security-policy.md | 9 + .../docs/concepts/policy/resource-quotas.md | 15 +- .../concepts/storage/persistent-volumes.md | 9 + .../docs/concepts/storage/storage-classes.md | 9 + .../workloads/controllers/cron-jobs.md | 13 +- .../workloads/controllers/daemonset.md | 13 +- .../controllers/jobs-run-to-completion.md | 13 +- .../en/docs/concepts/workloads/pods/pod.md | 12 +- .../access-cluster.md | 48 ++-- .../configure-access-multiple-clusters.md | 8 + .../configure-cloud-provider-firewall.md | 33 ++- .../configure-dns-cluster.md | 8 +- .../web-ui-dashboard.md | 13 +- .../setup-extension-api-server.md | 6 + .../administer-cluster/cluster-management.md | 11 +- .../configure-multiple-schedulers.md | 29 ++- .../configure-upgrade-etcd.md | 22 +- .../cpu-management-policies.md | 18 +- .../declare-network-policy.md | 5 + .../developing-cloud-controller-manager.md | 17 +- .../dns-horizontal-autoscaling.md | 6 + .../tasks/administer-cluster/encrypt-data.md | 8 + ...aranteed-scheduling-critical-addon-pods.md | 13 +- .../highly-available-master.md | 25 +- .../namespaces-walkthrough.md | 24 +- .../administer-cluster/out-of-resource.md | 11 +- .../reserve-compute-resources.md | 21 +- .../running-cloud-controller.md | 15 +- .../tasks/administer-cluster/static-pod.md | 13 +- .../tasks/administer-federation/deployment.md | 7 +- .../tasks/administer-federation/events.md | 10 +- .../tasks/administer-federation/secret.md | 23 +- .../configure-service-account.md | 16 ++ .../translate-compose-kubernetes.md | 241 ++++++++++-------- .../tasks/debug-application-cluster/audit.md | 23 +- .../core-metrics-pipeline.md | 11 + .../debug-application-introspection.md | 17 +- .../debug-application.md | 13 +- .../debug-cluster.md | 11 + .../debug-pod-replication-controller.md | 12 +- .../debug-service.md | 20 +- .../events-stackdriver.md | 13 +- .../logging-elasticsearch-kibana.md | 12 + .../logging-stackdriver.md | 15 +- .../monitor-node-health.md | 21 +- .../resource-usage-monitoring.md | 17 +- .../troubleshooting.md | 11 + .../federation-service-discovery.md | 78 +++--- .../set-up-cluster-federation-kubefed.md | 18 +- .../inject-data-application/podpreset.md | 19 +- .../coarse-parallel-processing-work-queue.md | 27 +- .../fine-parallel-processing-work-queue.md | 32 ++- .../job/parallel-processing-expansion.md | 13 +- .../docs/tasks/manage-gpus/scheduling-gpus.md | 11 + .../horizontal-pod-autoscale-walkthrough.md | 30 ++- .../horizontal-pod-autoscale.md | 19 +- .../rolling-update-replication-controller.md | 13 +- .../tasks/tls/managing-tls-in-a-cluster.md | 29 ++- 71 files changed, 1059 insertions(+), 321 deletions(-) diff --git a/content/en/docs/concepts/architecture/cloud-controller.md b/content/en/docs/concepts/architecture/cloud-controller.md index b83dc23124..eae58ff8b8 100644 --- a/content/en/docs/concepts/architecture/cloud-controller.md +++ b/content/en/docs/concepts/architecture/cloud-controller.md @@ -1,9 +1,10 @@ --- title: Concepts Underlying the Cloud Controller Manager +content_template: templates/concept weight: 30 --- -## Cloud Controller Manager +{{% capture overview %}} The cloud controller manager (CCM) concept (not to be confused with the binary) was originally created to allow cloud specific vendor code and the Kubernetes core to evolve independent of one another. The cloud controller manager runs alongside other master components such as the Kubernetes controller manager, the API server, and scheduler. It can also be started as a Kubernetes addon, in which case it runs on top of Kubernetes. @@ -15,6 +16,12 @@ Here's the architecture of a Kubernetes cluster without the cloud controller man ![Pre CCM Kube Arch](/images/docs/pre-ccm-arch.png) +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Design In the preceding diagram, Kubernetes and the cloud provider are integrated through several different components: @@ -254,3 +261,5 @@ The following cloud providers have implemented CCMs: Complete instructions for configuring and running the CCM are provided [here](/docs/tasks/administer-cluster/running-cloud-controller/#cloud-controller-manager). + +{{% /capture %}} diff --git a/content/en/docs/concepts/architecture/master-node-communication.md b/content/en/docs/concepts/architecture/master-node-communication.md index 7b95443abd..4f73d41287 100644 --- a/content/en/docs/concepts/architecture/master-node-communication.md +++ b/content/en/docs/concepts/architecture/master-node-communication.md @@ -4,12 +4,11 @@ reviewers: - roberthbailey - liggitt title: Master-Node communication +content_template: templates/concept weight: 20 --- -{{< toc >}} - -## Overview +{{% capture overview %}} This document catalogs the communication paths between the master (really the apiserver) and the Kubernetes cluster. The intent is to allow users to @@ -17,6 +16,12 @@ customize their installation to harden the network configuration such that the cluster can be run on an untrusted network (or on fully public IPs on a cloud provider). +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Cluster -> Master All communication paths from the cluster to the master terminate at the @@ -91,3 +96,4 @@ connection will be encrypted, it will not provide any guarantees of integrity. These connections **are not currently safe** to run over untrusted and/or public networks. +{{% /capture %}} diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index e52dc0eb38..ea4cef0a36 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -3,12 +3,11 @@ reviewers: - caesarxuchao - dchen1107 title: Nodes +content_template: templates/concept weight: 10 --- -{{< toc >}} - -## What is a node? +{{% capture overview %}} A `node` is a worker machine in Kubernetes, previously known as a `minion`. A node may be a VM or physical machine, depending on the cluster. Each node has @@ -17,6 +16,12 @@ components. The services on a node include Docker, kubelet and kube-proxy. See [The Kubernetes Node](https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#the-kubernetes-node) section in the architecture design doc for more details. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Node Status A node's status contains the following information: @@ -279,3 +284,5 @@ on each kubelet where you want to reserve resources. Node is a top-level resource in the Kubernetes REST API. More details about the API object can be found at: [Node API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#node-v1-core). + +{{% /capture %}} diff --git a/content/en/docs/concepts/cluster-administration/addons.md b/content/en/docs/concepts/cluster-administration/addons.md index 33b065ac7c..b8a70ecc08 100644 --- a/content/en/docs/concepts/cluster-administration/addons.md +++ b/content/en/docs/concepts/cluster-administration/addons.md @@ -1,8 +1,10 @@ --- title: Installing Addons +content_template: templates/concept --- -## Overview +{{% capture overview %}} + Add-ons extend the functionality of Kubernetes. @@ -10,6 +12,12 @@ This page lists some of the available add-ons and links to their respective inst Add-ons in each section are sorted alphabetically - the ordering does not imply any preferential status. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Networking and Network Policy @@ -40,3 +48,5 @@ Add-ons in each section are sorted alphabetically - the ordering does not imply There are several other add-ons documented in the deprecated [cluster/addons](https://git.k8s.io/kubernetes/cluster/addons) directory. Well-maintained ones should be linked to here. PRs welcome! + +{{% /capture %}} diff --git a/content/en/docs/concepts/cluster-administration/certificates.md b/content/en/docs/concepts/cluster-administration/certificates.md index 7df5cd0411..129470ddf0 100644 --- a/content/en/docs/concepts/cluster-administration/certificates.md +++ b/content/en/docs/concepts/cluster-administration/certificates.md @@ -1,15 +1,21 @@ --- title: Certificates +content_template: templates/concept weight: 20 --- -{{< toc >}} -## Creating Certificates +{{% capture overview %}} When using client certificate authentication, you can generate certificates manually through `easyrsa`, `openssl` or `cfssl`. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ### easyrsa **easyrsa** can manually generate certificates for your cluster. @@ -239,3 +245,5 @@ done. You can use the `certificates.k8s.io` API to provision x509 certificates to use for authentication as documented [here](/docs/tasks/tls/managing-tls-in-a-cluster). + +{{% /capture %}} diff --git a/content/en/docs/concepts/cluster-administration/kubelet-garbage-collection.md b/content/en/docs/concepts/cluster-administration/kubelet-garbage-collection.md index 9b25a524c8..99364fc56e 100644 --- a/content/en/docs/concepts/cluster-administration/kubelet-garbage-collection.md +++ b/content/en/docs/concepts/cluster-administration/kubelet-garbage-collection.md @@ -2,15 +2,22 @@ reviewers: - mikedanese title: Configuring kubelet Garbage Collection +content_template: templates/concept weight: 70 --- -{{< toc >}} +{{% capture overview %}} Garbage collection is a helpful function of kubelet that will clean up unused images and unused containers. Kubelet will perform garbage collection for containers every minute and garbage collection for images every five minutes. External garbage collection tools are not recommended as these tools can potentially break the behavior of kubelet by removing containers expected to exist. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Image Collection Kubernetes manages lifecycle of all images through imageManager, with the cooperation @@ -72,4 +79,10 @@ Including: | `--low-diskspace-threshold-mb` | `--eviction-hard` or `eviction-soft` | eviction generalizes disk thresholds to other resources | | `--outofdisk-transition-frequency` | `--eviction-pressure-transition-period` | eviction generalizes disk pressure transition to other resources | +{{% /capture %}} + +{{% capture whatsnext %}} + See [Configuring Out Of Resource Handling](/docs/tasks/administer-cluster/out-of-resource/) for more details. + +{{% /capture %}} diff --git a/content/en/docs/concepts/cluster-administration/logging.md b/content/en/docs/concepts/cluster-administration/logging.md index 7611a4fcd1..d96e8bfc45 100644 --- a/content/en/docs/concepts/cluster-administration/logging.md +++ b/content/en/docs/concepts/cluster-administration/logging.md @@ -3,15 +3,22 @@ reviewers: - piosz - x13n title: Logging Architecture +content_template: templates/concept weight: 60 --- +{{% capture overview %}} + Application and systems logs can help you understand what is happening inside your cluster. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism; as such, most container engines are likewise designed to support some kind of logging. The easiest and most embraced logging method for containerized applications is to write to the standard output and standard error streams. However, the native functionality provided by a container engine or runtime is usually not enough for a complete logging solution. For example, if a container crashes, a pod is evicted, or a node dies, you'll usually still want to access your application's logs. As such, logs should have a separate storage and lifecycle independent of nodes, pods, or containers. This concept is called _cluster-level-logging_. Cluster-level logging requires a separate backend to store, analyze, and query logs. Kubernetes provides no native storage solution for log data, but you can integrate many existing logging solutions into your Kubernetes cluster. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + Cluster-level logging architectures are described in assumption that a logging backend is present inside or outside of your cluster. If you're not interested in having cluster-level logging, you might still find @@ -243,3 +250,5 @@ container. You can implement cluster-level logging by exposing or pushing logs directly from every application; however, the implementation for such a logging mechanism is outside the scope of Kubernetes. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/cluster-administration/manage-deployment.md b/content/en/docs/concepts/cluster-administration/manage-deployment.md index 26dda7bbbf..a91813c558 100644 --- a/content/en/docs/concepts/cluster-administration/manage-deployment.md +++ b/content/en/docs/concepts/cluster-administration/manage-deployment.md @@ -4,13 +4,20 @@ reviewers: - janetkuo - mikedanese title: Managing Resources +content_template: templates/concept weight: 40 --- +{{% capture overview %}} + You've deployed your application and exposed it via a service. Now what? Kubernetes provides a number of tools to help you manage your application deployment, including scaling and updating. Among the features that we will discuss in more depth are [configuration files](/docs/concepts/configuration/overview/) and [labels](/docs/concepts/overview/working-with-objects/labels/). +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Organizing resource configurations Many applications require multiple resources to be created, such as a Deployment and a Service. Management of multiple resources can be simplified by grouping them together in the same file (separated by `---` in YAML). For example: @@ -391,7 +398,11 @@ $ kubectl edit deployment/my-nginx That's it! The Deployment will declaratively update the deployed nginx application progressively behind the scene. It ensures that only a certain number of old replicas may be down while they are being updated, and only a certain number of new replicas may be created above the desired number of pods. To learn more details about it, visit [Deployment page](/docs/concepts/workloads/controllers/deployment/). -## What's next? +{{% /capture %}} + +{{% capture whatsnext %}} - [Learn about how to use `kubectl` for application introspection and debugging.](/docs/tasks/debug-application-cluster/debug-application-introspection/) - [Configuration Best Practices and Tips](/docs/concepts/configuration/overview/) + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/cluster-administration/networking.md b/content/en/docs/concepts/cluster-administration/networking.md index 10abe8854b..6d0dfc6af4 100644 --- a/content/en/docs/concepts/cluster-administration/networking.md +++ b/content/en/docs/concepts/cluster-administration/networking.md @@ -2,9 +2,11 @@ reviewers: - thockin title: Cluster Networking +content_template: templates/concept weight: 50 --- +{{% capture overview %}} Kubernetes approaches networking somewhat differently than Docker does by default. There are 4 distinct networking problems to solve: @@ -14,10 +16,11 @@ default. There are 4 distinct networking problems to solve: 3. Pod-to-Service communications: this is covered by [services](/docs/concepts/services-networking/service/). 4. External-to-Service communications: this is covered by [services](/docs/concepts/services-networking/service/). +{{% /capture %}} + {{< toc >}} - -## Summary +{{% capture body %}} Kubernetes assumes that pods can communicate with other pods, regardless of which host they land on. Every pod gets its own IP address so you do not @@ -266,9 +269,12 @@ Weave Net runs as a [CNI plug-in](https://www.weave.works/docs/net/latest/cni-pl or stand-alone. In either version, it doesn't require any configuration or extra code to run, and in both cases, the network provides one IP address per pod - as is standard for Kubernetes. +{{% /capture %}} -## Other reading +{{% capture whatsnext %}} The early design of the networking model and its rationale, and some future plans are described in more detail in the [networking design document](https://git.k8s.io/community/contributors/design-proposals/network/networking.md). + +{{% /capture %}} diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index e55b435c7a..e4295b7ab3 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -2,9 +2,12 @@ reviewers: - chenopis title: The Kubernetes API +content_template: templates/concept weight: 30 --- +{{% capture overview %}} + Overall API conventions are described in the [API conventions doc](https://git.k8s.io/community/contributors/devel/api-conventions.md). API endpoints, resource types and samples are described in [API Reference](/docs/reference). @@ -17,6 +20,12 @@ Kubernetes also stores its serialized state (currently in [etcd](https://coreos. Kubernetes itself is decomposed into multiple components, which interact through its API. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## API changes In our experience, any system that is successful needs to grow and change as new use cases emerge or existing ones change. Therefore, we expect the Kubernetes API to continuously change and grow. However, we intend to not break compatibility with existing clients, for an extended period of time. In general, new API resources and new resource fields can be expected to be added frequently. Elimination of resources or fields will require following the [API deprecation policy](/docs/reference/using-api/deprecation-policy/). @@ -121,3 +130,5 @@ DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets Other extensions resources can be enabled by setting `--runtime-config` on apiserver. `--runtime-config` accepts comma separated values. For example: to disable deployments and ingress, set `--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingress=false` + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/overview/working-with-objects/labels.md b/content/en/docs/concepts/overview/working-with-objects/labels.md index 538e3561e6..b4fb6959cc 100644 --- a/content/en/docs/concepts/overview/working-with-objects/labels.md +++ b/content/en/docs/concepts/overview/working-with-objects/labels.md @@ -2,9 +2,12 @@ reviewers: - mikedanese title: Labels and Selectors +content_template: templates/concept weight: 40 --- +{{% capture overview %}} + _Labels_ are key/value pairs that are attached to objects, such as pods. Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. Labels can be used to organize and to select subsets of objects. Labels can be attached to objects at creation time and subsequently added and modified at any time. @@ -21,8 +24,12 @@ Each object can have a set of key/value labels defined. Each Key must be unique We'll eventually index and reverse-index labels for efficient queries and watches, use them to sort and group in UIs and CLIs, etc. We don't want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using [annotations](/docs/concepts/overview/working-with-objects/annotations/). +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Motivation Labels enable users to map their own organizational structures onto system objects in a loosely coupled fashion, without requiring clients to store these mappings. @@ -194,3 +201,5 @@ selector: One use case for selecting over labels is to constrain the set of nodes onto which a pod can schedule. See the documentation on [node selection](/docs/concepts/configuration/assign-pod-node/) for more information. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/overview/working-with-objects/names.md b/content/en/docs/concepts/overview/working-with-objects/names.md index 4e81494a92..2c3cbec15d 100644 --- a/content/en/docs/concepts/overview/working-with-objects/names.md +++ b/content/en/docs/concepts/overview/working-with-objects/names.md @@ -3,15 +3,24 @@ reviewers: - mikedanese - thockin title: Names +content_template: templates/concept weight: 20 --- +{{% capture overview %}} + All objects in the Kubernetes REST API are unambiguously identified by a Name and a UID. For non-unique user-provided attributes, Kubernetes provides [labels](/docs/user-guide/labels) and [annotations](/docs/concepts/overview/working-with-objects/annotations/). See the [identifiers design doc](https://git.k8s.io/community/contributors/design-proposals/architecture/identifiers.md) for the precise syntax rules for Names and UIDs. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Names {{< glossary_definition term_id="name" length="all" >}} @@ -21,3 +30,5 @@ By convention, the names of Kubernetes resources should be up to maximum length ## UIDs {{< glossary_definition term_id="uid" length="all" >}} + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/overview/working-with-objects/namespaces.md b/content/en/docs/concepts/overview/working-with-objects/namespaces.md index 52a9aabe01..c0de016bbb 100644 --- a/content/en/docs/concepts/overview/working-with-objects/namespaces.md +++ b/content/en/docs/concepts/overview/working-with-objects/namespaces.md @@ -4,12 +4,21 @@ reviewers: - mikedanese - thockin title: Namespaces +content_template: templates/concept weight: 30 --- +{{% capture overview %}} + Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## When to Use Multiple Namespaces Namespaces are intended for use in environments with many users spread across multiple @@ -88,3 +97,5 @@ Most Kubernetes resources (e.g. pods, services, replication controllers, and oth in some namespaces. However namespace resources are not themselves in a namespace. And low-level resources, such as [nodes](/docs/admin/node) and persistentVolumes, are not in any namespace. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/policy/pod-security-policy.md b/content/en/docs/concepts/policy/pod-security-policy.md index 3c998b6384..fc9c8426ec 100644 --- a/content/en/docs/concepts/policy/pod-security-policy.md +++ b/content/en/docs/concepts/policy/pod-security-policy.md @@ -3,16 +3,23 @@ reviewers: - pweil- - tallclair title: Pod Security Policies +content_template: templates/concept weight: 20 --- +{{% capture overview %}} + {{< feature-state state="beta" >}} Pod Security Policies enable fine-grained authorization of pod creation and updates. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## What is a Pod Security Policy? A _Pod Security Policy_ is a cluster-level resource that controls security @@ -558,3 +565,5 @@ default cannot be changed. Controlled via annotations on the PodSecurityPolicy. Refer to the [Sysctl documentation]( /docs/concepts/cluster-administration/sysctl-cluster/#podsecuritypolicy-annotations). + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/policy/resource-quotas.md b/content/en/docs/concepts/policy/resource-quotas.md index 2d69664bcb..32f8dd4159 100644 --- a/content/en/docs/concepts/policy/resource-quotas.md +++ b/content/en/docs/concepts/policy/resource-quotas.md @@ -2,14 +2,23 @@ reviewers: - derekwaynecarr title: Resource Quotas +content_template: templates/concept weight: 10 --- +{{% capture overview %}} + When several users or teams share a cluster with a fixed number of nodes, there is a concern that one team could use more than its fair share of resources. Resource quotas are a tool for administrators to address this concern. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + A resource quota, defined by a `ResourceQuota` object, provides constraints that limit aggregate resource consumption per namespace. It can limit the quantity of objects that can be created in a namespace by type, as well as the total amount of compute resources that may @@ -307,6 +316,10 @@ restrictions around nodes: pods from several namespaces may run on the same node See a [detailed example for how to use resource quota](/docs/tasks/administer-cluster/quota-api-object/). -## Read More +{{% /capture %}} + +{{% capture whatsnext %}} See [ResourceQuota design doc](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_resource_quota.md) for more information. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md index 72b66b9807..dd1cb3406f 100644 --- a/content/en/docs/concepts/storage/persistent-volumes.md +++ b/content/en/docs/concepts/storage/persistent-volumes.md @@ -5,13 +5,20 @@ reviewers: - thockin - msau42 title: Persistent Volumes +content_template: templates/concept weight: 20 --- +{{% capture overview %}} + This document describes the current state of `PersistentVolumes` in Kubernetes. Familiarity with [volumes](/docs/concepts/storage/volumes/) is suggested. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Introduction Managing storage is a distinct problem from managing compute. The `PersistentVolume` subsystem provides an API for users and administrators that abstracts details of how storage is provided from how it is consumed. To do this we introduce two new API resources: `PersistentVolume` and `PersistentVolumeClaim`. @@ -608,3 +615,5 @@ and need persistent storage, we recommend that you use the following pattern: dynamic storage support (in which case the user should create a matching PV) or the cluster has no storage system (in which case the user cannot deploy config requiring PVCs). + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/storage/storage-classes.md b/content/en/docs/concepts/storage/storage-classes.md index 7e49d36b28..a4a0bf145d 100644 --- a/content/en/docs/concepts/storage/storage-classes.md +++ b/content/en/docs/concepts/storage/storage-classes.md @@ -5,15 +5,22 @@ reviewers: - thockin - msau42 title: Storage Classes +content_template: templates/concept weight: 30 --- +{{% capture overview %}} + This document describes the concept of `StorageClass` in Kubernetes. Familiarity with [volumes](/docs/concepts/storage/volumes/) and [persistent volumes](/docs/concepts/storage/persistent-volumes) is suggested. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Introduction A `StorageClass` provides a way for administrators to describe the "classes" of @@ -670,3 +677,5 @@ specified by the `WaitForFirstConsumer` volume binding mode. Delaying volume binding allows the scheduler to consider all of a pod's scheduling constraints when choosing an appropriate PersistentVolume for a PersistentVolumeClaim. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md index 84abde442e..521a69b44f 100644 --- a/content/en/docs/concepts/workloads/controllers/cron-jobs.md +++ b/content/en/docs/concepts/workloads/controllers/cron-jobs.md @@ -4,12 +4,11 @@ reviewers: - soltysh - janetkuo title: CronJob +content_template: templates/concept weight: 80 --- -{{< toc >}} - -## What is a cron job? +{{% capture overview %}} A _Cron Job_ manages time based [Jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/), namely: @@ -21,6 +20,12 @@ on a given schedule, written in [Cron](https://en.wikipedia.org/wiki/Cron) forma For instructions on creating and working with cron jobs, and for an example of a spec file for a cron job, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs). +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Cron Job Limitations A cron job creates a job object _about_ once per execution time of its schedule. We say "about" because there @@ -43,3 +48,5 @@ starting at all. The Cronjob is only responsible for creating Jobs that match its schedule, and the Job in turn is responsible for the management of the Pods it represents. + +{{% /capture %}} diff --git a/content/en/docs/concepts/workloads/controllers/daemonset.md b/content/en/docs/concepts/workloads/controllers/daemonset.md index 15237bf250..4ef6e7f325 100644 --- a/content/en/docs/concepts/workloads/controllers/daemonset.md +++ b/content/en/docs/concepts/workloads/controllers/daemonset.md @@ -6,12 +6,11 @@ reviewers: - janetkuo - kow3ns title: DaemonSet +content_template: templates/concept weight: 50 --- -{{< toc >}} - -## What is a DaemonSet? +{{% capture overview %}} A _DaemonSet_ ensures that all (or some) Nodes run a copy of a Pod. As nodes are added to the cluster, Pods are added to them. As nodes are removed from the cluster, those Pods are garbage @@ -28,6 +27,12 @@ In a simple case, one DaemonSet, covering all nodes, would be used for each type A more complex setup might use multiple DaemonSets for a single type of daemon, but with different flags and/or different memory and cpu requests for different hardware types. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Writing a DaemonSet Spec ### Create a DaemonSet @@ -201,3 +206,5 @@ Use a Deployment for stateless services, like frontends, where scaling up and do number of replicas and rolling out updates are more important than controlling exactly which host the Pod runs on. Use a DaemonSet when it is important that a copy of a Pod always run on all or certain hosts, and when it needs to start before other Pods. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md b/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md index 9b9b8ab124..32141476d5 100644 --- a/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md +++ b/content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md @@ -3,12 +3,11 @@ reviewers: - erictune - soltysh title: Jobs - Run to Completion +content_template: templates/concept weight: 70 --- -{{< toc >}} - -## What is a Job? +{{% capture overview %}} A _job_ creates one or more pods and ensures that a specified number of them successfully terminate. As pods successfully complete, the _job_ tracks the successful completions. When a specified number @@ -21,6 +20,12 @@ due to a node hardware failure or a node reboot). A Job can also be used to run multiple pods in parallel. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Running an example Job Here is an example Job config. It computes π to 2000 places and prints it out. @@ -395,3 +400,5 @@ object, but complete control over what pods are created and how work is assigned ## Cron Jobs Support for creating Jobs at specified times/dates (i.e. cron) is available in Kubernetes [1.4](https://github.com/kubernetes/kubernetes/pull/11980). More information is available in the [cron job documents](/docs/concepts/workloads/controllers/cron-jobs/) + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/workloads/pods/pod.md b/content/en/docs/concepts/workloads/pods/pod.md index 23f3cf3fe5..d3fbee3e91 100644 --- a/content/en/docs/concepts/workloads/pods/pod.md +++ b/content/en/docs/concepts/workloads/pods/pod.md @@ -1,15 +1,21 @@ --- reviewers: title: Pods +content_template: templates/concept weight: 20 --- -{{< toc >}} - +{{% capture overview %}} _Pods_ are the smallest deployable units of computing that can be created and managed in Kubernetes. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## What is a Pod? A _pod_ (as in a pod of whales or pea pod) is a group of one or more containers @@ -199,3 +205,5 @@ spec.containers[0].securityContext.privileged: forbidden '<*>(0xc20b222db0)true' Pod is a top-level resource in the Kubernetes REST API. More details about the API object can be found at: [Pod API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core). + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/access-application-cluster/access-cluster.md b/content/en/docs/tasks/access-application-cluster/access-cluster.md index 062787551d..92717cd7a1 100644 --- a/content/en/docs/tasks/access-application-cluster/access-cluster.md +++ b/content/en/docs/tasks/access-application-cluster/access-cluster.md @@ -1,13 +1,20 @@ --- title: Accessing Clusters weight: 20 +content_template: templates/concept --- +{{% capture overview %}} + +This topic discusses multiple ways to interact with clusters. + +{{% /capture %}} + {{< toc >}} -## Accessing the cluster API +{{% capture body %}} -### Accessing for the first time with kubectl +## Accessing for the first time with kubectl When accessing the Kubernetes API for the first time, we suggest using the Kubernetes CLI, `kubectl`. @@ -26,7 +33,7 @@ $ kubectl config view Many of the [examples](/docs/user-guide/kubectl-cheatsheet) provide an introduction to using kubectl and complete documentation is found in the [kubectl manual](/docs/user-guide/kubectl-overview). -### Directly accessing the REST API +## Directly accessing the REST API Kubectl handles locating and authenticating to the apiserver. If you want to directly access the REST API with an http client like @@ -43,7 +50,7 @@ curl or wget, or a browser, there are several ways to locate and authenticate: - Works with some types of client code that are confused by using a proxy. - Need to import a root cert into your browser to protect against MITM. -#### Using kubectl proxy +### Using kubectl proxy The following command runs kubectl in a mode where it acts as a reverse proxy. It handles locating the apiserver and authenticating. @@ -67,27 +74,12 @@ $ curl http://localhost:8080/api/ } ``` -#### Without kubectl proxy (before v1.3.x) -It is possible to avoid using kubectl proxy by passing an authentication token -directly to the apiserver, like this: - -```shell -$ APISERVER=$(kubectl config view | grep server | cut -f 2- -d ":" | tr -d " ") -$ TOKEN=$(kubectl config view | grep token | cut -f 2 -d ":" | tr -d " ") -$ curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure -{ - "versions": [ - "v1" - ] -} -``` - -#### Without kubectl proxy (post v1.3.x) +### Without kubectl proxy In Kubernetes version 1.3 or later, `kubectl config view` no longer displays the token. Use `kubectl describe secret...` to get the token for the default service account, like this: -``` shell +```shell $ APISERVER=$(kubectl config view | grep server | cut -f 2- -d ":" | tr -d " ") $ TOKEN=$(kubectl describe secret $(kubectl get secrets | grep default | cut -f1 -d ' ') | grep -E '^token' | cut -f2 -d':' | tr -d '\t') $ curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure @@ -118,12 +110,12 @@ for this. [Configuring Access to the API](/docs/admin/accessing-the-api) describes how a cluster admin can configure this. Such approaches may conflict with future high-availability support. -### Programmatic access to the API +## Programmatic access to the API Kubernetes officially supports [Go](#go-client) and [Python](#python-client) client libraries. -#### Go client +### Go client * 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. @@ -133,19 +125,19 @@ as the kubectl CLI does to locate and authenticate to the apiserver. See this [e If the application is deployed as a Pod in the cluster, please refer to the [next section](#accessing-the-api-from-a-pod). -#### Python client +### Python client To use [Python client](https://github.com/kubernetes-client/python), run the following command: `pip install kubernetes`. See [Python Client Library page](https://github.com/kubernetes-client/python) for more installation options. The Python client can use the same [kubeconfig file](/docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig/) as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes-client/python/tree/master/examples/example1.py). -#### Other languages +### Other languages There are [client libraries](/docs/reference/using-api/client-libraries/) for accessing the API from other languages. See documentation for other libraries for how they authenticate. -### Accessing the API from a Pod +## Accessing the API from a Pod When accessing the API from a pod, locating and authenticating to the apiserver are somewhat different. @@ -275,7 +267,7 @@ The supported formats for the name segment of the URL are: } ``` -#### Using web browsers to access services running on the cluster +### Using web browsers to access services running on the cluster You may be able to put an apiserver proxy url into the address bar of a browser. However: @@ -334,3 +326,5 @@ There are several different proxies you may encounter when using Kubernetes: Kubernetes users will typically not need to worry about anything other than the first two types. The cluster admin will typically ensure that the latter types are setup correctly. + +{{% /capture %}} diff --git a/content/en/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md b/content/en/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md index 41e873a1e8..cdebb3015c 100644 --- a/content/en/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md +++ b/content/en/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md @@ -26,6 +26,14 @@ You need to have the [`kubectl`](/docs/tasks/tools/install-kubectl/) command-lin {{% /capture %}} +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + {{% capture steps %}} ## Define clusters, users, and contexts diff --git a/content/en/docs/tasks/access-application-cluster/configure-cloud-provider-firewall.md b/content/en/docs/tasks/access-application-cluster/configure-cloud-provider-firewall.md index eeae6bc0f4..cd1cce6410 100644 --- a/content/en/docs/tasks/access-application-cluster/configure-cloud-provider-firewall.md +++ b/content/en/docs/tasks/access-application-cluster/configure-cloud-provider-firewall.md @@ -3,15 +3,30 @@ reviewers: - bprashanth - davidopp title: Configure Your Cloud Provider's Firewalls +content_template: templates/task weight: 90 --- +{{% capture prerequisites %}} + Many cloud providers (e.g. Google Compute Engine) define firewalls that help prevent inadvertent exposure to the internet. When exposing a service to the external world, you may need to open up one or more ports in these firewalls to serve traffic. This document describes this process, as well as any provider specific details that may be necessary. -### Restrict Access For LoadBalancer Service +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Restrict Access For LoadBalancer Service When using a Service with `spec.type: LoadBalancer`, you can specify the IP ranges that are allowed to access the load balancer by using `spec.loadBalancerSourceRanges`. This field takes a list of IP CIDR ranges, which Kubernetes will use to configure firewall exceptions. @@ -55,7 +70,7 @@ spec: - 130.211.204.2/32 ``` -### Google Compute Engine +## Google Compute Engine When using a Service with `spec.type: LoadBalancer`, the firewall will be opened automatically. When using `spec.type: NodePort`, however, the firewall @@ -69,11 +84,9 @@ You can add a firewall with the `gcloud` command line tool: gcloud compute firewall-rules create my-rule --allow=tcp: ``` -**Note** -There is one important security note when using firewalls on Google Compute Engine: - -as of Kubernetes v1.0.0, GCE firewalls are defined per-vm, rather than per-ip -address. This means that when you open a firewall for a service's ports, +{{< note >}} +**Note**: GCE firewalls are defined per-vm, rather than per-ip +address. This means that when you open a firewall for a service's ports, anything that serves on that port on that VM's host IP address may potentially serve traffic. Note that this is not a problem for other Kubernetes services, as they listen on IP addresses that are different than the host node's external @@ -93,8 +106,6 @@ Consequently, please be careful when opening firewalls in Google Compute Engine or Google Kubernetes Engine. You may accidentally be exposing other services to the wilds of the internet. -This will be fixed in an upcoming release of Kubernetes. +{{< /note >}} -### Other cloud providers - -Coming soon. +{{% /capture %}} diff --git a/content/en/docs/tasks/access-application-cluster/configure-dns-cluster.md b/content/en/docs/tasks/access-application-cluster/configure-dns-cluster.md index f66673e3b2..cde20991cd 100644 --- a/content/en/docs/tasks/access-application-cluster/configure-dns-cluster.md +++ b/content/en/docs/tasks/access-application-cluster/configure-dns-cluster.md @@ -1,7 +1,13 @@ --- title: Configure DNS for a Cluster weight: 120 +content_template: templates/concept --- -Kubernetes offers a DNS cluster addon, which most of the supported environments enable by default. For more information on how to configure DNS for a Kubernetes cluster, see the [Kubernetes DNS sample plugin.](https://github.com/kubernetes/kubernetes/tree/release-1.5/examples/cluster-dns) +{{% capture overview %}} +Kubernetes offers a DNS cluster addon, which most of the supported environments enable by default. +{{% /capture %}} +{{% capture body %}} +For more information on how to configure DNS for a Kubernetes cluster, see the [Kubernetes DNS sample plugin.](https://github.com/kubernetes/kubernetes/tree/release-1.5/examples/cluster-dns) +{{% /capture %}} diff --git a/content/en/docs/tasks/access-application-cluster/web-ui-dashboard.md b/content/en/docs/tasks/access-application-cluster/web-ui-dashboard.md index c60ceaf04f..a38a9552f4 100644 --- a/content/en/docs/tasks/access-application-cluster/web-ui-dashboard.md +++ b/content/en/docs/tasks/access-application-cluster/web-ui-dashboard.md @@ -4,17 +4,24 @@ reviewers: - mikedanese - rf232 title: Web UI (Dashboard) +content_template: templates/concept weight: 10 --- +{{% capture overview %}} + Dashboard is a web-based Kubernetes user interface. You can use Dashboard to deploy containerized applications to a Kubernetes cluster, troubleshoot your containerized application, and manage the cluster itself along with its attendant resources. You can use Dashboard to get an overview of applications running on your cluster, as well as for creating or modifying individual Kubernetes resources (such as Deployments, Jobs, DaemonSets, etc). For example, you can scale a Deployment, initiate a rolling update, restart a pod or deploy new applications using a deploy wizard. Dashboard also provides information on the state of Kubernetes resources in your cluster, and on any errors that may have occurred. ![Kubernetes Dashboard UI](/images/docs/ui-dashboard.png) +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Deploying the Dashboard UI The Dashboard UI is not deployed by default. To deploy it, run the following command: @@ -165,7 +172,11 @@ Pod lists and detail pages link to logs viewer that is built into Dashboard. The ![Logs viewer](/images/docs/ui-dashboard-logs-view.png) -## More information +{{% /capture %}} + +{{% capture whatsnext %}} For more information, see the [Kubernetes Dashboard project page](https://github.com/kubernetes/dashboard). + +{{% /capture %}} diff --git a/content/en/docs/tasks/access-kubernetes-api/setup-extension-api-server.md b/content/en/docs/tasks/access-kubernetes-api/setup-extension-api-server.md index 92a234e80c..62b5704dfc 100644 --- a/content/en/docs/tasks/access-kubernetes-api/setup-extension-api-server.md +++ b/content/en/docs/tasks/access-kubernetes-api/setup-extension-api-server.md @@ -20,6 +20,12 @@ Setting up an extension API server to work the aggregation layer allows the Kube {{% /capture %}} +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + {{% capture steps %}} ## Setup an extension api-server to work with the aggregation layer diff --git a/content/en/docs/tasks/administer-cluster/cluster-management.md b/content/en/docs/tasks/administer-cluster/cluster-management.md index 413248cc72..1a3c985afd 100644 --- a/content/en/docs/tasks/administer-cluster/cluster-management.md +++ b/content/en/docs/tasks/administer-cluster/cluster-management.md @@ -3,15 +3,22 @@ reviewers: - lavalamp - thockin title: Cluster Management +content_template: templates/concept --- -{{< toc >}} +{{% capture overview %}} This document describes several topics related to the lifecycle of a cluster: creating a new cluster, upgrading your cluster's master and worker nodes, performing node maintenance (e.g. kernel upgrades), and upgrading the Kubernetes API version of a running cluster. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Creating and configuring a Cluster To install Kubernetes on a set of machines, consult one of the existing [Getting Started guides](/docs/setup/) depending on your environment. @@ -211,3 +218,5 @@ kubectl convert -f pod.yaml --output-version v1 ``` For more options, please refer to the usage of [kubectl convert](/docs/reference/generated/kubectl/kubectl-commands/#convert) command. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/configure-multiple-schedulers.md b/content/en/docs/tasks/administer-cluster/configure-multiple-schedulers.md index bad469431f..e1b55f3b28 100644 --- a/content/en/docs/tasks/administer-cluster/configure-multiple-schedulers.md +++ b/content/en/docs/tasks/administer-cluster/configure-multiple-schedulers.md @@ -3,8 +3,11 @@ reviewers: - davidopp - madhusudancs title: Configure Multiple Schedulers +content_template: templates/task --- +{{% capture overview %}} + Kubernetes ships with a default scheduler that is described [here](/docs/admin/kube-scheduler/). If the default scheduler does not suit your needs you can implement your own scheduler. Not just that, you can even run multiple schedulers simultaneously alongside the default @@ -16,7 +19,19 @@ document. Please refer to the kube-scheduler implementation in [pkg/scheduler](https://github.com/kubernetes/kubernetes/tree/{{< param "githubbranch" >}}/pkg/scheduler) in the Kubernetes source directory for a canonical example. -### 1. Package the scheduler +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Package the scheduler Package your scheduler binary into a container image. For the purposes of this example, let's just use the default scheduler (kube-scheduler) as our second scheduler as well. @@ -48,7 +63,7 @@ docker build -t gcr.io/my-gcp-project/my-kube-scheduler:1.0 . gcloud docker -- push gcr.io/my-gcp-project/my-kube-scheduler:1.0 ``` -### 2. Define a Kubernetes Deployment for the scheduler +## Define a Kubernetes Deployment for the scheduler Now that we have our scheduler in a container image, we can just create a pod config for it and run it in our Kubernetes cluster. But instead of creating a pod @@ -70,7 +85,7 @@ Please see the [kube-scheduler documentation](/docs/admin/kube-scheduler/) for detailed description of other command line arguments. -### 3. Run the second scheduler in the cluster +## Run the second scheduler in the cluster In order to run your scheduler in a Kubernetes cluster, just create the deployment specified in the config above in a Kubernetes cluster: @@ -126,7 +141,7 @@ $ kubectl edit clusterrole system:kube-scheduler - update ``` -### 4. Specify schedulers for pods +## 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 in that pod spec. Let's look at three examples. @@ -178,6 +193,10 @@ kubectl create -f pod3.yaml kubectl get pods ``` +{{% /capture %}} + +{{% capture discussion %}} + ### Verifying that the pods were scheduled using the desired schedulers In order to make it easier to work through these examples, we did not verify that the @@ -195,3 +214,5 @@ verify that the pods were scheduled by the desired schedulers. ```shell kubectl get events ``` + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md b/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md index 38b82096a8..4eff0d0846 100644 --- a/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md +++ b/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md @@ -3,16 +3,24 @@ reviewers: - mml - wojtek-t title: Operating etcd clusters for Kubernetes +content_template: templates/task --- +{{% capture overview %}} + {{< glossary_definition term_id="etcd" length="all" prepend="etcd is a ">}} - +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} ## Prerequisites @@ -276,6 +284,10 @@ be back with new resource version. That would mean that restarting node components is not needed. But the assumptions here may not hold forever. {{< /note >}} +{{% /capture %}} + +{{% capture discussion %}} + ### Design This section describes how we are going to do the migration, given the @@ -399,3 +411,5 @@ you can talk to your cluster's etcd), try: ```shell curl -X PUT "http://${host}:${port}/v2/keys/_test" ``` + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/cpu-management-policies.md b/content/en/docs/tasks/administer-cluster/cpu-management-policies.md index e79d9a31d0..0dd23ad78c 100644 --- a/content/en/docs/tasks/administer-cluster/cpu-management-policies.md +++ b/content/en/docs/tasks/administer-cluster/cpu-management-policies.md @@ -4,11 +4,12 @@ reviewers: - sjenning - ConnorDoyle - balajismaniam +content_template: templates/task --- -{{< feature-state state="beta" >}} +{{% capture overview %}} -{{< toc >}} +{{< feature-state state="beta" >}} Kubernetes keeps many aspects of how pods execute on nodes abstracted from the user. This is by design.  However, some workloads require @@ -17,6 +18,18 @@ acceptably. The kubelet provides methods to enable more complex workload placement policies while keeping the abstraction free from explicit placement directives. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## CPU Management Policies By default, the kubelet uses [CFS quota](https://en.wikipedia.org/wiki/Completely_Fair_Scheduler) @@ -197,3 +210,4 @@ and `requests` are set equal to `limits` when not explicitly specified. And the container's resource limit for the CPU resource is an integer greater than or equal to one. The `nginx` container is granted 2 exclusive CPUs. +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/declare-network-policy.md b/content/en/docs/tasks/administer-cluster/declare-network-policy.md index 64602625a7..6c471332d8 100644 --- a/content/en/docs/tasks/administer-cluster/declare-network-policy.md +++ b/content/en/docs/tasks/administer-cluster/declare-network-policy.md @@ -21,6 +21,11 @@ You'll need to have a Kubernetes cluster in place, with network policy support. **Note**: The above list is sorted alphabetically by product name, not by recommendation or preference. This example is valid for a Kubernetes cluster using any of these providers. {{% /capture %}} +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} {{% capture steps %}} diff --git a/content/en/docs/tasks/administer-cluster/developing-cloud-controller-manager.md b/content/en/docs/tasks/administer-cluster/developing-cloud-controller-manager.md index 9168b8b138..9a39764526 100644 --- a/content/en/docs/tasks/administer-cluster/developing-cloud-controller-manager.md +++ b/content/en/docs/tasks/administer-cluster/developing-cloud-controller-manager.md @@ -4,20 +4,23 @@ reviewers: - thockin - wlan0 title: Developing Cloud Controller Manager +content_template: templates/concept --- -**Cloud Controller Manager is an alpha feature in 1.8. In upcoming releases it will -be the preferred way to integrate Kubernetes with any cloud. This will ensure cloud providers -can develop their features independently from the core Kubernetes release cycles.** +{{% capture overview %}} -{{< toc >}} - -## Background +{{< feature-state for_k8s_version="1.8" state="alpha" >}} Before going into how to build your own cloud controller manager, some background on how it works under the hood is helpful. The cloud controller manager is code from `kube-controller-manager` utilizing Go interfaces to allow implementations from any cloud to be plugged in. Most of the scaffolding and generic controller implementations will be in core, but it will always exec out to the cloud interfaces it is provided, so long as the [cloud provider interface](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go#L29-L50) is satisfied. To dive a little deeper into implementation details, all cloud controller managers will import packages from Kubernetes core, the only difference being each project will register their own cloud providers by calling [cloudprovider.RegisterCloudProvider](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/plugins.go#L42-L52) where a global variable of available cloud providers is updated. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Developing ### Out of Tree @@ -33,3 +36,5 @@ Using existing out-of-tree cloud providers as an example may be helpful. You can ### In Tree For in-tree cloud providers, you can run the in-tree cloud controller manager as a [Daemonset](/docs/tasks/administer-cluster/cloud-controller-manager-daemonset-example.yaml) in your cluster. See the [running cloud controller manager docs](/docs/tasks/administer-cluster/running-cloud-controller.md) for more details. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md b/content/en/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md index 795abbc654..27d0107cd6 100644 --- a/content/en/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md +++ b/content/en/docs/tasks/administer-cluster/dns-horizontal-autoscaling.md @@ -18,6 +18,12 @@ Kubernetes cluster. {{% /capture %}} +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + {{% capture steps %}} ## Determining whether DNS horizontal autoscaling is already enabled diff --git a/content/en/docs/tasks/administer-cluster/encrypt-data.md b/content/en/docs/tasks/administer-cluster/encrypt-data.md index 3d68a1b44e..ff291a33f8 100644 --- a/content/en/docs/tasks/administer-cluster/encrypt-data.md +++ b/content/en/docs/tasks/administer-cluster/encrypt-data.md @@ -21,6 +21,14 @@ This page shows how to enable and configure encryption of secret data at rest. {{% /capture %}} +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + {{% capture steps %}} ## Configuration and determining whether encryption at rest is already enabled diff --git a/content/en/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md b/content/en/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md index 6b72b8ffba..ccff3750be 100644 --- a/content/en/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md +++ b/content/en/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md @@ -4,11 +4,10 @@ reviewers: - filipg - piosz title: Guaranteed Scheduling For Critical Add-On Pods +content_template: templates/concept --- -{{< toc >}} - -## Overview +{{% capture overview %}} In addition to Kubernetes core components like api-server, scheduler, controller-manager running on a master machine there are a number of add-ons which, for various reasons, must run on a regular cluster node (rather than the Kubernetes master). @@ -17,6 +16,12 @@ A cluster may stop working properly if a critical add-on is evicted (either manu and becomes pending (for example when the cluster is highly utilized and either there are other pending pods that schedule into the space vacated by the evicted critical add-on pod or the amount of resources available on the node changed for some other reason). +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Rescheduler: guaranteed scheduling of critical add-ons **Rescheduler is deprecated as of Kubernetes 1.10 and will be removed in version 1.12 in accordance with the [deprecation policy](/docs/reference/deprecation-policy) for beta features.** @@ -62,3 +67,5 @@ A pod could also be considered critical, if its priority is greater than or equa To be considered critical, the pod has to run in the `kube-system` namespace (configurable via flag) and * Have the priorityClass set as "system-cluster-critical" or "system-node-critical", the latter being the highest for entire cluster and `scheduler.alpha.kubernetes.io/critical-pod` annotation set to empty string(This will be deprecated too). + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/highly-available-master.md b/content/en/docs/tasks/administer-cluster/highly-available-master.md index f789f21b6c..5427e198e1 100644 --- a/content/en/docs/tasks/administer-cluster/highly-available-master.md +++ b/content/en/docs/tasks/administer-cluster/highly-available-master.md @@ -2,12 +2,27 @@ reviewers: - jszczepkowski title: Set up High-Availability Kubernetes Masters +content_template: templates/task --- +{{% capture overview %}} + +{{< feature-state for_k8s_version="1.5" state="alpha" >}} + +You can replicate Kubernetes masters in `kube-up` or `kube-down` scripts for Google Compute Engine. +This document describes how to use kube-up/down scripts to manage highly available (HA) masters and how HA masters are implemented for use with GCE. + +{{% /capture %}} + {{< toc >}} -Kubernetes version 1.5 adds alpha support for replicating Kubernetes masters in `kube-up` or `kube-down` scripts for Google Compute Engine. -This document describes how to use kube-up/down scripts to manage highly available (HA) masters and how HA masters are implemented for use with GCE. +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} ## Starting an HA-compatible cluster @@ -104,6 +119,10 @@ If the cluster is large, it may take a long time to duplicate its state. This operation may be sped up by migrating etcd data directory, as described [here](https://coreos.com/etcd/docs/latest/admin_guide.html#member-migration) (we are considering adding support for etcd data dir migration in future). +{{% /capture %}} + +{{% capture discussion %}} + ## Implementation notes ![ha-master-gce](/images/docs/ha-master-gce.png) @@ -154,3 +173,5 @@ To make such deployment secure, communication between etcd instances is authoriz ## Additional reading [Automated HA master deployment - design doc](https://git.k8s.io/community/contributors/design-proposals/cluster-lifecycle/ha_master.md) + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/namespaces-walkthrough.md b/content/en/docs/tasks/administer-cluster/namespaces-walkthrough.md index 898ba5fa8d..898d8ff029 100644 --- a/content/en/docs/tasks/administer-cluster/namespaces-walkthrough.md +++ b/content/en/docs/tasks/administer-cluster/namespaces-walkthrough.md @@ -3,8 +3,10 @@ reviewers: - derekwaynecarr - janetkuo title: Namespaces Walkthrough +content_template: templates/task --- +{{% capture overview %}} Kubernetes _namespaces_ help different projects, teams, or customers to share a Kubernetes cluster. It does this by providing the following: @@ -16,14 +18,26 @@ Use of multiple namespaces is optional. This example demonstrates how to use Kubernetes namespaces to subdivide your cluster. -### Step Zero: Prerequisites +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Prerequisites This example assumes the following: 1. You have an [existing Kubernetes cluster](/docs/setup/). 2. You have a basic understanding of Kubernetes _[Pods](/docs/concepts/workloads/pods/pod/)_, _[Services](/docs/concepts/services-networking/service/)_, and _[Deployments](/docs/concepts/workloads/controllers/deployment/)_. -### Step One: Understand the default namespace +## Understand the default namespace By default, a Kubernetes cluster will instantiate a default namespace when provisioning the cluster to hold the default set of Pods, Services, and Deployments used by the cluster. @@ -36,7 +50,7 @@ NAME STATUS AGE default Active 13m ``` -### Step Two: Create new namespaces +## Create new namespaces For this exercise, we will create two additional Kubernetes namespaces to hold our content. @@ -83,7 +97,7 @@ development Active 29s name=development production Active 23s name=production ``` -### Step Three: Create pods in each namespace +## Create pods in each namespace A Kubernetes namespace provides the scope for Pods, Services, and Deployments in the cluster. @@ -251,3 +265,5 @@ At this point, it should be clear that the resources users create in one namespa As the policy support in Kubernetes evolves, we will extend this scenario to show how you can provide different authorization rules for each namespace. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/out-of-resource.md b/content/en/docs/tasks/administer-cluster/out-of-resource.md index d225988e21..62c9f8344d 100644 --- a/content/en/docs/tasks/administer-cluster/out-of-resource.md +++ b/content/en/docs/tasks/administer-cluster/out-of-resource.md @@ -4,9 +4,10 @@ reviewers: - vishh - timstclair title: Configure Out Of Resource Handling +content_template: templates/concept --- -{{< toc >}} +{{% capture overview %}} This page explains how to configure out of resource handling with `kubelet`. @@ -15,6 +16,12 @@ are low. This is especially important when dealing with incompressible compute resources, such as memory or disk space. If such resources are exhausted, nodes become unstable. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Eviction Policy The `kubelet` can proactively monitor for and prevent total starvation of a @@ -369,3 +376,5 @@ to prevent system OOMs, and promote eviction of workloads so cluster state can r The Pod eviction may evict more Pods than needed due to stats collection timing gap. This can be mitigated by adding the ability to get root container stats on an on-demand basis [(https://github.com/google/cadvisor/issues/1247)](https://github.com/google/cadvisor/issues/1247) in the future. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/reserve-compute-resources.md b/content/en/docs/tasks/administer-cluster/reserve-compute-resources.md index bad61545e7..21ad5376aa 100644 --- a/content/en/docs/tasks/administer-cluster/reserve-compute-resources.md +++ b/content/en/docs/tasks/administer-cluster/reserve-compute-resources.md @@ -4,9 +4,10 @@ reviewers: - derekwaynecarr - dashpole title: Reserve Compute Resources for System Daemons +content_template: templates/task --- -{{< toc >}} +{{% capture overview %}} Kubernetes nodes can be scheduled to `Capacity`. Pods can consume all the available capacity on a node by default. This is an issue because nodes @@ -20,6 +21,18 @@ compute resources for system daemons. Kubernetes recommends cluster administrators to configure `Node Allocatable` based on their workload density on each node. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Node Allocatable ```text @@ -185,6 +198,10 @@ more features are added. Over time, kubernetes project will attempt to bring down utilization of node system daemons, but that is not a priority as of now. So expect a drop in `Allocatable` capacity in future releases. +{{% /capture %}} + +{{% capture discussion %}} + ## Example Scenario Here is an example to illustrate Node Allocatable computation: @@ -230,3 +247,5 @@ the proper part of the cgroup hierarchy. As of Kubernetes version 1.7, `kubelet` supports specifying `storage` as a resource for `kube-reserved` and `system-reserved`. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/running-cloud-controller.md b/content/en/docs/tasks/administer-cluster/running-cloud-controller.md index f79be347f8..107d23a48b 100644 --- a/content/en/docs/tasks/administer-cluster/running-cloud-controller.md +++ b/content/en/docs/tasks/administer-cluster/running-cloud-controller.md @@ -4,18 +4,23 @@ reviewers: - thockin - wlan0 title: Kubernetes Cloud Controller Manager +content_template: templates/concept --- +{{% capture overview %}} + {{< feature-state state="alpha" >}} -{{< toc >}} - -## Cloud Controller Manager - Kubernetes v1.6 introduced a new binary called `cloud-controller-manager`. `cloud-controller-manager` is a daemon that embeds cloud-specific control loops. These cloud-specific control loops were originally in the `kube-controller-manager`. Since cloud providers develop and release at a different pace compared to the Kubernetes project, abstracting the provider-specific code to the `cloud-controller-manager` binary allows cloud vendors to evolve independently from the core Kubernetes code. The `cloud-controller-manager` can be linked to any cloud provider that satisfies [cloudprovider.Interface](https://git.k8s.io/kubernetes/pkg/cloudprovider/cloud.go). For backwards compatibility, the [cloud-controller-manager](https://github.com/kubernetes/kubernetes/tree/master/cmd/cloud-controller-manager) provided in the core Kubernetes project uses the same cloud libraries as `kube-controller-manager`. Cloud providers already supported in Kubernetes core are expected to use the in-tree cloud-controller-manager to transition out of Kubernetes core. In future Kubernetes releases, all cloud controller managers will be developed outside of the core Kubernetes project managed by sig leads or cloud vendors. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Administration ### Requirements @@ -91,3 +96,5 @@ As this initiative evolves, changes will be made to address these issues in upco ## Developing your own Cloud Controller Manager To build and develop your own cloud controller manager, read the [Developing Cloud Controller Manager](/docs/tasks/administer-cluster/developing-cloud-controller-manager.md) doc. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-cluster/static-pod.md b/content/en/docs/tasks/administer-cluster/static-pod.md index c8d3511b23..139ecf40da 100644 --- a/content/en/docs/tasks/administer-cluster/static-pod.md +++ b/content/en/docs/tasks/administer-cluster/static-pod.md @@ -2,8 +2,11 @@ reviewers: - jsafrane title: Static Pods +content_template: templates/concept --- +{{% capture overview %}} + **If you are running clustered Kubernetes and are using static pods to run a pod on every node, you should probably be using a [DaemonSet](/docs/concepts/workloads/controllers/daemonset/)!** *Static pods* are managed directly by kubelet daemon on a specific node, without the API server observing it. It does not have an associated replication controller, and kubelet daemon itself watches it and restarts it when it crashes. There is no health check. Static pods are always bound to one kubelet daemon and always run on the same node with it. @@ -11,6 +14,12 @@ title: Static Pods Kubelet automatically tries to create a *mirror pod* on the Kubernetes API server for each static pod. This means that the pods are visible on the API server but cannot be controlled from there. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Static pod creation Static pod can be created in two ways: either by using configuration file(s) or by HTTP. @@ -108,7 +117,7 @@ static-web-my-node1 1/1 Running 0 12s Back to our `my-node1` host, we can try to stop the container manually and see, that kubelet automatically restarts it in a while: -```shell +```none [joe@host ~] $ ssh my-node1 [joe@my-node1 ~] $ docker stop f6d05272b57e [joe@my-node1 ~] $ sleep 20 @@ -132,3 +141,5 @@ Running kubelet periodically scans the configured directory (`/etc/kubelet.d` in CONTAINER ID IMAGE COMMAND CREATED ... e7a62e3427f1 nginx:latest "nginx -g 'daemon of 27 seconds ago ``` + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-federation/deployment.md b/content/en/docs/tasks/administer-federation/deployment.md index db1a4043dc..4c73ae39aa 100644 --- a/content/en/docs/tasks/administer-federation/deployment.md +++ b/content/en/docs/tasks/administer-federation/deployment.md @@ -15,9 +15,10 @@ Deployment](/docs/concepts/workloads/controllers/deployment/) and provide the sa Creating them in the federation control plane ensures that the desired number of replicas exist across the registered clusters. -**As of Kubernetes version 1.5, Federated Deployment is an Alpha feature. The core -functionality of Deployment is present, but some features -(such as full rollout compatibility) are still in development.** +{{< feature-state for_k8s_version="1.5" state="alpha" >}} + +Some features +(such as full rollout compatibility) are still in development. {{% /capture %}} {{% capture prerequisites %}} diff --git a/content/en/docs/tasks/administer-federation/events.md b/content/en/docs/tasks/administer-federation/events.md index 4f1a2f23b5..299d36215a 100644 --- a/content/en/docs/tasks/administer-federation/events.md +++ b/content/en/docs/tasks/administer-federation/events.md @@ -1,14 +1,20 @@ --- title: Federated Events +content_template: templates/concept --- +{{% capture overview %}} + {{< include "federation-current-state.md" >}} This guide explains how to use events in federation control plane to help in debugging. +{{% /capture %}} {{< toc >}} +{{% capture body %}} + ## Prerequisites This guide assumes that you have a running Kubernetes Cluster @@ -23,7 +29,7 @@ You are also expected to have a basic [working knowledge of Kubernetes](/docs/setup/) in general. -## Overview +## View federation events Events in federation control plane (referred to as "federation events" in this guide) are very similar to the traditional Kubernetes @@ -39,3 +45,5 @@ kubectl --context=federation-cluster get events ``` The standard kubectl get, update, delete commands will all work. + +{{% /capture %}} diff --git a/content/en/docs/tasks/administer-federation/secret.md b/content/en/docs/tasks/administer-federation/secret.md index 48795b0dd1..028a1f1624 100644 --- a/content/en/docs/tasks/administer-federation/secret.md +++ b/content/en/docs/tasks/administer-federation/secret.md @@ -1,13 +1,25 @@ --- title: Federated Secrets +content_template: templates/concept --- +{{% capture overview %}} + {{< include "federation-current-state.md" >}} This guide explains how to use secrets in Federation control plane. +Secrets in federation control plane (referred to as "federated secrets" in +this guide) are very similar to the traditional [Kubernetes +Secrets](/docs/concepts/configuration/secret/) providing the same functionality. +Creating them in the federation control plane ensures that they are synchronized +across all the clusters in federation. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Prerequisites This guide assumes that you have a running Kubernetes Cluster @@ -22,15 +34,6 @@ You are also expected to have a basic [working knowledge of Kubernetes](/docs/setup/) in general and [Secrets](/docs/concepts/configuration/secret/) in particular. -## Overview - -Secrets in federation control plane (referred to as "federated secrets" in -this guide) are very similar to the traditional [Kubernetes -Secrets](/docs/concepts/configuration/secret/) providing the same functionality. -Creating them in the federation control plane ensures that they are synchronized -across all the clusters in federation. - - ## Creating a Federated Secret The API for Federated Secret is 100% compatible with the @@ -86,3 +89,5 @@ Note that at this point, deleting a federated secret will not delete the corresponding secrets from underlying clusters. You must delete the underlying secrets manually. We intend to fix this in the future. + +{{% /capture %}} diff --git a/content/en/docs/tasks/configure-pod-container/configure-service-account.md b/content/en/docs/tasks/configure-pod-container/configure-service-account.md index 223652f067..5f8d628995 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-service-account.md +++ b/content/en/docs/tasks/configure-pod-container/configure-service-account.md @@ -4,9 +4,11 @@ reviewers: - liggitt - thockin title: Configure Service Accounts for Pods +content_template: templates/task weight: 90 --- +{{% capture overview %}} A service account provides an identity for processes that run in a Pod. *This is a user introduction to Service Accounts. See also the @@ -26,6 +28,18 @@ cluster). Processes in containers inside pods can also contact the apiserver. When they do, they are authenticated as a particular Service Account (for example, `default`). +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Use the Default Service Account to access the API server. When you create a pod, if you do not specify a service account, it is @@ -233,3 +247,5 @@ spec: TODO: Test and explain how to use additional non-K8s secrets with an existing service account. --> + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md b/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md index 634a05628b..de377395e4 100644 --- a/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md +++ b/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md @@ -2,129 +2,33 @@ reviewers: - cdrage title: Translate a Docker Compose File to Kubernetes Resources +content_template: templates/task weight: 170 --- -{{< toc >}} - -# Kubernetes + Compose = Kompose +{{% capture overview %}} What's Kompose? It's a conversion tool for all things compose (namely Docker Compose) to container orchestrators (Kubernetes or OpenShift). More information can be found on the Kompose website at [http://kompose.io](http://kompose.io). -In three simple steps, we'll take you from Docker Compose to Kubernetes. +{{% /capture %}} -__1. Take a sample docker-compose.yaml file__ +{{< toc >}} -```yaml -version: "2" +{{% capture prerequisites %}} -services: +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - redis-master: - image: k8s.gcr.io/redis:e2e - ports: - - "6379" +{{% /capture %}} - redis-slave: - image: gcr.io/google_samples/gb-redisslave:v1 - ports: - - "6379" - environment: - - GET_HOSTS_FROM=dns +{{% capture steps %}} - frontend: - image: gcr.io/google-samples/gb-frontend:v4 - ports: - - "80:80" - environment: - - GET_HOSTS_FROM=dns - labels: - kompose.service.type: LoadBalancer -``` - -__2. Run `kompose up` in the same directory__ - -```bash -$ kompose up -We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. -If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. - -INFO Successfully created Service: redis -INFO Successfully created Service: web -INFO Successfully created Deployment: redis -INFO Successfully created Deployment: web - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. -``` - -__Alternatively, you can run `kompose convert` and deploy with `kubectl`__ - -__2.1. Run `kompose convert` in the same directory__ - -```bash -$ kompose convert -INFO Kubernetes file "frontend-service.yaml" created -INFO Kubernetes file "redis-master-service.yaml" created -INFO Kubernetes file "redis-slave-service.yaml" created -INFO Kubernetes file "frontend-deployment.yaml" created -INFO Kubernetes file "redis-master-deployment.yaml" created -INFO Kubernetes file "redis-slave-deployment.yaml" created -``` - -__2.2. And start it on Kubernetes!__ - -```bash -$ kubectl create -f frontend-service.yaml,redis-master-service.yaml,redis-slave-service.yaml,frontend-deployment.yaml,redis-master-deployment.yaml,redis-slave-deployment.yaml -service "frontend" created -service "redis-master" created -service "redis-slave" created -deployment "frontend" created -deployment "redis-master" created -deployment "redis-slave" created -``` - -__3. View the newly deployed service__ - -Now that your service has been deployed, let's access it. - -If you're already using `minikube` for your development process: - -```bash -$ minikube service frontend -``` - -Otherwise, let's look up what IP your service is using! - -```sh -$ kubectl describe svc frontend -Name: frontend -Namespace: default -Labels: service=frontend -Selector: service=frontend -Type: LoadBalancer -IP: 10.0.0.183 -LoadBalancer Ingress: 123.45.67.89 -Port: 80 80/TCP -NodePort: 80 31144/TCP -Endpoints: 172.17.0.4:80 -Session Affinity: None -No events. - -``` - -If you're using a cloud provider, your IP will be listed next to `LoadBalancer Ingress`. - -```sh -$ curl http://123.45.67.89 -``` - -# Installation +## Install Kompose We have multiple ways to install Kompose. Our preferred method is downloading the binary from the latest GitHub release. -#### GitHub release +### GitHub release Kompose is released via GitHub on a three-week cycle, you can see all current releases on the [GitHub release page](https://github.com/kubernetes/kompose/releases). @@ -144,7 +48,7 @@ sudo mv ./kompose /usr/local/bin/kompose Alternatively, you can download the [tarball](https://github.com/kubernetes/kompose/releases). -#### Go +### Go Installing using `go get` pulls from the master branch with the latest development changes. @@ -152,7 +56,7 @@ Installing using `go get` pulls from the master branch with the latest developme go get -u github.com/kubernetes/kompose ``` -#### CentOS +### CentOS Kompose is in [EPEL](https://fedoraproject.org/wiki/EPEL) CentOS repository. If you don't have [EPEL](https://fedoraproject.org/wiki/EPEL) repository already installed and enabled you can do it by running `sudo yum install epel-release` @@ -163,14 +67,14 @@ If you have [EPEL](https://fedoraproject.org/wiki/EPEL) enabled in your system, sudo yum -y install kompose ``` -#### Fedora +### Fedora Kompose is in Fedora 24, 25 and 26 repositories. You can install it just like any other package. ```bash sudo dnf -y install kompose ``` -#### macOS +### macOS On macOS you can install latest release via [Homebrew](https://brew.sh): ```bash @@ -178,7 +82,120 @@ brew install kompose ``` -# User Guide +## Use Kompose + +In just a few steps, we'll take you from Docker Compose to Kubernetes. All +you need is an existing `docker-compose.yml` file. + +1. Go to the directory containing your `docker-compose.yml` file. If you don't + have one, test using this one. + + ```yaml + version: "2" + + services: + + redis-master: + image: k8s.gcr.io/redis:e2e + ports: + - "6379" + + redis-slave: + image: gcr.io/google_samples/gb-redisslave:v1 + ports: + - "6379" + environment: + - GET_HOSTS_FROM=dns + + frontend: + image: gcr.io/google-samples/gb-frontend:v4 + ports: + - "80:80" + environment: + - GET_HOSTS_FROM=dns + labels: + kompose.service.type: LoadBalancer + ``` + +2. Run the `kompose up` command to deploy to Kubernetes directly, or skip to + the next step instead to generate a file to use with `kubectl`. + + ```bash + $ kompose up + We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. + If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. + + INFO Successfully created Service: redis + INFO Successfully created Service: web + INFO Successfully created Deployment: redis + INFO Successfully created Deployment: web + + Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. + ``` + +3. To convert the `docker-compose.yml` file to files that you can use with + `kubectl`, run `kompose convert` and then `kubectl create -f `. + + ```bash + $ kompose convert + INFO Kubernetes file "frontend-service.yaml" created + INFO Kubernetes file "redis-master-service.yaml" created + INFO Kubernetes file "redis-slave-service.yaml" created + INFO Kubernetes file "frontend-deployment.yaml" created + INFO Kubernetes file "redis-master-deployment.yaml" created + INFO Kubernetes file "redis-slave-deployment.yaml" created + ``` + + ```bash + $ kubectl create -f frontend-service.yaml,redis-master-service.yaml,redis-slave-service.yaml,frontend-deployment.yaml,redis-master-deployment.yaml,redis-slave-deployment.yaml + service "frontend" created + service "redis-master" created + service "redis-slave" created + deployment "frontend" created + deployment "redis-master" created + deployment "redis-slave" created + ``` + + Your deployments are running in Kubernetes. + +4. Access your application. + + If you're already using `minikube` for your development process: + + ```bash + $ minikube service frontend + ``` + + Otherwise, let's look up what IP your service is using! + + ```sh + $ kubectl describe svc frontend + Name: frontend + Namespace: default + Labels: service=frontend + Selector: service=frontend + Type: LoadBalancer + IP: 10.0.0.183 + LoadBalancer Ingress: 123.45.67.89 + Port: 80 80/TCP + NodePort: 80 31144/TCP + Endpoints: 172.17.0.4:80 + Session Affinity: None + No events. + + ``` + + If you're using a cloud provider, your IP will be listed next to `LoadBalancer Ingress`. + + ```sh + $ curl http://123.45.67.89 + ``` + +{{% /capture %}} + +{{% capture discussion %}} + +## User Guide - CLI - [`kompose convert`](#kompose-convert) @@ -568,3 +585,5 @@ Please note that changing service name might break some `docker-compose` files. Kompose supports Docker Compose versions: 1, 2 and 3. We have limited support on versions 2.1 and 3.2 due to their experimental nature. A full list on compatibility between all three versions is listed in our [conversion document](https://github.com/kubernetes/kompose/blob/master/docs/conversion.md) including a list of all incompatible Docker Compose keys. + +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/audit.md b/content/en/docs/tasks/debug-application-cluster/audit.md index f5c406b9c4..75c9656fd2 100644 --- a/content/en/docs/tasks/debug-application-cluster/audit.md +++ b/content/en/docs/tasks/debug-application-cluster/audit.md @@ -3,10 +3,11 @@ reviewers: - soltysh - sttts - ericchiang +content_template: templates/concept title: Auditing --- -{{< toc >}} +{{% capture overview %}} {{< feature-state state="beta" >}} @@ -23,6 +24,12 @@ answer the following questions: - from where was it initiated? - to where was it going? +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + [Kube-apiserver][kube-apiserver] performs auditing. Each request on each stage of its execution generates an event, which is then pre-processed according to a certain policy and written to a backend. The policy determines what's recorded @@ -97,6 +104,7 @@ In both cases, audit events structure is defined by the API in the `audit.k8s.io` API group. The current version of the API is [`v1beta1`][auditing-api]. +{{< note >}} **Note:** In case of patches, request body is a JSON array with patch operations, not a JSON object with an appropriate Kubernetes API object. For example, the following request body is a valid patch request to `/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`. @@ -114,6 +122,7 @@ request to `/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`. } ] ``` +{{< /note >}} ### Log backend @@ -200,7 +209,7 @@ In this example, we will use fluentd to split audit events by different namespac 1. install [fluentd, fluent-plugin-forest and fluent-plugin-rewrite-tag-filter][fluentd_install_doc] in the kube-apiserver node 1. create a config file for fluentd - ```shell + ```none $ cat < /etc/fluentd/config # fluentd conf runs in the same host with kube-apiserver @@ -260,7 +269,7 @@ In this example, we will use fluentd to split audit events by different namespac --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-log-path=/var/log/kube-audit --audit-log-format=json ``` -1. check audits for different namespaces in /var/log/audit-*.log +1. check audits for different namespaces in `/var/log/audit-*.log` ### Use logstash to collect and distribute audit events from webhook backend @@ -271,7 +280,7 @@ different users into different files. 1. install [logstash][logstash_install_doc] 1. create config file for logstash - ```shell + ```none $ cat < /etc/logstash/config input{ http{ @@ -308,7 +317,7 @@ different users into different files. 1. create a [kubeconfig file](/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig/) for kube-apiserver webhook audit backend - ```shell + ```none $ cat < /etc/kubernetes/audit-webhook-kubeconfig apiVersion: v1 clusters: @@ -333,7 +342,7 @@ different users into different files. --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-webhook-config-file=/etc/kubernetes/audit-webhook-kubeconfig ``` -1. check audits in logstash node's directories /var/log/kube-audit-*/audit +1. check audits in logstash node's directories `/var/log/kube-audit-*/audit` Note that in addition to file output plugin, logstash has a variety of outputs that let users route data where they want. For example, users can emit audit events to elasticsearch @@ -392,3 +401,5 @@ and `audit-log-maxage` options. [logstash]: https://www.elastic.co/products/logstash [logstash_install_doc]: https://www.elastic.co/guide/en/logstash/current/installing-logstash.html [kube-aggregator]: /docs/concepts/api-extension/apiserver-aggregation + +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/core-metrics-pipeline.md b/content/en/docs/tasks/debug-application-cluster/core-metrics-pipeline.md index ea1fd9dcad..f289704423 100644 --- a/content/en/docs/tasks/debug-application-cluster/core-metrics-pipeline.md +++ b/content/en/docs/tasks/debug-application-cluster/core-metrics-pipeline.md @@ -3,13 +3,22 @@ reviewers: - fgrzadkowski - piosz title: Core metrics pipeline +content_template: templates/concept --- +{{% capture overview %}} + Starting from Kubernetes 1.8, resource usage metrics, such as container CPU and memory usage, are available in Kubernetes through the Metrics API. These metrics can be either accessed directly by user, for example by using `kubectl top` command, or used by a controller in the cluster, e.g. Horizontal Pod Autoscaler, to make decisions. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## The Metrics API Through the Metrics API you can get the amount of resource currently used @@ -42,3 +51,5 @@ Metrics Server registered in the main API server through which was introduced in Kubernetes 1.7. Learn more about the metrics server in [the design doc](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/instrumentation/metrics-server.md). + +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md b/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md index 07c8a135e5..27cf1dc7df 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md @@ -2,15 +2,22 @@ reviewers: - janetkuo - thockin +content_template: templates/concept title: Application Introspection and Debugging --- +{{% capture overview %}} + Once your application is running, you'll inevitably need to debug problems with it. Earlier we described how you can use `kubectl get pods` to retrieve simple status information about your pods. But there are a number of ways to get even more information about your application. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Using `kubectl describe pod` to fetch details about pods For this example we'll use a Deployment to create two pods, similar to the earlier example. @@ -255,7 +262,9 @@ kubernetes-node-861h NotReady 1h v1.6.0+fff5156 kubernetes-node-bols Ready 1h v1.6.0+fff5156 kubernetes-node-st6x Ready 1h v1.6.0+fff5156 kubernetes-node-unaj Ready 1h v1.6.0+fff5156 +``` +```shell $ kubectl describe node kubernetes-node-861h Name: kubernetes-node-861h Role @@ -307,8 +316,12 @@ Allocated resources: ------------ ---------- --------------- ------------- 900m (60%) 2200m (146%) 1009286400 (66%) 5681286400 (375%) Events: +``` +```shell $ kubectl get node kubernetes-node-861h -o yaml +``` +```yaml apiVersion: v1 kind: Node metadata: @@ -350,7 +363,7 @@ status: systemUUID: ABE5F6B4-D44B-108B-C46A-24CCE16C8B6E ``` -## What's next? +{{% capture whatsnext %}} Learn about additional debugging tools, including: @@ -360,4 +373,4 @@ Learn about additional debugging tools, including: * [Connecting to containers via proxies](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) * [Connecting to containers via port forwarding](/docs/tasks/access-application-cluster/port-forward-access-application-cluster/) - +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/debug-application.md b/content/en/docs/tasks/debug-application-cluster/debug-application.md index 829b6e2a1e..969be001bd 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-application.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-application.md @@ -3,14 +3,21 @@ reviewers: - mikedanese - thockin title: Troubleshoot Applications +content_template: templates/concept --- +{{% capture overview %}} + This guide is to help users debug applications that are deployed into Kubernetes and not behaving correctly. This is *not* a guide for people who want to debug their cluster. For that you should check out [this guide](/docs/admin/cluster-troubleshooting). +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Diagnosing the problem The first step in troubleshooting is triage. What is the problem? Is it your Pods, your Replication Controller or @@ -183,8 +190,12 @@ check: * 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? Kubernetes doesn't do port remapping, so if your application serves on 8080, the `containerPort` field needs to be 8080. -#### More information +{{% /capture %}} + +{{% capture whatsnext %}} If none of the above solves your problem, follow the instructions in [Debugging Service document](/docs/user-guide/debugging-services) to make sure that your `Service` is running, has `Endpoints`, and your `Pods` are actually serving; you have DNS working, iptables rules installed, and kube-proxy does not seem to be misbehaving. You may also visit [troubleshooting document](/docs/troubleshooting/) for more information. + +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/debug-cluster.md b/content/en/docs/tasks/debug-application-cluster/debug-cluster.md index 8031cbc9f8..01c4b86a44 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-cluster.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-cluster.md @@ -2,13 +2,22 @@ reviewers: - davidopp title: Troubleshoot Clusters +content_template: templates/concept --- +{{% capture overview %}} + This doc is about cluster troubleshooting; we assume you have already ruled out your application as the root cause of the problem you are experiencing. See the [application troubleshooting guide](/docs/tasks/debug-application-cluster/debug-application) for tips on application debugging. You may also visit [troubleshooting document](/docs/troubleshooting/) for more information. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Listing your cluster The first thing to debug in your cluster is if your nodes are all registered correctly. @@ -113,3 +122,5 @@ Mitigations: - Action: [Multiple independent clusters](/docs/concepts/cluster-administration/federation/) (and avoid making risky changes to all clusters at once) - Mitigates: Everything listed above. + +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md b/content/en/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md index f196853172..8aec219b4d 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md @@ -2,11 +2,10 @@ reviewers: - bprashanth title: Debug Pods and Replication Controllers +content_template: templates/concept --- -{{< toc >}} - -## Debugging pods +{{% capture overview %}} 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: @@ -18,6 +17,12 @@ there been recent restarts? Continue debugging depending on the state of the pods. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ### My pod stays pending If a pod is stuck in `Pending` it means that it can not be scheduled onto a @@ -105,3 +110,4 @@ or they can't. If they can't create pods, then please refer to the You can also use `kubectl describe rc ${CONTROLLER_NAME}` to inspect events related to the replication controller. +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/debug-service.md b/content/en/docs/tasks/debug-application-cluster/debug-service.md index 67c72c908d..9b9c4ab8f4 100644 --- a/content/en/docs/tasks/debug-application-cluster/debug-service.md +++ b/content/en/docs/tasks/debug-application-cluster/debug-service.md @@ -2,16 +2,22 @@ reviewers: - thockin - bowei +content_template: templates/concept title: Debug Services --- +{{% capture overview %}} An issue that comes up rather frequently for new installations of Kubernetes is that a `Service` is not working properly. You've run your `Deployment` and created a `Service`, but you get no response when you try to access it. This document will hopefully help you to figure out what's going wrong. +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Conventions Throughout this doc you will see various commands that you can run. Some @@ -45,7 +51,7 @@ OUTPUT For many steps here you will want to see what a `Pod` running in the cluster sees. The simplest way to do this is to run an interactive busybox `Pod`: -```shell +```none $ kubectl run -it --rm --restart=Never busybox --image=busybox sh If you don't see a command prompt, try pressing enter. / # @@ -291,6 +297,8 @@ and verify it: ```shell $ kubectl get service hostnames -o json +``` +```json { "kind": "Service", "apiVersion": "v1", @@ -430,7 +438,7 @@ depends on your `Node` OS. On some OSes it is a file, such as /var/log/kube-proxy.log, while other OSes use `journalctl` to access logs. You should see something like: -```shell +```none I1027 22:14:53.995134 5063 server.go:200] Running in resource-only container "/kube-proxy" I1027 22:14:53.998163 5063 server.go:247] Using iptables Proxier. I1027 22:14:53.999055 5063 server.go:255] Tearing down userspace rules. Errors here are acceptable. @@ -584,7 +592,7 @@ the permission to operate in `/sys` on node. If everything works properly, you should see something like: ```shell -u@node$ for intf in /sys/devices/virtual/net/cbr0/brif/*; do cat $intf/hairpin_mode; done +for intf in /sys/devices/virtual/net/cbr0/brif/*; do cat $intf/hairpin_mode; done 1 1 1 @@ -603,7 +611,6 @@ UP BROADCAST RUNNING PROMISC MULTICAST MTU:1460 Metric:1 * Seek help if none of above works out. - ## Seek help If you get this far, something very strange is happening. Your `Service` is @@ -617,7 +624,10 @@ Contact us on [email](https://groups.google.com/forum/#!forum/kubernetes-users) or [GitHub](https://github.com/kubernetes/kubernetes). -## More information +{{% /capture %}} + +{{% capture whatsnext %}} Visit [troubleshooting document](/docs/troubleshooting/) for more information. +{{% /capture %}} diff --git a/content/en/docs/tasks/debug-application-cluster/events-stackdriver.md b/content/en/docs/tasks/debug-application-cluster/events-stackdriver.md index 0c3ba613be..6755fa6843 100644 --- a/content/en/docs/tasks/debug-application-cluster/events-stackdriver.md +++ b/content/en/docs/tasks/debug-application-cluster/events-stackdriver.md @@ -2,10 +2,11 @@ reviewers: - piosz - x13n +content_template: templates/concept title: Events in Stackdriver --- - +{{% capture overview %}} Kubernetes events are objects that provide insight into what is happening inside a cluster, such as what decisions were made by scheduler or why some @@ -23,18 +24,24 @@ to capture events. This article describes a solution that exports Kubernetes events to Stackdriver Logging, where they can be processed and analyzed. +{{< note >}} **Note:** it is not guaranteed that all events happening in a cluster will be exported to Stackdriver. One possible scenario when events will not be exported is when event exporter is not running (e.g. during restart or upgrade). In most cases it's fine to use events for purposes like setting up [metrics][sdLogMetrics] and [alerts][sdAlerts], but you should be aware of the potential inaccuracy. +{{< /note >}} [sdLogMetrics]: https://cloud.google.com/logging/docs/view/logs_based_metrics [sdAlerts]: https://cloud.google.com/logging/docs/view/logs_based_metrics#creating_an_alerting_policy +{{% /capture %}} + {{< toc >}} +{{% capture body %}} + ## Deployment ### Google Kubernetes Engine @@ -85,4 +92,6 @@ jsonPayload.source.component="default-scheduler" jsonPayload.involvedObject.name:"nginx-deployment" ``` -Filtered events in the Stackdriver Logging interface +{{< figure src="/images/docs/stackdriver-event-exporter-filter.png" alt="Filtered events in the Stackdriver Logging interface" width="500" >}} + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana.md b/content/en/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana.md index e772927207..78ef4bfe8f 100644 --- a/content/en/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana.md +++ b/content/en/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana.md @@ -2,9 +2,12 @@ reviewers: - piosz - x13n +content_template: templates/concept title: Logging Using Elasticsearch and Kibana --- +{{% capture overview %}} + On the Google Compute Engine (GCE) platform, the default logging support targets [Stackdriver Logging](https://cloud.google.com/logging/), which is described in detail in the [Logging With Stackdriver Logging](/docs/user-guide/logging/stackdriver). @@ -16,6 +19,10 @@ Stackdriver Logging when running on GCE. Note that Elasticsearch and Kibana cannot be setup automatically in the Kubernetes cluster hosted on Google Kubernetes Engine, you have to deploy it manually. +{{% /capture %}} + +{{% capture body %}} + To use Elasticsearch and Kibana for cluster logging, you should set the following environment variable as shown below when creating your cluster with kube-up.sh: @@ -101,6 +108,11 @@ Here is a typical view of ingested logs from the Kibana viewer: ![Kibana logs](/images/docs/kibana-logs.png) +{{% /capture %}} + +{{% capture whatsnext %}} + Kibana opens up all sorts of powerful options for exploring your logs! For some ideas on how to dig into it, check out [Kibana's documentation](https://www.elastic.co/guide/en/kibana/current/discover.html). +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/debug-application-cluster/logging-stackdriver.md b/content/en/docs/tasks/debug-application-cluster/logging-stackdriver.md index 9085d4cf94..97399790d8 100644 --- a/content/en/docs/tasks/debug-application-cluster/logging-stackdriver.md +++ b/content/en/docs/tasks/debug-application-cluster/logging-stackdriver.md @@ -3,15 +3,26 @@ reviewers: - piosz - x13n title: Logging Using Stackdriver +content_template: templates/concept --- +{{% capture overview %}} + Before reading this page, it's highly recommended to familiarize yourself with the [overview of logging in Kubernetes](/docs/concepts/cluster-administration/logging). +{{< note >}} **Note:** By default, Stackdriver logging collects only your container's standard output and standard error streams. To collect any logs your application writes to a file (for example), see the [sidecar approach](/docs/concepts/cluster-administration/logging#sidecar-container-with-a-logging-agent) in the Kubernetes logging overview. +{{< /note >}} + +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} ## Deploying @@ -213,7 +224,7 @@ command line interface from the [Google Cloud SDK](https://cloud.google.com/sdk/ It uses Stackdriver Logging [filtering syntax](https://cloud.google.com/logging/docs/view/advanced_filters) to query specific logs. For example, you can run the following command: -```shell +```none $ gcloud beta logging read 'logName="projects/$YOUR_PROJECT_ID/logs/count"' --format json | jq '.[].textPayload' ... "2: Mon Jan 1 00:01:02 UTC 2001\n" @@ -335,3 +346,5 @@ with minor changes: Then run `make build push` from this directory. After updating `DaemonSet` to pick up the new image, you can use the plugin you installed in the fluentd configuration. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/debug-application-cluster/monitor-node-health.md b/content/en/docs/tasks/debug-application-cluster/monitor-node-health.md index beab96da8e..ca308d2b0d 100644 --- a/content/en/docs/tasks/debug-application-cluster/monitor-node-health.md +++ b/content/en/docs/tasks/debug-application-cluster/monitor-node-health.md @@ -2,12 +2,11 @@ reviewers: - Random-Liu - dchen1107 +content_template: templates/task title: Monitor Node Health --- -{{< toc >}} - -## Node Problem Detector +{{% capture overview %}} *Node problem detector* is a [DaemonSet](/docs/concepts/workloads/controllers/daemonset/) monitoring the node health. It collects node problems from various daemons and reports them @@ -24,6 +23,16 @@ introduced to deal with node problems. See more information [here](https://github.com/kubernetes/node-problem-detector). +{{% /capture %}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Limitations * The kernel issue detection of node problem detector only supports file based @@ -153,6 +162,10 @@ Kernel monitor uses [`Translator`](https://github.com/kubernetes/node-problem-de plugin to translate kernel log the internal data structure. It is easy to implement a new translator for a new log format. +{{% /capture %}} + +{{% capture discussion %}} + ## Caveats It is recommended to run the node problem detector in your cluster to monitor @@ -163,3 +176,5 @@ resource overhead on each node. Usually this is fine, because: * Resource limit is set for node problem detector. * Even under high load, the resource usage is acceptable. (see [benchmark result](https://github.com/kubernetes/node-problem-detector/issues/2#issuecomment-220255629)) + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/debug-application-cluster/resource-usage-monitoring.md b/content/en/docs/tasks/debug-application-cluster/resource-usage-monitoring.md index 6435ebaa9b..665e52ef1a 100644 --- a/content/en/docs/tasks/debug-application-cluster/resource-usage-monitoring.md +++ b/content/en/docs/tasks/debug-application-cluster/resource-usage-monitoring.md @@ -1,12 +1,19 @@ --- reviewers: - mikedanese +content_template: templates/concept title: Tools for Monitoring Compute, Storage, and Network Resources --- +{{% capture overview %}} + Understanding how an application behaves when deployed is crucial to scaling the application and providing a reliable service. In a Kubernetes cluster, application performance can be examined at many different levels: containers, [pods](/docs/user-guide/pods), [services](/docs/user-guide/services), and whole clusters. As part of Kubernetes we want to provide users with detailed resource usage information about their running applications at all these levels. This will give users deep insights into how their applications are performing and where possible application bottlenecks may be found. In comes [Heapster](https://github.com/kubernetes/heapster), a project meant to provide a base monitoring platform on Kubernetes. -## Overview +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} Heapster is a cluster-wide aggregator of monitoring and event data. It currently supports Kubernetes natively and works on all Kubernetes setups. Heapster runs as a pod in the cluster, similar to how any Kubernetes application would run. The Heapster pod discovers all nodes in the cluster and queries usage information from the nodes' [Kubelet](/docs/admin/kubelet/)s, the on-machine Kubernetes agent. The Kubelet itself fetches the data from [cAdvisor](https://github.com/google/cadvisor). Heapster groups the information by pod along with the relevant labels. This data is then pushed to a configurable backend for storage and visualization. Currently supported backends include [InfluxDB](http://influxdb.com/) (with [Grafana](http://grafana.org/) for visualization), [Google Cloud Monitoring](https://cloud.google.com/monitoring/) and many others described in more details [here](https://git.k8s.io/heapster/docs/sink-configuration.md). The overall architecture of the service can be seen below: @@ -54,10 +61,10 @@ Here is a snapshot of the Google Cloud Monitoring dashboard showing cluster-wide ![Google Cloud Monitoring dashboard](/images/docs/gcm.png) -## Try it out! +{{% /capture %}} + +{{% capture whatsnext %}} Now that you've learned a bit about Heapster, feel free to try it out on your own clusters! The [Heapster repository](https://github.com/kubernetes/heapster) is available on GitHub. It contains detailed instructions to setup Heapster and its storage backends. Heapster runs by default on most Kubernetes clusters, so you may already have it! Feedback is always welcome. Please let us know if you run into any issues via the troubleshooting [channels](/docs/troubleshooting/). -*** -*Authors: Vishnu Kannan and Victor Marmol, Google Software Engineers.* -*This article was originally posted in [Kubernetes Blog](https://kubernetes.io/blog/2015/05/resource-usage-monitoring-kubernetes).* +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/debug-application-cluster/troubleshooting.md b/content/en/docs/tasks/debug-application-cluster/troubleshooting.md index 073884d16f..c0d98cfeb2 100644 --- a/content/en/docs/tasks/debug-application-cluster/troubleshooting.md +++ b/content/en/docs/tasks/debug-application-cluster/troubleshooting.md @@ -2,9 +2,12 @@ reviewers: - brendandburns - davidopp +content_template: templates/concept title: Troubleshooting --- +{{% capture overview %}} + Sometimes things go wrong. This guide is aimed at making them right. It has two sections: @@ -14,6 +17,12 @@ two sections: You should also check the known issues for the [release](https://github.com/kubernetes/kubernetes/releases) you're using. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Getting help If your problem isn't answered by any of the guides above, there are variety of @@ -93,3 +102,5 @@ problem, such as: * Kubernetes version: `kubectl version` * Cloud provider, OS distro, network configuration, and Docker version * Steps to reproduce the problem + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/federation/federation-service-discovery.md b/content/en/docs/tasks/federation/federation-service-discovery.md index 01d0e4b396..8b14127fcc 100644 --- a/content/en/docs/tasks/federation/federation-service-discovery.md +++ b/content/en/docs/tasks/federation/federation-service-discovery.md @@ -2,9 +2,12 @@ reviewers: - bprashanth - quinton-hoole +content_template: templates/task title: Cross-cluster Service Discovery using Federated Services --- +{{% capture overview %}} + {{< include "federation-current-state.md" >}} This guide explains how to use Kubernetes Federated Services to deploy @@ -13,24 +16,6 @@ easy to achieve cross-cluster service discovery and availability zone fault tolerance for your Kubernetes applications. -{{< toc >}} - -## Prerequisites - -This guide assumes that you have a running Kubernetes Cluster -Federation installation. If not, then head over to the -[federation admin guide](/docs/admin/federation/) to learn how to -bring up a cluster federation (or have your cluster administrator do -this for you). Other tutorials, for example -[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation) -by Kelsey Hightower, are also available to help you. - -You are also expected to have a basic -[working knowledge of Kubernetes](/docs/setup/) in -general, and [Services](/docs/concepts/services-networking/service/) in particular. - -## Overview - Federated Services are created in much that same way as traditional [Kubernetes Services](/docs/concepts/services-networking/service/) by making an API call which specifies the desired properties of your service. In the @@ -52,6 +37,32 @@ automatically find the local shard of the Federated Service in their cluster if it exists and is healthy, or the closest healthy shard in a different cluster if it does not. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + +## Prerequisites + +This guide assumes that you have a running Kubernetes Cluster +Federation installation. If not, then head over to the +[federation admin guide](/docs/admin/federation/) to learn how to +bring up a cluster federation (or have your cluster administrator do +this for you). Other tutorials, for example +[this one](https://github.com/kelseyhightower/kubernetes-cluster-federation) +by Kelsey Hightower, are also available to help you. + +You are also expected to have a basic +[working knowledge of Kubernetes](/docs/setup/) in +general, and [Services](/docs/concepts/services-networking/service/) in particular. + ## Hybrid cloud capabilities Federations of Kubernetes Clusters can include clusters running in @@ -186,7 +197,7 @@ nameServers: - ns-cloud-a4.googledomains.com. ``` -``` shell +```shell $ gcloud dns record-sets list --zone example-dot-com NAME TYPE TTL DATA example.com. NS 21600 ns-cloud-e1.googledomains.com., ns-cloud-e2.googledomains.com. @@ -268,10 +279,10 @@ So, using our NGINX example service above, and the Federated Service DNS name form just described, let's consider an example: A Pod in a cluster in the `us-central1-f` availability zone needs to contact our NGINX service. Rather than use the service's traditional cluster-local -DNS name (```"nginx.mynamespace"```, which is automatically expanded -to ```"nginx.mynamespace.svc.cluster.local"```) it can now use the +DNS name (`"nginx.mynamespace"`, which is automatically expanded +to `"nginx.mynamespace.svc.cluster.local"`) it can now use the service's Federated DNS name, which is -```"nginx.mynamespace.myfederation"```. This will be automatically +`"nginx.mynamespace.myfederation"`. This will be automatically expanded and resolved to the closest healthy shard of my NGINX service, wherever in the world that may be. If a healthy shard exists in the local cluster, that service's cluster-local (typically @@ -343,9 +354,13 @@ endpoint (see e.g. us-central1 above, which has three alternatives) many clients will fail over automatically to one of the alternative IP's in less time than that given appropriate configuration. +{{% /capture %}} + +{{% capture discussion %}} + ## Troubleshooting -#### I cannot connect to my cluster federation API +### I cannot connect to my cluster federation API Check that your 1. Client (typically kubectl) is correctly configured (including API endpoints and login credentials). @@ -354,16 +369,18 @@ Check that your See the [federation admin guide](/docs/admin/federation/) to learn how to bring up a cluster federation correctly (or have your cluster administrator do this for you), and how to correctly configure your client. -#### I can create a federated service successfully against the cluster federation API, but no matching services are created in my underlying clusters +### I can create a federated service successfully against the cluster federation API, but no matching services are created in my underlying clusters Check that: 1. Your clusters are correctly registered in the Cluster Federation API (`kubectl describe clusters`). -2. Your clusters are all 'Active'. This means that the cluster Federation system was able to connect and authenticate against the clusters' endpoints. If not, consult the logs of the federation-controller-manager pod to ascertain what the failure might be. -```kubectl --namespace=federation logs $(kubectl get pods --namespace=federation -l module=federation-controller-manager -o name)``` +2. Your clusters are all 'Active'. This means that the cluster Federation system was able to connect and authenticate against the clusters' endpoints. If not, consult the logs of the federation-controller-manager pod to ascertain what the failure might be. + ``` + kubectl --namespace=federation logs $(kubectl get pods --namespace=federation -l module=federation-controller-manager -o name) + ``` 3. That the login credentials provided to the Cluster Federation API for the clusters have the correct authorization and quota to create services in the relevant namespace in the clusters. Again you should see associated error messages providing more detail in the above log file if this is not the case. 4. Whether any other error is preventing the service creation operation from succeeding (look for `service-controller` errors in the output of `kubectl logs federation-controller-manager --namespace federation`). -#### I can create a federated service successfully, but no matching DNS records are created in my DNS provider. +### I can create a federated service successfully, but no matching DNS records are created in my DNS provider. Check that: 1. Your federation name, DNS provider, DNS domain name are configured correctly. Consult the [federation admin guide](/docs/admin/federation/) or [tutorial](https://github.com/kelseyhightower/kubernetes-cluster-federation) to learn @@ -371,15 +388,16 @@ how to configure your Cluster Federation system's DNS provider (or have your clu 2. Confirm that the Cluster Federation's service-controller is successfully connecting to and authenticating against your selected DNS provider (look for `service-controller` errors or successes in the output of `kubectl logs federation-controller-manager --namespace federation`). 3. Confirm that the Cluster Federation's service-controller is successfully creating DNS records in your DNS provider (or outputting errors in its logs explaining in more detail what's failing). -#### Matching DNS records are created in my DNS provider, but clients are unable to resolve against those names +### Matching DNS records are created in my DNS provider, but clients are unable to resolve against those names Check that: 1. The DNS registrar that manages your federation DNS domain has been correctly configured to point to your configured DNS provider's nameservers. See for example [Google Domains Documentation](https://support.google.com/domains/answer/3290309?hl=en&ref_topic=3251230) and [Google Cloud DNS Documentation](https://cloud.google.com/dns/update-name-servers), or equivalent guidance from your domain registrar and DNS provider. -#### This troubleshooting guide did not help me solve my problem +### This troubleshooting guide did not help me solve my problem -1. Please use one of our [support channels](/docs/tasks/debug-application-cluster/troubleshooting/) to seek assistance. +1. Please use one of our [support channels](/docs/tasks/debug-application-cluster/troubleshooting/) to seek assistance. ## For more information * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/multicluster/federation.md) details use cases that motivated this work. +{{% /capture %}} diff --git a/content/en/docs/tasks/federation/set-up-cluster-federation-kubefed.md b/content/en/docs/tasks/federation/set-up-cluster-federation-kubefed.md index bba21741bc..3b9be17f39 100644 --- a/content/en/docs/tasks/federation/set-up-cluster-federation-kubefed.md +++ b/content/en/docs/tasks/federation/set-up-cluster-federation-kubefed.md @@ -1,13 +1,13 @@ --- reviewers: - madhusudancs +content_template: templates/task title: Set up Cluster Federation with Kubefed --- +{{% capture overview %}} {{< include "federation-current-state.md" >}} -{{< toc >}} - Kubernetes version 1.5 and above includes a new command line tool called [`kubefed`](/docs/admin/kubefed/) to help you administrate your federated clusters. `kubefed` helps you to deploy a new Kubernetes cluster federation @@ -19,6 +19,18 @@ using `kubefed`. > Note: `kubefed` is a beta feature in Kubernetes 1.6. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Prerequisites This guide assumes that you have a running Kubernetes cluster. Please @@ -535,3 +547,5 @@ kubectl delete ns federation-system --context=rivendell Note that `rivendell` is the host cluster name, replace that with the appropriate name in your configuration. + +{{% /capture %}} diff --git a/content/en/docs/tasks/inject-data-application/podpreset.md b/content/en/docs/tasks/inject-data-application/podpreset.md index 0a37c92e97..6bb469295a 100644 --- a/content/en/docs/tasks/inject-data-application/podpreset.md +++ b/content/en/docs/tasks/inject-data-application/podpreset.md @@ -2,17 +2,31 @@ reviewers: - jessfraz title: Inject Information into Pods Using a PodPreset +content_template: templates/task weight: 60 --- +{{% capture overview %}} + You can use a `podpreset` object to inject information like secrets, volume mounts, and environment variables etc into pods at creation time. This task shows some examples on using the `PodPreset` resource. -You can get an overview of PodPresets at -[Understanding Pod Presets](/docs/concepts/workloads/pods/podpreset/). + +{{% /capture %}} {{< toc >}} +{{% capture prerequisites %}} + +Get an overview of PodPresets at +[Understanding Pod Presets](/docs/concepts/workloads/pods/podpreset/). + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Create a Pod Preset ### Simple Pod Spec Example @@ -162,3 +176,4 @@ $ kubectl delete podpreset allow-database podpreset "allow-database" deleted ``` +{{% /capture %}} diff --git a/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md b/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md index 2fde1b5e72..d609a9661b 100644 --- a/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md +++ b/content/en/docs/tasks/job/coarse-parallel-processing-work-queue.md @@ -1,20 +1,19 @@ --- title: Coarse Parallel Processing Using a Work Queue +content_template: templates/task weight: 30 --- {{< toc >}} -# Example: Job with Work Queue with Pod Per Work Item +{{% capture overview %}} In this example, we will run a Kubernetes Job with multiple parallel -worker processes. You may want to be familiar with the basic, -non-parallel, use of [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) first. +worker processes. In this example, as each pod is created, it picks up one unit of work from a task queue, completes it, deletes it from the queue, and exits. - Here is an overview of the steps in this example: 1. **Start a message queue service.** In this example, we use RabbitMQ, but you could use another @@ -24,6 +23,21 @@ Here is an overview of the steps in this example: 1. **Start a Job that works on tasks from the queue**. The Job starts several pods. Each pod takes one task from the message queue, processes it, and repeats until the end of the queue is reached. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +Be familiar with the basic, +non-parallel, use of [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/). + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Starting a message queue service This example uses RabbitMQ, but it should be easy to adapt to another AMQP-type message service. @@ -260,6 +274,9 @@ Events: All our pods succeeded. Yay. +{{% /capture %}} + +{{% capture discussion %}} ## Alternatives @@ -295,3 +312,5 @@ that the message is acknowledged by the amqp-consume command and the time that t exits with success, or if the node crashes before the kubelet is able to post the success of the pod back to the api-server, then the Job will not appear to be complete, even though all items in the queue have been processed. + +{{% /capture %}} diff --git a/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md b/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md index ea8612ce52..ee979f7935 100644 --- a/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md +++ b/content/en/docs/tasks/job/fine-parallel-processing-work-queue.md @@ -1,15 +1,13 @@ --- title: Fine Parallel Processing Using a Work Queue +content_template: templates/task weight: 40 --- -{{< toc >}} - -# Example: Job with Work Queue with Multiple Work Items Per Pod +{{% capture overview %}} In this example, we will run a Kubernetes Job with multiple parallel -worker processes. You may want to be familiar with the basic, -non-parallel, use of [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) first. +worker processes in a given pod. In this example, as each pod is created, it picks up one unit of work from a task queue, processes it, and repeats until the end of the queue is reached. @@ -27,6 +25,24 @@ Here is an overview of the steps in this example: 1. **Start a Job that works on tasks from the queue**. The Job starts several pods. Each pod takes one task from the message queue, processes it, and repeats until the end of the queue is reached. +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + +Be familiar with the basic, +non-parallel, use of [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/). + +{{% /capture %}} + +{{% capture steps %}} ## Starting Redis @@ -212,6 +228,10 @@ Working on lemon As you can see, one of our pods worked on several work units. +{{% /capture %}} + +{{% capture discussion %}} + ## Alternatives If running a queue service or modifying your containers to use a work queue is inconvenient, you may @@ -221,3 +241,5 @@ If you have a continuous stream of background processing work to run, then consider running your background workers with a `replicationController` instead, and consider running a background processing library such as [https://github.com/resque/resque](https://github.com/resque/resque). + +{{% /capture %}} diff --git a/content/en/docs/tasks/job/parallel-processing-expansion.md b/content/en/docs/tasks/job/parallel-processing-expansion.md index 18cd4b4b54..cddd89ad98 100644 --- a/content/en/docs/tasks/job/parallel-processing-expansion.md +++ b/content/en/docs/tasks/job/parallel-processing-expansion.md @@ -1,16 +1,21 @@ --- title: Parallel Processing using Expansions +content_template: templates/concept weight: 20 --- -{{< toc >}} - -# Example: Multiple Job Objects from Template Expansion +{{% capture overview %}} In this example, we will run multiple Kubernetes Jobs created from a common template. You may want to be familiar with the basic, non-parallel, use of [Jobs](/docs/concepts/jobs/run-to-completion-finite-workloads/) first. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Basic Template Expansion First, download the following template of a job to a file called `job.yaml` @@ -189,3 +194,5 @@ If you have a large number of job objects, you may find that: In this case, you can consider one of the other [job patterns](/docs/concepts/jobs/run-to-completion-finite-workloads/#job-patterns). + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/manage-gpus/scheduling-gpus.md b/content/en/docs/tasks/manage-gpus/scheduling-gpus.md index 5f548e4352..58077bdbee 100644 --- a/content/en/docs/tasks/manage-gpus/scheduling-gpus.md +++ b/content/en/docs/tasks/manage-gpus/scheduling-gpus.md @@ -1,14 +1,23 @@ --- reviewers: - vishh +content_template: templates/concept title: Schedule GPUs --- +{{% capture overview %}} + Kubernetes includes **experimental** support for managing NVIDIA GPUs spread across nodes. The support for NVIDIA GPUs was added in v1.6 and has gone through multiple backwards incompatible iterations. This page describes how users can consume GPUs across different Kubernetes versions and the current limitations. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## v1.8 onwards **From 1.8 onwards, the recommended way to consume GPUs is to use [device @@ -208,3 +217,5 @@ works on 1.8 and 1.9 as well. It will be deprecated in 1.10 and removed in - Support for hardware accelerators in Kubernetes is still in alpha. - Better APIs will be introduced to provision and consume accelerators in a scalable manner. - Kubernetes will automatically ensure that applications consuming GPUs get the best possible performance. + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md index bc715cd627..798236e5ea 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md @@ -5,10 +5,11 @@ reviewers: - justinsb - directxman12 title: Horizontal Pod Autoscaler Walkthrough +content_template: templates/task weight: 100 --- -{{< toc >}} +{{% capture overview %}} Horizontal Pod Autoscaler automatically scales the number of pods in a replication controller, deployment or replica set based on observed CPU utilization @@ -16,7 +17,12 @@ in a replication controller, deployment or replica set based on observed CPU uti This document walks you through an example of enabling Horizontal Pod Autoscaler for the php-apache server. For more information on how Horizontal Pod Autoscaler behaves, see the [Horizontal Pod Autoscaler user guide](/docs/tasks/run-application/horizontal-pod-autoscale/). -## Prerequisites +{{% /capture %}} + +{{< toc >}} + + +{{% capture prerequisites %}} This example requires a running Kubernetes cluster and kubectl, version 1.2 or later. [Heapster](https://github.com/kubernetes/heapster) monitoring needs to be deployed in the cluster @@ -31,7 +37,11 @@ not related to any Kubernetes object you must have a Kubernetes cluster at versi you must be able to communicate with the API server that provides the external metrics API. See the [Horizontal Pod Autoscaler user guide](/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-custom-metrics) for more details. -## Step One: Run & expose php-apache server +{{% /capture %}} + +{{% capture steps %}} + +## Run & expose php-apache server To demonstrate Horizontal Pod Autoscaler we will use a custom docker image based on the php-apache image. The Dockerfile has the following content: @@ -62,7 +72,7 @@ service "php-apache" created deployment "php-apache" created ``` -## Step Two: Create Horizontal Pod Autoscaler +## Create Horizontal Pod Autoscaler Now that the server is running, we will create the autoscaler using [kubectl autoscale](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/docs/user-guide/kubectl/kubectl_autoscale.md). @@ -90,7 +100,7 @@ php-apache Deployment/php-apache/scale 0% / 50% 1 10 1 Please note that the current CPU consumption is 0% as we are not sending any requests to the server (the ``CURRENT`` column shows the average across all the pods controlled by the corresponding deployment). -## Step Three: Increase load +## Increase load Now, we will see how the autoscaler reacts to increased load. We will start a container, and send an infinite loop of queries to the php-apache service (please run it in a different terminal): @@ -125,7 +135,7 @@ php-apache 7 7 7 7 19m Since the amount of load is not controlled in any way it may happen that the final number of replicas will differ from this example. -## Step Four: Stop load +## Stop load We will finish our example by stopping the user load. @@ -146,7 +156,13 @@ php-apache 1 1 1 1 27m Here CPU utilization dropped to 0, and so HPA autoscaled the number of replicas back down to 1. +{{< note >}} **Note** autoscaling the replicas may take a few minutes. +{{< /note >}} + +{{% /capture %}} + +{{% capture discussion %}} ## Autoscaling on multiple metrics and custom metrics @@ -377,3 +393,5 @@ We will create the autoscaler by executing the following command: $ kubectl create -f https://k8s.io/docs/tasks/run-application/hpa-php-apache.yaml horizontalpodautoscaler "php-apache" created ``` + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md index 46f2615624..663ebca21c 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md @@ -4,14 +4,11 @@ reviewers: - jszczepkowski - directxman12 title: Horizontal Pod Autoscaler +content_template: templates/concept weight: 90 --- -{{< toc >}} - -This document describes the current state of the Horizontal Pod Autoscaler in Kubernetes. - -## What is the Horizontal Pod Autoscaler? +{{% capture overview %}} The Horizontal Pod Autoscaler automatically scales the number of pods in a replication controller, deployment or replica set based on observed CPU utilization (or, with @@ -24,6 +21,12 @@ The resource determines the behavior of the controller. The controller periodically adjusts the number of replicas in a replication controller or deployment to match the observed average CPU utilization to the target specified by user. +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## How does the Horizontal Pod Autoscaler work? ![Horizontal Pod Autoscaler diagram](/images/docs/horizontal-pod-autoscaler.svg) @@ -180,8 +183,12 @@ custom metrics API and, optionally, external metrics API with the API aggregatio In Kubernetes 1.7, the standard aggregation layer that Kubernetes provides runs in-process with the kube-apiserver, so the target IP address can be found with `kubectl get pods --selector k8s-app=kube-apiserver --namespace kube-system -o jsonpath='{.items[0].status.podIP}'`. -## Further reading +{{% /capture %}} + +{{% capture whatsnext %}} * Design documentation: [Horizontal Pod Autoscaling](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md). * kubectl autoscale command: [kubectl autoscale](/docs/reference/generated/kubectl/kubectl-commands/#autoscale). * Usage example of [Horizontal Pod Autoscaler](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/). + +{{% /capture %}} diff --git a/content/en/docs/tasks/run-application/rolling-update-replication-controller.md b/content/en/docs/tasks/run-application/rolling-update-replication-controller.md index 027726a3bc..5e2e2c0b97 100644 --- a/content/en/docs/tasks/run-application/rolling-update-replication-controller.md +++ b/content/en/docs/tasks/run-application/rolling-update-replication-controller.md @@ -2,12 +2,11 @@ reviewers: - janetkuo title: Perform Rolling Update Using a Replication Controller +content_template: templates/concept weight: 80 --- -{{< toc >}} - -## Overview +{{% capture overview %}} {{< note >}} **Note**: The preferred way to create a replicated application is to use a @@ -41,6 +40,12 @@ Rolling updates are initiated with the `kubectl rolling-update` command: $ kubectl rolling-update NAME \ ([NEW_NAME] --image=IMAGE | -f FILE) +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + ## Passing a configuration file To initiate a rolling update using a configuration file, pass the new file to @@ -261,3 +266,5 @@ 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. + +{{% /capture %}} diff --git a/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md b/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md index ce9bc6c0ae..1452291997 100644 --- a/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md +++ b/content/en/docs/tasks/tls/managing-tls-in-a-cluster.md @@ -1,14 +1,13 @@ --- title: Manage TLS Certificates in a Cluster +content_template: templates/task reviewers: - mikedanese - beacham - liggit --- -{{< toc >}} - -## Overview +{{% capture overview %}} Every Kubernetes cluster has a cluster root Certificate Authority (CA). The CA is generally used by cluster components to validate the API server's @@ -20,6 +19,18 @@ can request a certificate signing using the `certificates.k8s.io` API using a protocol that is similar to the [ACME draft](https://github.com/ietf-wg-acme/acme/). +{{% /capture %}} + +{{< toc >}} + +{{% capture prerequisites %}} + +{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + +{{% /capture %}} + +{{% capture steps %}} + ## Trusting TLS in a Cluster Trusting the cluster root CA from an application running as a pod usually @@ -43,12 +54,12 @@ Kubernetes service accessed through DNS. **Note:** This tutorial uses CFSSL: Cloudflare's PKI and TLS toolkit [click here](https://blog.cloudflare.com/introducing-cfssl/) to know more. {{< /note >}} -### Step 0. Download and install CFSSL +## Download and install CFSSL The cfssl tools used in this example can be downloaded at [https://pkg.cfssl.org/](https://pkg.cfssl.org/). -### Step 1. Create a Certificate Signing Request +## Create a Certificate Signing Request Generate a private key and certificate signing request (or CSR) by running the following command: @@ -88,7 +99,7 @@ encoded [pkcs#10](https://tools.ietf.org/html/rfc2986) certification request, and `server-key.pem` containing the PEM encoded key to the certificate that is still to be created. -### Step 2. Create a Certificate Signing Request object to send to the Kubernetes API +## Create a Certificate Signing Request object to send to the Kubernetes API Generate a CSR yaml blob and send it to the apiserver by running the following command: @@ -139,13 +150,13 @@ Subject Alternative Names: Events: ``` -### Step 3. Get the Certificate Signing Request Approved +## Get the Certificate Signing Request Approved Approving the certificate signing request is either done by an automated approval process or on a one off basis by a cluster administrator. More information on what this involves is covered below. -### Step 4. Download the Certificate and Use It +## Download the Certificate and Use It Once the CSR is signed and approved you should see the following: @@ -206,3 +217,5 @@ Kubernetes controller manager provides a default implementation of a signer. To enable it, pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` parameters to the controller manager with paths to your Certificate Authority's keypair. + +{{% /capture %}}