Skip to content

Commit

Permalink
docs/multiplexing: overhaul plugin documentation (#14509)
Browse files Browse the repository at this point in the history
* docs/multiplexing: overhaul plugin documentation

* update nav data

* remove dupe nav data

* add external plugin section to index

* move custom plugin backends under internals/plugins

* remove ref to moved page

* revert moving custom plugin backends

* add building plugins from source section to plug dev

* add mux section to plugin arch

* add mux section to custom plugin page

* reorder custom database page

* use 'external plugin' where appropriate

* add link to plugin multiplexing

* fix example serve multiplex func call

* address review comments

* address review comments

* Minor format updates (#14590)

* mv Plugins to top-level; update upgrading plugins

* update links after changing paths

* add section on external plugin scaling characteristics

* add updates on plugin registration in plugin management page

* add plugin learn resource

* be more explicit about mux upgrade steps; add notes on when to avoid db muxing

* add plugin upgrade built-in section

* add caveats to built-in plugin upgrade

* improvements to built-in plugin override

* formatting, add redirects, correct multiplexing use case

* fix go-plugin link

* Apply suggestions from code review

Co-authored-by: Loann Le <[email protected]>

* remove single item list; add link to Database interface

Co-authored-by: Yoko Hyakuna <[email protected]>
Co-authored-by: Loann Le <[email protected]>
  • Loading branch information
3 people committed Mar 22, 2022
1 parent c36513f commit 816980a
Show file tree
Hide file tree
Showing 16 changed files with 690 additions and 340 deletions.
2 changes: 1 addition & 1 deletion website/content/docs/auth/azure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ method as an external plugin. The azure plugin method is integrated into Vault a
a builtin method by default.

Assuming you have saved the binary `vault-plugin-auth-azure` to some folder and
configured the [plugin directory](/docs/internals/plugins#plugin-directory)
configured the [plugin directory](/docs/plugins/plugin-architecture#plugin-directory)
for your server at `path/to/plugins`:

1. Enable the plugin in the catalog:
Expand Down
2 changes: 1 addition & 1 deletion website/content/docs/configuration/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ to specify where the configuration is.

~> Note: Since each plugin runs as a separate process, you need to do the same
for each plugin in your [plugins
directory](/docs/internals/plugins#plugin-directory).
directory](/docs/plugins/plugin-architecture#plugin-directory).

If you use a Linux distribution with a modern version of systemd, you can add
the following directive to the "[Service]" configuration section:
Expand Down
2 changes: 1 addition & 1 deletion website/content/docs/internals/limits.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,7 @@ are a function of the alphabet size.

### External plugin limits

The [plugin system](/docs/internals/plugins) launches a separate process
The [plugin system](/docs/plugins) launches a separate process
initiated by Vault that communicates over RPC. For each secret engine and auth
method that's enabled as an external plugin, Vault will spawn a process on the
host system. For the Database Secrets Engines, external database plugins will
Expand Down
236 changes: 0 additions & 236 deletions website/content/docs/internals/plugins.mdx

This file was deleted.

2 changes: 1 addition & 1 deletion website/content/docs/partnerships.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ This program is intended to be largely a self-service process with links and gui

Vault is an Identity-based security solution that leverages trusted sources of identity to keep secrets and application data secured with one centralized, audited workflow for tightly controlling access to secrets across applications, systems, and infrastructure while encrypting data both in flight and at rest. For a full description of the current features please refer to the Vault [website](/).

Vault has a secure [plugin](/docs/internals/plugins) architecture. Vault’s plugins are completely separate, standalone applications that Vault executes and communicates with over RPC. This means the plugin process does not share the same memory space as Vault and therefore can only access the interfaces and arguments given to it.
Vault has a secure [plugin](/docs/plugins) architecture. Vault’s plugins are completely separate, standalone applications that Vault executes and communicates with over RPC. This means the plugin process does not share the same memory space as Vault and therefore can only access the interfaces and arguments given to it.

Vault plugins can be built-in and bundled with the Vault binary, or be external that has to be manually mounted. Built-in plugins are developed by HashiCorp, while external plugins can be developed by HashiCorp, technology partners, or the community. There is a curated collection of all plugins, both built-in and external, located on the [Plugin Portal](/docs/plugin-portal).

Expand Down
54 changes: 0 additions & 54 deletions website/content/docs/plugin.mdx

This file was deleted.

39 changes: 39 additions & 0 deletions website/content/docs/plugins/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
layout: docs
page_title: Plugin System
description: Learn about Vault's plugin system.
---


# Plugin System

All Vault auth methods and secrets engines are considered plugins. This simple concept
allows both built-in and external plugins to be treated like Legos. Any plugin
can exist at multiple different locations. Different versions of a plugin may
be at each location, with each version differing from Vault's version.

## Built-In Plugins

Built-in plugins are shipped with Vault, often for commonly used implementations,
and require no additional operator intervention to run. Built-in plugins are
just like any other backend code inside Vault.

To use a different or edited version of a built-in plugin, the plugin must be
run as an external plugin. See [Overriding Built-in Plugins](/docs/upgrading/plugins#overriding-built-in-plugins)
for details on how to override a built-in plugin in-place.

## External Plugins

External plugins are not shipped with Vault and require additional operator
intervention to run.

To run an external plugin, a binary of the plugin is required. Plugin
binaries can be obtained from [releases.hashicorp.com](https://releases.hashicorp.com/)
or they can be [built from source](/docs/plugins/plugin-development#building-a-plugin-from-source).

Vault's external plugins are completely separate, standalone applications that
Vault executes and communicates with over RPC. Each time a Vault secret engine
or auth method is mounted, a new process is spawned. However, database plugins
can be made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
which allows a single plugin process to be used for multiple database
connections.
Loading

0 comments on commit 816980a

Please sign in to comment.