Add latest changes from gitlab-org/gitlab@16-1-stable-eev16.1.0-rc42

3 files changed, 73 insertions, 7 deletions

diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md
index 1e887d8bd67..d54d286c19d 100644
--- a/doc/administration/operations/fast_ssh_key_lookup.md
+++ b/doc/administration/operations/fast_ssh_key_lookup.md
@@ -121,7 +121,8 @@ users as long as a large file exists.
 
 To disable writes to the `authorized_keys` file:
 
-1. On the top bar, select **Main menu > Admin**.
+1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
+1. Select **Admin Area**.
 1. On the left sidebar, select **Settings > Network**.
 1. Expand **Performance optimization**.
 1. Clear the **Use authorized_keys file to authenticate SSH keys** checkbox.
@@ -140,7 +141,8 @@ This overview is brief. Refer to the above instructions for more context.
 
 1. [Rebuild the `authorized_keys` file](../raketasks/maintenance.md#rebuild-authorized_keys-file).
 1. Enable writes to the `authorized_keys` file.
-   1. On the top bar, select **Main menu > Admin**.
+   1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
+   1. Select **Admin Area**.
    1. On the left sidebar, select **Settings > Network**.
    1. Expand **Performance optimization**.
    1. Select the **Use authorized_keys file to authenticate SSH keys** checkbox.
diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md
index 249d6232616..5c4af32fc3d 100644
--- a/doc/administration/operations/gitlab_sshd.md
+++ b/doc/administration/operations/gitlab_sshd.md
@@ -27,9 +27,8 @@ If you are considering switching from OpenSSH to `gitlab-sshd`, consider these c
 
 - `gitlab-sshd` supports the PROXY protocol. It can run behind proxy servers that rely
   on it, such as HAProxy. The PROXY protocol is not enabled by default, but [it can be enabled](#proxy-protocol-support).
-- `gitlab-sshd` **does not** support SSH certificates. For more details, see the
-  [confidential issue](../../user/project/issues/confidential_issues.md)
-  `https://gitlab.com/gitlab-org/gitlab-shell/-/issues/495`.
+- `gitlab-sshd` does not support SSH certificates. For discussion about adding them,
+  see [issue 655](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/655).
 
 ## Enable `gitlab-sshd`
 
diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md
index efc55a5fbc3..d7d6f6228f9 100644
--- a/doc/administration/operations/puma.md
+++ b/doc/administration/operations/puma.md
@@ -99,7 +99,7 @@ To change the worker timeout to 600 seconds:
 ## Disable Puma clustered mode in memory-constrained environments
 
 WARNING:
-This feature is an [Experiment](../../policy/alpha-beta-support.md#experiment) and subject to change without notice. The feature
+This feature is an [Experiment](../../policy/experiment-beta-support.md#experiment) and subject to change without notice. The feature
 is not ready for production use. If you want to use this feature, you should test
 outside of production first. See the [known issues](#puma-single-mode-known-issues)
 for additional details.
@@ -211,6 +211,71 @@ make Prometheus scrape them over HTTPS, and support for it is being discussed
 Hence, it is not technically possible to turn off this HTTP listener without
 losing Prometheus metrics.
 
+### Using an encrypted SSL key
+
+> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/7799) in GitLab 16.1.
+
+Puma supports the use of an encrypted private SSL key, which can be
+decrypted at runtime. The following instructions illustrate how to
+configure this:
+
+1. Encrypt the key with a password if it is not already:
+
+   ```shell
+   openssl rsa -aes256 -in /path/to/ssl-key.pem -out /path/to/encrypted-ssl-key.pem
+   ```
+
+   Enter in a password twice to write the encrypted file. In this
+   example, we use `some-password-here`.
+
+1. Create a script or executable that prints the password. For
+   example, create a basic script in
+   `/var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password` that echoes
+   the password:
+
+   ```shell
+   #!/bin/sh
+   echo some-password-here
+   ```
+
+   Note that in production, you should avoid storing the password on
+   disk and use a secure mechanism for retrieving a password, such as
+   Vault. For example, the script might look like:
+
+   ```shell
+   #!/bin/sh
+   export VAULT_ADDR=http://vault-password-distribution-point:8200
+   export VAULT_TOKEN=<some token>
+
+   echo "$(vault kv get -mount=secret puma-ssl-password)"
+   ```
+
+1. Ensure the Puma process has sufficient permissions to execute the
+   script and to read the encrypted key:
+
+   ```shell
+   chown git:git /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
+   chmod 770 /var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password
+   chmod 660 /path/to/encrypted-ssl-key.pem
+   ```
+
+1. Edit `/etc/gitlab/gitlab.rb`, and replace `puma['ssl_certificate_key']` with the encrypted key and specify
+   `puma['ssl_key_password_command]`:
+
+   ```ruby
+   puma['ssl_certificate_key'] = '/path/to/encrypted-ssl-key.pem'
+   puma['ssl_key_password_command'] = '/var/opt/gitlab/gitlab-rails/etc/puma-ssl-key-password'
+   ```
+
+1. Reconfigure GitLab:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
+1. If GitLab comes up successfully, you should be able to remove the
+   unencrypted SSL key that was stored on the GitLab instance.
+
 ## Switch from Unicorn to Puma
 
 NOTE:
@@ -333,7 +398,7 @@ gitlab_rails['env'] = {
 For source installations, set the environment variable.
 Refer to [Puma Worker timeout](../operations/puma.md#change-the-worker-timeout).
 
-[Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
+[Reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation) GitLab for the changes to take effect.
 
 #### Troubleshooting without affecting other users