forked from kubernetes/kubernetes
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
First pass at organizing our docs for three separate audiences: User, Cluster Admin, and developer. Wrote a top-level guide for each one, by selecting parts of the old docs/README.md. The new docs/README.md mostly points to these 3 guides.
- Loading branch information
Showing
4 changed files
with
197 additions
and
105 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,113 +1,16 @@ | ||
| # Kubernetes Documentation | ||
|
|
||
| * [Primary concepts](#primary-concepts) | ||
| * [Further reading](#further-reading) | ||
| * The [User's guide](user-guide.md) is for anyone who wants to run programs and services on an exisiting Kubernetes cluster. | ||
|
|
||
| * The [Cluster Admin's guide](cluster-admin-guide.md) is for anyone setting up a Kubernetes cluster or administering it. | ||
|
|
||
| Getting started guides are in [getting-started-guides](getting-started-guides). | ||
| * The [Developer guide](developer-guide.md) is for anyone wanting to write programs that access the kubernetes API, | ||
| write plugins or extensions, or modify the core code of kubernetes. | ||
|
|
||
| There are example files and walkthroughs in the [examples](../examples) folder. | ||
| * The [Kubectl Command Line Interface]([kubectl.md](kubectl.md)) is a detailed reference on the `kubectl` CLI. | ||
|
|
||
| If you're developing Kubernetes, docs are in the [devel](devel) folder. | ||
| * The [API object documentation](http://kubernetes.io/third_party/swagger-ui/) is a detailed description of all fields found in core API objects. | ||
|
|
||
| Design docs are in [design](design). | ||
|
|
||
| API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/). | ||
|
|
||
| Frequently asked questions are answered on this project's [wiki](https://github.com/GoogleCloudPlatform/kubernetes/wiki). | ||
|
|
||
| ## Primary concepts | ||
|
|
||
| * **Overview** ([overview.md](overview.md)): A brief overview | ||
| of Kubernetes concepts. | ||
|
|
||
| * **Nodes** ([node.md](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. | ||
|
|
||
| * **Accessing the API** ([accessing_the_api.md](accessing_the_api.md)): | ||
| Ports, IPs, proxies, and firewall rules. | ||
|
|
||
| * **Kubernetes Web Interface** ([ui.md](ui.md)): Accessing the Kubernetes | ||
| web user interface. | ||
|
|
||
| * **Kubectl Command Line Interface** ([kubectl.md](kubectl.md)): | ||
| The `kubectl` command line reference. | ||
|
|
||
| * **Roadmap** ([roadmap.md](roadmap.md)): The set of supported use cases, features, | ||
| docs, and patterns that are required before Kubernetes 1.0. | ||
|
|
||
| * **Glossary** ([glossary.md](glossary.md)): Terms and concepts. | ||
|
|
||
| * **Cluster Management** ([cluster_management.md](cluster_management.md)): Starting and upgrading clusters. | ||
|
|
||
|
|
||
| ## Further reading | ||
|
|
||
|
|
||
| * **Annotations** ([annotations.md](annotations.md)): Attaching | ||
| arbitrary non-identifying metadata. | ||
|
|
||
| * **API Conventions** ([api-conventions.md](api-conventions.md)): | ||
| Defining the verbs and resources used in the Kubernetes API. | ||
|
|
||
| * **Authentication Plugins** ([authentication.md](authentication.md)): | ||
| The current and planned states of authentication tokens. | ||
|
|
||
| * **Authorization Plugins** ([authorization.md](authorization.md)): | ||
| Authorization applies to all HTTP requests on the main apiserver port. | ||
| This doc explains the available authorization implementations. | ||
|
|
||
| * **API Client Libraries** ([client-libraries.md](client-libraries.md)): | ||
| A list of existing client libraries, both supported and user-contributed. | ||
|
|
||
| * **Kubernetes Container Environment** ([container-environment.md](container-environment.md)): | ||
| Describes the environment for Kubelet managed containers on a Kubernetes | ||
| node. | ||
|
|
||
| * **DNS Integration with SkyDNS** ([dns.md](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** ([networking.md](networking.md)): Pod networking overview. | ||
|
|
||
| * **OpenVSwitch GRE/VxLAN networking** ([ovs-networking.md](ovs-networking.md)): | ||
| Using OpenVSwitch to set up networking between pods across | ||
| Kubernetes nodes. | ||
|
|
||
| * **The Kubernetes Resource Model** ([resources.md](resources.md)): | ||
| Provides resource information such as size, type, and quantity to assist in | ||
| assigning Kubernetes resources appropriately. | ||
|
|
||
| * **Using Salt to configure Kubernetes** ([salt.md](salt.md)): The Kubernetes | ||
| cluster can be configured using Salt. | ||
| * An overview of the [Design of Kubernetes](../DESIGN.md) | ||
|
|
||
| * There are example files and walkthroughs in the [examples](../examples) folder. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # 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.md). | ||
|
|
||
| ## Planning a cluster | ||
|
|
||
| There are many different examples of how to setup a kubernetes cluster. Many of them are listed in this | ||
| [matrix](docs/getting-started-guides/README.md). We call each of the combinations in this matrix a *distro*. | ||
|
|
||
| Before chosing a particular guide, here are some things to consider: | ||
| - Are you just looking to try out Kubernetes on your laptop, or build a high-availability many-node cluster? Both | ||
| models are supported, but some distros are better for one case or the other. | ||
| - Will you be using a hosted Kubernetes cluster, such as [GKE](https://cloud.google.com/container-engine), or setting | ||
| one up yourself? | ||
| - Will your cluster be on-premises, or in the cloud (IaaS)? Kubernetes does not directly support hybrid clusters. We | ||
| recommend setting up multiple clusters rather than spanning distant locations. | ||
| - Will you be running Kubernetes on "bare metal" or virtual machines? Kubernetes supports both, via different distros. | ||
| - Do you just want to run a cluster, or do you expect to do active development of kubernetes project code? If the | ||
| latter, it is better to pick a distro actively used by other developers. Some distros only use binary releases, but | ||
| offer is a greater variety of choices. | ||
| - Not all distros are maintained as actively. Prefer ones which are listed as tested on a more recent version of | ||
| Kubernetes. | ||
| - If you are configuring kubernetes on-premises, you will need to consider what [networking | ||
| model](../../docs/networking.md) fits best. | ||
| - If you are designing for very [high-availability](availability.md), you may want multiple clusters in multiple zones. | ||
|
|
||
| ## Setting up a cluster | ||
|
|
||
| Pick one of the Getting Started Guides from the [matrix](docs/getting-started-guides/README.md) and follow it. | ||
| If none of the Getting Started Guides fits, you may want to pull ideas from several of the guides. | ||
|
|
||
| One option for custom networking is *OpenVSwitch GRE/VxLAN networking* ([ovs-networking.md](ovs-networking.md)), which | ||
| uses OpenVSwitch to set up networking between pods across | ||
| Kubernetes nodes. | ||
|
|
||
| If you are modifying an existing guide which uses Salt, this document explains [how Salt is used in the Kubernetes | ||
| project.](salt.md). | ||
|
|
||
| ## Upgrading a cluster | ||
| [Upgrading a cluster](cluster_management.md). | ||
|
|
||
| ## Managing nodes | ||
|
|
||
| [Managing nodes](node.md). | ||
|
|
||
| ## Optional Cluster Services | ||
|
|
||
| * **DNS Integration with SkyDNS** ([dns.md](dns.md)): | ||
| Resolving a DNS name directly to a Kubernetes service. | ||
|
|
||
| * **Logging** with [Kibana](logging.md) | ||
|
|
||
| ## Multi-tenant support | ||
|
|
||
| * **Namespaces** ([namespaces.md](namespaces.md)): Namespaces help different | ||
| projects, teams, or customers to share a kubernetes cluster. | ||
|
|
||
| ## Security | ||
|
|
||
| * **Kubernetes Container Environment** ([container-environment.md](container-environment.md)): | ||
| Describes the environment for Kubelet managed containers on a Kubernetes | ||
| node. | ||
|
|
||
| * **Securing access to the API Server** [accessing the api]( accessing_the_api.md) | ||
|
|
||
| * **Authentication** [authentication]( authentication.md) | ||
|
|
||
| * **Authorization** [authorization]( authorization.md) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Kubernetes Developer Guide | ||
|
|
||
| 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.md) and the [Cluster Admin | ||
| Guide](cluster-admin-guide.md). | ||
|
|
||
|
|
||
| ## Developing against the Kubernetes API | ||
|
|
||
| * API objects are explained at [http://kubernetes.io/third_party/swagger-ui/](http://kubernetes.io/third_party/swagger-ui/). | ||
|
|
||
| * **Annotations** ([annotations.md](annotations.md)): are for attaching arbitrary non-identifying metadata to objects. | ||
| Programs that automate Kubernetes objects may use annotations to store small amounts of their state. | ||
|
|
||
| * **API Conventions** ([api-conventions.md](api-conventions.md)): | ||
| Defining the verbs and resources used in the Kubernetes API. | ||
|
|
||
| * **API Client Libraries** ([client-libraries.md](client-libraries.md)): | ||
| A list of existing client libraries, both supported and user-contributed. | ||
|
|
||
| ## Writing Plugins | ||
|
|
||
| * **Authentication Plugins** ([authentication.md](authentication.md)): | ||
| The current and planned states of authentication tokens. | ||
|
|
||
| * **Authorization Plugins** ([authorization.md](authorization.md)): | ||
| Authorization applies to all HTTP requests on the main apiserver port. | ||
| This doc explains the available authorization implementations. | ||
|
|
||
| ## Contributing to the Kubernetes Project | ||
|
|
||
| See this [README](../docs/devel/README.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # 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](cluster-admin-guide.md). | ||
| The developer guide describes 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** ([node.md](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. | ||
|
|
||
| * **Accessing the API** ([accessing_the_api.md](accessing_the_api.md)): | ||
| Ports, IPs, proxies, and firewall rules. | ||
|
|
||
| * **Kubernetes Web Interface** ([ui.md](ui.md)): Accessing the Kubernetes | ||
| web user interface. | ||
|
|
||
| * **Kubectl Command Line Interface** ([kubectl.md](kubectl.md)): | ||
| The `kubectl` command line reference. | ||
|
|
||
| * **Roadmap** ([roadmap.md](roadmap.md)): The set of supported use cases, features, | ||
| docs, and patterns that are required before Kubernetes 1.0. | ||
|
|
||
| * **Glossary** ([glossary.md](glossary.md)): Terms and concepts. | ||
|
|
||
| ## Further reading | ||
|
|
||
|
|
||
| * **Annotations** ([annotations.md](annotations.md)): Attaching | ||
| arbitrary non-identifying metadata. | ||
|
|
||
| * **Kubernetes Container Environment** ([container-environment.md](container-environment.md)): | ||
| Describes the environment for Kubelet managed containers on a Kubernetes | ||
| node. | ||
|
|
||
| * **DNS Integration with SkyDNS** ([dns.md](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** ([networking.md](networking.md)): Pod networking overview. | ||
|
|
||
| * **The Kubernetes Resource Model** ([resources.md](resources.md)): | ||
| Provides resource information such as size, type, and quantity to assist in | ||
| assigning Kubernetes resources appropriately. | ||
|
|
||
| * **Accessing cluster services via a Proxy** [accessing-the-cluster.md](../docs/accessing-the-cluster.md) | ||
|
|
||
| * 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). | ||
|
|