From 5c7476bda03e5c9987bc859a7d2328a98eabec6a Mon Sep 17 00:00:00 2001 From: Michael Palumbo Date: Mon, 26 Mar 2018 14:09:13 -0400 Subject: [PATCH] Improved docs and added missing fields from #2523 (#2524) --- examples/keyvault-params/README.md | 87 ++++++++++++++++-------- examples/keyvault-params/kubernetes.json | 29 ++++++-- 2 files changed, 81 insertions(+), 35 deletions(-) diff --git a/examples/keyvault-params/README.md b/examples/keyvault-params/README.md index 7b03ee5180..ca04eed304 100644 --- a/examples/keyvault-params/README.md +++ b/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 -* apiServerPrivateKey -* caCertificate -* clientCertificate -* clientPrivateKey -* kubeConfigCertificate -* kubeConfigPrivateKey -* etcdServerCertificate -* etcdServerPrivateKey -* etcdClientCertificate -* etcdClientPrivateKey -* etcdPeerCertificates -* etcdPeerPrivateKeys -* servicePrincipal secret (a special case) - -The parameters above could still be set as plain text. - -To refer to a keyvault secret, the value of the parameter in the api model file should be formatted as: - - "": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/[/]" +* certificateProfile + * apiServerCertificate + * apiServerPrivateKey + * caCertificate + * caPrivateKey + * clientCertificate + * clientPrivateKey + * kubeConfigCertificate + * kubeConfigPrivateKey + * etcdServerCertificate + * etcdServerPrivateKey + * etcdClientCertificate + * etcdClientPrivateKey + * etcdPeerCertificates (length of array depends on number of master nodes) + * etcdPeerPrivateKeys (length of array depends on number of master nodes) +* servicePrincipalProfile* (a special case) + +## Certificate Profile + +For parameters referenced in the `properties.certificateProfile` section of the api model file, the value of each field should be formatted as: + +```json +{ + "": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/[/]" +} +``` + 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. -The keyvault ID format is *"/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults/* +* `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) + +## 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`. -The example **kubernetes.json** shows you how to refer deployment parameter to a secret in a keyvault. +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//resourceGroups//providers/Microsoft.KeyVault/vaults/", + "secretName": "", + "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 ``` diff --git a/examples/keyvault-params/kubernetes.json b/examples/keyvault-params/kubernetes.json index 7f3588397d..42f8d268d4 100644 --- a/examples/keyvault-params/kubernetes.json +++ b/examples/keyvault-params/kubernetes.json @@ -43,13 +43,28 @@ } }, "certificateProfile": { - "caCertificate": "", - "apiServerCertificate": "/subscriptions/my-sub/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/my-kv/secrets/my-secret1/ver1", - "apiServerPrivateKey": "", - "clientCertificate": "", - "clientPrivateKey": "", - "kubeConfigCertificate": "", - "kubeConfigPrivateKey": "" + "caCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "caPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "apiServerCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "apiServerPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "clientCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "clientPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "kubeConfigCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "kubeConfigPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "etcdServerCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "etcdServerPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "etcdClientCertificate": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "etcdClientPrivateKey": "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "etcdPeerCertificates": [ + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/" + ], + "etcdPeerPrivateKeys": [ + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/", + "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults//secrets/" + ] } } } \ No newline at end of file