Skip to content

Commit

Permalink
docs: clarify Vault CA provider permissions needed (#15478)
Browse files Browse the repository at this point in the history
  • Loading branch information
jkirschner-hashicorp authored Dec 3, 2022
1 parent 5efdd8b commit 66e28f3
Show file tree
Hide file tree
Showing 3 changed files with 212 additions and 127 deletions.
20 changes: 15 additions & 5 deletions website/content/api-docs/connect/ca.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,13 @@ The table below shows this endpoint's support for

The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config).

~> **If currently using Vault CA provider:**
If you intend to change the CA provider from Vault to another,
or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath),
you must temporarily elevate the privileges of the Vault token
or auth method in use as described in the
[Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations).

### JSON Request Body Schema

- `Provider` `(string: <required>)` - Specifies the CA provider type to use.
Expand All @@ -177,11 +184,14 @@ The corresponding CLI command is [`consul connect ca set-config`](/commands/conn
for the chosen provider. For more information on configuring the Connect CA
providers, see [Provider Config](/docs/connect/ca).

- `ForceWithoutCrossSigning` `(bool: <optional>)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support cross
signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without
Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
- `ForceWithoutCrossSigning` `(bool: false)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support root cross-signing.

~> **Caution:** Setting this field to `true` will cause temporary connection failures
until service mesh proxies and/or Consul client agents receive a new certificate
that establishes trust with the new root.
Do not use this field unless you are sure you need it.
Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
for more detail.

### Sample Payload
Expand Down
18 changes: 14 additions & 4 deletions website/content/commands/connect/ca.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -97,17 +97,27 @@ Configuration updated!

The return code will indicate success or failure.

~> **If currently using Vault CA provider:**
If you intend to change the CA provider from Vault to another,
or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath),
you must temporarily elevate the privileges of the Vault token
or auth method in use as described in the
[Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations).

#### Command Options

- `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration.
The format of this config file matches the request payload documented in the
[Update CA Configuration API](/api-docs/connect/ca#update-ca-configuration).

- `-force-without-cross-signing` `(bool: <optional>)` - Indicates that the CA change
should be forced to complete even if the current CA doesn't support cross
signing. Changing root without cross-signing may cause temporary connection
failures until the rollout completes. See [Forced Rotation Without
Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
should be forced to complete even if the current CA doesn't support root cross-signing.

~> **Caution:** Use of this flag will cause temporary connection failures
until service mesh proxies and/or Consul client agents receive a new certificate
that establishes trust with the new root.
Do not use this flag unless you are sure you need it.
Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing)
for more detail.

#### API Options
Expand Down
Loading

0 comments on commit 66e28f3

Please sign in to comment.