Improved docs and added missing fields from #2523 (#2524)

examples/keyvault-params/README.md

@@ -4,37 +4,66 @@
 
 ACS-Engine enables you to retrieve the following k8s deployment parameters from Microsoft Azure KeyVault:
 
-*	apiServerCertificate
+* certificateProfile
-*	apiServerPrivateKey
+  * apiServerCertificate
-*	caCertificate
+  * apiServerPrivateKey
-*	clientCertificate
+  * caCertificate
-*	clientPrivateKey
+  * caPrivateKey
-*	kubeConfigCertificate
+  * clientCertificate
-*	kubeConfigPrivateKey
+  * clientPrivateKey
-* etcdServerCertificate
+  * kubeConfigCertificate
-* etcdServerPrivateKey
+  * kubeConfigPrivateKey
-* etcdClientCertificate
+  * etcdServerCertificate
-* etcdClientPrivateKey
+  * etcdServerPrivateKey
-* etcdPeerCertificates
+  * etcdClientCertificate
-* etcdPeerPrivateKeys
+  * etcdClientPrivateKey
-*	servicePrincipal secret (a special case)
+  * etcdPeerCertificates (length of array depends on number of master nodes)
+  * etcdPeerPrivateKeys (length of array depends on number of master nodes)
+* servicePrincipalProfile* (a special case)
 
-The parameters above could still be set as plain text.
+## Certificate Profile
 
-To refer to a keyvault secret, the value of the parameter in the api model file should be formatted as:
+For parameters referenced in the `properties.certificateProfile` section of the api model file, the value of each field should be formatted as:
+
+```json
+{
+  "<PARAMETER>": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<NAME>[/<VERSION>]"
+}
+```
 
-	"<PARAMETER>": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<NAME>[/<VERSION>]"
 where:
-- **SUB_ID** is the subscription ID of the keyvault
-- **RG_NAME** is the resource group of the keyvault
-- **KV_NAME** is the name of the keyvault
-- **NAME** is the name of the secret in the keyvault
-- **VERSION** (optional) is the version of the secret (default: the latest version)
 
-The treatment of servicePrincipal secret is slightly different. As a plain text, the secret is set in *servicePrincipalProfile.secret*. Alternatively, as a keyvault reference, the secret is set in *servicePrincipalProfile.keyvaultSecretRef*, which separates kevault ID, secret name, and optionally the version.
+* `SUB_ID` - is the subscription ID of the keyvault
-The keyvault ID format is *"/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>*
+* `RG_NAME` - is the resource group of the keyvault
+* `KV_NAME` - is the name of the keyvault
+* `NAME` - is the name of the secret in the keyvault
+* `VERSION` (optional) - is the version of the secret (default: the latest version)
 
-The example **kubernetes.json** shows you how to refer deployment parameter to a secret in a keyvault.
+## Service Principal Profile
+
+For the service principal profile secret, the keyvault is referenced differently. If embedding the secret as plain text, the secret is set in `properties.servicePrincipalProfile.secret`.
+
+If the secret is stored in a keyvault, it can be referenced as follows:
+
+```json
+{
+  "servicePrincipalProfile": {
+    "clientId": "97ffd212-b56b-430a-97bd-9d15cc01ed43",
+      "secret": "",
+      "keyvaultSecretRef": {
+        "vaultID": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>",
+        "secretName": "<NAME>",
+        "version": "<VERSION>"
+    }
+  }
+}
+```
+
+The version field is optional.
+
+## Example
+
+The example `kubernetes.json` shows you how to refer deployment parameter to a secret in a keyvault.
 
 **Important** The secrets in the KeyVault for the Certificates and Private Keys must be Base64 encoded, and all on a single line -- this means you can't use the `--encoding base64` option of the Azure CLI. Instead you should use the `base64` command:
 
@@ -47,7 +76,9 @@ The example **kubernetes.json** shows you how to refer deployment parameter to a
 ```
 
 ## KeyVault Configuration
+
 To enable Azure Resource Manager to retrieve the secrets from the KeyVault, template deployment must be enabled on the KeyVault:
+
 ```sh
 az keyvault update -g $RG_NAME -n $KV_NAME --enabled-for-template-deployment
 ```

examples/keyvault-params/kubernetes.json

@@ -43,13 +43,28 @@
       }
     },
     "certificateProfile": {
-      "caCertificate": "<caCertificate>",
+      "caCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CA_CRT_NAME>",
-      "apiServerCertificate": "/subscriptions/my-sub/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/my-kv/secrets/my-secret1/ver1",
+      "caPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CA_KEY_NAME>",
-      "apiServerPrivateKey": "<apiServerPrivateKey>",
+      "apiServerCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<APISERVER_CRT_NAME>",
-      "clientCertificate": "<clientCertificate>",
+      "apiServerPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<APISERVER_KEYNAME>",
-      "clientPrivateKey": "<clientPrivateKey>",
+      "clientCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CLIENT_CRT_NAME>",
-      "kubeConfigCertificate": "<kubeConfigCertificate>",
+      "clientPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CLIENT_KEY_NAME>",
-      "kubeConfigPrivateKey": "<kubeConfigPrivateKey>"
+      "kubeConfigCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<KUBE_CRT_NAME>",
+      "kubeConfigPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<KUBE_KEY_NAME>",
+      "etcdServerCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDSERVER_CRT_NAME>",
+      "etcdServerPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDSERVER_KEY_NAME>",
+      "etcdClientCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDCLIENT_CRT_NAME>",
+      "etcdClientPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDCLIENT_KEY_NAME>",
+      "etcdPeerCertificates": [
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER0_CRT_NAME>",
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER1_CRT_NAME>",
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER2_CRT_NAME>"
+      ],
+      "etcdPeerPrivateKeys": [
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER0_KEY_NAME>",
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER1_KEY_NAME>",
+        "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<ETCDPEER2_KEY_NAME>"
+      ]
     }
   }
 }