Docs: Updated plugin versioning usage docs for pinned versions (#25607)

website/content/docs/commands/plugin/reload.mdx

@@ -62,7 +62,7 @@ flags](/vault/docs/commands) included on all commands.
   the plugin catalog.
 
 - `-type` `(string: "")` - The type of plugin to reload, one of auth, secret, or
-  database. Mutually exclusive with -mounts. If not provided, all plugins
+  database. Mutually exclusive with `-mounts`. If not provided, all plugins
   with a matching name will be reloaded.
 
 - `-mounts` `(array: [])` - Array or comma-separated string mount paths of the

website/content/docs/plugins/index.mdx

@@ -57,12 +57,19 @@ registering an external plugin. Multiple versions of a plugin can be registered
 in the catalog simultaneously, and a version can be selected when mounting a
 plugin or tuning an existing mount in-place.
 
+Alternatively, users can select pinned versions to enforce uniform cluster-wide
+version selection. When a pinned version is in effect, versions cannot be
+specified in mount config, and existing mounts that specify a version will
+ignore the locally configured version. See the
+[pinned versions](/vault/api-docs/system/plugins-pins) API for more details.
+
 If no version is specified when creating a new mount, the following precedence is used
 for any available plugins whose type and name match:
 
-* The plugin registered with no version
-* The plugin with the most recent semantic version among any registered versions
-* The plugin built into Vault
+1. The pinned version of the plugin, if any exists.
+1. The plugin registered with no version.
+1. The plugin with the most recent semantic version among any registered versions.
+1. The plugin built into Vault.
 
 ### Built-In versions
 

website/content/docs/upgrading/plugins.mdx

@@ -30,6 +30,7 @@ an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.
         -sha256=<SHA256 Hex value of the plugin binary> \
         secret \
         my-secret-plugin
+    Success! Registered plugin: my-secret-plugin
     ```
 
 1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
@@ -37,6 +38,7 @@ an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.
 
     ```shell-session
     $ vault secrets enable my-secret-plugin
+    Success! Enabled the my-secret-plugin secrets engine at: my-secret-plugin/
     ```
 
 1. Register a second version of your plugin. You **must** use the same plugin
@@ -50,39 +52,33 @@ an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.
         -version=v1.0.1 \
         secret \
         my-secret-plugin
+    Success! Registered plugin: my-secret-plugin
     ```
 
-1. Tune the existing mount to configure it to use the newly registered version.
+1. Set the new version as the cluster's pinned version.
 
    ```shell-session
-   $ vault secrets tune -plugin-version=v1.0.1 my-secret-plugin
+   $ vault write sys/plugins/pins/secret/my-secret-plugin version=v1.0.1
    ```
 
-1. If you wish, you can check the updated configuration. Notice the "Version" is
-   now different from the "Running Version".
+1. Trigger a global [plugin reload](/vault/docs/commands/plugin/reload) to
+   reload all instances of the plugin.
+
+    ```shell-session
+    $ vault plugin reload -type=secret -plugin=my-secret-plugin -scope=global
+    Success! Reloading plugin: my-secret-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
+    ```
+
+1. **Optional:** Check the "Running Version" field to verify the new version is
+    running:
 
     ```shell-session
     $ vault secrets list -detailed
     ```
 
-1. Finally, trigger a [plugin reload](/vault/docs/commands/plugin/reload) to reload all
-   mounted backends using that plugin or a subset of the mounts using that plugin
-   with either the `plugin` or `mounts` flag respectively.
-
-    ```shell-session
-    $ vault plugin reload -plugin my-secret-plugin
-    ```
-
-Until the last step, the mount will still run the first version of `my-secret-plugin`. When
+Until the reload step, the mount will still run the first version of `my-secret-plugin`. When
 the reload is triggered, Vault will kill `my-secret-plugin`’s process and start the
-new plugin process for `my-secret-plugin` version 1.0.1. The "Running Version" should also
-now match the "Version" when you run `vault secrets list -detailed`.
-
--> **Important:** Plugin reload of a new plugin binary must be
-performed on each Vault instance. Performing a plugin upgrade on a single
-instance or through a load balancer can result in mismatched
-plugin binaries within a cluster. On a replicated cluster this may be accomplished
-by setting the 'scope' parameter of the reload to 'global'.
+new plugin process for `my-secret-plugin` version 1.0.1.
 
 ### Upgrading database plugins
 
@@ -94,6 +90,7 @@ by setting the 'scope' parameter of the reload to 'global'.
         -sha256=<SHA256 Hex value of the plugin binary> \
         database \
         my-db-plugin
+    Success! Registered plugin: my-db-plugin
     ```
 
 1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
@@ -104,6 +101,7 @@ by setting the 'scope' parameter of the reload to 'global'.
     $ vault write database/config/my-db \
         plugin_name=my-db-plugin \
         # ...
+    Success! Data written to: database/config/my-db
     ```
 
 1. Register a second version of your plugin. You **must** use the same plugin
@@ -117,18 +115,30 @@ by setting the 'scope' parameter of the reload to 'global'.
         -version=v1.0.1 \
         database \
         my-db-plugin
+    Success! Registered plugin: my-db-plugin
     ```
 
-1. Update the database config with the new version. The database secrets
-   engine will immediately reload the plugin, using the new version. Any omitted
-   config parameters will not be updated.
+1. Set the new version as the cluster's pinned version.
 
     ```shell-session
-    $ vault write database/config/my-db \
-        plugin_version=v1.0.1
+    $ vault write sys/plugins/pins/database/my-db-plugin version=v1.0.1
     ```
 
-Until the last step, the mount will still run the first version of `my-db-plugin`. When
+1. Trigger a global [plugin reload](/vault/docs/commands/plugin/reload) to
+   reload all instances of the plugin.
+
+    ```shell-session
+    $ vault plugin reload -type=database -plugin=my-db-plugin -scope=global
+    Success! Reloading plugin: my-db-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
+    ```
+
+1. **Optional:** Verify the current version of the running plugin:
+
+    ```shell-session
+    $ vault read database/config/my-db
+    ```
+
+Until the reload step, the mount will still run the first version of `my-db-plugin`. When
 the reload is triggered, Vault will kill `my-db-plugin`’s process and start the
 new plugin process for `my-db-plugin` version 1.0.1.