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 -->