Skip to content
This repository has been archived by the owner on Jan 11, 2023. It is now read-only.

Commit

Permalink
Improved docs and added missing fields from #2523 (#2524)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jackfrancis
Michael Palumbo authored and jackfrancis committed Mar 26, 2018
1 parent cb5f7ae commit 5c7476b
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 35 deletions.
87 changes: 59 additions & 28 deletions examples/keyvault-params/README.md
View file
Expand Up @@ -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:

"<PARAMETER>": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<NAME>[/<VERSION>]"
* 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
{
"<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.
The keyvault ID format is *"/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>*
* `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/<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:

Expand All @@ -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
```
29 changes: 22 additions & 7 deletions examples/keyvault-params/kubernetes.json
View file
Expand Up @@ -43,13 +43,28 @@
}
},
"certificateProfile": {
"caCertificate": "<caCertificate>",
"apiServerCertificate": "/subscriptions/my-sub/resourceGroups/my-rg/providers/Microsoft.KeyVault/vaults/my-kv/secrets/my-secret1/ver1",
"apiServerPrivateKey": "<apiServerPrivateKey>",
"clientCertificate": "<clientCertificate>",
"clientPrivateKey": "<clientPrivateKey>",
"kubeConfigCertificate": "<kubeConfigCertificate>",
"kubeConfigPrivateKey": "<kubeConfigPrivateKey>"
"caCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CA_CRT_NAME>",
"caPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CA_KEY_NAME>",
"apiServerCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<APISERVER_CRT_NAME>",
"apiServerPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<APISERVER_KEYNAME>",
"clientCertificate": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CLIENT_CRT_NAME>",
"clientPrivateKey": "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.KeyVault/vaults/<KV_NAME>/secrets/<CLIENT_KEY_NAME>",
"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>"
]
}
}
}

0 comments on commit 5c7476b

Please sign in to comment.