Code organization

OpenBao repository is organized into five main modules:

• An API client (in api/) for interacting with OpenBao instances,
• A collection of useful helper modules (in sdk/),
• The Web UI, built with Ember (in ui/),
• The API and documentation website (in website/), and
• The cli and server code, everywhere else.

Of these, api/ and sdk/ are separate Go modules meant to be importable into other applications. The Go module in the root of the project is for the server and is not meant to be externally importable.

API

The included API is a bespoke API client written in Go. Because this is expected to be stable, we need to carefully consider whether a change will be breaking to consumers of the library. Some key files are:

• api/client.go is the main entry point of the client.
• api/logical.go has backend-agnostic utilities for speaking OpenBao API semantics.
• api/secret.go has structured response parsing.
• api/auth has various specialized authentication plugin helpers.
• api/sys_*.go, api/kv*.go, api/auth.go, and api/ssh.go have backend-specific calls for various portions of the API space (such as sys/, authenticating to OpenBao, or the ssh plugin).

Upstream also includes OpenAPI-based client libraries that haven't yet been forked; if maintainers are interested in helping to support these libraries, let us know!

SDK

The SDK module exists to share externally usable, independent modules with people outside of OpenBao. These may be things useful in conjunction with OpenBao (e.g., sdk/plugin for building auth and secret plugins), they might be testing libraries (such as sdk/helper/testcluster for testing plugins or external projects that rely on OpenBao from Go tests), or they might be standalone libraries provided to the community (such as sdk/helper/shamir/.

Each of these packages are different and serve a different goal; some commonly used packages are:

• sdk/framework/ contains various HTTP helpers such as typing and parsing for request parameters.
• sdk/logical/ contains the type definitions for core and plugin interoperability, including requests, responses, and the underlying storage model.
• sdk/plugin/ contains the GRPC bindings for external auth and secret plugins.
• sdk/database/ contains the same bindings but for external database plugins.
• sdk/physical/ contains the interface definition of a storage backend, including implementations of the File and InMemory non-production backends.
• sdk/helper/ contains many external libraries. Some highlights are:
  • sdk/helper/shamir/ implements Shamir's secret sharing and has been moved for external consumption.
  • sdk/helper/certutil/ has leaf and CA certificate creation code used by the PKI engine and the database secrets engine.
  • sdk/helper/ocsp/ contains an OCSP client utilized by the cert auth method, originally forked from Snowflake.

Note that the SDK has a loose breakage policy: while we aim to minimize disruption, the SDK firstly serves OpenBao's server and thus will be updated as requirements here change. As such, the SDK is versioned with a 0 major version to indicate this potential lack of compatibility.

UI

The Web UI is built with Ember.

Website

The website is built with Docusaurus and includes two main sections:

• api-docs a hand-maintained API reference to all endpoints in OpenBao.
• docs, for everything else, including information about various plugins, this contributing guide, and various decisions made by the TSC and the OpenBao community.

To add a new page, create the .mdx file in the appropriate subfolder within website/content and then add the page to the sidebar (if the page is under docs/, then to website/sidebars.ts else if the page is under community/, then to website/sidebarsCommunity.ts).

OpenBao CLI, server, and plugins

The remaining code is for the OpenBao CLI, server, and a few built-in plugins.

At a high level, these directories are:

• internal/audit/ contains interface definitions for auditing requests and responses.
• internal/builtin/ contains the builtin plugins:
  • internal/builtin/audit/ contains the built-in audit backends such as file or syslog.
  • internal/builtin/credential/ contains the built-in authentication plugins such as AppRole or cert.
  • internal/builtin/logical/ contains the built-in secret engines such as PKI or kv.
  • internal/builtin/plugin/ contains a source-agnostic plugin wrapper (either using the builtin plugin or handling the GRPC connection to an external plugin).
• internal/command/ contains the CLI interface definitions: each command is in a separate file connected through internal/command/commands.go. Many plugins reuse the same generic read, write, list, ... commands, but a few (like K/V or PKI) have plugin-specific commands. This also includes Agent, Proxy, and Server configuration parsing and startup code, though much of the functionality for the latter is elsewhere.
• internal/helper/ includes various internal libraries useful only in the context of OpenBao.
• internal/http/ contains the main server code creating the http.ServeMux.
• internal/physical/ contains production quality physical storage backend implementations. This currently only includes Raft.
• internal/plugins/database/ contains the plugins for the database secrets engine to support creating short-lived dynamic credentials for these database types.
• internal/serviceregistration/ contains helpers for supporting service registration against various providers. This is only utilized by OpenBao Server.
• internal/vault/ contains the Core of the server: this implements barrier encryption, identity storage, token storage, and many sys/ endpoint implementations.

Key dependencies of the server code are:

• go-secure-stdlib which is a collection of shared parsing and configuration utility libraries used by many plugins and the Core.
• go-kms-wrapping which implements auto-unseal for various providers (such as Transit or GCP).
• raft which implements the core Raft storage backend.
• openbao-template which implements templating for OpenBao Agent.