|
| 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)1. |
| 170 | +This entry is of the form `<service-name>.<namespace-name>.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 | +[]() |
| 184 | +<!-- END MUNGE: GENERATED_ANALYTICS --> |
0 commit comments