Various manual fixes for syntax highlighting and lists; much prettier docs ensue.

2016-02-17 16:18:59 -08:00
parent d6311dbd19
commit f0aea25011
102 changed files with 1486 additions and 1364 deletions
@@ -16,6 +16,7 @@ The Kubernetes API is served by the Kubernetes apiserver process.  Typically,
 there is one of these running on a single kubernetes-master node.

 By default the Kubernetes APIserver serves HTTP on 2 ports:
+
  1. Localhost Port
    - serves HTTP
    - default is port 8080, change with `--insecure-port` flag.
@@ -47,6 +48,7 @@ kube-up.sh.  Other cloud providers may vary.

 There are three differently configured serving ports because there are a
 variety of uses cases:
+
   1. Clients outside of a Kubernetes cluster, such as human running `kubectl`
      on desktop machine.  Currently, accesses the Localhost Port via a proxy (nginx)
      running on the `kubernetes-master` machine.  The proxy can use cert-based authentication
@@ -12,6 +12,7 @@ the request, (such as user, resource, and namespace) with access
 policies.  An API call must be allowed by some policy in order to proceed.

 The following implementations are available, and are selected by flag:
+
  - `--authorization-mode=AlwaysDeny`
  - `--authorization-mode=AlwaysAllow`
  - `--authorization-mode=ABAC`
@@ -25,6 +26,7 @@ The following implementations are available, and are selected by flag:
 ### Request Attributes

 A request has 5 attributes that can be considered for authorization:
+
  - user (the user-string which a user was authenticated as).
  - group (the list of group names the authenticated user is a member of).
  - whether the request is readonly (GETs are readonly).
@@ -46,6 +48,7 @@ The file format is [one JSON object per line](http://jsonlines.org/).  There sho
 one map per line.

 Each line is a "policy object".  A policy object is a map with the following properties:
+
  - `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user.
  - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user.
  - `readonly`, type boolean, when true, means that the policy only applies to GET
@@ -125,7 +128,4 @@ An authorization module can be completely implemented in go, or can call out
 to a remote authorization service.  Authorization modules can implement
 their own caching to reduce the cost of repeated authorization calls with the
 same or similar arguments.  Developers should then consider the interaction between
-caching and revocation of permissions.
-
-
-
+caching and revocation of permissions.
@@ -39,6 +39,7 @@ of the relevant log files.  (note that on systemd-based systems, you may need to
 This is an incomplete list of things that could go wrong, and how to adjust your cluster setup to mitigate the problems.

 Root causes:
+
  - VM(s) shutdown
  - Network partition within cluster, or between cluster and users
  - Crashes in Kubernetes software
@@ -46,6 +47,7 @@ Root causes:
  - Operator error, e.g. misconfigured Kubernetes software or application software

 Specific scenarios:
+
  - Apiserver VM shutdown or apiserver crashing
    - Results
      - unable to stop, update, or start new pods, services, replication controller
@@ -79,6 +81,7 @@ Specific scenarios:
      - etc.

 Mitigations:
+
 - Action: Use IaaS provider's automatic VM restarting feature for IaaS VMs
  - Mitigates: Apiserver VM shutdown or apiserver crashing
  - Mitigates: Supporting services VM shutdown or crashes
@@ -165,8 +165,4 @@ on GCE.

 DaemonSet objects effectively have [API version `v1alpha1`](../api.html#api-versioning).
 Alpha objects may change or even be discontinued in future software releases.
-However, due to to a known issue, they will appear as API version `v1beta1` if enabled.
-
-
-
-
+However, due to to a known issue, they will appear as API version `v1beta1` if enabled.
@@ -36,7 +36,4 @@ time.

 ## For more information

-See [the docs for the DNS cluster addon](http://releases.k8s.io/release-1.1/cluster/addons/dns/README.md).
-
-
-
+See [the docs for the DNS cluster addon](http://releases.k8s.io/release-1.1/cluster/addons/dns/README.md).
@@ -20,7 +20,8 @@ Setting up a truly reliable, highly available distributed system requires a numb
 wearing underwear, pants, a belt, suspenders, another pair of underwear, and another pair of pants.  We go into each
 of these steps in detail, but a summary is given here to help guide and orient the user.

-The steps involved are as follows:
+The steps involved are as follows:
+
   * [Creating the reliable constituent nodes that collectively form our HA master implementation.](#reliable-nodes)
   * [Setting up a redundant, reliable storage layer with clustered etcd.](#establishing-a-redundant-reliable-data-storage-layer)
   * [Starting replicated, load balanced Kubernetes API servers](#replicated-api-servers)
@@ -143,7 +144,8 @@ First you need to create the initial log file, so that Docker mounts a file inst
 touch /var/log/kube-apiserver.log
 ```

-Next, you need to create a `/srv/kubernetes/` directory on each node.  This directory includes:
+Next, you need to create a `/srv/kubernetes/` directory on each node.  This directory includes:
+
   * basic_auth.csv  - basic auth user and password
   * ca.crt - Certificate Authority cert
   * known_tokens.csv - tokens that entities (e.g. the kubelet) can use to talk to the apiserver
@@ -1,12 +1,9 @@
 ---
 title: "Kubernetes Cluster Admin Guide"
 ---
-
 The cluster admin guide is for anyone creating or administering a Kubernetes cluster.
 It assumes some familiarity with concepts in the [User Guide](../user-guide/README).

-
-
 {% include pagetoc.html %}

 ## Planning a cluster
@@ -1,7 +1,6 @@
 ---
 title: "Considerations for running multiple Kubernetes clusters"
 ---
-
 You may want to set up multiple Kubernetes clusters, both to
 have clusters in different regions to be nearer to your users, and to tolerate failures and/or invasive maintenance.
 This document describes some of the issues to consider when making a decision about doing so.
@@ -15,7 +14,9 @@ we [plan to do this in the future](../proposals/federation).
 On IaaS providers such as Google Compute Engine or Amazon Web Services, a VM exists in a
 [zone](https://cloud.google.com/compute/docs/zones) or [availability
 zone](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones).
+
 We suggest that all the VMs in a Kubernetes cluster should be in the same availability zone, because:
+
  - compared to having a single global Kubernetes cluster, there are fewer single-points of failure
  - compared to a cluster that spans availability zones, it is easier to reason about the availability properties of a
    single-zone cluster.
@@ -24,12 +25,14 @@ We suggest that all the VMs in a Kubernetes cluster should be in the same availa

 It is okay to have multiple clusters per availability zone, though on balance we think fewer is better.
 Reasons to prefer fewer clusters are:
+
  - improved bin packing of Pods in some cases with more nodes in one cluster (less resource fragmentation)
  - reduced operational overhead (though the advantage is diminished as ops tooling and processes matures)
  - reduced costs for per-cluster fixed resource costs, e.g. apiserver VMs (but small as a percentage
    of overall cluster cost for medium to large clusters).

 Reasons to have multiple clusters include:
+
  - strict security policies requiring isolation of one class of work from another (but, see Partitioning Clusters
    below).
  - test clusters to canary new Kubernetes releases or other cluster software.
@@ -5,6 +5,7 @@ title: "Networking in Kubernetes"

 Kubernetes approaches networking somewhat differently than Docker does by
 default.  There are 4 distinct networking problems to solve:
+
 1. Highly-coupled container-to-container communications: this is solved by
   [pods](../user-guide/pods) and `localhost` communications.
 2. Pod-to-Pod communications: this is the primary focus of this document.
@@ -59,6 +60,7 @@ different approach.

 Kubernetes imposes the following fundamental requirements on any networking
 implementation (barring any intentional network segmentation policies):
+
   * all containers can communicate with all other containers without NAT
   * all nodes can communicate with all containers (and vice-versa) without NAT
   * the IP that a container sees itself as is the same IP that others see it as
@@ -134,6 +134,7 @@ When kubelet flag `--register-node` is true (the default), the kubelet will atte
 register itself with the API server.  This is the preferred pattern, used by most distros.

 For self-registration, the kubelet is started with the following options:
+
  - `--api-servers=` tells the kubelet the location of the apiserver.
  - `--kubeconfig` tells kubelet where to find credentials to authenticate itself to the apiserver.
  - `--cloud-provider=` tells the kubelet how to talk to a cloud provider to read metadata about itself.
@@ -6,6 +6,7 @@ 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. Resource quotas
 work like this:
+
 - Different teams work in different namespaces.  Currently this is voluntary, but
  support for making this mandatory via ACLs is planned.
 - The administrator creates a Resource Quota for each namespace.
@@ -28,6 +29,7 @@ work like this:
  [admission controller](admission-controllers)) before the quota is checked to avoid this problem.

 Examples of policies that could be created using namespaces and quotas are:
