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
2018-06-22 11:20:04 -07:00
parent ec15f3fab9
commit 75f00dfc60
71 changed files with 1059 additions and 321 deletions
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}
@@ -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 %}}