From 49189f645a0490d7ced843ec7359e3db6490466f Mon Sep 17 00:00:00 2001
From: Maksim Fedotov <m_fedotov@wargaming.net>
Date: Tue, 26 Oct 2021 17:43:47 +0300
Subject: [PATCH] docs: forbidden node labels and annotations

---
 .../use-cases/deny-wildcard-hostnames.md      |  5 +--
 .../namespace-labels-and-annotations.md       |  6 ++--
 .../use-cases/node-labels-and-annotations.md  | 32 +++++++++++++++++++
 docs/operator/use-cases/taint-services.md     |  2 +-
 4 files changed, 37 insertions(+), 8 deletions(-)
 create mode 100644 docs/operator/use-cases/node-labels-and-annotations.md

diff --git a/docs/operator/use-cases/deny-wildcard-hostnames.md b/docs/operator/use-cases/deny-wildcard-hostnames.md
index f1f675de9..553a56221 100644
--- a/docs/operator/use-cases/deny-wildcard-hostnames.md
+++ b/docs/operator/use-cases/deny-wildcard-hostnames.md
@@ -26,7 +26,4 @@ EOF
 Doing this, Alice will not be able to use `oil.bigorg.com`, being the tenant-owner of `gas`.
 
 # What’s next
-
-This ends our tour in Capsule use cases. As we improve Capsule, more  use cases about multi-tenancy, policy admission control, and cluster  governance will be covered in the future.
-
-Stay tuned!
\ No newline at end of file
+See how Bill, the cluster admin can protect specific labels and annotations on Nodes from modifications by Tenant Owners. [Denying specific user-defined labels or annotations on Nodes](./node-labels-and-annotations.md).
diff --git a/docs/operator/use-cases/namespace-labels-and-annotations.md b/docs/operator/use-cases/namespace-labels-and-annotations.md
index 594a53099..ff805e1cb 100644
--- a/docs/operator/use-cases/namespace-labels-and-annotations.md
+++ b/docs/operator/use-cases/namespace-labels-and-annotations.md
@@ -1,4 +1,4 @@
-# Denying user-defined labels or annotations
+# Denying specific user-defined labels or annotations on Namespaces
 
 By default, capsule allows tenant owners to add and modify any label or annotation on their namespaces. 
 
@@ -13,9 +13,9 @@ kind: Tenant
 metadata:
   name: oil
   annotations:
-    capsule.clastix.io/forbidden-namespace-labels: foo.acme.net, bar.acme.net
+    capsule.clastix.io/forbidden-namespace-labels: foo.acme.net,bar.acme.net
     capsule.clastix.io/forbidden-namespace-labels-regexp: .*.acme.net
-    capsule.clastix.io/forbidden-namespace-annotations: foo.acme.net, bar.acme.net
+    capsule.clastix.io/forbidden-namespace-annotations: foo.acme.net,bar.acme.net
     capsule.clastix.io/forbidden-namespace-annotations-regexp: .*.acme.net
 spec:
   owners:
diff --git a/docs/operator/use-cases/node-labels-and-annotations.md b/docs/operator/use-cases/node-labels-and-annotations.md
new file mode 100644
index 000000000..68d98be73
--- /dev/null
+++ b/docs/operator/use-cases/node-labels-and-annotations.md
@@ -0,0 +1,32 @@
+# Denying specific user-defined labels or annotations on Nodes
+
+When using `capsule` together with [capsule-proxy](https://github.com/clastix/capsule-proxy), Bill can allow Tenant Owners to [modify Nodes](../../proxy/overview.md).
+
+By default, it will allow tenant owners to add and modify any label or annotation on their nodes. 
+
+But there are some scenarios, when tenant owners should not have an ability to add or modify specific labels or annotations (there are some types of labels or annotations, which must be protected from modifications - for example, which are set by `cloud-providers` or `autoscalers`).
+
+Bill, the cluster admin, can deny Tenant Owners to add or modify specific labels and annotations on Nodes:
+
+```yaml
+kubectl apply -f - << EOF
+apiVersion: capsule.clastix.io/v1alpha1
+kind: CapsuleConfiguration
+metadata:
+  name: default
+  annotations:
+    capsule.clastix.io/forbidden-node-labels: foo.acme.net,bar.acme.net
+    capsule.clastix.io/forbidden-node-labels-regexp: .*.acme.net
+    capsule.clastix.io/forbidden-node-annotations: foo.acme.net,bar.acme.net
+    capsule.clastix.io/forbidden-node-annotations-regexp: .*.acme.net
+spec:
+  userGroups:
+    - capsule.clastix.io
+    - system:serviceaccounts:default
+EOF
+```
+# What’s next
+
+This ends our tour in Capsule use cases. As we improve Capsule, more  use cases about multi-tenancy, policy admission control, and cluster  governance will be covered in the future.
+
+Stay tuned!
\ No newline at end of file
diff --git a/docs/operator/use-cases/taint-services.md b/docs/operator/use-cases/taint-services.md
index fd4279846..811c4016c 100644
--- a/docs/operator/use-cases/taint-services.md
+++ b/docs/operator/use-cases/taint-services.md
@@ -25,4 +25,4 @@ EOF
 When Alice creates a service in a namespace, this will inherit the given label and/or annotation.
 
 # What’s next
-See how Bill, the cluster admin, can allow Alice to use specific labels or annotations. [Allow adding labels and annotations on namespaces](./namespace-labels-and-annotations.md).
+See how Bill, the cluster admin, can protect specific labels and annotations on Namespaces from modifications by Alice. [Denying specific user-defined labels or annotations on Namespaces](./namespace-labels-and-annotations.md).