mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-23 19:56:01 +00:00
Initial TOC for the user guide.
This commit is contained in:
Brian Grant
parent
9c47e0d20c
commit
0045ebd570
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
|
||||
@ -1,82 +0,0 @@
|
||||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- END STRIP_FOR_RELEASE -->
|
||||
|
||||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
# Glossary and Concept Index
|
||||
|
||||
**Authorization**
|
||||
:Kubernetes does not currently have an authorization system. Anyone with the cluster password can do anything. We plan
|
||||
to add sophisticated authorization, and to make it pluggable. See the [access control design doc](design/access.md) and
|
||||
[this issue](https://github.com/GoogleCloudPlatform/kubernetes/issues/1430).
|
||||
|
||||
**Annotation**
|
||||
: A key/value pair that can hold large (compared to a Label), and possibly not human-readable data. Intended to store
|
||||
non-identifying metadata associated with an object, such as provenance information. Not indexed.
|
||||
|
||||
**Image**
|
||||
: A [Docker Image](https://docs.docker.com/userguide/dockerimages/). See [images](user-guide/images.md).
|
||||
|
||||
**Label**
|
||||
: A key/value pair conveying user-defined identifying attributes of an object, and used to form sets of related objects, such as
|
||||
pods which are replicas in a load-balanced service. Not intended to hold large or non-human-readable data. See [labels](user-guide/labels.md).
|
||||
|
||||
**Name**
|
||||
: A user-provided name for an object. See [identifiers](user-guide/identifiers.md).
|
||||
|
||||
**Namespace**
|
||||
: A namespace is like a prefix to the name of an object. You can configure your client to use a particular namespace,
|
||||
so you do not have to type it all the time. Namespaces allow multiple projects to prevent naming collisions between unrelated teams.
|
||||
|
||||
**Pod**
|
||||
: A collection of containers which will be scheduled onto the same node, which share and an IP and port space, and which
|
||||
can be created/destroyed together. See [pods](user-guide/pods.md).
|
||||
|
||||
**Replication Controller**
|
||||
: A _replication controller_ ensures that a specified number of pod "replicas" are running at any one time. Both allows
|
||||
for easy scaling of replicated systems, and handles restarting of a Pod when the machine it is on reboots or otherwise fails.
|
||||
|
||||
**Resource**
|
||||
: CPU, memory, and other things that a pod can request. See [compute resources](user-guide/compute-resources.md).
|
||||
|
||||
**Secret**
|
||||
: An object containing sensitive information, such as authentication tokens, which can be made available to containers upon request. See [secrets](user-guide/secrets.md).
|
||||
|
||||
**Selector**
|
||||
: An expression that matches Labels. Can identify related objects, such as pods which are replicas in a load-balanced
|
||||
service. See [labels](user-guide/labels.md).
|
||||
|
||||
**Service**
|
||||
: A load-balanced set of `pods` which can be accessed via a single stable IP address. See [services](user-guide/services.md).
|
||||
|
||||
**UID**
|
||||
: An identifier on all Kubernetes objects that is set by the Kubernetes API server. Can be used to distinguish between historical
|
||||
occurrences of same-Name objects. See [identifiers](user-guide/identifiers.md).
|
||||
|
||||
**Volume**
|
||||
: 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. See [volumes](user-guide/volumes.md).
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
113
docs/user-guide/README.md
Normal file
113
docs/user-guide/README.md
Normal file
@ -0,0 +1,113 @@
|
||||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- 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 -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
@ -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 -->
|
||||
[]()
|
||||
|
||||
@ -1,130 +0,0 @@
|
||||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- END STRIP_FOR_RELEASE -->
|
||||
|
||||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||
# Kubernetes User Guide
|
||||
|
||||
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](../admin/README.md).
|
||||
The [Developer Guide](../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.
|
||||
|
||||
## Primary concepts
|
||||
|
||||
* **Overview** ([overview.md](overview.md)): A brief overview
|
||||
of Kubernetes concepts.
|
||||
|
||||
* **Nodes** ([docs/admin/node.md](../admin/node.md)): A node is a worker machine in Kubernetes.
|
||||
|
||||
* **Pods** ([pods.md](pods.md)): A pod is a tightly-coupled group of containers
|
||||
with shared volumes.
|
||||
|
||||
* **The Life of a Pod** ([pod-states.md](pod-states.md)):
|
||||
Covers the intersection of pod states, the PodStatus type, the life-cycle
|
||||
of a pod, events, restart policies, and replication controllers.
|
||||
|
||||
* **Replication Controllers** ([replication-controller.md](replication-controller.md)):
|
||||
A replication controller ensures that a specified number of pod "replicas" are
|
||||
running at any one time.
|
||||
|
||||
* **Services** ([services.md](services.md)): A Kubernetes service is an abstraction
|
||||
which defines a logical set of pods and a policy by which to access them.
|
||||
|
||||
* **Volumes** ([volumes.md](volumes.md)): A Volume is a directory, possibly with some
|
||||
data in it, which is accessible to a Container.
|
||||
|
||||
* **Labels** ([labels.md](labels.md)): Labels are key/value pairs that are
|
||||
attached to objects, such as pods. Labels can be used to organize and to
|
||||
select subsets of objects.
|
||||
|
||||
* **Secrets** ([secrets.md](secrets.md)): A Secret stores sensitive data
|
||||
(e.g. ssh keys, passwords) separately from the Pods that use them, protecting
|
||||
the sensitive data from proliferation by tools that process pods.
|
||||
|
||||
* **Accessing the API and other cluster services via a Proxy** [accessing-the-cluster.md](accessing-the-cluster.md)
|
||||
|
||||
* **API Overview** ([docs/api.md](../api.md)): Pointers to API documentation on various topics
|
||||
and explanation of Kubernetes's approaches to API changes and API versioning.
|
||||
|
||||
* **Kubernetes Web Interface** ([ui.md](ui.md)): Accessing the Kubernetes
|
||||
web user interface.
|
||||
|
||||
* **Kubectl Command Line Interface** ([kubectl/kubectl.md](kubectl/kubectl.md)):
|
||||
The `kubectl` command line reference.
|
||||
|
||||
* **Sharing Cluster Access** ([sharing-clusters.md](sharing-clusters.md)):
|
||||
How to share client credentials for a kubernetes cluster.
|
||||
|
||||
* **Roadmap** ([docs/roadmap.md](../roadmap.md)): The set of supported use cases, features,
|
||||
docs, and patterns that are required before Kubernetes 1.0.
|
||||
|
||||
* **Glossary** ([docs/glossary.md](../glossary.md)): Terms and concepts.
|
||||
|
||||
## Further reading
|
||||
<!--- make sure all documents from the docs directory are linked somewhere.
|
||||
This one-liner (execute in docs/ dir) prints unlinked documents (only from this
|
||||
dir - no recursion):
|
||||
for i in *.md; do grep -r $i . | grep -v "^\./$i" > /dev/null; rv=$?; if [[ $rv -ne 0 ]]; then echo $i; fi; done
|
||||
-->
|
||||
|
||||
* **Annotations** ([annotations.md](annotations.md)): Attaching
|
||||
arbitrary non-identifying metadata.
|
||||
|
||||
* **Downward API** ([downward-api.md](downward-api.md)): Accessing system
|
||||
configuration from a pod without accessing Kubernetes API (see also
|
||||
[container-environment.md](container-environment.md)).
|
||||
|
||||
* **Kubernetes Container Environment** ([container-environment.md](container-environment.md)):
|
||||
Describes the environment for Kubelet managed containers on a Kubernetes
|
||||
node (see also [downward-api.md](downward-api.md)).
|
||||
|
||||
* **DNS Integration with SkyDNS** ([docs/admin/dns.md](../admin/dns.md)):
|
||||
Resolving a DNS name directly to a Kubernetes service.
|
||||
|
||||
* **Identifiers** ([identifiers.md](identifiers.md)): Names and UIDs
|
||||
explained.
|
||||
|
||||
* **Images** ([images.md](images.md)): Information about container images
|
||||
and private registries.
|
||||
|
||||
* **Logging** ([logging.md](logging.md)): Pointers to logging info.
|
||||
|
||||
* **Namespaces** ([namespaces.md](namespaces.md)): Namespaces help different
|
||||
projects, teams, or customers to share a kubernetes cluster.
|
||||
|
||||
* **Networking** ([docs/admin/networking.md](../admin/networking.md)): Pod networking overview.
|
||||
|
||||
* **Services and firewalls** ([docs/services-firewalls.md](../services-firewalls.md)): How
|
||||
to use firewalls.
|
||||
|
||||
* **Compute Resources** ([compute-resources.md](compute-resources.md)):
|
||||
Provides resource information such as size, type, and quantity to assist in
|
||||
assigning Kubernetes resources appropriately.
|
||||
|
||||
* The [API object documentation](http://kubernetes.io/third_party/swagger-ui/).
|
||||
|
||||
* Frequently asked questions are answered on this project's [wiki](https://github.com/GoogleCloudPlatform/kubernetes/wiki).
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
Loading…
Reference in New Issue
Block a user