From ceccbc049c6dbbc82df3e16e648c617727407a9b Mon Sep 17 00:00:00 2001
From: Qiming Teng <tengqim@cn.ibm.com>
Date: Thu, 20 Feb 2020 07:44:30 +0800
Subject: [PATCH] Resource name constraints (1) (#19106)

xref: #17969, #19099, #18746
---
 .../overview/working-with-objects/names.md    | 34 +++++++++++++++++--
 .../extensible-admission-controllers.md       |  2 ++
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/content/en/docs/concepts/overview/working-with-objects/names.md b/content/en/docs/concepts/overview/working-with-objects/names.md
index af24d5f184..60c07391a5 100644
--- a/content/en/docs/concepts/overview/working-with-objects/names.md
+++ b/content/en/docs/concepts/overview/working-with-objects/names.md
@@ -2,7 +2,7 @@
 reviewers:
 - mikedanese
 - thockin
-title: Names
+title: Object Names and IDs
 content_template: templates/concept
 weight: 20
 ---
@@ -18,14 +18,41 @@ For non-unique user-provided attributes, Kubernetes provides [labels](/docs/conc
 
 {{% /capture %}}
 
-
 {{% capture body %}}
 
 ## Names
 
 {{< glossary_definition term_id="name" length="all" >}}
 
-Kubernetes resources can have names up to 253 characters long. The characters allowed in names are: digits (0-9), lower case letters (a-z), `-`, and `.`.
+Below are three types of commonly used name constraints for resources.
+
+### DNS Subdomain Names
+
+Most resource types require a name that can be used as a DNS subdomain name
+as defined in [RFC 1123](https://tools.ietf.org/html/rfc1123).
+This means the name must:
+
+- contain no more than 253 characters
+- contain only lowercase alphanumeric characters, '-' or '.'
+- start with an alphanumeric character
+- end with an alphanumeric character
+
+### DNS Label Names
+
+Some resource types require their names to follow the DNS
+label standard as defined in [RFC 1123](https://tools.ietf.org/html/rfc1123).
+This means the name must:
+
+- contain at most 63 characters
+- contain only lowercase alphanumeric characters or '-'
+- start with an alphanumeric character
+- end with an alphanumeric character
+
+### Path Segment Names
+
+Some resource types require their names to be able to be safely encoded as a
+path segment. In other words, the name may not be "." or ".." and the name may
+not contain "/" or "%".
 
 Here’s an example manifest for a Pod named `nginx-demo`.
 
@@ -42,6 +69,7 @@ spec:
     - containerPort: 80
 ```
 
+
 {{< note >}}
 Some resource types have additional restrictions on their names.
 {{< /note >}}
diff --git a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md
index 3500ed0c53..4131a79df8 100644
--- a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md
+++ b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md
@@ -631,6 +631,8 @@ So a webhook response to add that label would be:
 ## Webhook configuration
 
 To register admission webhooks, create `MutatingWebhookConfiguration` or `ValidatingWebhookConfiguration` API objects.
+The name of a `MutatingWebhookConfiguration` or a `ValidatingWebhookConfiguration` object must be a valid
+[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 
 Each configuration can contain one or more webhooks.
 If multiple webhooks are specified in a single configuration, each should be given a unique name.