kubernetes 0.0.1 → 0.0.2

data/docs/resources.md

@@ -0,0 +1,218 @@
+# The Kubernetes resource model
+
+To do good pod placement, Kubernetes needs to know how big pods are, as well as the sizes of the nodes onto which they are being placed.  The definition of "how big" is given by the Kubernetes resource model - the subject of this document.
+
+The resource model aims to be:
+* simple, for common cases;
+* extensible, to accommodate future growth;
+* regular, with few special cases; and
+* precise, to avoid misunderstandings and promote pod portability.
+
+## The resource model
+A Kubernetes _resource_ is something that can be requested by, allocated to, or consumed by a pod or container.  Examples include memory (RAM), CPU, disk-time, and network bandwidth.
+
+Once resources on a node have been allocated to one pod, they should not be allocated to another until that pod is removed or exits. This means that Kubernetes schedulers should ensure that the sum of the resources allocated (requested and granted) to its pods never exceeds the usable capacity of the node. Testing whether a pod will fit on a node is called _feasibility checking_. Note that the resource model currently prohibits over-committing resources; we will want to relax that restriction later.
+
+### Resource types
+
+All resources have a _type_ that is identified by their _typename_ (a string, e.g., "memory").  Several resource types are predefined by Kubernetes (a full list is below), although only two will be supported at first: CPU and memory.  Users and system administrators can define their own resource types if they wish (e.g., Hadoop slots).
+
+A fully-qualified resource typename is constructed from a DNS-style _subdomain_ with at least one dot, a slash `/`, and a path comprised of one or more segments separated by slashes.
+* The subdomain must conform to [RFC 1035 section 2.3.1 'subdomain' syntax](http://tools.ietf.org/html/rfc1035) (e.g., `kubernetes.io`, `myveryown.org`).
+* The path must conform to [RFC 3986 URI `path-rootless` syntax](http://tools.ietf.org/html/rfc3986#section-3.3)  (e.g., `memory`, `shinyNewResource/v2`), save that it must not use dot-segments (`.` and `..`).
+* As a shorthand, any resource typename that does not start with a subdomain and a slash will automatically be prefixed with the built-in Kubernetes _namespace_, `kubernetes.io/resources/` in order to fully-qualify it.  This namespace is reserved for code in the open source Kubernetes repository; as a result, all user typenames MUST be fully qualified, and cannot be created in this namespace.
+* Typenames are treated as literal strings, and neither escaped nor case-converted.  This means that case is signifcant (unlike RFC 1035 subdomains) and paths should avoid characters that need percent-encoding.
+
+The recommended best practice is to use a lowercase subdomain and Go-like ASCII camelCase for path components.  Some example typenames include `memory` (which will be fully-qualified as `kubernetes.io/resources/memory`), and `myveryown.org/shinyNewResource/v2`.
+
+For future reference, note that some resources, such as CPU and network bandwidth, are _compressible_, which means that their usage can potentially be throttled in a relatively benign manner. All other resources are _incompressible_, which means that any attempt to throttle them is likely to cause grief.  This distinction will be important if a Kubernetes implementation supports over-committing of resources.
+
+### Resource quantities
+
+Initially, all Kubernetes resource types are _quantitative_, and have an associated _unit_ for quantities of the associated resource (e.g., bytes for memory, bytes per seconds for bandwidth, instances for software licences). The units will always be a resource type's natural base units (e.g., bytes, not MB), to avoid confusion between binary and decimal multipliers and the underlying unit multiplier (e.g., is memory measured in MiB, MB, or GB?).  
+
+Resource quantities can be added and subtracted: for example, a node has a fixed quantity of each resource type that can be allocated to pods/containers; once such an allocation has been made, the allocated resources cannot be made available to other pods/containers without over-committing the resources.
+
+To make life easier for people, quantities can be represented externally as unadorned integers, or as fixed-point integers with one of these SI suffices  (E, P, T, G, M, K, m) or their power-of-two equivalents (Ei, Pi, Ti, Gi, Mi, Ki).  For example, the following represent roughly the same value: 128974848, "129e6", "129M" , "123Mi".  Small quantities can be represented directly as decimals (e.g., 0.3), or using milli-units (e.g., "300m").
+  * "Externally" means in user interfaces, reports, graphs, and in JSON or YAML resource specifications that might be generated or read by people.
+  * Case is significant: "m" and "M" are not the same, so "k" is not a valid SI suffix. There are no power-of-two equivalents for SI suffixes that represent multipliers less than 1.
+  * These conventions only apply to resource quantities, not arbitrary values.
+
+Internally (i.e., everywhere else), Kubernetes will represent resource quantities as integers so it can avoid problems with rounding errors, and will not use strings to represent numeric values. To achieve this, quantities that naturally have fractional parts (e.g., CPU seconds/second) will be scaled to integral numbers of milli-units (e.g., milli-CPUs) as soon as they are read in.  Internal APIs, data structures, and protobufs will use these scaled integer units.  Raw measurement data such as usage may still need to be tracked and calculated using floating point values, but internally they should be rescaled to avoid some values being in milli-units and some not.
+  * Note that reading in a resource quantity and writing it out again may change the way its values are represented, and truncate precision (e.g., 1.0001 may become 1.000), so comparison and difference operations (e.g., by an updater) must be done on the internal representations.
+  * Avoiding milli-units in external representations has advantages for people who will use Kubernetes, but runs the risk of developers forgetting to rescale or accidentally using floating-point representations. That seems like the right choice. We will try to reduce the risk by providing libraries that automatically do the quantization for JSON/YAML inputs.
+
+### Resource specifications
+
+A _resource specification_ can be used to describe resource requests, resource allocations, and/or resource usage for a container or pod, and capacity for a node.  For example (although it would be unusual to see all of these fields simultaneously):
+```
+resources: [
+  request:   [ cpu: 2.5, memory: "40Mi" ],
+  limit:     [ cpu: 4.0, memory: "99Mi" ],
+  capacity:  [ cpu: 12,  memory: "128Gi" ],
+  maxusage:  [ cpu: 3.8, memory: "80Mi" ],
+]
+```
+
+Where:
+* _request_: the amount of resources being requested, or that were requested and have been allocated. Scheduler algorithms will use these quantities to test feasibility (whether a pod will fit onto a node).  If a container (or pod) tries to use more resources than its _request_, any associated SLOs are voided - e.g., the program it is running may be throttled (compressible resource types), or the attempt may be denied. If _request_ is omitted for a container, it defaults to _limit_ if that is explicitly specified, otherwise to an implementation-defined value; this will always be 0 for a user-defined resource type. If _request_ is omitted for a pod, it defaults to the sum of the (explicit ior implicit) _request_ values for the containers it encloses.
+
+* _limit_ [optional]: an upper bound or cap on the maximum amount of resources that will be made available to a container otr pod; if a container or pod uses more resources than its _limit_, it may be terminated. The _limit_ defaults to "unbounded"; in practice, this probably means the capacity of an enclosing container, pod, or node, but may result in non-deterministic behavior, especially for memory.
+
+* _capacity_: the total allocatable resources of a node.  Initially, the resources at a given scope will bound the resources of the sum of inner scopes. This may be loosened in the future to permit overcommittment.
+
+* _maxusage_: the largest observed resource usage.  (See the Appendix for richer data structures.)
+
+Notes:
+
+  * It is an error to specify the same resource type more than once in each list.
+
+  * It is an error for the _request_ or _limit_ values for a pod to be less than the sum of the (explicit or defaulted) values for the containers it encloses.  (We may relax this later.)
+
+  * If multiple pods are running on the same node and attempting to use more resources than they have requested, the result is implementation-defined. For example: unallocated or unused resources might be spread equally across claimants, or the assignment might be weighted by the size of the original request, or as a function of limits, or priority, or the phase of the moon, perhaps modulated by the direction of the tide. Thus, although it's not mandatory to provide a _request_, it's probably a good idea.  (Note that the _request_ could be filled in by an automated system that is observing actual usage and/or historical data.)
+
+  * Internally, the Kubernetes master can decide the defaulting behavior and the kubelet implementation may expected an absolute specification.  For example, if the master decided that "the default is unbounded" it would pass 2^64 to the kubelet.
+
+
+
+## Kubernetes-defined resource types
+The following resource types are predefined ("reserved") by Kubernetes in the `resources.kubernetes.io` namespace, and so cannot be used for user-defined resources.  Note that the syntax of all resource types in the resource spec is deliberately similar, but some resource types (e.g., CPU) may receive significantly more support than simply tracking quantities in the schedulers and/or the Kubelet.
+
+### Processor cycles
+  * Name: `cpu` (or `kubernetes.io/resources/cpu`)
+  * Units: Kubernetes Compute Unit seconds/second (i.e., CPU cores normalized to a canonical "Kubernetes CPU")
+  * Internal representation: milli-KCUs
+  * Compressible? yes
+  * Qualities: [this is a placeholder for the kind of thing that may be supported in the future]
+    * [future] `schedulingLatency`: as per lmctfy
+    * [future] `cpuConversionFactor`: property of a node: the speed of a CPU core on the node's processor divided by the speed of the canonical Kubernetes CPU (a floating point value; default = 1.0).
+
+To reduce performance portability problems for pods, and to avoid worse-case provisioning behavior, the units of CPU will be normalized to a canonical "Kubernetes Compute Unit" (KCU, pronounced ˈko͝oko͞o), which will roughly be equivalent to a single CPU hyperthreaded core for some recent x86 processor. The normalization may be implementation-defined, although some reasonable defaults will be provided in the open-source Kubernetes code.
+
+Note that requesting 2 KCU won't guarantee that precisely 2 physical cores will be allocated - control of aspects like this will be handled by resource _qualities_ (a future feature).
+
+
+### Memory
+  * Name: `memory` (or `kubernetes.io/resources/memory`)
+  * Units: bytes
+  * Compressible? no (at least initially)
+
+The precise meaning of what "memory" means is implementation dependent, but the basic idea is to rely on the underlying `memcg` mechanisms, support, and definitions.
+
+Note that most people will want to use power-of-two suffixes (Mi, Gi) for memory quantities
+rather than decimal ones: "64MiB" rather than "64MB".
+
+
+## Resource metadata
+A resource type may have an associated read-only ResourceType structure, that contains metadata about the type.  For example:
+```
+resourceTypes: [
+  "kubernetes.io/resources/memory": [
+    isCompressible: false, ... 
+  ]
+  "kubernetes.io/resources/cpu": [
+    isCompressible: true, internalScaleExponent: 3, ...
+  ]
+  "kubernetes.io/resources/diskSpace": [ ... }
+]
+```
+
+Kubernetes will provide ResourceType metadata for its predefined types.  If no resource metadata can be found for a resource type, Kubernetes will assume that it is a quantified, incompressible resource that is not specified in milli-units, and has no default value.
+
+The defined properties are as follows:
+
+| field name | type | contents |
+| ---------- | ---- | -------- |
+| name | string, required | the typename, as a fully-qualified string (e.g., `kubernetes.io/resources/cpu`) |
+| internalScaleExponent | int, default=0 | external values are multiplied by 10 to this power for internal storage (e.g., 3 for milli-units) |
+| units | string, required | format: `unit* [per unit+]` (e.g., `second`, `byte per second`). An empty unit field means "dimensionless". |
+| isCompressible | bool, default=false | true if the resource type is compressible |
+| defaultRequest | string, default=none | in the same format as a user-supplied value |
+| _[future]_ quantization | number, default=1 | smallest granularity of allocation: requests may be rounded up to a multiple of this unit; implementation-defined unit (e.g., the page size for RAM). |
+
+
+# Appendix: future extensions
+
+The following are planned future extensions to the resource model, included here to encourage comments.
+
+## Extended usage data
+
+Singleton values for observed and predicted future usage will rapidly prove inadequate, so we will support the following structure for extended usage information: 
+
+```
+resources: [
+  usage:     [ cpu: <CPU-info>, memory: <memory-info> ],
+  predicted: [ cpu: <CPU-info>, memory: <memory-info> ],
+]
+```
+
+where a `<CPU-info>` or `<memory-info>` structure looks like this:
+```
+{
+    mean: <value>    # arithmetic mean
+    max: <value>     # minimum value
+    min: <value>     # maximum value
+    count: <value>   # number of data points
+    percentiles: [   # map from %iles to values
+      "10": <10th-percentile-value>,
+      "50": <median-value>,
+      "99": <99th-percentile-value>,
+      "99.9": <99.9th-percentile-value>,
+      ...
+    ]
+ }
+```
+All parts of this structure are optional, although we strongly encourage including quantities for 50, 90, 95, 99, 99.5, and 99.9 percentiles.  _[In practice, it will be important to include additional info such as the length of the time window over which the averages are calculated, the confidence level, and information-quality metrics such as the number of dropped or discarded data points.]_
+and predicted 
+
+## Future resource types
+
+### _[future] Network bandwidth_
+  * Name: "networkBandwidth" (or `kubernetes.io/resources/networkBandwidth`)
+  * Units: bytes per second
+  * Compressible? yes
+
+### _[future] Network operations_
+  * Name: "networkIOPS" (or `kubernetes.io/resources/networkOperations`)
+  * Units: operations (messages) per second
+  * Compressible? yes
+
+### _[future] Storage space_
+  * Name: "storageSpace" (or `kubernetes.io/resources/storageSpace`)
+  * Units: bytes
+  * Compressible? no
+
+The amount of secondary storage space available to a container.  The main target is local disk drives and SSDs, although this could also be used to qualify remotely-mounted volumes.   Specifying whether a resource is a raw disk, an SSD, a disk array, or a file system fronting any of these, is left for future work.
+
+### _[future] Storage time_
+  * Name: storageTime (or `kubernetes.io/resources/storageTime`)
+  * Units: seconds per second of disk time
+  * Internal representation: milli-units
+  * Compressible? yes
+
+This is the amount of time a container spends accessing disk, including actuator and transfer time.  A standard disk drive provides 1.0 diskTime seconds per second.
+
+### _[future] Storage operations_
+  * Name: "storageIOPS" (or `kubernetes.io/resources/storageIOPS`)
+  * Units: operations per second
+  * Compressible? yes
+
+
+## Named, individual resources
+
+This is primarily important for things like disks, flash and network
+cards, where there can be multiple, separate resource suppliers, and
+the aprtition of the request across them may matter.  (Note that the
+unadorned `storageSpace` resource type doesn't imply a particular
+disk.)  Such resources will be identified by extending the resource
+typename with the instance identifier. For example:
+
+resources: [
+  request: [
+    cpu: 2.3, memory: "4Gi",
+    "storageSpace/hda":  "0.5Ti", "storageTime/hda":  0.3,
+    "storageSpace/ssd1": "0.1Ti", "storageTime/ssd1": 0.9,
+ ],
+]
+
+Note that this does make it hard to parse typenames (e.g., is "foo.com/a/b" a type named "a/b" or a type named "a" with an subdivision of "b"?).  Comments welcome.

data/docs/roadmap.md

@@ -0,0 +1,65 @@
+# Kubernetes Roadmap
+
+Updated August 28, 2014
+
+This document is intended to capture the set of features, docs, and patterns that we feel are required to call Kubernetes “feature complete” for a 1.0 release candidate.  This list does not emphasize the bug fixes and stabilization that will be required to take it all the way to production ready.  This is a living document, and is certainly open for discussion.
+
+## APIs
+1. ~~Versioned APIs:  Manage APIs for master components and kubelets with explicit versions, version-specific conversion routines, and component-to-component version checking.~~ **Done**
+2. Component-centric APIs:  Clarify which types belong in each component’s API and which ones are truly common.
+  1. Clarify the role of etcd in the cluster.
+3. Idempotency: Whenever possible APIs must be idempotent.
+4. Container restart policy: Policy for each pod or container stating whether and when it should be restarted upon termination.
+5. Life cycle events/hooks and notifications: Notify containers about what is happening to them.
+6. Re-think the network parts of the API: Find resolution on the the multiple issues around networking.
+  1. ~~Utility of HostPorts in ip-per-pod~~ **Done**
+  2. Services/Links/Portals/Ambassadors
+7. Durable volumes: Provide a model for data that survives some kinds of outages.
+8. Auth[nz] and ACLs: Have a plan for how the API and system will express:
+  1. Identity & authentication
+  2. Authorization & access control
+  3. Cluster subdivision, accounting, & isolation
+
+## Factoring and pluggability
+1. ~~Pluggable scheduling: Cleanly separate the scheduler from the apiserver.~~ **Done**
+2. Pluggable naming and discovery: Call-outs or hooks to enable external naming systems.
+3. Pluggable volumes: Allow new kinds of data sources as volumes.
+4. Replication controller: Make replication controller a standalone entity in the master stack.
+5. Pod templates: Proposal to make pod templates a first-class API object, rather than an artifact of replica controller
+
+## Cluster features
+1. ~~Minion death: Cleanly handle the loss of a minion.~~ **Done**
+2. Configure DNS: Provide DNS service for k8s running pods, containers and services. Auto-populate it with the things we know.
+3. Resource requirements and scheduling: Use knowledge of resources available and resources required to do better scheduling.
+4. ~~True IP-per-pod: Get rid of last remnants of shared port spaces for pods.~~ **Done**
+5. IP-per-service: Proposal to make services cleaner.
+6. Basic deployment tools: This includes tools for higher-level deployments configs.
+7. Standard mechanisms for deploying k8s on k8s with a clear strategy for reusing the infrastructure for self-host.
+
+## Node features
+1. Container termination reasons: Capture and report exit codes and other termination reasons.
+2. Garbage collect old container images: Clean up old docker images that consume local disk. Maybe a TTL on images.
+3. Container logs: Expose stdout/stderr from containers without users having to SSH into minions.  Needs a rotation policy to avoid disks getting filled.
+4. Container performance information: Capture and report performance data for each container.
+5. Host log management: Make sure we don't kill nodes with full disks.
+
+## Global features
+2. Input validation: Stop bad input as early as possible.
+3. Error propagation: Report problems reliably and consistently.
+4. Consistent patterns of usage of IDs and names throughout the system.
+5. Binary release: Repeatable process to produce binaries for release.
+
+## Patterns, policies, and specifications
+1. Deprecation policy: Declare the project’s intentions with regards to expiring and removing features and interfaces.
+2. Compatibility policy: Declare the project’s intentions with regards to saved state and live upgrades of components.
+3. Naming/discovery: Demonstrate techniques for common patterns:
+  1. Master-elected services
+  2. DB replicas
+  3. Sharded services
+  4. Worker pools
+4. Health-checking: Specification for how it works and best practices.
+5. Logging: Demonstrate setting up log collection.
+6. ~~Monitoring: Demonstrate setting up cluster monitoring.~~ **Done**
+7. Rolling updates: Demo and best practices for live application upgrades.
+  1. Have a plan for how higher level deployment / update concepts should / should not fit into Kubernetes
+8. Minion requirements: Document the requirements and integrations between kubelet and minion machine environments.

data/docs/salt.md

@@ -0,0 +1,85 @@
+# Using Salt to configure Kubernetes
+
+The Kubernetes cluster can be configured using Salt.
+
+The Salt scripts are shared across multiple hosting providers, so it's important to understand some background information prior to making a modification to ensure your changes do not break hosting Kubernetes across multiple environments.  Depending on where you host your Kubernetes cluster, you may be using different operating systems and different networking configurations.  As a result, it's important to understand some background information before making Salt changes in order to minimize introducing failures for other hosting providers.
+
+## Salt cluster setup
+
+The **salt-master** service runs on the kubernetes-master node.
+
+The **salt-minion** service runs on the kubernetes-master node and each kubernetes-minion node in the cluster.
+
+Each salt-minion service is configured to interact with the **salt-master** service hosted on the kubernetes-master via the **master.conf** file.  
+
+```
+[root@kubernetes-master] $ cat /etc/salt/minion.d/master.conf
+master: kubernetes-master
+```
+The salt-master is contacted by each salt-minion and depending upon the machine information presented, the salt-master will provision the machine as either a kubernetes-master or kubernetes-minion with all the required capabilities needed to run Kubernetes.
+
+If you are running the Vagrant based environment, the **salt-api** service is running on the kubernetes-master.  It is configured to enable the vagrant user to introspect the salt cluster in order to find out about machines in the Vagrant environment via a REST API.  
+
+## Salt security
+
+Security is not enabled on the salt-master, and the salt-master is configured to auto-accept incoming requests from minions.  It is not recommended to use this security configuration in production environments.
+
+```
+[root@kubernetes-master] $ cat /etc/salt/master.d/auto-accept.conf
+open_mode: True
+auto_accept: True
+```
+## Salt minion configuration
+
+Each minion in the salt cluster has an associated configuration that instructs the salt-master how to provision the required resources on the machine.
+
+An example file is presented below using the Vagrant based environment.
+
+```
+[root@kubernetes-master] $ cat /etc/salt/minion.d/grains.conf
+grains:
+  master_ip: $MASTER_IP
+  etcd_servers: $MASTER_IP
+  cloud_provider: vagrant
+  roles:
+    - kubernetes-master
+```
+
+Each hosting environment has a slightly different grains.conf file that is used to build conditional logic where required in the Salt files.
+
+The following enumerates the set of defined key/value pairs that are supported today.  If you add new ones, please make sure to update this list.
+
+Key | Value
+------------- | -------------
+cbr-cidr | (Optional) The minion IP address range used for the docker container bridge.
+cloud | (Optional) Which IaaS platform is used to host kubernetes, *gce*, *azure*
+cloud_provider | (Optional) The cloud_provider used by apiserver: *gce*, *azure*, *vagrant*
+etcd_servers | (Required) Comma-delimited list of IP addresses the apiserver and kubelet use to reach etcd
+hostnamef | (Optional) The full host name of the machine, i.e. hostname -f
+master_ip | (Optional) The IP address that the apiserver will bind against
+node_ip | (Optional) The IP address to use to address this node
+minion_ip | (Optional) Mapped to the kubelet hostname_override, K8S TODO - change this name
+network_mode | (Optional) Networking model to use among nodes: *openvswitch*
+roles | (Required) 1. **kubernetes-master** means this machine is the master in the kubernetes cluster.  2. **kubernetes-pool** means this machine is a kubernetes-minion.  Depending on the role, the Salt scripts will provision different resources on the machine.
+
+These keys may be leveraged by the Salt sls files to branch behavior.
+
+In addition, a cluster may be running a Debian based operating system or Red Hat based operating system (Centos, Fedora, RHEL, etc.).  As a result, its important to sometimes distinguish behavior based on operating system using if branches like the following.
+
+```
+{% if grains['os_family'] == 'RedHat' %}
+// something specific to a RedHat environment (Centos, Fedora, RHEL) where you may use yum, systemd, etc.
+{% else %}
+// something specific to Debian environment (apt-get, initd)
+{% endif %}
+```
+
+## Best Practices
+
+1.  When configuring default arguments for processes, its best to avoid the use of EnvironmentFiles (Systemd in Red Hat environments) or init.d files (Debian distributions) to hold default values that should be common across operating system environments.  This helps keep our Salt template files easy to understand for editors that may not be familiar with the particulars of each distribution.
+
+## Future enhancements (Networking)
+
+Per pod IP configuration is provider specific, so when making networking changes, its important to sand-box these as all providers may not use the same mechanisms (iptables, openvswitch, etc.)
+
+We should define a grains.conf key that captures more specifically what network configuration environment is being used to avoid future confusion across providers.

data/docs/security.md

@@ -0,0 +1,26 @@
+# Security in Kubernetes
+
+General design principles and guidelines related to security of containers, APIs, and infrastructure in Kubernetes.
+
+
+## Objectives
+
+1.  Ensure a clear isolation between container and the underlying host it runs on
+2.  Limit the ability of the container to negatively impact the infrastructure or other containers
+3.  [Principle of Least Privilege](http://en.wikipedia.org/wiki/Principle_of_least_privilege) - ensure components are only authorized to perform the actions they need, and limit the scope of a compromise by limiting the capabilities of individual components
+4.  Reduce the number of systems that have to be hardened and secured by defining clear boundaries between components
+
+
+## Design Points
+
+### Isolate the data store from the minions and supporting infrastructure
+
+Access to the central data store (etcd) in Kubernetes allows an attacker to run arbitrary containers on hosts, to gain access to any protected information stored in either volumes or in pods (such as access tokens or shared secrets provided as environment variables), to intercept and redirect traffic from running services by inserting middlemen, or to simply delete the entire history of the custer.
+
+As a general principle, access to the central data store should be restricted to the components that need full control over the system and which can apply appropriate authorization and authentication of change requests.  In the future, etcd may offer granular access control, but that granularity will require an administrator to understand the schema of the data to properly apply security.  An administrator must be able to properly secure Kubernetes at a policy level, rather than at an implementation level, and schema changes over time should not risk unintended security leaks.
+
+Both the Kubelet and Kube Proxy need information related to their specific roles - for the Kubelet, the set of pods it should be running, and for the Proxy, the set of services and endpoints to load balance.  The Kubelet also needs to provide information about running pods and historical termination data.  The access pattern for both Kubelet and Proxy to load their configuration is an efficient "wait for changes" request over HTTP.  It should be possible to limit the Kubelet and Proxy to only access the information they need to perform their roles and no more.
+
+The controller manager for Replication Controllers and other future controllers act on behalf of a user via delegation to perform automated maintenance on Kubernetes resources. Their ability to access or modify resource state should be strictly limited to their intended duties and they should be prevented from accessing information not pertinent to their role.  For example, a replication controller needs only to create a copy of a known pod configuration, to determine the running state of an existing pod, or to delete an existing pod that it created - it does not need to know the contents or current state of a pod, nor have access to any data in the pods attached volumes.
+
+The Kubernetes pod scheduler is responsible for reading data from the pod to fit it onto a minion in the cluster.  At a minimum, it needs access to view the ID of a pod (to craft the binding), its current state, any resource information necessary to identify placement, and other data relevant to concerns like anti-affinity, zone or region preference, or custom logic.  It does not need the ability to modify pods or see other resources, only to create bindings.  It should not need the ability to delete bindings unless the scheduler takes control of relocating components on failed hosts (which could be implemented by a separate component that can delete bindings but not create them).  The scheduler may need read access to user or project-container information to determine preferential location (underspecified at this time).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kubernetes
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Riccardo Carlesso
@@ -10,14 +10,32 @@ bindir: bin
 cert_chain: []
 date: 2010-09-21 00:00:00.000000000 Z
 dependencies: []
-description: Currently a placeholder. In the future, a Gem to get up to speed with
-  Kubernetes
+description: ! 'Currently a placeholder. In the future, a Gem to get up to speed with
+  Kubernetes. For more info: https://github.com/GoogleCloudPlatform/kubernetes/'
 email: palladiusbonton@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Makefile
 - README.md
+- docs/access.md
+- docs/architecture.dia
+- docs/architecture.svg
+- docs/client-libraries.md
+- docs/flaky-tests.md
+- docs/identifiers.md
+- docs/networking.md
+- docs/ovs-networking.md
+- docs/ovs-networking.png
+- docs/pods.md
+- docs/releasing.dot
+- docs/releasing.md
+- docs/releasing.png
+- docs/resources.md
+- docs/roadmap.md
+- docs/salt.md
+- docs/security.md
 homepage: http://rubygems.org/gems/kubernetes
 licenses:
 - Apache License
@@ -41,5 +59,5 @@ rubyforge_project:
 rubygems_version: 2.3.0
 signing_key: 
 specification_version: 4
-summary: Kubernetes Gemfile
+summary: To install Kubernetes in rubyish environments
 test_files: []