github.com/enmand/kubernetes@v1.2.0-alpha.0/docs/admin/namespaces.md (about)

     1  <!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
     2  
     3  <!-- BEGIN STRIP_FOR_RELEASE -->
     4  
     5  <img src="http://kubernetes.io/img/warning.png" alt="WARNING"
     6       width="25" height="25">
     7  <img src="http://kubernetes.io/img/warning.png" alt="WARNING"
     8       width="25" height="25">
     9  <img src="http://kubernetes.io/img/warning.png" alt="WARNING"
    10       width="25" height="25">
    11  <img src="http://kubernetes.io/img/warning.png" alt="WARNING"
    12       width="25" height="25">
    13  <img src="http://kubernetes.io/img/warning.png" alt="WARNING"
    14       width="25" height="25">
    15  
    16  <h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
    17  
    18  If you are using a released version of Kubernetes, you should
    19  refer to the docs that go with that version.
    20  
    21  <strong>
    22  The latest 1.0.x release of this document can be found
    23  [here](http://releases.k8s.io/release-1.0/docs/admin/namespaces.md).
    24  
    25  Documentation for other releases can be found at
    26  [releases.k8s.io](http://releases.k8s.io).
    27  </strong>
    28  --
    29  
    30  <!-- END STRIP_FOR_RELEASE -->
    31  
    32  <!-- END MUNGE: UNVERSIONED_WARNING -->
    33  
    34  # Namespaces
    35  
    36  ## Abstract
    37  
    38  A Namespace is a mechanism to partition resources created by users into
    39  a logically named group.
    40  
    41  ## Motivation
    42  
    43  A single cluster should be able to satisfy the needs of multiple users or groups of users (henceforth a 'user community').
    44  
    45  Each user community wants to be able to work in isolation from other communities.
    46  
    47  Each user community has its own:
    48  
    49  1. resources (pods, services, replication controllers, etc.)
    50  2. policies (who can or cannot perform actions in their community)
    51  3. constraints (this community is allowed this much quota, etc.)
    52  
    53  A cluster operator may create a Namespace for each unique user community.
    54  
    55  The Namespace provides a unique scope for:
    56  
    57  1. named resources (to avoid basic naming collisions)
    58  2. delegated management authority to trusted users
    59  3. ability to limit community resource consumption
    60  
    61  ## Use cases
    62  
    63  1.  As a cluster operator, I want to support multiple user communities on a single cluster.
    64  2.  As a cluster operator, I want to delegate authority to partitions of the cluster to trusted users
    65      in those communities.
    66  3.  As a cluster operator, I want to limit the amount of resources each community can consume in order
    67      to limit the impact to other communities using the cluster.
    68  4.  As a cluster user, I want to interact with resources that are pertinent to my user community in
    69      isolation of what other user communities are doing on the cluster.
    70  
    71  
    72  ## Usage
    73  
    74  Look [here](namespaces/) for an in depth example of namespaces.
    75  
    76  ### Viewing namespaces
    77  
    78  You can list the current namespaces in a cluster using:
    79  
    80  ```console
    81  $ kubectl get namespaces
    82  NAME          LABELS    STATUS
    83  default       <none>    Active
    84  kube-system   <none>    Active
    85  ```
    86  
    87  Kubernetes starts with two initial namespaces:
    88     * `default` The default namespace for objects with no other namespace
    89     * `kube-system` The namespace for objects created by the Kubernetes system
    90  
    91  You can also get the summary of a specific namespace using:
    92  
    93  ```console
    94  $ kubectl get namespaces <name>
    95  ```
    96  
    97  Or you can get detailed information with:
    98  
    99  ```console
   100  $ kubectl describe namespaces <name>
   101  Name:	   default
   102  Labels:	   <none>
   103  Status:	   Active
   104  
   105  No resource quota.
   106  
   107  Resource Limits
   108   Type		Resource	Min	Max	Default
   109   ----				--------	---	---	---
   110   Container			cpu			-	-	100m
   111  ```
   112  
   113  Note that these details show both resource quota (if present) as well as resource limit ranges.
   114  
   115  Resource quota tracks aggregate usage of resources in the *Namespace* and allows cluster operators
   116  to define *Hard* resource usage limits that a *Namespace* may consume.
   117  
   118  A limit range defines min/max constraints on the amount of resources a single entity can consume in
   119  a *Namespace*.
   120  
   121  See [Admission control: Limit Range](../design/admission_control_limit_range.md)
   122  
   123  A namespace can be in one of two phases:
   124     * `Active` the namespace is in use
   125     * `Terminating` the namespace is being deleted, and can not be used for new objects
   126  
   127  See the [design doc](../design/namespaces.md#phases) for more details.
   128  
   129  ### Creating a new namespace
   130  
   131  To create a new namespace, first create a new YAML file called `my-namespace.yaml` with the contents:
   132  
   133  ```yaml
   134  apiVersion: v1
   135  kind: Namespace
   136  metadata:
   137    name: <insert-namespace-name-here>
   138  ```
   139  
   140  Note that the name of your namespace must be a DNS compatible label.
   141  
   142  More information on the `finalizers` field can be found in the namespace [design doc](../design/namespaces.md#finalizers).
   143  
   144  Then run:
   145  
   146  ```console
   147  $ kubectl create -f ./my-namespace.yaml
   148  ```
   149  
   150  ### Working in namespaces
   151  
   152  See [Setting the namespace for a request](../../docs/user-guide/namespaces.md#setting-the-namespace-for-a-request)
   153  and [Setting the namespace preference](../../docs/user-guide/namespaces.md#setting-the-namespace-preference).
   154  
   155  ### Deleting a namespace
   156  
   157  You can delete a namespace with
   158  
   159  ```console
   160  $ kubectl delete namespaces <insert-some-namespace-name>
   161  ```
   162  
   163  **WARNING, this deletes _everything_ under the namespace!**
   164  
   165  This delete is asynchronous, so for a time you will see the namespace in the `Terminating` state.
   166  
   167  ## Namespaces and DNS
   168  
   169  When you create a [Service](../../docs/user-guide/services.md), it creates a corresponding [DNS entry](dns.md).
   170  This entry is of the form `<service-name>.<namespace-name>.svc.cluster.local`, which means
   171  that if a container just uses `<service-name>` it will resolve to the service which
   172  is local to a namespace.  This is useful for using the same configuration across
   173  multiple namespaces such as Development, Staging and Production.  If you want to reach
   174  across namespaces, you need to use the fully qualified domain name (FQDN).
   175  
   176  ## Design
   177  
   178  Details of the design of namespaces in Kubernetes, including a [detailed example](../design/namespaces.md#example-openshift-origin-managing-a-kubernetes-namespace)
   179  can be found in the [namespaces design doc](../design/namespaces.md)
   180  
   181  
   182  <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
   183  [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/namespaces.md?pixel)]()
   184  <!-- END MUNGE: GENERATED_ANALYTICS -->