Namespaces

    Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all. Start using namespaces when you need the features they provide.

    Namespaces provide a scope for names. Names of resources need to be unique within a namespace, but not across namespaces. Namespaces cannot be nested inside one another and each Kubernetes resource can only be in one namespace.

    Namespaces are a way to divide cluster resources between multiple users (via ).

    It is not necessary to use multiple namespaces to separate slightly different resources, such as different versions of the same software: use labels to distinguish resources within the same namespace.

    Note: For a production cluster, consider not using the namespace. Instead, make other namespaces and use those.

    Initial namespaces

    Kubernetes starts with four initial namespaces:

    default

    Kubernetes includes this namespace so that you can start using your new cluster without first creating a namespace.

    kube-node-lease

    kube-public

    This namespace is readable by all clients (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.

    The namespace for objects created by the Kubernetes system.

    Creation and deletion of namespaces are described in the .

    Note: Avoid creating namespaces with the prefix kube-, since it is reserved for Kubernetes system namespaces.

    You can list the current namespaces in a cluster using:

    To set the namespace for a current request, use the --namespace flag.

    For example:

    Namespaces and DNS

    When you create a Service, it creates a corresponding . This entry is of the form <service-name>.<namespace-name>.svc.cluster.local, which means that if a container only uses , it will resolve to the service which is local to a namespace. This is useful for using the same configuration across multiple namespaces such as Development, Staging and Production. If you want to reach across namespaces, you need to use the fully qualified domain name (FQDN).

    As a result, all namespace names must be valid RFC 1123 DNS labels.

    Warning:

    By creating namespaces with the same name as , Services in these namespaces can have short DNS names that overlap with public DNS records. Workloads from any namespace performing a DNS lookup without a trailing dot will be redirected to those services, taking precedence over public DNS.

    To mitigate this, limit privileges for creating namespaces to trusted users. If required, you could additionally configure third-party security controls, such as , to block creating any namespace with the name of public TLDs.

    Most Kubernetes resources (e.g. pods, services, replication controllers, and others) are in some namespaces. However namespace resources are not themselves in a namespace. And low-level resources, such as nodes and , are not in any namespace.

    To see which Kubernetes resources are and aren’t in a namespace:

    Automatic labelling

    FEATURE STATE: Kubernetes 1.22 [stable]

    The Kubernetes control plane sets an immutable kubernetes.io/metadata.name on all namespaces, provided that the NamespaceDefaultLabelName feature gate is enabled. The value of the label is the namespace name.