minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-31 18:04:52 +03:00
Code Activity

DOCS-580: Fixing reported issues with Vault tutorial (#591)

Browse Source 
@djwfyi cursory review in case I missed something.

Closes #580 

I do need to do further testing beyond the patches here. But I'm going
to handle that out-of-band.
This commit is contained in:
Ravind Kumar
2022-09-30 17:47:12 -04:00
committed by GitHub
parent ce1a843a62
commit d5d3243413
21 changed files with 61 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
source/extra/kes.service
View File

@ -8,11 +8,13 @@ AssertFileIsExecutable=/usr/local/bin/kes
[Service] [Service]
WorkingDirectory=/etc/kes/ WorkingDirectory=/etc/kes/
AmbientCapabilities=CAP_IPC_LOCK
User=kes User=kes
Group=kes Group=kes
ProtectProc=invisible ProtectProc=invisible
ExecStart=/usr/local/bin/kes server --config=/etc/kes/config.yaml ExecStart=/usr/local/bin/kes server --config=/opt/kes/config.yaml --mlock
# Let systemd restart this service always # Let systemd restart this service always
Restart=always Restart=always

6
source/includes/common/common-minio-kes-aws.rst
View File

@ -34,7 +34,7 @@ Manager:
- /v1/key/generate/* - /v1/key/generate/*
- /v1/key/decrypt/* - /v1/key/decrypt/*
identities: identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
# In production environments, each client connecting to KES must # In production environments, each client connecting to KES must
# Have their TLS hash listed under at least one `policy`. # Have their TLS hash listed under at least one `policy`.
@ -92,7 +92,7 @@ Manager:
- /v1/key/generate/* - /v1/key/generate/*
- /v1/key/decrypt/* - /v1/key/decrypt/*
identities: identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
# Specify the connection information for the KMS and Secrets Manager endpoint. # Specify the connection information for the KMS and Secrets Manager endpoint.
# The endpoint should be resolvable from the host. # The endpoint should be resolvable from the host.
@ -115,7 +115,7 @@ value. You can use this functionality to set credentials without writing them to
the configuration file. the configuration file.
- Set ``MINIO_IDENTITY_HASH`` to the output of - Set ``MINIO_IDENTITY_HASH`` to the output of
``kes tool identity of minio-kes.cert``. ``kes identity of minio-kes.cert``.
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``. The value **must** match for both ``endpoint`` and ``region``.

2
source/includes/common/common-minio-kes-azure.rst
View File

@ -35,7 +35,7 @@ Manager:
- /v1/key/generate/* - /v1/key/generate/*
- /v1/key/decrypt/* - /v1/key/decrypt/*
identities: identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
# Specify the connection information for the Key Vualt endpoint. # Specify the connection information for the Key Vualt endpoint.
# The endpoint should be resolvable from the host. # The endpoint should be resolvable from the host.

2
source/includes/common/common-minio-kes-gcp.rst
View File

@ -34,7 +34,7 @@ Manager:
- /v1/key/generate/* - /v1/key/generate/*
- /v1/key/decrypt/* - /v1/key/decrypt/*
identities: identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
# Specify the connection information for the Secrets Manager endpoint. # Specify the connection information for the Secrets Manager endpoint.
# The endpoint should be resolvable from the host. # The endpoint should be resolvable from the host.

9
source/includes/common/common-minio-kes-hashicorp.rst
View File

@ -9,9 +9,10 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
address: 0.0.0.0:7373 address: 0.0.0.0:7373
# Disable the root identity, as we do not need that level of access for # Disable the root administrator identity, as we do not need that level of access for
# supporting SSE operations. # supporting SSE operations.
root: disabled admin:
identity: disabled
# Specify the TLS keys generated in the previous step here # Specify the TLS keys generated in the previous step here
# For production environments, use keys signed by a known and trusted # For production environments, use keys signed by a known and trusted
@ -29,7 +30,7 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
- /v1/key/generate/* # e.g. '/minio-' - /v1/key/generate/* # e.g. '/minio-'
- /v1/key/decrypt/* - /v1/key/decrypt/*
identities: identities:
- ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes tool identity of minio-kes.cert' - ${MINIO_IDENTITY_HASH} # Replace with the output of 'kes identity of minio-kes.cert'
# In production environments, each client connecting to KES must # In production environments, each client connecting to KES must
# Have their TLS hash listed under at least one `policy`. # Have their TLS hash listed under at least one `policy`.
@ -40,6 +41,8 @@ The following YAML provides the minimum required fields for using Hashicorp Vaul
keystore: keystore:
vault: vault:
endpoint: https://HOSTNAME:8200 endpoint: https://HOSTNAME:8200
engine: "/path/to/engine" # Replace with the path to the K/V Engine
version: "v1|v2" # Specify v1 or v2 depending on the version of the K/V Engine
approle: approle:
id: "VAULTAPPID" # Hashicorp Vault AppRole ID id: "VAULTAPPID" # Hashicorp Vault AppRole ID
secret: "VAULTAPPSECRET" # Hashicorp Vault AppRole Secret ID secret: "VAULTAPPSECRET" # Hashicorp Vault AppRole Secret ID

9
source/includes/common/common-minio-kes.rst
View File

@ -48,13 +48,13 @@ The following commands create two TLS certificates that expire within 30 days of
# These commands output keys to |kescertpath| # These commands output keys to |kescertpath|
# and |miniocertpath| respectively # and |miniocertpath| respectively
kes tool identity new \ kes identity new \
--key |kescertpath|/kes-server.key \ --key |kescertpath|/kes-server.key \
--cert |kescertpath|/kes-server.cert \ --cert |kescertpath|/kes-server.cert \
--ip "127.0.0.1" \ --ip "127.0.0.1" \
--dns localhost --dns localhost
kes tool identity new \ kes identity new \
--key |miniocertpath|/minio-kes.key \ --key |miniocertpath|/minio-kes.key \
--cert |miniocertpath|/minio-kes.cert \ --cert |miniocertpath|/minio-kes.cert \
--ip "127.0.0.1" \ --ip "127.0.0.1" \
@ -85,6 +85,7 @@ Run the following commands in a terminal or shell to start the KES server as a f
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
:substitutions:
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes)) sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
@ -223,7 +224,7 @@ Defaults to port ``7373`` on all host network interfaces.
.. start-kes-conf-root-desc .. start-kes-conf-root-desc
The identity for the KES superuser (``root``) identity. The identity for the KES superuser (``root``) identity.
Clients connecting with a TLS certificate whose hash (``kes tool identity of client.cert``) matches this value have access to all KES API operations. Clients connecting with a TLS certificate whose hash (``kes identity of client.cert``) matches this value have access to all KES API operations.
Specify ``disabled`` to remove the root identity and rely only on the ``policy`` configuration for controlling identity and access management to KES. Specify ``disabled`` to remove the root identity and rely only on the ``policy`` configuration for controlling identity and access management to KES.
@ -256,7 +257,7 @@ the ``minio-sse-`` prefix.
|KES| uses mTLS to authorize connecting clients by comparing the |KES| uses mTLS to authorize connecting clients by comparing the
hash of the TLS certificate against the ``identities`` of each configured hash of the TLS certificate against the ``identities`` of each configured
policy. Use the ``kes tool identity of`` command to compute the identity of the policy. Use the ``kes identity of`` command to compute the identity of the
MinIO mTLS certificate and add it to the ``policy.<NAME>.identities`` array MinIO mTLS certificate and add it to the ``policy.<NAME>.identities`` array
to associate MinIO to the ``<NAME>`` policy. to associate MinIO to the ``<NAME>`` policy.

17
source/includes/linux/common-minio-kes.rst
View File

@ -31,7 +31,7 @@ Create the ``/etc/systemd/system/kes.service`` file on all KES hosts:
You may need to run ``systemctl daemon-reload`` to load the new service file into ``systemctl``. You may need to run ``systemctl daemon-reload`` to load the new service file into ``systemctl``.
The ``kes.service`` file runs as the ``kes-user`` User and Group by default. The ``kes.service`` file runs as the ``kes`` User and Group by default.
You can create the user and group using the ``useradd`` and ``groupadd`` commands. You can create the user and group using the ``useradd`` and ``groupadd`` commands.
The following example creates the user and group. The following example creates the user and group.
These commands typically require root (``sudo``) permissions. These commands typically require root (``sudo``) permissions.
@ -39,17 +39,16 @@ These commands typically require root (``sudo``) permissions.
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
groupadd -r kes-user groupadd -r kes
useradd -M -r -g kes-user kes-user useradd -M -r -g kes kes
The ``kes-user`` user and group must have read access to all files used by the KES service: The ``kes`` user and group must have read access to all files used by the KES service:
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
:substitutions: :substitutions:
chown -R kes-user:kes-user /opt/kes chown -R kes:kes /opt/kes
chown -R kes-user:kes-user /etc/kes
.. end-kes-service-file-desc .. end-kes-service-file-desc
@ -107,10 +106,10 @@ This procedure assumes a structure similar to the following:
-rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert -rw-r--r-- 1 minio-user:minio-user |miniocertpath|/kes-server.cert
# For the KES Hosts # For the KES Hosts
-rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.cert -rw-r--r-- 1 kes:kes |kescertpath|/kes-server.cert
-rw-r--r-- 1 kes-user:kes-user |kescertpath|/kes-server.key -rw-r--r-- 1 kes:kes |kescertpath|/kes-server.key
If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath|/certs directory such that each MinIO server can properly validate the KES certificates. If the KES certificates are self-signed *or* signed by Certificate Authority (CA) that is *not* globally trusted, you **must** add the CA certificate to the |miniocertpath| directory such that each MinIO server can properly validate the KES certificates.
.. end-kes-generate-kes-certs-prod-desc .. end-kes-generate-kes-certs-prod-desc

2
source/includes/linux/steps-configure-minio-kes-aws-quick.rst
View File

@ -52,7 +52,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``. The value **must** match for both ``endpoint`` and ``region``.

2
source/includes/linux/steps-configure-minio-kes-aws.rst
View File

@ -58,7 +58,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``. The value **must** match for both ``endpoint`` and ``region``.

2
source/includes/linux/steps-configure-minio-kes-azure-quick.rst
View File

@ -52,7 +52,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``endpoint`` with the URL for the Keyvault instance. - Replace the ``endpoint`` with the URL for the Keyvault instance.

2
source/includes/linux/steps-configure-minio-kes-azure.rst
View File

@ -58,7 +58,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``endpoint`` with the URL for the Keyvault instance. - Replace the ``endpoint`` with the URL for the Keyvault instance.

2
source/includes/linux/steps-configure-minio-kes-gcp-quick.rst
View File

@ -52,7 +52,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use.

2
source/includes/linux/steps-configure-minio-kes-gcp.rst
View File

@ -58,7 +58,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use.

4
source/includes/linux/steps-configure-minio-kes-hashicorp-quick.rst
View File

@ -56,10 +56,10 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s). - Replace the ``vault.endpoint`` with the hostname of the Vault server(s).
- Set the ``vault.engine`` and ``vault.version`` to the appropriate values for the Vault K/V Engine configuration
- Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`. - Replace the ``VAULTAPPID`` and ``VAULTAPPSECRET`` with the appropriate :ref:`Vault AppRole credentials <minio-sse-vault-prereq-vault>`.
b. Create the MinIO Environment File b. Create the MinIO Environment File

4
source/includes/linux/steps-configure-minio-kes-hashicorp.rst
View File

@ -48,7 +48,7 @@ a. Create the KES Configuration File
.. code-block:: shell .. code-block:: shell
:substitutions: :substitutions:
nano /etc/kes/config.yaml nano /opt/kes/config.yaml
.. include:: /includes/common/common-minio-kes-hashicorp.rst .. include:: /includes/common/common-minio-kes-hashicorp.rst
:start-after: start-kes-configuration-hashicorp-vault-desc :start-after: start-kes-configuration-hashicorp-vault-desc
@ -62,7 +62,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s). - Replace the ``vault.endpoint`` with the hostname of the Vault server(s).

2
source/includes/macos/steps-configure-minio-kes-aws.rst
View File

@ -50,7 +50,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``REGION`` with the appropriate region for AWS Secrets Manager. - Replace the ``REGION`` with the appropriate region for AWS Secrets Manager.
The value **must** match for both ``endpoint`` and ``region``. The value **must** match for both ``endpoint`` and ``region``.

2
source/includes/macos/steps-configure-minio-kes-azure.rst
View File

@ -50,7 +50,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``endpoint`` with the URL for the Keyvault instance. - Replace the ``endpoint`` with the URL for the Keyvault instance.

2
source/includes/macos/steps-configure-minio-kes-gcp.rst
View File

@ -50,7 +50,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use. - Set ``GCPPROJECTID`` to the GCP project for the Secrets Manager instance KES should use.

2
source/includes/macos/steps-configure-minio-kes-hashicorp.rst
View File

@ -53,7 +53,7 @@ a. Create the KES Configuration File
:class: copyable :class: copyable
:substitutions: :substitutions:
kes tool identity of |miniocertpath|/minio-kes.cert kes identity of |miniocertpath|/minio-kes.cert
- Replace the ``vault.endpoint`` with the hostname of the Vault server(s). - Replace the ``vault.endpoint`` with the hostname of the Vault server(s).

32
source/includes/windows/common-minio-kes.rst
View File

@ -22,16 +22,16 @@ The following commands creates two TLS certificates that expire within 30 days o
# These commands output the certificates to |kescertpath| # These commands output the certificates to |kescertpath|
C:\kes.exe tool identity new \ C:\kes.exe identity new \
--key |kescertpath| \ kes-server.key \ --key |kescertpath|\kes-server.key \
--cert |kescertpath| \ kes-server.cert \ --cert |kescertpath|\kes-server.cert \
--ip "127.0.0.1" \ --ip "127.0.0.1" \
--dns localhost --dns localhost
C:\kes.exe tool identity new \ C:\kes.exe identity new \
--key |miniocertpath| \ minio-kes.key \ --key |miniocertpath|\minio-kes.key \
--cert |miniocertpath| \ minio-kes.cert \ --cert |miniocertpath|\minio-kes.cert \
--ip "127.0.0.1" \ --ip "127.0.0.1" \
--dns localhost --dns localhost
The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate. The ``--ip`` and ``--dns`` parameters set the IP and DNS ``SubjectAlternativeName`` for the certificate.
@ -66,7 +66,7 @@ Run the following command in a terminal or shell to start the KES server as a fo
:class: copyable :class: copyable
:substitutions: :substitutions:
C:\kes.exe server --auth --config=|kesconfigpath| \ config \ kes-config.yaml C:\kes.exe server --auth --config=|kesconfigpath|\config\kes-config.yaml
Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background. Defer to the documentation for your MacOS Operating System version for instructions on running a process in the background.
@ -80,8 +80,8 @@ Run the following command in a terminal or shell to start the MinIO server as a
:class: copyable :class: copyable
:substitutions: :substitutions:
export MINIO_CONFIG_ENV_FILE=|minioconfigpath| \ config \ minio export MINIO_CONFIG_ENV_FILE=|minioconfigpath|\config\minio
C: \ minio.exe server --console-address :9090 C:\minio.exe server --console-address :9090
.. end-kes-minio-start-server-desc .. end-kes-minio-start-server-desc
@ -97,8 +97,8 @@ The following command uses the ``kes key create`` command to create a new Extern
:substitutions: :substitutions:
export KES_SERVER=https://127.0.0.1:7373 export KES_SERVER=https://127.0.0.1:7373
export KES_CLIENT_KEY=|miniocertpath| \ minio-kes.key export KES_CLIENT_KEY=|miniocertpath|\minio-kes.key
export KES_CLIENT_CERT=|miniocertpath| \ minio-kes.cert export KES_CLIENT_CERT=|miniocertpath|\minio-kes.cert
C:\kes.exe key create -k encrypted-bucket-key C:\kes.exe key create -k encrypted-bucket-key
@ -129,9 +129,9 @@ This command assumes the ``minio-kes.cert``, ``minio-kes.key``, and ``kes-server
# Add these environment variables to the existing environment file # Add these environment variables to the existing environment file
MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373 MINIO_KMS_KES_ENDPOINT=https://127.0.0.1:7373
MINIO_KMS_KES_CERT_FILE=|miniocertpath| \ minio-kes.cert MINIO_KMS_KES_CERT_FILE=|miniocertpath|\minio-kes.cert
MINIO_KMS_KES_KEY_FILE=|miniocertpath| \ minio-kes.key MINIO_KMS_KES_KEY_FILE=|miniocertpath|\minio-kes.key
MINIO_KMS_KES_CAPATH=|miniocertpath| \ kes-server.cert MINIO_KMS_KES_CAPATH=|miniocertpath|\kes-server.cert
MINIO_KMS_KES_KEY_NAME=minio-backend-default-key MINIO_KMS_KES_KEY_NAME=minio-backend-default-key
minio.exe server [ARGUMENTS] minio.exe server [ARGUMENTS]

4
source/operations/server-side-encryption/configure-minio-kes-hashicorp.rst
View File

@ -155,15 +155,18 @@ Select the corresponding tab to the engine used by your Vault deployment for ins
path "kv/data/*" { path "kv/data/*" {
capabilities = [ "create", "read"] capabilities = [ "create", "read"]
}
path "kv/metadata/*" { path "kv/metadata/*" {
capabilities = [ "list", "delete"] capabilities = [ "list", "delete"]
}
Write the policy to Vault using ``vault policy write kes-policy kes-policy.hcl`` Write the policy to Vault using ``vault policy write kes-policy kes-policy.hcl``
MinIO requires using AppRole authentication for secure communication with the Vault server. MinIO requires using AppRole authentication for secure communication with the Vault server.
The following commands: The following commands:
- Enable AppRole Authentication
- Create an App Role ID for |KES| - Create an App Role ID for |KES|
- Binds that role to the created KES policy - Binds that role to the created KES policy
- Requests a RoleID and SecretID - Requests a RoleID and SecretID
@ -171,6 +174,7 @@ The following commands:
.. code-block:: shell .. code-block:: shell
:class: copyable :class: copyable
vault auth enable approle
vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m vault write auth/approle/role/kes-role token_num_uses=0 secret_id_num_uses=0 period=5m
vault write auth/approle/role/kes-role policies=kes-policy vault write auth/approle/role/kes-role policies=kes-policy
vault read auth/approle/role/kes-role/role-id vault read auth/approle/role/kes-role/role-id