Add upgrade and config docs for MSSQL EKM Provider (#13859)
This commit is contained in:
Tom Proctor
GitHub
parent
999503c0b5
commit
cf3e245302
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Configure the Vault EKM Provider
|
||||
description: Configuration options for the Vault EKM Provider for Microsoft SQL Server.
|
||||
---
|
||||
|
||||
# Configuring the Vault EKM Provider
|
||||
|
||||
Configuration is stored in a `config.json` file under ProgramData in a path that
|
||||
mirrors the installation folder. This defaults to
|
||||
`C:\ProgramData\HashiCorp\Transit Vault EKM Provider\config.json`.
|
||||
|
||||
-> **Note:** If the Vault EKM Provider has already been installed, Microsoft
|
||||
SQL Server needs to be restarted for configuration changes to take effect.
|
||||
|
||||
The following options are supported:
|
||||
|
||||
- `vaultApiBaseUrl` `(string: required)` - Address of Vault server, e.g.
|
||||
`https://vault.example.com:8200`
|
||||
- `enableTrace` `(bool: false)` - Enable trace logging. Logs are viewable from
|
||||
the event viewer. See [troubleshooting](/docs/platform/mssql/troubleshooting)
|
||||
for further details.
|
||||
- `namespace` `(string: "")` - Set the Vault namespace to use. Applies to both
|
||||
AppRole and Transit.
|
||||
- `appRoleMountPath` `(string: "approle")` - Use this to specify the path to the
|
||||
AppRole auth mount if it was set to a non-default path.
|
||||
- `transitMountPath` `(string: "transit")` - Use this to specify the path to the
|
||||
Transit mount if it was set to a non-default path.
|
||||
|
|
@ -20,8 +20,8 @@ Keys (KEK) managed by Vault's [Transit][transit] secret engine using SQL Server'
|
|||
[transit]: https://www.vaultproject.io/docs/secrets/transit
|
||||
|
||||
|
||||
See [installation](/docs/platform/mssql/installation) for help getting started
|
||||
with the Vault EKM provider for SQL Server.
|
||||
See [installation](/docs/platform/mssql/installation) and [configuration](/docs/platform/mssql/configuration)
|
||||
for help getting started with the Vault EKM provider for SQL Server.
|
||||
|
||||
## Features
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,14 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Install Vault EKM Provider
|
||||
page_title: Install the Vault EKM Provider
|
||||
description: Installation steps for the Vault EKM Provider for Microsoft SQL Server.
|
||||
---
|
||||
|
||||
# Installing the Vault EKM Provider
|
||||
|
||||
This guide assumes you are installing the Vault EKM Provider for the first time.
|
||||
For upgrade instructions, see [upgrading](/docs/platform/mssql/upgrading).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Vault Enterprise server 1.9+ with a license for the Advanced Data Protection Key Management module
|
||||
|
|
@ -31,9 +34,6 @@ The EKM provider requires AppRole auth and the Transit secret engine to be setup
|
|||
on the Vault server. The steps below can be used to configure Vault ready for the
|
||||
EKM provider to use it.
|
||||
|
||||
-> **Note:** The first release of the Vault EKM provider does not support custom
|
||||
mount paths or namespaces for the AppRole and Transit engines.
|
||||
|
||||
-> **Note:** rsa-2048 is currently the only supported key type.
|
||||
|
||||
1. Set up AppRole auth:
|
||||
|
|
@ -95,8 +95,9 @@ The remaining steps are all run on the database server.
|
|||
|
||||
1. Download and run the latest Vault EKM provider installer from
|
||||
[releases.hashicorp.com](https://releases.hashicorp.com/vault-mssql-ekm-provider/)
|
||||
|
||||
1. Enter your Vault server's address when prompted and complete the installer
|
||||
1. If you need to configure non-default namespace or mount paths for your AppRole and
|
||||
Transit engines, see [configuration](/docs/platform/mssql/configuration).
|
||||
|
||||
### Configure the EKM provider using SQL
|
||||
|
||||
|
|
@ -201,7 +202,7 @@ installation.
|
|||
```sql
|
||||
SELECT * FROM sys.dm_database_encryption_keys;
|
||||
|
||||
SELECT (SELECT name FROM sys.databases WHERE database_id = k.database_id) as name,
|
||||
SELECT (SELECT name FROM sys.databases WHERE database_id = k.database_id) as name,
|
||||
encryption_state, key_algorithm, key_length,
|
||||
encryptor_type, encryption_state_desc, encryption_scan_state_desc FROM sys.dm_database_encryption_keys k;
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Troubleshoot Vault EKM Provider
|
||||
page_title: Troubleshoot the Vault EKM Provider
|
||||
description: Troubleshooting steps for the Vault EKM Provider for Microsoft SQL Server.
|
||||
---
|
||||
|
||||
# Trobuleshooting the Vault EKM Provider
|
||||
# Troubleshooting the Vault EKM Provider
|
||||
|
||||
## Check Windows Event Logs
|
||||
|
||||
|
|
@ -14,17 +14,7 @@ Logs from the Vault EKM provider will appear in Windows Event Viewer under
|
|||
### Enable trace logging
|
||||
|
||||
If the logs in the Event Viewer don't give enough information to help debug
|
||||
your issue, you can enable trace logging. Find the provider's config file at
|
||||
`config.json` in your install location, which defaults to
|
||||
`C:\Program Files\HashiCorp\Transit Vault EKM Provider\`. Set `enableTrace` to
|
||||
true, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"vaultApiBaseUrl": "http://vault.example.com:8200",
|
||||
"enableTrace": true
|
||||
}
|
||||
```
|
||||
your issue, you can [enable trace logging](/docs/platform/mssql/configuration#enabletrace).
|
||||
|
||||
Restart SQL Server for the config change to take effect, and you should see more
|
||||
detailed logs in the same section of Windows Event Viewer.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Upgrade the Vault EKM Provider
|
||||
description: Upgrade steps for the Vault EKM Provider for Microsoft SQL Server.
|
||||
---
|
||||
|
||||
# Upgrading the Vault EKM Provider
|
||||
|
||||
~> **Note:** The upgrade process will put the database into maintenance mode and
|
||||
require a restart. It is highly recommended to test this procedure in a
|
||||
staging environment prior to running it on a production database.
|
||||
|
||||
1. Disable the Vault EKM Provider, and verify it is marked disabled:
|
||||
|
||||
```sql
|
||||
ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider DISABLE;
|
||||
SELECT * FROM sys.cryptographic_providers;
|
||||
```
|
||||
|
||||
1. Install the latest version from [releases.hashicorp.com][releases], following
|
||||
the instructions in the installer.
|
||||
1. If you get a "Files in Use" prompt while running the installer, select
|
||||
"Do not close applications. A reboot will be required", and restart
|
||||
after the installation has completed.
|
||||
1. Reload the provider DLL:
|
||||
|
||||
```sql
|
||||
ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider
|
||||
FROM FILE = 'C:\Program Files\HashiCorp\Transit Vault EKM Provider\TransitVaultEKM.dll';
|
||||
```
|
||||
|
||||
1. Now re-enable the Vault EKM Provider and verify it is both marked enabled
|
||||
and the version reported matches the version of the installer:
|
||||
|
||||
```sql
|
||||
ALTER CRYPTOGRAPHIC PROVIDER TransitVaultProvider ENABLE;
|
||||
SELECT * FROM sys.cryptographic_providers;
|
||||
```
|
||||
|
||||
1. Finally, restart Microsoft SQL Server.
|
||||
|
||||
[releases]: https://releases.hashicorp.com/vault-mssql-ekm-provider/
|
||||
|
|
@ -1539,6 +1539,14 @@
|
|||
"title": "Installation",
|
||||
"path": "platform/mssql/installation"
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"path": "platform/mssql/configuration"
|
||||
},
|
||||
{
|
||||
"title": "Upgrading",
|
||||
"path": "platform/mssql/upgrading"
|
||||
},
|
||||
{
|
||||
"title": "Troubleshooting",
|
||||
"path": "platform/mssql/troubleshooting"
|
||||
|
|
|
|||
Loading…
Reference in New Issue