From 8a911b39afea310946c14f949be9c520988bebcb Mon Sep 17 00:00:00 2001 From: "Matt T. Proud" Date: Wed, 8 Oct 2014 21:09:18 +0200 Subject: [PATCH] Swap internal doc. refs to relative links. This commit addresses issue #1571, which requests that all internal Kubernetes links are swapped to relative ones to better facilitate browsing of documentation on local forks, not to mention make the documentation have less needless boilerplate. --- CONTRIBUTING.md | 2 +- DESIGN.md | 8 ++--- README.md | 12 +++---- docs/access.md | 66 +++++++++++++++++----------------- docs/container-environment.md | 8 ++--- docs/networking.md | 7 ++-- docs/pods.md | 6 ++-- docs/ux.md | 2 +- examples/walkthrough/README.md | 6 ++-- 9 files changed, 57 insertions(+), 60 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90672b17f7952..2d1491087feba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ Follow either of the two links above to access the appropriate CLA and instructi ## Protocols for Collaborative Development -Please read [this doc](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/collab.md) for information on how we're running development for the project. +Please read [this doc](docs/collab.md) for information on how we're running development for the project. ## Adding dependencies diff --git a/DESIGN.md b/DESIGN.md index 8dbfacae8c901..a5bf10824578c 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -52,7 +52,7 @@ While Docker itself works with individual containers, Kubernetes provides higher A _pod_ (as in a pod of whales or pea pod) is a relatively tightly coupled group of containers that are scheduled onto the same host. It models an application-specific "virtual host" in a containerized environment. Pods serve as units of scheduling, deployment, and horizontal scaling/replication, share fate, and share some resources, such as storage volumes and IP addresses. -[More details on pods](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md). +[More details on pods](docs/pods.md). ### Labels @@ -66,11 +66,11 @@ Kubernetes currently supports two objects that use label selectors to keep track - `service`: A service is a configuration unit for the [proxies](#kubernetes-proxy) that run on every worker node. It is named and points to one or more pods. - `replicationController`: A replication controller takes a template and ensures that there is a specified number of "replicas" of that template running at any one time. If there are too many, it'll kill some. If there are too few, it'll start more. -The set of pods that a `service` targets is defined with a label selector. Similarly, the population of pods that a `replicationController` is monitoring is also defined with a label selector. +The set of pods that a `service` targets is defined with a label selector. Similarly, the population of pods that a `replicationController` is monitoring is also defined with a label selector. For management convenience and consistency, `services` and `replicationControllers` may themselves have labels and would generally carry the labels their corresponding pods have in common. -[More details on labels](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/labels.md). +[More details on labels](docs/labels.md). ## The Kubernetes Node @@ -138,7 +138,7 @@ The heavy lifting of configuring the VMs is done by [SaltStack](http://www.salts The bootstrapping works like this: 1. The `kube-up.sh` script uses the GCE [`startup-script`](https://developers.google.com/compute/docs/howtos/startupscript) mechanism for both the master node and the minion nodes. - * For the minion, this simply configures and installs SaltStack. The network range that this minion is assigned is baked into the startup-script for that minion (see [the networking doc](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/networking.md) for more details). + * For the minion, this simply configures and installs SaltStack. The network range that this minion is assigned is baked into the startup-script for that minion (see [the networking doc](docs/networking.md) for more details). * For the master, the release files are downloaded from GCS and unpacked. Various parts (specifically the SaltStack configuration) are installed in the right places. 2. SaltStack then installs the necessary servers on each node. * All go code is currently downloaded to each machine and compiled at install time. diff --git a/README.md b/README.md index 236dc9ce64d91..bf70e80e19622 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Kubernetes Kubernetes is an open source implementation of container cluster management. -[Kubernetes Design Document](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/DESIGN.md) - [Kubernetes @ Google I/O 2014](http://youtu.be/tsk0pWf4ipw) +[Kubernetes Design Document](DESIGN.md) - [Kubernetes @ Google I/O 2014](http://youtu.be/tsk0pWf4ipw) [![GoDoc](https://godoc.org/github.com/GoogleCloudPlatform/kubernetes?status.png)](https://godoc.org/github.com/GoogleCloudPlatform/kubernetes) [![Travis](https://travis-ci.org/GoogleCloudPlatform/kubernetes.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/kubernetes) @@ -26,9 +26,9 @@ While the concepts and architecture in Kubernetes represent years of experience * [Circle CI](https://circleci.com/docs/docker#google-compute-engine-and-kubernetes) * [Digital Ocean](https://github.com/bketelsen/coreos-kubernetes-digitalocean) * [OpenStack](https://developer.rackspace.com/blog/running-coreos-and-kubernetes/) -* [kubecfg command line tool](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/cli.md) +* [kubecfg command line tool](docs/cli.md) * [Kubernetes API Documentation](http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html) -* [Kubernetes Client Libraries](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/client-libraries.md) +* [Kubernetes Client Libraries](docs/client-libraries.md) * [Discussion and Community Support](#community-discussion-and-support) * [Hacking on Kubernetes](#development) * [Hacking on Kubernetes Salt configuration](docs/salt.md) @@ -38,8 +38,8 @@ While the concepts and architecture in Kubernetes represent years of experience Check out examples of Kubernetes in action, and community projects in the larger ecosystem: -* [Detailed example application](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/examples/guestbook/README.md) -* [Example of dynamic updates](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/examples/update-demo/README.md) +* [Detailed example application](examples/guestbook/README.md) +* [Example of dynamic updates](examples/update-demo/README.md) * [Cluster monitoring with heapster and cAdvisor](https://github.com/GoogleCloudPlatform/heapster) * [Community projects](https://github.com/GoogleCloudPlatform/kubernetes/wiki/Kubernetes-Community) @@ -178,7 +178,7 @@ hack/e2e-test.sh 1 1 1 ``` ### Testing out flaky tests -[Instructions here](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/flaky-tests.md) +[Instructions here](docs/flaky-tests.md) ### Add/Update dependencies diff --git a/docs/access.md b/docs/access.md index 93012e09d80e7..eb386a249bbb2 100644 --- a/docs/access.md +++ b/docs/access.md @@ -1,6 +1,6 @@ # K8s Identity and Access Management Sketch -This document suggests a direction for identity and access management in the Kubernetes system. +This document suggests a direction for identity and access management in the Kubernetes system. ## Background @@ -27,7 +27,7 @@ For both cases it may be useful to think about these categories differently: - Insider Path - attack on K8s system components. Attacker may have privileged access to networks, machines or K8s software and data. Software errors in K8s system components and administrator error are some types of threat in this category. This document is primarily concerned with K8s API paths, and secondarily with Internal paths. The Application path also needs to be secure, but is not the focus of this document. - + ### Assets to protect External User assets: @@ -47,26 +47,26 @@ K8s Cluster assets: - The value of K8s cluster computing resources (cpu, memory, etc). This document is primarily about protecting K8s User assets and K8s cluster assets from other K8s Users and K8s Project and Cluster Admins. - + ### Usage environments -Cluster in Small organization: - - K8s Admins may be the same people as K8s Users. - - few K8s Admins. +Cluster in Small organization: + - K8s Admins may be the same people as K8s Users. + - few K8s Admins. - prefer ease of use to fine-grained access control/precise accounting, etc. - Product requirement that it be easy for potential K8s Cluster Admin to try out setting up a simple cluster. -Cluster in Large organization: - - K8s Admins typically distinct people from K8s Users. May need to divide K8s Cluster Admin access by roles. - - K8s Users need to be protected from each other. - - Auditing of K8s User and K8s Admin actions important. +Cluster in Large organization: + - K8s Admins typically distinct people from K8s Users. May need to divide K8s Cluster Admin access by roles. + - K8s Users need to be protected from each other. + - Auditing of K8s User and K8s Admin actions important. - flexible accurate usage accounting and resource controls important. - - Lots of automated access to APIs. + - Lots of automated access to APIs. - Need to integrate with existing enterprise directory, authentication, accounting, auditing, and security policy infrastructure. -Org-run cluster: - - organization that runs K8s master components is same as the org that runs apps on K8s. +Org-run cluster: + - organization that runs K8s master components is same as the org that runs apps on K8s. - Minions may be on-premises VMs or physical machines; Cloud VMs; or a mix. - + Hosted cluster: - Offering K8s API as a service, or offering a Paas or Saas built on K8s - May already offer web services, and need to integrate with existing customer account concept, and existing authentication, accounting, auditing, and security policy infrastructure. @@ -76,10 +76,10 @@ Hosted cluster: K8s ecosystem services: - There may be companies that want to offer their existing services (Build, CI, A/B-test, release automation, etc) for use with K8s. There should be some story for this case. -Pods configs should be largely portable between Org-run and hosted configurations. +Pods configs should be largely portable between Org-run and hosted configurations. -# Design +# Design Related discussion: - https://github.com/GoogleCloudPlatform/kubernetes/issues/442 - https://github.com/GoogleCloudPlatform/kubernetes/issues/443 @@ -87,7 +87,7 @@ Related discussion: This doc describes two security profiles: - Simple profile: like single-user mode. Make it easy to evaluate K8s without lots of configuring accounts and policies. Protects from unauthorized users, but does not partition authorized users. - Enterprise profile: Provide mechanisms needed for large numbers of users. Defense in depth. Should integrate with existing enterprise security infrastructure. - + K8s distribution should include templates of config, and documentation, for simple and enterprise profiles. System should be flexible enough for knowledgeable users to create intermediate profiles, but K8s developers should only reason about those two Profiles, not a matrix. Features in this doc are divided into "Initial Feature", and "Improvements". Initial features would be candidates for version 1.00. @@ -121,16 +121,16 @@ Simple Profile: - single `userAccount`, used by all K8s Users and Project Admins. One access token shared by all. Enterprise Profile: - - every human user has own `userAccount`. + - every human user has own `userAccount`. - `userAccount`s have labels that indicate both membership in groups, and ability to act in certain roles. - each service using the API has own `userAccount` too. (e.g. `scheduler`, `repcontroller`) - automated jobs to denormalize the ldap group info into the local system list of users into the K8s userAccount file. -###Unix accounts -A `userAccount` is not a Unix user account. The fact that a pod is started by a `userAccount` does not mean that the processes in that pod's containers run as a Unix user with a corresponding name or identity. +###Unix accounts +A `userAccount` is not a Unix user account. The fact that a pod is started by a `userAccount` does not mean that the processes in that pod's containers run as a Unix user with a corresponding name or identity. Initially: -- The unix accounts available in a container, and used by the processes running in a container are those that are provided by the combination of the base operating system and the Docker manifest. +- The unix accounts available in a container, and used by the processes running in a container are those that are provided by the combination of the base operating system and the Docker manifest. - Kubernetes doesn't enforce any relation between `userAccount` and unix accounts. Improvements: @@ -141,17 +141,17 @@ Improvements: ###Namespaces K8s will have a have a `namespace` API object. It is similar to a Google Compute Engine `project`. It provides a namespace for objects created by a group of people co-operating together, preventing name collisions with non-cooperating groups. It also serves as a reference point for authorization policies. -Namespaces are described in [namespace.md](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/namespaces.md). +Namespaces are described in [namespace.md](docs/namespaces.md). In the Enterprise Profile: - - a `userAccount` may have permission to access several `namespace`s. + - a `userAccount` may have permission to access several `namespace`s. In the Simple Profile: - There is a single `namespace` used by the single user. Namespaces versus userAccount vs Labels: - `userAccount`s are intended for audit logging (both name and UID should be logged), and to define who has access to `namespace`s. -- `labels` (see [docs/labels.md](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/labels.md)) should be used to distinguish pods, users, and other objects that cooperate towards a common goal but are different in some way, such as version, or responsibilities. +- `labels` (see [docs/labels.md](docs/labels.md)) should be used to distinguish pods, users, and other objects that cooperate towards a common goal but are different in some way, such as version, or responsibilities. - `namespace`s prevent name collisions between uncoordinated groups of people, and provide a place to attach common policies for co-operating groups of people. @@ -162,17 +162,17 @@ Goals for K8s authentication: - Allow for authentication to be handled by a system external to Kubernetes, to allow integration with existing to enterprise authorization systems. The kubernetes namespace itself should avoid taking contributions of multiple authorization schemes. Instead, a trusted proxy in front of the apiserver can be used to authenticate users. - For organizations whose security requirements only allow FIPS compliant implementations (e.g. apache) for authentication. - So the proxy can terminate SSL, and isolate the CA-signed certificate from less trusted, higher-touch APIserver. - - For organizations that already have existing SaaS web services (e.g. storage, VMs) and want a common authentication portal. + - For organizations that already have existing SaaS web services (e.g. storage, VMs) and want a common authentication portal. - Avoid mixing authentication and authorization, so that authorization policies be centrally managed, and to allow changes in authentication methods without affecting authorization code. Initially: - Tokens used to authenticate a user. -- Long lived tokens identify a particular `userAccount`. +- Long lived tokens identify a particular `userAccount`. - Administrator utility generates tokens at cluster setup. - OAuth2.0 Bearer tokens protocol, http://tools.ietf.org/html/rfc6750 - No scopes for tokens. Authorization happens in the API server - Tokens dynamically generated by apiserver to identify pods which are making API calls. -- Tokens checked in a module of the APIserver. +- Tokens checked in a module of the APIserver. - Authentication in apiserver can be disabled by flag, to allow testing without authorization enabled, and to allow use of an authenticating proxy. In this mode, a query parameter or header added by the proxy will identify the caller. Improvements: @@ -193,10 +193,10 @@ K8s authorization should: - Allow for a range of maturity levels, from single-user for those test driving the system, to integration with existing to enterprise authorization systems. - Allow for centralized management of users and policies. In some organizations, this will mean that the definition of users and access policies needs to reside on a system other than k8s and encompass other web services (such as a storage service). - Allow processes running in K8s Pods to take on identity, and to allow narrow scoping of permissions for those identities in order to limit damage from software faults. -- Have Authorization Policies exposed as API objects so that a single config file can create or delete Pods, Controllers, Services, and the identities and policies for those Pods and Controllers. +- Have Authorization Policies exposed as API objects so that a single config file can create or delete Pods, Controllers, Services, and the identities and policies for those Pods and Controllers. - Be separate as much as practical from Authentication, to allow Authentication methods to change over time and space, without impacting Authorization policies. -K8s will implement a relatively simple +K8s will implement a relatively simple [Attribute-Based Access Control](http://en.wikipedia.org/wiki/Attribute_Based_Access_Control) model. The model will be described in more detail in a forthcoming document. The model will - Be less complex than XACML @@ -208,16 +208,16 @@ Authorization policy is set by creating a set of Policy objects. The API Server will be the Enforcement Point for Policy. For each API call that it receives, it will construct the Attributes needed to evaluate the policy (what user is making the call, what resource they are accessing, what they are trying to do that resource, etc) and pass those attributes to a Decision Point. The Decision Point code evaluates the Attributes against all the Policies and allows or denies the API call. The system will be modular enough that the Decision Point code can either be linked into the APIserver binary, or be another service that the apiserver calls for each Decision (with appropriate time-limited caching as needed for performance). Policy objects may be applicable only to a single namespace or to all namespaces; K8s Project Admins would be able to create those as needed. Other Policy objects may be applicable to all namespaces; a K8s Cluster Admin might create those in order to authorize a new type of controller to be used by all namespaces, or to make a K8s User into a K8s Project Admin.) - + ## Accounting -The API should have a `quota` concept (see https://github.com/GoogleCloudPlatform/kubernetes/issues/442). A quota object relates a namespace (and optionally a label selector) to a maximum quantity of resources that may be used (see [resources.md](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/resources.md)). +The API should have a `quota` concept (see https://github.com/GoogleCloudPlatform/kubernetes/issues/442). A quota object relates a namespace (and optionally a label selector) to a maximum quantity of resources that may be used (see [resources.md](docs/resources.md)). Initially: - a `quota` object is immutable. - for hosted K8s systems that do billing, Project is recommended level for billing accounts. -- Every object that consumes resources should have a `namespace` so that Resource usage stats are roll-up-able to `namespace`. +- Every object that consumes resources should have a `namespace` so that Resource usage stats are roll-up-able to `namespace`. - K8s Cluster Admin sets quota objects by writing a config file. Improvements: @@ -246,5 +246,3 @@ Initial implementation: Improvements: - API server does logging instead. - Policies to drop logging for high rate trusted API calls, or by users performing audit or other sensitive functions. - - diff --git a/docs/container-environment.md b/docs/container-environment.md index 0b49cc93c45ba..69c93b25ad6cb 100644 --- a/docs/container-environment.md +++ b/docs/container-environment.md @@ -2,12 +2,12 @@ # Kubernetes Container Environment ## Overview -This document describes the environment for Kubelet managed containers on a Kubernetes node (kNode).  In contrast to the Kubernetes cluster API, which provides an API for creating and managing containers, the Kubernetes container environment provides the container access to information about what else is going on in the cluster.  +This document describes the environment for Kubelet managed containers on a Kubernetes node (kNode).  In contrast to the Kubernetes cluster API, which provides an API for creating and managing containers, the Kubernetes container environment provides the container access to information about what else is going on in the cluster.  This cluster information makes it possible to build applications that are *cluster aware*.   -Additionally, the Kubernetes container environment defines a series of signals that are surfaced to optional signal handlers defined as part of individual containers.  Container signals are somewhat analagous to operating system signals in a traditional process model.   However these signals are designed to make it easier to build reliable, scalable cloud applications in the Kubernetes cluster.  Containers that participate in this cluster lifecycle become *cluster native*.  +Additionally, the Kubernetes container environment defines a series of signals that are surfaced to optional signal handlers defined as part of individual containers.  Container signals are somewhat analagous to operating system signals in a traditional process model.   However these signals are designed to make it easier to build reliable, scalable cloud applications in the Kubernetes cluster.  Containers that participate in this cluster lifecycle become *cluster native*.  -Another important part of the container environment is the file system that is available to the container. In Kubernetes, the filesystem is a combination of the Docker image and pod volumes. The design and usage of pod volumes is described in its own [document](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/volumes.md) +Another important part of the container environment is the file system that is available to the container. In Kubernetes, the filesystem is a combination of the Docker image and pod volumes. The design and usage of pod volumes is described in its own [document](docs/volumes.md) The following sections describe both the cluster information provided to containers, as well as the signals and life-cycle that allows containers to interact with the management system. @@ -44,7 +44,7 @@ There are currently two container signals that are surfaced to containers, and t This signal is sent immediately before a container is created.  It signals that the container will be created immediately after the call completes.  No parameters are passed. *Note - *Some event handlers (namely ‘exec’ are incompatible with this event) -*PostStart* +*PostStart* This signal is sent immediately after a container is created.  It signals to the container that it has been created.  No parameters are passed to the handler. diff --git a/docs/networking.md b/docs/networking.md index 8753c1d9cf31a..c88b32a38875e 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -2,7 +2,7 @@ ## Model and motivation -Kubernetes deviates from the default Docker networking model. The goal is for each [pod](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md) to have an IP in a flat shared networking namespace that has full communication with other physical computers and containers across the network. IP-per-pod creates a clean, backward-compatible model where pods can be treated much like VMs or physical hosts from the perspectives of port allocation, networking, naming, service discovery, load balancing, application configuration, and migration. +Kubernetes deviates from the default Docker networking model. The goal is for each [pod](docs/pods.md) to have an IP in a flat shared networking namespace that has full communication with other physical computers and containers across the network. IP-per-pod creates a clean, backward-compatible model where pods can be treated much like VMs or physical hosts from the perspectives of port allocation, networking, naming, service discovery, load balancing, application configuration, and migration. OTOH, dynamic port allocation requires supporting both static ports (e.g., for externally accessible services) and dynamically allocated ports, requires partitioning centrally allocated and locally acquired dynamic ports, complicates scheduling (since ports are a scarce resource), is inconvenient for users, complicates application configuration, is plagued by port conflicts and reuse and exhaustion, requires non-standard approaches to naming (e.g., etcd rather than DNS), requires proxies and/or redirection for programs using standard naming/addressing mechanisms (e.g., web browsers), requires watching and cache invalidation for address/port changes for instances in addition to watching group membership changes, and obstructs container/pod migration (e.g., using CRIU). NAT introduces additional complexity by fragmenting the addressing space, which breaks self-registration mechanisms, among other problems. @@ -27,7 +27,7 @@ Ports mapped in from the 'main IP' (and hence the internet if the right firewall We start Docker with: DOCKER_OPTS="--bridge cbr0 --iptables=false" -We set up this bridge on each node with SaltStack, in [container_bridge.py](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/cluster/saltbase/salt/_states/container_bridge.py). +We set up this bridge on each node with SaltStack, in [container_bridge.py](cluster/saltbase/salt/_states/container_bridge.py). cbr0: container_bridge.ensure: @@ -65,7 +65,7 @@ Docker allocates IP addresses from a bridge we create on each node, using its ### Other networking implementation examples With the primary aim of providing IP-per-pod-model, other implementations exist to serve the purpose outside of GCE. - - [OpenVSwitch with GRE/VxLAN](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/ovs-networking.md) + - [OpenVSwitch with GRE/VxLAN](docs/ovs-networking.md) - [Flannel](https://github.com/coreos/flannel#flannel) ## Challenges and future work @@ -105,4 +105,3 @@ Another approach could be to create a new host interface alias for each pod, if ### IPv6 IPv6 would be a nice option, also, but we can't depend on it yet. Docker support is in progress: [Docker issue #2974](https://github.com/dotcloud/docker/issues/2974), [Docker issue #6923](https://github.com/dotcloud/docker/issues/6923), [Docker issue #6975](https://github.com/dotcloud/docker/issues/6975). Additionally, direct ipv6 assignment to instances doesn't appear to be supported by major cloud providers (e.g., AWS EC2, GCE) yet. We'd happily take pull requests from people running Kubernetes on bare metal, though. :-) - diff --git a/docs/pods.md b/docs/pods.md index 18eca51b8a0e6..9d378240a9c75 100644 --- a/docs/pods.md +++ b/docs/pods.md @@ -2,7 +2,7 @@ ## What is a _pod_? -A _pod_ (as in a pod of whales or pea pod) models an application-specific "logical host" in a containerized environment. It may contain one or more containers which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host. +A _pod_ (as in a pod of whales or pea pod) models an application-specific "logical host" in a containerized environment. It may contain one or more containers which are relatively tightly coupled -- in a pre-container world, they would have executed on the same physical or virtual host. Like running containers, pods are considered to be relatively ephemeral rather than durable entities. As discussed in [life of a pod](pod-states.md), pods are scheduled to nodes and remain there until termination (according to restart policy) or deletion. When a node dies, the pods scheduled to that node are deleted. Specific pods are never rescheduled to new nodes; instead, they must be replaced (see [replication controller](replication-controller.md) for more details). (In the future, a higher-level API may support pod migration.) @@ -10,9 +10,9 @@ Like running containers, pods are considered to be relatively ephemeral rather t ### Resource sharing and communication -Pods facilitate data sharing and communication among their constituents. +Pods facilitate data sharing and communication among their constituents. -The containers in the pod all use the same network namespace/IP and port space, and can find and communicate with each other using localhost. Each pod has an IP address in a flat shared networking namespace that has full communication with other physical computers and containers across the network. The hostname is set to the pod's Name for the containers within the pod. [More details on networking](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/networking.md). +The containers in the pod all use the same network namespace/IP and port space, and can find and communicate with each other using localhost. Each pod has an IP address in a flat shared networking namespace that has full communication with other physical computers and containers across the network. The hostname is set to the pod's Name for the containers within the pod. [More details on networking](docs/networking.md). In addition to defining the containers that run in the pod, the pod specifies a set of shared storage volumes. Volumes enable data to survive container restarts and to be shared among the containers within the pod. diff --git a/docs/ux.md b/docs/ux.md index baee849d5f402..93aa1a602ef48 100644 --- a/docs/ux.md +++ b/docs/ux.md @@ -24,7 +24,7 @@ The Kubernetes user interface is a query-based visualization of the Kubernetes A _GroupBy_ takes a label ```key``` as a parameter, places all objects with the same value for that key within a single group. For example ```/groups/host/selector``` groups pods by host. ```/groups/name/selector``` groups pods by name. Groups are hiearchical, for example ```/groups/name/host/selector``` first groups by pod name, and then by host. #### Select -Select takes a [label selector](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/labels.md) and uses it to filter, so only resources which match that label selector are displayed. For example, ```/groups/host/selector/name=frontend```, shows pods, grouped by host, which have a label with the name `frontend`. +Select takes a [label selector](docs/labels.md) and uses it to filter, so only resources which match that label selector are displayed. For example, ```/groups/host/selector/name=frontend```, shows pods, grouped by host, which have a label with the name `frontend`. ## Rebuilding the UX diff --git a/examples/walkthrough/README.md b/examples/walkthrough/README.md index f026c8726a7ea..0786329bef336 100644 --- a/examples/walkthrough/README.md +++ b/examples/walkthrough/README.md @@ -3,7 +3,7 @@ ## Pods The first atom of Kubernetes is a _pod_. A pod is a collection of containers that are symbiotically group. -See [pods](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/pods.md) for more details. +See [pods](docs/pods.md) for more details. ### Intro @@ -23,7 +23,7 @@ desiredState: A pod definition is a declaration of a _desired state_. Desired state is a really important part of Kubernetes. Many things present a desired state to the system, and it is Kubernetes' responsibility to make sure that the current state matches the desired state. For example, when you create a Pod, you declare that you want the containers in it to be running. If the containers happen to not be running (program failure, ...), Kubernetes will continue to (re)create them for you until you delete the Pod. -See the [design document](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/DESIGN.md) for more details. +See the [design document](DESIGN.md) for more details. ### Volumes @@ -75,7 +75,7 @@ In Kubernetes, ```emptyDir``` Volumes live for the lifespan of the Pod, which is If you want to mount a directory that already exists in the file system (e.g. ```/var/logs```) you can use the ```hostDir``` directive. -See [volumes](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/volumes.md) for more details. +See [volumes](docs/volumes.md) for more details. ### Multiple Containers