Incorrect documentation on custom database plugins

[akamensky]

Describe the bug /me attempt to write a plugin for handling temporary users in database using https://www.vaultproject.io/docs/secrets/databases/custom as a guide. /me discover that

1. github.com/hashicorp/vault/api/plugins package does not exist, instead seemingly same types and functions are available in github.com/hashicorp/vault/api
2. github.com/hashicorp/vault/sdk/database/v5 does not have method Serve(Database, TLSConfig) method, only Serve(Database) exists
3. Using v5 with 1.7.3, but without TLSConfig (because of point numero 2), results in:

   Code: 400
   Errors:
   error creating database object: invalid database version: 2 errors occurred:
   * error getting plugin type: unable to get database plugin type: rpc error: code = Unavailable desc = transport is closing
   * Incompatible API version with plugin. Plugin version: 5, Client versions: [3 4]

4. In code comments are saying that methods are not critical, however that is incorrect, having stub methods is the cause of point number 3, and only actually implementing them resolves this (so incorrect/misleading code comments).

To Reproduce Steps to reproduce the behavior:

1. Try implementing a custom database plugin using only available documentation.
2. ...
3. Profit

Expected behavior Up-to-date documentation that references actual existing packages. Preferably with some example code. Also explanations on the use of arguments and return values. I.e. ctx argument is present in pretty much all of Database methods, but there is no documentation on what kind of context object can be expected. Is it timed, or is it cancellable? What is the use for context in context of plugin?

Environment:

• Vault Server Version (retrieve with vault status): 1.7.3
• Vault CLI Version (retrieve with vault version): N/A
• Server Operating System/Architecture: Docker official image

Vault server configuration file(s):

{
  "plugin_directory" : "/vault/plugins"
}

Additional context SDK/API are maybe bug free, but documentation needs to be up-to-date else how can anyone really use it?

[akamensky]

Also, while v5 seemingly works, how ffs do I log from there? I cannot find anywhere in documentation how to make log entries from plugin to main app logs...

[heatherezell]

@taoism4504 Maybe we can work with @digivava on sorting this out?