Documentation and current OpenBao functionality

[microwavenby]

Hi there community,

I wanted to note that the documentation has left me with expectations for features that do not currently exist within OpenBao as a platform - namely the availability of the UI, and the ability to use Postgres as a storage backend.

While the release notes for v2.0.2 mention that the UI is not enabled, the documentation does not make this mention -- https://openbao.org/docs/configuration/ui/

Discussion about the UI

Issue 129

Expectations of Postgres as a storage backend - present, maybe will change in the future

https://openbao.org/docs/configuration/storage/postgresql/

The reality of Postgres as a storage backend is mentioned only in discussions threads:

(output from an OpenBao Docker container configured to use storage type postgresql)

Unknown storage type postgresql

Discussion about Postgresql as a storage engine

The build pipeline is quite complex and unclear, and the documentation for compiling from source ends at building a dev server with make dev -- https://openbao.org/docs/install/#compiling-from-source

Is the correct approach to the documentation inaccuracies to create pull requests against them? Or are there other plans do keep the documentation aligned with OpenBao versions that are necessary first?

[cipherboy]

\o hey @microwavenby

Yeah, documentation is a bit interesting right now. Because our support policy will likely be latest release only, we haven't really considered versioned documentation. I suppose it might still be useful for historical purposes.... The net is that all documentation builds from main currently.

For the UI and Postgres engines, I do agree, it probably makes sense to hide that section via draft: true, at least until either are brought to a shipped release.

Happy to take PRs in either direction.

[microwavenby]

@cipherboy thanks for the reply.

This is somewhat of a tangent, but on that other issue #129 I saw that the contributor team was missing the appropriate expertise to complete that task currently. I have some frontend experience (certainly more than my Golang experience), though admittedly it's with React (Remix and Next.js) and not Ember.js.

But, trimming functionality seems likely to be less of a learning curve than writing new functionality. I'm willing to give that a look (if what you're lacking is wiling hands, rather than specifically Ember experience)

[cipherboy]

\o hey @microwavenby -- sorry about the delay!

Yeah, we definitely are lacking the skills. I have some front-end experience with React but very little with Ember (and a lot more Golang experience)... So its definitely an area we'd appreciate help in! We've discussed this on past community calls and I think we're generally open to either updating the current UI or considering a rewrite. Even just scoping the work of what is left would be very much appreciated. :-)

(An IBM employee had started a rewrite in Angular but hadn't made it very far prior to the acquisition.)

We've trimmed a little of it (it no longer is in release builds for instance), but we've not fully trimmed all references to it, in all projects (e.g., in openbao-helm)

[cipherboy]

Speaking just on the rewrite approach...

One of the major requirements I had for a rewrite was allowing plugins to indicate custom components. Not sure how possible that is or what languages/frameworks make that easiest... (if it is even possible -- I mean, theoretically from a early 2000s web dev "just load a <script> element and some iframes it is, but... come on.) :-)

But there's two forms of it, IMO:

1. A Drupal-like (or any other pluggable old-world web system) that had a very rudimentary CRUD-like interface that was inferred semi-automatically from plugins. In our case, perhaps something that's little more than a thinly wrapper over the OpenAPI bindings.
2. Fully plugin-specified, custom web components by plugins, replacing that first system.

This eventually allow the core to have its own fairly minimal UI component, but let each plugin dictate their own UI which would be a rather powerful enhancement for third-party plugins and collaboration in the ecosystem. With the plugin registry, I think that'd enable a lot of really interesting use cases.

My one worry with this is that we lack unified branding. On the one hand, it is rather nice that, e.g., if Google or Amazon wanted to step up and maintain their plugins as first-class entities, they could use their own branding on their plugin pages... But on the other hand, it definitely could cause visual confusion if there's too many distinct styles. Maybe it won't be a problem since I guess there should only be two styles (global theme + plugin theme) on any given page...

Hmm, things to ponder. :-)

[microwavenby]

I think you allude to an issue with each plugin "dictating their own UI" and "lacking unified branding" -- and that's usability. If each plugin can have its own arbitrary interfaces and layout, it's going to be an interesting challenge to retain a floor of accessibility, internationalization, and usability.

That said..
There's something interesting about having a system that delegates routes to plugins (e.g., ui/plugin/FOO routing and rendering gets handed off to the UI the plugin provides) but it may be adding complexity over something flatter like "Your plugin needs to provide one page in X framework. Here are these environment / session / etc parameters available to you. Here is the library we provide for interacting with the OpenBao backend API."

[cipherboy]

I think you allude to an issue with each plugin "dictating their own UI" and "lacking unified branding" -- and that's usability. If each plugin can have its own arbitrary interfaces and layout, it's going to be an interesting challenge to retain a floor of accessibility, internationalization, and usability.

Of these, I think we currently maybe have usability at best... Internationalization is completely non-existent and I'm not honestly sure how well accessibility is handled in the UI today... both of which are problematic. :-) While throwing out an existing feature is hard and not something I'd suggest lightly, we are tightly coupled to an older version of HashiCorp's design system and the Ember set up, neither of which lends itself to internationalization (not to mention, all errors and many, many other strings in OpenBao aren't internationalized either).

Either of these are massive projects, but coupled with a less-than-popular core framework... We likely can't stay abreast of changes in HashiCorp's design system to take advantage of newer accessibility updates since we need to fork it and also can't easily add internationalization as a result either.

Idk, my general thoughts are a new, more popular and widely understood combination of frameworks is the way to go.

---

There's something interesting about having a system that delegates routes to plugins (e.g., ui/plugin/FOO routing and rendering gets handed off to the UI the plugin provides)

I concur; we already make opinionated choices (your plugin has to use our GRPC interface and must be runnable from a binary entrypoint; while you can theoretically do this in any language, in practice people only use our SDK). Extending this to include a UI SDK and specific endpoints seems logical, IMO. But I've not looked at e.g., React to see if it supports this form of externally loadable delegated rendering or not. How that interacts with a shared client (we need to give it an API client so that it has access to the session's auth credentials, for instance) is also beyond me. :-)

But from someone who comes from the days of <script /> tags, AJAX, and XHTML, it seemed like a fun problem.

[microwavenby]

Idk, my general thoughts are a new, more popular and widely understood combination of frameworks is the way to go.

This sounds like a good idea. I'm of two minds on the how -- do we expect static site code to be served by the golang plugin on top of the API? If so, maybe just using 11ty with some hooks that use vault-js to talk to OpenBao's API (or the like) is the way to go.

The other direction might be a separate repo, separate container, and something like Remix or Svelte. I'm not sure how much we benefit here from having a wholly different language and codebase packed into the same repo with its own several heads on the hydra build pipeline, except for simplifying the deployment to a single container. (Not underestimating that value, just observing its limitation)

But from someone who comes from the days of <script /> tags, AJAX, and XHTML, it seemed like a fun problem.

I have no idea if "fun problems" is the right way to go with open source - I can see the allure, if it gets one person excited about the project, but will it continue to be accessible for contributors if it's "clever" or "innovative".

[cipherboy]

\o hey @microwavenby, sorry for the late reply here, I've been busy!

v2.1.0 released so the docs should just about be current again (sans still releasing from main and not release/2.1.x). PostgreSQL support landed with improvements over upstream (paginated list, transactional storage support plus native table creation).

The UI is in better shape; #739 should track its re-introduction, though I think there's still a bit of work to do before we're confident in it to ship. But we're getting there!