+
 - In a cluster with a capacity of 32 GiB RAM, and 16 cores, let team A use 20 Gib and 10 cores,
  let B use 10GiB and 4 cores, and hold 2GiB and 2 cores in reserve for future allocation.
 - Limit the "testing" namespace to using 1 core and 1GiB RAM.  Let the "production" namespace
@@ -130,6 +132,7 @@ expressed in absolute units.  So, if you add nodes to your cluster, this does *n
 automatically give each namespace the ability to consume more resources.

 Sometimes more complex policies may be desired, such as:
+
  - proportionally divide total cluster resources among several teams.
  - allow each tenant to grow resource usage as needed, but have a generous
    limit to prevent accidental resource exhaustion.
@@ -11,6 +11,7 @@ incomplete features are referred to in order to better describe service accounts

 Kubernetes distinguished between the concept of a user account and a service accounts
 for a number of reasons:
+
  - User accounts are for humans.  Service accounts are for processes, which
    run in pods.
  - User accounts are intended to be global. Names must be unique across all
@@ -29,6 +30,7 @@ for a number of reasons:
 ## Service account automation

 Three separate components cooperate to implement the automation around service accounts:
+
  - A Service account admission controller
  - A Token controller
  - A Service account controller
@@ -39,6 +41,7 @@ The modification of pods is implemented via a plugin
 called an [Admission Controller](admission-controllers). It is part of the apiserver.
 It acts synchronously to modify pods as they are created or updated. When this plugin is active
 (and it is by default on most distributions), then it does the following when a pod is created or modified:
+
  1. If the pod does not have a `ServiceAccount` set, it sets the `ServiceAccount` to `default`.
  2. It ensures that the `ServiceAccount` referenced by the pod exists, and otherwise rejects it.
  4. If the pod does not contain any `ImagePullSecrets`, then `ImagePullSecrets` of the
@@ -49,6 +52,7 @@ It acts synchronously to modify pods as they are created or updated. When this p
 ### Token Controller

 TokenController runs as part of controller-manager. It acts asynchronously. It:
+
 - observes serviceAccount creation and creates a corresponding Secret to allow API access.
 - observes serviceAccount deletion and deletes all corresponding ServiceAccountToken Secrets
 - observes secret addition, and ensures the referenced ServiceAccount exists, and adds a token to the secret if needed