Initial TOC for the user guide.

nikhiljindal · Jul 15, 2015 · 0045ebd · 0045ebd
1 parent 9c47e0d
commit 0045ebd
Show file tree

Hide file tree

Showing 8 changed files with 121 additions and 229 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -22,7 +22,7 @@ certainly want the docs that go with that version.</h1>
 <!-- END MUNGE: UNVERSIONED_WARNING -->
 # Kubernetes Documentation: releases.k8s.io/HEAD
 
-* The [User's guide](user-guide/user-guide.md) is for anyone who wants to run programs and
+* The [User's guide](user-guide/README.md) is for anyone who wants to run programs and
   services on an existing Kubernetes cluster.
 
 * The [Cluster Admin's guide](admin/README.md) is for anyone setting up

diff --git a/docs/admin/README.md b/docs/admin/README.md
@@ -23,7 +23,7 @@ certainly want the docs that go with that version.</h1>
 # 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/user-guide.md).
+It assumes some familiarity with concepts in the [User Guide](../user-guide/README.md).
 
 ## Planning a cluster
 

diff --git a/docs/api.md b/docs/api.md
@@ -22,7 +22,7 @@ certainly want the docs that go with that version.</h1>
 <!-- END MUNGE: UNVERSIONED_WARNING -->
 # The Kubernetes API
 
-Primary system and API concepts are documented in the [User guide](user-guide/user-guide.md).
+Primary system and API concepts are documented in the [User guide](user-guide/README.md).
 
 Overall API conventions are described in the [API conventions doc](api-conventions.md).
 

diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -24,7 +24,7 @@ certainly want the docs that go with that version.</h1>
 
 The developer guide is for anyone wanting to either write code which directly accesses the
 kubernetes API, or to contribute directly to the kubernetes project.
-It assumes some familiarity with concepts in the [User Guide](user-guide/user-guide.md) and the [Cluster Admin
+It assumes some familiarity with concepts in the [User Guide](user-guide/README.md) and the [Cluster Admin
 Guide](admin/README.md).
 
 

diff --git a/docs/glossary.md b/docs/glossary.md
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
@@ -0,0 +1,113 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+![WARNING](http://kubernetes.io/img/warning.png)
+![WARNING](http://kubernetes.io/img/warning.png)
+![WARNING](http://kubernetes.io/img/warning.png)
+
+<h1>PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+![WARNING](http://kubernetes.io/img/warning.png)
+![WARNING](http://kubernetes.io/img/warning.png)
+![WARNING](http://kubernetes.io/img/warning.png)
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+# Kubernetes User Guide: Managing Applications
+
+**Table of Contents**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+- [Kubernetes User Guide: Managing Applications](#kubernetes-user-guide:-managing-applications)
+  - [Quick walkthrough](#quick-walkthrough)
+  - [Thorough walkthrough](#thorough-walkthrough)
+  - [Concept guide](#concept-guide)
+  - [Further reading](#further-reading)
+
+<!-- END MUNGE: GENERATED_TOC -->
+
+The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster.  Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](../../docs/admin/README.md). The [Developer Guide](../../docs/developer-guide.md) is for anyone wanting to either write code which directly accesses the kubernetes API, or to contribute directly to the kubernetes project.
+
+Please ensure you have completed the [prerequisites for running examples from the user guide](prereqs.md).
+
+## Quick walkthrough
+
+1. [Kubernetes 101](walkthrough/README.md)
+1. [Kubernetes 201](walkthrough/k8s201.md)
+
+## Thorough walkthrough
+
+If you don't have much familiarity with Kubernetes, we recommend you read the following sections in order:
+
+1. [Quick start: launch and expose an application](quick-start.md)
+1. [Configuring and launching containers: configuring common container parameters](configuring-containers.md)
+1. [Deploying continuously running applications](deploying-applications.md)
+1. [Connecting applications: exposing applications to clients and users](connecting-applications.md)
+1. [Working with containers in production](production-pods.md)
+1. [Managing deployments](managing-deployments.md)
+1. [Application introspection and debugging](introspection-and-debugging.md)
+    1. [Using the Kubernetes web user interface](ui.md)
+    1. [Logging](logging.md)
+    1. [Monitoring](monitoring.md)
+    1. [Getting into containers via `exec`](getting-into-containers.md)
+    1. [Connecting to containers via proxies](connecting-to-applications-proxy.md)
+    1. [Connecting to containers via port forwarding](connecting-to-applications-port-forward.md)
+
+## Concept guide
+
+[**Overview**](overview.md)
+: A brief overview of Kubernetes concepts.
+
+[**Pod**](pods.md)
+: A pod is a co-located group of containers and volumes.
+
+[**Label**](labels.md)
+: A label is a key/value pair that is attached to a resource, such as a pod, to convey a user-defined identifying attribute. Labels can be used to organize and to select subsets of resources.
+
+[**Selector**](labels.md#label-selectors)
+: A selector is an expression that matches labels in order to identify related resources, such as which pods are targeted by a load-balanced service.
+
+[**Replication Controller**](replication-controller.md)
+: A replication controller ensures that a specified number of pod replicas are running at any one time. It both allows for easy scaling of replicated systems and handles re-creation of a pod when the machine it is on reboots or otherwise fails.
+
+[**Service**](services.md)
+: A service defines a set of pods and a means by which to access them, such as single stable IP address and corresponding DNS name.
+
+[**Volume**](volumes.md)
+: A volume is a directory, possibly with some data in it, which is accessible to a Container as part of its filesystem.  Kubernetes volumes build upon [Docker Volumes](https://docs.docker.com/userguide/dockervolumes/), adding provisioning of the volume directory and/or device.
+
+[**Secret**](secrets.md)
+: A secret stores sensitive data, such as authentication tokens, which can be made available to containers upon request.
+
+[**Name**](identifiers.md)
+: A user- or client-provided name for a resource.
+
+[**Namespace**](namespaces.md)
+: A namespace is like a prefix to the name of a resource. Namespaces help different projects, teams, or customers to share a cluster, such as by preventing name collisions between unrelated teams.
+
+[**Annotation**](annotations.md)
+: A key/value pair that can hold larger (compared to a label), and possibly not human-readable, data, intended to store non-identifying auxiliary data, especially data manipulated by tools and system extensions.  Efficient filtering by annotation values is not supported.
+
+## Further reading
+
+* API resources
+  * [Working with resources](working-with-resources.md)
+
+* Pods and containers
+  * [Pod lifecycle and restart policies](pod-states.md)
+  * [Lifecycle hooks](container-environment.md)
+  * [Compute resources, such as cpu and memory](compute-resources.md)
+  * [Specifying commands and requesting capabilities](containers.md)
+  * [Downward API: accessing system configuration from a pod](downward-api.md)
+  * [Images and registries](images.md)
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md
@@ -20,11 +20,13 @@ certainly want the docs that go with that version.</h1>
 <!-- END STRIP_FOR_RELEASE -->
 
 <!-- END MUNGE: UNVERSIONED_WARNING -->
-# Kubernetes User Documentation
+# Kubernetes Overview
 
 Kubernetes is an open-source system for managing containerized applications across multiple hosts in a cluster. It provides mechanisms for application deployment, scheduling, updating, maintenance, and scaling. A key feature of Kubernetes is that it actively manages the containers to ensure that the state of the cluster continually matches the user's intentions.
 
-Today, Kubernetes supports just [Docker](http://www.docker.io) containers, but other container image formats and container runtimes will be supported in the future (e.g., [Rocket](https://coreos.com/blog/rocket/) support is in progress). Similarly, while Kubernetes currently focuses on continuously-running stateless (e.g. web server or in-memory object cache) and "cloud native" stateful applications (e.g. NoSQL datastores), in the near future it will support all the other workload types commonly found in production cluster environments, such as batch, stream processing, and traditional databases. 
+Kubernetes supports [Docker](http://www.docker.io) and [Rocket](https://coreos.com/blog/rocket/) containers, and other container image formats and container runtimes will be supported in the future.
+
+While Kubernetes currently focuses on continuously-running stateless (e.g. web server or in-memory object cache) and "cloud native" stateful applications (e.g. NoSQL datastores), in the near future it will support all the other workload types commonly found in production cluster environments, such as batch, stream processing, and traditional databases.
 
 In Kubernetes, all containers run inside [pods](pods.md). A pod can host a single container, or multiple cooperating containers; in the latter case, the containers in the pod are guaranteed to be co-located on the same machine and can share resources. A pod can also contain zero or more [volumes](volumes.md), which are directories that are private to a container or shared across containers in a pod. For each pod the user creates, the system finds a machine that is healthy and that has sufficient available capacity, and starts up the corresponding container(s) there. If a container fails it can be automatically restarted by Kubernetes' node agent, called the Kubelet. But if the pod or its machine fails, it is not automatically moved or restarted unless the user also defines a [replication controller](replication-controller.md), which we discuss next.
 
@@ -38,17 +40,6 @@ Modern Internet applications are commonly built by layering micro-services, for
 
 Every resource in Kubernetes, such as a pod, is identified by a URI and has a UID. Important components of the URI are the kind of object (e.g. pod), the object’s name, and the object’s [namespace](namespaces.md). For a certain object kind, every name is unique within its namespace. In contexts where an object name is provided without a namespace, it is assumed to be in the default namespace. UID is unique across time and space.
 
-Other details:
-
-* [API](../api.md)
-* [Client libraries](../client-libraries.md)
-* [Command-line interface](kubectl/kubectl.md)
-* [UI](ui.md)
-* [Images and registries](images.md)
-* [Container environment](container-environment.md)
-* [Logging](logging.md)
-* Monitoring using [CAdvisor](https://github.com/google/cadvisor) and [Heapster](https://github.com/GoogleCloudPlatform/heapster)
-
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/overview.md?pixel)]()