---
reviewers:
- derekwaynecarr
- janetkuo
title: Share a Cluster with Namespaces
content_type: task
weight: 340
---

<!-- overview -->
This page shows how to view, work in, and delete {{< glossary_tooltip text="namespaces" term_id="namespace" >}}.
The page also shows how to use Kubernetes namespaces to subdivide your cluster.

## {{% heading "prerequisites" %}}

* Have an [existing Kubernetes cluster](/docs/setup/).
* You have a basic understanding of Kubernetes {{< glossary_tooltip text="Pods" term_id="pod" >}},
  {{< glossary_tooltip term_id="service" text="Services" >}}, and
  {{< glossary_tooltip text="Deployments" term_id="deployment" >}}.

<!-- steps -->

## Viewing namespaces

List the current namespaces in a cluster using:

```shell
kubectl get namespaces
```
```console
NAME              STATUS   AGE
default           Active   11d
kube-node-lease   Active   11d
kube-public       Active   11d
kube-system       Active   11d
```

Kubernetes starts with four initial namespaces:

* `default` The default namespace for objects with no other namespace
* `kube-node-lease` This namespace holds [Lease](/docs/concepts/architecture/leases/) objects associated with each node. Node leases allow the kubelet to send [heartbeats](/docs/concepts/architecture/nodes/#heartbeats) so that the control plane can detect node failure.
* `kube-public` This namespace is created automatically and is readable by all users
  (including those not authenticated). This namespace is mostly reserved for cluster usage,
  in case that some resources should be visible and readable publicly throughout the whole cluster.
  The public aspect of this namespace is only a convention, not a requirement.
* `kube-system` The namespace for objects created by the Kubernetes system

You can also get the summary of a specific namespace using:

```shell
kubectl get namespaces <name>
```

Or you can get detailed information with:

```shell
kubectl describe namespaces <name>
```
```console
Name:           default
Labels:         <none>
Annotations:    <none>
Status:         Active

No resource quota.

Resource Limits
 Type       Resource    Min Max Default
 ----               --------    --- --- ---
 Container          cpu         -   -   100m
```

Note that these details show both resource quota (if present) as well as resource limit ranges.

Resource quota tracks aggregate usage of resources in the Namespace and allows cluster operators
to define *Hard* resource usage limits that a Namespace may consume.

A limit range defines min/max constraints on the amount of resources a single entity can consume in
a Namespace.

See [Admission control: Limit Range](https://git.k8s.io/design-proposals-archive/resource-management/admission_control_limit_range.md)

A namespace can be in one of two phases:

* `Active` the namespace is in use
* `Terminating` the namespace is being deleted, and can not be used for new objects

For more details, see [Namespace](/docs/reference/kubernetes-api/cluster-resources/namespace-v1/)
in the API reference.

## Creating a new namespace

{{< note >}}
Avoid creating namespace with prefix `kube-`, since it is reserved for Kubernetes system namespaces.
{{< /note >}}

Create a new YAML file called `my-namespace.yaml` with the contents:

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: <insert-namespace-name-here>
```
Then run:

```shell
kubectl create -f ./my-namespace.yaml
```

Alternatively, you can create namespace using below command:

```shell
kubectl create namespace <insert-namespace-name-here>
``` 

The name of your namespace must be a valid
[DNS label](/docs/concepts/overview/working-with-objects/names#dns-label-names).

There's an optional field `finalizers`, which allows observables to purge resources whenever the
namespace is deleted. Keep in mind that if you specify a nonexistent finalizer, the namespace will
be created but will get stuck in the `Terminating` state if the user tries to delete it.

More information on `finalizers` can be found in the namespace