diff --git a/docs/README.md b/docs/README.md index 9807c43700ba3..f356385168370 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/cluster-admin-guide.md b/docs/cluster-admin-guide.md new file mode 100644 index 0000000000000..d59c224ede9d2 --- /dev/null +++ b/docs/cluster-admin-guide.md @@ -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) + diff --git a/docs/developer-guide.md b/docs/developer-guide.md new file mode 100644 index 0000000000000..9a11801ac2482 --- /dev/null +++ b/docs/developer-guide.md @@ -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). diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000000000..0a4b6dc6d4aab --- /dev/null +++ b/docs/user-guide.md @@ -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). +