From 3c23d75133c9a3f288127d90274a436d673d579f Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Fri, 31 Mar 2017 13:50:16 -0700 Subject: [PATCH] Move Guide topics: Names, Namespaces. (#3183) --- _data/concepts.yml | 2 + .../overview/working-with-objects/names.md | 18 ++++ .../working-with-objects/namespaces.md | 88 +++++++++++++++++++ docs/user-guide/identifiers.md | 12 +-- docs/user-guide/namespaces.md | 81 +---------------- 5 files changed, 112 insertions(+), 89 deletions(-) create mode 100644 docs/concepts/overview/working-with-objects/names.md create mode 100644 docs/concepts/overview/working-with-objects/namespaces.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 5165740b14..514ed250ed 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -10,6 +10,8 @@ toc: - title: Working with Kubernetes Objects section: - docs/concepts/overview/working-with-objects/kubernetes-objects.md + - docs/concepts/overview/working-with-objects/names.md + - docs/concepts/overview/working-with-objects/namespaces.md - docs/concepts/overview/working-with-objects/labels.md - docs/concepts/overview/working-with-objects/annotations.md - docs/concepts/overview/kubernetes-api.md diff --git a/docs/concepts/overview/working-with-objects/names.md b/docs/concepts/overview/working-with-objects/names.md new file mode 100644 index 0000000000..195ff57de4 --- /dev/null +++ b/docs/concepts/overview/working-with-objects/names.md @@ -0,0 +1,18 @@ +--- +assignees: +- mikedanese +- thockin +title: Names +--- + +All objects in the Kubernetes REST API are unambiguously identified by a Name and a UID. + +For non-unique user-provided attributes, Kubernetes provides [labels](/docs/user-guide/labels) and [annotations](/docs/user-guide/annotations). + +## Names + +Names are generally client-provided. Only one object of a given kind can have a given name at a time (i.e., they are spatially unique). But if you delete an object, you can make a new object with the same name. Names are used to refer to an object in a resource URL, such as `/api/v1/pods/some-name`. By convention, the names of Kubernetes resources should be up to maximum length of 253 characters and consist of lower case alphanumeric characters, `-`, and `.`, but certain resources have more specific restrictions. See the [identifiers design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/identifiers.md) for the precise syntax rules for names. + +## UIDs + +UID are generated by Kubernetes. Every object created over the whole lifetime of a Kubernetes cluster has a distinct UID (i.e., they are spatially and temporally unique). diff --git a/docs/concepts/overview/working-with-objects/namespaces.md b/docs/concepts/overview/working-with-objects/namespaces.md new file mode 100644 index 0000000000..1ce6861760 --- /dev/null +++ b/docs/concepts/overview/working-with-objects/namespaces.md @@ -0,0 +1,88 @@ +--- +assignees: +- derekwaynecarr +- mikedanese +- thockin +title: Namespaces +--- + +Kubernetes supports multiple virtual clusters backed by the same physical cluster. +These virtual clusters are called namespaces. + +## When to Use Multiple 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 are a way to divide cluster resources between multiple uses (via [resource quota](/docs/admin/resourcequota/)). + +In future versions of Kubernetes, objects in the same namespace will have the same +access control policies by default. + +It is not necessary to use multiple namespaces just to separate slightly different +resources, such as different versions of the same software: use [labels](/docs/user-guide/labels) to distinguish +resources within the same namespace. + +## Working with Namespaces + +Creation and deletion of namespaces is described in the [Admin Guide documentation +for namespaces](/docs/admin/namespaces) + +### Viewing namespaces + +You can list the current namespaces in a cluster using: + +```shell +$ kubectl get namespaces +NAME LABELS STATUS +default Active +kube-system Active +``` + +Kubernetes starts with two initial namespaces: + + * `default` The default namespace for objects with no other namespace + * `kube-system` The namespace for objects created by the Kubernetes system + +### Setting the namespace for a request + +To temporarily set the namespace for a request, use the `--namespace` flag. + +For example: + +```shell +$ kubectl --namespace= run nginx --image=nginx +$ kubectl --namespace= get pods +``` + +### Setting the namespace preference + +You can permanently save the namespace for all subsequent kubectl commands in that +context. + +```shell +$ kubectl config set-context $(kubectl config current-context) --namespace= +# Validate it +$ kubectl config view | grep namespace: +``` + +## Namespaces and DNS + +When you create a [Service](/docs/user-guide/services), it creates a corresponding [DNS entry](/docs/admin/dns). +This entry is of the form `..svc.cluster.local`, which means +that if a container just 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). + +## Not All Objects are in a Namespace + +Most Kubernetes resources (e.g. pods, services, replication controllers, and others) are +in some namespace. However namespace resources are not themselves in a namespace. +And low-level resources, such as [nodes](/docs/admin/node) and +persistentVolumes, are not in any namespace. Events are an exception: they may or may not +have a namespace, depending on the object the event is about. diff --git a/docs/user-guide/identifiers.md b/docs/user-guide/identifiers.md index 195ff57de4..bcb4f620c5 100644 --- a/docs/user-guide/identifiers.md +++ b/docs/user-guide/identifiers.md @@ -5,14 +5,6 @@ assignees: title: Names --- -All objects in the Kubernetes REST API are unambiguously identified by a Name and a UID. +{% include user-guide-content-moved.md %} -For non-unique user-provided attributes, Kubernetes provides [labels](/docs/user-guide/labels) and [annotations](/docs/user-guide/annotations). - -## Names - -Names are generally client-provided. Only one object of a given kind can have a given name at a time (i.e., they are spatially unique). But if you delete an object, you can make a new object with the same name. Names are used to refer to an object in a resource URL, such as `/api/v1/pods/some-name`. By convention, the names of Kubernetes resources should be up to maximum length of 253 characters and consist of lower case alphanumeric characters, `-`, and `.`, but certain resources have more specific restrictions. See the [identifiers design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/identifiers.md) for the precise syntax rules for names. - -## UIDs - -UID are generated by Kubernetes. Every object created over the whole lifetime of a Kubernetes cluster has a distinct UID (i.e., they are spatially and temporally unique). +[Names](/docs/concepts/overview/working-with-objects/names/) diff --git a/docs/user-guide/namespaces.md b/docs/user-guide/namespaces.md index 1ce6861760..d4a0c4a607 100644 --- a/docs/user-guide/namespaces.md +++ b/docs/user-guide/namespaces.md @@ -6,83 +6,6 @@ assignees: title: Namespaces --- -Kubernetes supports multiple virtual clusters backed by the same physical cluster. -These virtual clusters are called namespaces. +{% include user-guide-content-moved.md %} -## When to Use Multiple 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 are a way to divide cluster resources between multiple uses (via [resource quota](/docs/admin/resourcequota/)). - -In future versions of Kubernetes, objects in the same namespace will have the same -access control policies by default. - -It is not necessary to use multiple namespaces just to separate slightly different -resources, such as different versions of the same software: use [labels](/docs/user-guide/labels) to distinguish -resources within the same namespace. - -## Working with Namespaces - -Creation and deletion of namespaces is described in the [Admin Guide documentation -for namespaces](/docs/admin/namespaces) - -### Viewing namespaces - -You can list the current namespaces in a cluster using: - -```shell -$ kubectl get namespaces -NAME LABELS STATUS -default Active -kube-system Active -``` - -Kubernetes starts with two initial namespaces: - - * `default` The default namespace for objects with no other namespace - * `kube-system` The namespace for objects created by the Kubernetes system - -### Setting the namespace for a request - -To temporarily set the namespace for a request, use the `--namespace` flag. - -For example: - -```shell -$ kubectl --namespace= run nginx --image=nginx -$ kubectl --namespace= get pods -``` - -### Setting the namespace preference - -You can permanently save the namespace for all subsequent kubectl commands in that -context. - -```shell -$ kubectl config set-context $(kubectl config current-context) --namespace= -# Validate it -$ kubectl config view | grep namespace: -``` - -## Namespaces and DNS - -When you create a [Service](/docs/user-guide/services), it creates a corresponding [DNS entry](/docs/admin/dns). -This entry is of the form `..svc.cluster.local`, which means -that if a container just 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). - -## Not All Objects are in a Namespace - -Most Kubernetes resources (e.g. pods, services, replication controllers, and others) are -in some namespace. However namespace resources are not themselves in a namespace. -And low-level resources, such as [nodes](/docs/admin/node) and -persistentVolumes, are not in any namespace. Events are an exception: they may or may not -have a namespace, depending on the object the event is about. +[Namespaces](/docs/concepts/overview/working-with-objects/namespaces/)