etcd database plugin HTTP API

The etcd database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles against an etcd cluster's built-in v3 Auth API.

Configure connection

In addition to the parameters defined by the Database Secrets Engine, this plugin has a number of parameters to further configure a connection.

Method	Path
POST	/database/config/:name

Parameters

• endpoints (string: <required>) – Specifies a comma-separated list of etcd client URLs, e.g. https://etcd1.example:2379,https://etcd2.example:2379.

• username (string) – Specifies the root credential username OpenBao uses to log into the cluster and issue/revoke dynamic users. Required if authentication is enabled on the cluster.

• password (string) – Specifies the root credential password corresponding to username.

• dial_timeout (string: "5s") – Specifies a Go duration string for how long the client waits to establish a connection.

• use_tls (bool: false) – Specifies whether to use TLS when connecting to the cluster, even if no other TLS field is set.

• tls_ca (string) – Specifies the PEM-encoded CA certificate used to verify the cluster's certificate.

• tls_certificate (string) – Specifies the PEM-encoded client certificate for mutual TLS. Requires tls_key.

• tls_key (string) – Specifies the PEM-encoded client private key for mutual TLS. Requires tls_certificate.

• insecure (bool: false) – Disables TLS certificate verification. Not recommended for production use.

• username_template (string) - Template describing how dynamic usernames are generated.

Default Username Template

{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 10) (.RoleName | truncate 10) (random 15) (unix_time) | replace "." "-" | truncate 60 }}

Example Usernames:

Example
DisplayName	token
RoleName	myrolename
Username	v-token-myrolena-uszt1n4cyhal4-1614294836

Sample payload

{
  "plugin_name": "etcd-database-plugin",
  "allowed_roles": "reader",
  "endpoints": "https://etcd.example.com:2379",
  "username": "root",
  "password": "password"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/etcd

Statements

This plugin does not use semicolon-separated statement lists. creation_statements accepts a JSON role document containing pre-existing etcd role names, inline custom role definitions, or both. For more information on configuring database roles, see the Role API in the database secrets engine docs.

The following are the statements used by this plugin. If not mentioned in this list the plugin does not support that statement type.

• creation_statements (string: <required>) – Specifies a JSON document describing the etcd roles to grant the new user:

  {
    "roles": ["reader"],
    "custom_roles": [
      {
        "name": "app_writer",
        "permissions": [
          {
            "permission": "readwrite",
            "key": "/app/",
            "prefix": true
          },
          {
            "permission": "read",
            "key": "/config/sample"
          }
        ]
      }
    ]
  }

  The document supports these fields:

  • roles (array<string>) – Names of pre-existing etcd roles. Every role in this array must already exist on the cluster.
  • custom_roles (array<object>) – Inline roles that the plugin creates if necessary before issuing the credential. Each role has a required name and a permissions array. A permission contains permission (read, write, or readwrite) and key. By default, the permission applies to that exact key; set prefix: true for a prefix or provide range_end for an explicit key range.

  The plugin grants every role from both fields to the new user. Custom-role management is additive-only: the plugin creates a missing role and grants or updates each listed permission, but it does not revoke permissions omitted from a later creation_statements value and does not delete custom roles. Changing a permission's key or range adds the new permission without removing the old range. To narrow access, revoke the obsolete permissions directly in etcd or create a new, uniquely named role and retire the old role after its active credentials have been revoked. Avoid sharing a custom-role name across OpenBao roles unless the accumulated permissions are intentional.

  Custom roles are preserved when a dynamic user is revoked because other active users may still reference them. If granting a role to the user fails, the plugin calls UserDelete before returning the error, so no half-configured user is left behind. There is no built-in default; a role without creation_statements fails to issue credentials.

revocation_statements, rollback_statements, and root_rotation_statements are accepted by the database secrets engine framework but are not used by this plugin. Revocation always calls UserDelete, which is treated as success if the user has already been removed. Password rotation, for both root credentials and static roles, always calls UserChangePassword.

Root credential rotation

$ bao write -force database/rotate-root/etcd

Rotates the root user's password (the username/password pair configured on database/config/:name) via UserChangePassword. The old password is not recoverable afterward.

Static roles

Static roles rotate the password of an existing etcd user on a schedule, via UserChangePassword:

$ bao write database/static-roles/svc \
    db_name=etcd \
    username=svc \
    rotation_period=24h

etcd has no native credential-expiry concept on users, so dynamic-role lease expiry is enforced by OpenBao revoking the lease (UserDelete), not by the database itself.