Swap internal doc. refs to relative links.

This commit addresses issue kubernetes#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.
lavalamp · Oct 8, 2014 · 8a911b3 · 8a911b3
1 parent 119fc0e
commit 8a911b3
Show file tree

Hide file tree

Showing 9 changed files with 57 additions and 60 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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,18 +76,18 @@ 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
 
 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.
-
-