From aebf488b5ad146133deeeee4debcd6ebf47e8a9b Mon Sep 17 00:00:00 2001
From: Scott Hussey <sh8121@att.com>
Date: Thu, 18 Apr 2019 16:22:47 -0500
Subject: [PATCH] Docs for utilizing etcd encryption

Add documentation for how to manipulate the EncryptionPolicy
document to configure apiserver persisting data to etcd
encrypted

Change-Id: I90234a676139931584b67208233b83cf61a8bcf2
---
 .../configuration/encryption-policy.rst       | 60 +++++++++++++++++--
 1 file changed, 55 insertions(+), 5 deletions(-)

diff --git a/doc/source/configuration/encryption-policy.rst b/doc/source/configuration/encryption-policy.rst
index 423978ce..fa288975 100644
--- a/doc/source/configuration/encryption-policy.rst
+++ b/doc/source/configuration/encryption-policy.rst
@@ -1,11 +1,13 @@
 EncryptionPolicy
 ================
 
-Encryption policy defines how encryption should be applied via Promenade.  The
-primary use-case for this is to encrypt ``genesis.sh`` or ``join.sh`` scripts.
+Encryption policy defines how encryption should be applied via Promenade, either
+directly or via charts maintained in the Promenade project.
 
-Sample Document
----------------
+Encrypting script in-line data
+------------------------------
+
+The primary use-case for this is to encrypt ``genesis.sh`` or ``join.sh`` scripts.
 
 .. code-block:: yaml
 
@@ -26,8 +28,56 @@ Sample Document
 
 
 Scripts
--------
+^^^^^^^
 
 The genesis and join scripts can be built with sensitive content encrypted.
 Currently the only encryption method available is ``gpg``, which can be enabled
 by setting that key to an empty dictionary.
+
+Kubernetes apiserver persistence encryption
+-------------------------------------------
+
+Kubernetes supports `encrypting data`_ it writes to etcd. This is defined by an
+encryption policy document enabled using a CLI option for the apiserver binary.
+Separating out the policy into the EncryptionPolicy document is needed as there
+must be guaranteed consistency between the policy put in place for bootstrapping
+the cluster and apiservers put in place via Helm chart.
+
+Neither Promenade, nor the apiserver chart, do anything to ensure you do not lock
+yourself out of your data. When rotating encryption keys, you will need to always
+leave all keys that reflect data currently encrypted in the profile. Note the
+instructions on how to rotate keys in the linked Kubernetes documentation.
+
+To make this encryption configuration effective, you must substitute into two
+other documents
+
+  * Substitute ``.etcd`` into ``.apiserver.encryption`` of your Genesis profile
+    document.
+
+  * Substitute ``.etcd`` into ``.values.conf.encryption_provider.content.resources``
+    of your Armada chart definition for the apiserver chart. See the Promenade
+    ``basic`` examples for reference.
+
+.. code-block:: yaml
+
+    ---
+    schema: promenade/EncryptionPolicy/v1
+    metadata:
+      schema: metadata/Document/v1
+      name: encryption-policy
+      layeringDefinition:
+        abstract: false
+        layer: site
+      storagePolicy: cleartext
+    data:
+      etcd:
+        - resources:
+            - 'secrets'
+          providers:
+            - secretbox:
+                keys:
+                 - name: key1
+                   secret: blzKzBp6wkjU/2xzBqzgJV9FrVkkjBTT43mbctIhdPQ=
+    ...
+
+.. _encrypting data: https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/