From 4922d8a1153f5d7220993e230a454dd0d293e0b0 Mon Sep 17 00:00:00 2001
From: Danielle Tomlinson <dani@hashicorp.com>
Date: Wed, 12 Dec 2018 13:02:44 +0100
Subject: [PATCH] guides: Update for globbed namespace rules

---
 .../source/guides/security/acl.html.markdown  | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/website/source/guides/security/acl.html.markdown b/website/source/guides/security/acl.html.markdown
index 15ed4b11f6aa..0ab8ba1ec04c 100644
--- a/website/source/guides/security/acl.html.markdown
+++ b/website/source/guides/security/acl.html.markdown
@@ -253,6 +253,36 @@ namespace "default" {
 }
 ```
 
+Namespace definitions may also include globs, that can be used to provide access to a category of namespaces, while allowing more specific privileges where required. For example, the below policy allows read access to most production namespaces, but allows write access to the `"production-api"` namespace, and rejects any access to the `"production-ppi"` namespace.
+
+```
+namespace "production-*" {
+    policy = "read"
+}
+
+namespace "production-api" {
+    policy = "write"
+}
+
+namespace "production-ppi" {
+    policy = "deny"
+}
+```
+
+Namespaces are matched to their policies first by performing a lookup on any _exact match_, before falling back to performing a glob based lookup. When looking up namespaces by glob, the matching policy with the fewest number of matched characters will be chosen. For example:
+
+```
+namespace "*-ppi" {
+    policy = "deny"
+}
+
+namespace "*" {
+    policy = "write"
+}
+```
+
+Will evaluate to deny for `production-ppi`, because it is 9 characters different from the `"*-ppi"` rule, but 13 characters different from the `"*"` rule.
+
 ### Node Rules
 
 The `node` policy controls access to the [Node API](/api/nodes.html) such as listing nodes or triggering a node drain.