From a8adc874b7758e9a5cee86abe4477fb3b1a893fc Mon Sep 17 00:00:00 2001
From: Ahmed MUSTAFA <Ahmed.Mustafa@amadeus.com>
Date: Tue, 8 Jun 2021 17:48:46 +0200
Subject: [PATCH] add README docs and yaml snippets for azure keyvault provider

---
 docs/provider-azure-key-vault.md           | 41 ++++++++++++++++++++++
 docs/snippets/azkv-credentials-secret.yaml |  8 +++++
 docs/snippets/azkv-external-secret.yaml    | 36 +++++++++++++++++++
 docs/snippets/azkv-secret-store.yaml       | 16 +++++++++
 4 files changed, 101 insertions(+)
 create mode 100644 docs/snippets/azkv-credentials-secret.yaml
 create mode 100644 docs/snippets/azkv-external-secret.yaml
 create mode 100644 docs/snippets/azkv-secret-store.yaml

diff --git a/docs/provider-azure-key-vault.md b/docs/provider-azure-key-vault.md
index 383145f4a..74d78954b 100644
--- a/docs/provider-azure-key-vault.md
+++ b/docs/provider-azure-key-vault.md
@@ -1,2 +1,43 @@
 
 ![aws sm](./pictures/eso-az-kv-azure-kv.png)
+
+## Azure Key vault
+
+External Secrets Operator integrates with [Azure Key vault](https://azure.microsoft.com/en-us/services/key-vault/) for secrets , certificates and Keys management.
+
+### Authentication
+
+At the moment, we only support [service principals](https://docs.microsoft.com/en-us/azure/key-vault/general/authentication) authentication.
+
+#### Service Principal key authentication
+
+A service Principal client and Secret is created and the JSON keyfile is stored in a `Kind=Secret`. The `ClientID` and `ClientSecret` should be configured for the secret. This service principal should have proper access rights to the keyvault to be managed by the operator
+
+```yaml
+{% include 'azkv-credentials-secret.yaml' %}
+```
+
+### Update secret store
+Be sure the `azkv` provider is listed in the `Kind=SecretStore`
+
+```yaml
+{% include 'azkv-secret-store.yaml' %}
+```
+
+### Creating external secret
+
+To create a kubernetes secret from the Azure Key vault secret a `Kind=ExternalSecret` is needed.
+
+You can manage keys/secrets/certificates saved inside the keyvault , by setting a "/" prefixed type in the secret name , the default type is a `secret`. other supported values are `cert` and `key`
+
+to select all secrets inside the key vault , you can use the `dataFrom` directive
+
+```yaml
+{% include 'azkv-external-secret.yaml' %}
+```
+
+The operator will fetch the Azure Key vault secret and inject it as a `Kind=Secret`
+```
+kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d
+```
+
diff --git a/docs/snippets/azkv-credentials-secret.yaml b/docs/snippets/azkv-credentials-secret.yaml
new file mode 100644
index 000000000..ac9966a45
--- /dev/null
+++ b/docs/snippets/azkv-credentials-secret.yaml
@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: azure-secret-sp
+type: Opaque
+data:
+  ClientID: bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LWlkCg==  #service-principal-ID
+  ClientSecret: bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LXNlY3JldAo= #service-principal-secret
diff --git a/docs/snippets/azkv-external-secret.yaml b/docs/snippets/azkv-external-secret.yaml
new file mode 100644
index 000000000..a70d2b23b
--- /dev/null
+++ b/docs/snippets/azkv-external-secret.yaml
@@ -0,0 +1,36 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: ExternalSecret
+metadata:
+  name: example-external-secret
+spec:
+  refreshInterval: 1h           # rate SecretManager pulls Azure
+  secretStoreRef:
+    kind: SecretStore
+    name: example-secret-store               # name of the SecretStore (or kind specified)
+ 
+  target:
+    name: secret-to-be-created  # name of the k8s Secret to be created
+    creationPolicy: Owner
+  
+  data:
+  - secretKey: dev-secret-test  # name of the  key to be created in the secret object
+    remoteRef:
+      key: dev-secret-test #name of the SECRET in the Azure KV (no prefix => SECRET)
+
+  - secretKey: dev-another-secret-test  # name of the  key to be created in the secret object
+    remoteRef:
+      key: secret/dev-secret-test #type and name of secret in the Azure KV
+
+  - secretKey: dev-cert-test  # name of the  key to be created in the secret object
+    remoteRef:
+      key: cert/dev-cert-test #type/name of certificate in the Azure KV 
+                              #raw value will be returned , use templating features for data processing
+
+  - secretKey: dev-key-test  # name of the  key to be created in the secret object
+    remoteRef:
+      key: key/dev-key-test #type/name of the public key in the Azure KV 
+  
+  # dataFrom , return ALL secrets saved in the referenced secretStore 
+  # each secret name in the KV will be used as the secret key in the SECRET k8s target object
+  dataFrom: 
+  - name: "*"
\ No newline at end of file
diff --git a/docs/snippets/azkv-secret-store.yaml b/docs/snippets/azkv-secret-store.yaml
new file mode 100644
index 000000000..c0969aca1
--- /dev/null
+++ b/docs/snippets/azkv-secret-store.yaml
@@ -0,0 +1,16 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: example-secret-store
+spec:
+  azurekv:      #Provider type , azure keyvault
+    tenantid: "d3bc2180-xxxx-xxxx-xxxx-154105743342" #azure tenant ID
+    vaultUrl: "https://my-keyvault-name.vault.azure.net" #Keyvault URL
+    authSecretRef:
+      #Secret created in the cluster holding the azure service principal with proper access rights
+      clientID:
+        name: azure-secret-sp  
+        key: ClientID
+      clientSecret:
+        name: azure-secret-sp
+        key: ClientSecret