Skip to content

remove hyphen from "auto unseal" in OpenBao #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
arska wants to merge 2 commits into from
Closed

remove hyphen from "auto unseal" in OpenBao #182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94dc60b
Update Vale version in Makefile
arska Feb 2, 2026
e26bc8d
remove hyphen from "auto unseal" in OpenBao
arska Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ else
endif

preview_cmd ?= $(engine_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora ghcr.io/vshn/antora-preview:3.1.4 --antora=docs --style=vshn
vale_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages --workdir /pages ghcr.io/vshn/vale:2.15.5 --minAlertLevel=error .
vale_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages --workdir /pages ghcr.io/vshn/vale:3.13.0 --minAlertLevel=error .

UNAME := $(shell uname)
ifeq ($(UNAME), Linux)
Expand Down
38 changes: 19 additions & 19 deletions docs/modules/ROOT/pages/adr/0049-managed-openbao.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ include::partial$adr-meta.adoc[]
[NOTE]
.Summary
====
This ADR outlines the implementation of a managed OpenBao service on the AppCat platform to provide secret management capabilities to customers.
This builds upon the suggestion of xref:adr/0024-product-choice-for-secret-management.adoc[] to use OpenBao as secret and PKI management solution.
This ADR outlines the implementation of a managed OpenBao service on the AppCat platform to provide customers with secret management capabilities.
This builds upon the suggestion of xref:adr/0024-product-choice-for-secret-management.adoc[] to use OpenBao as a secret and PKI management solution.
====

== Context
Expand All @@ -25,7 +25,7 @@ Following the suggestion in xref:adr/0024-product-choice-for-secret-management.a
- Open-source license with Linux Foundation backing
- Self-hostable deployment model

The service must integrate with the existing AppCat patterns including:
The service must integrate with the existing AppCat patterns, including:

- Crossplane-based provisioning
- Managed namespace deployment model
Expand Down Expand Up @@ -58,7 +58,7 @@ Deploy OpenBao using the official Helm chart with external storage backends (Pos

Implementation::

- Use `provider-helm` to deploy OpenBao Helm chart
- Use `provider-helm` to deploy the OpenBao Helm chart
- PostgreSQL backend for secret storage (leveraging existing `VSHNPostgreSQL`)
- Initialization through composition functions

Expand All @@ -80,7 +80,7 @@ Deploy OpenBao using the official Helm chart with integrated storage using Raft

Implementation::

- Use `provider-helm` to deploy OpenBao Helm chart
- Use `provider-helm` to deploy the OpenBao Helm chart
- Raft storage backend for simplicity
- Built-in clustering for high availability

Expand Down Expand Up @@ -114,7 +114,7 @@ Disadvantages::

- High development effort
- Additional operational complexity
- Maintenance burden for custom operator
- Maintenance burden for the custom operator

== Decision

Expand Down Expand Up @@ -148,7 +148,7 @@ spec:
fqdn: "openbao.example.com" # Fully qualified domain name
serviceLevel: guaranteed # besteffort or guaranteed
openBaoSettings:
# Auto-unseal configuration (optional)
# auto unseal configuration (optional)
# Enables automatic unsealing using external key management systems
# Only one provider should be configured at a time
autoUnseal:
Expand Down Expand Up @@ -221,26 +221,26 @@ data:
ROOT_TOKEN: <base64-encoded-root-token>
```

**Auto-unseal**
**Auto unseal**

Auto unseal allows OpenBao to unseal automatically without manual intervention using an external key management system. This is crucial for automated recovery and reduces operational burden.

By default OpenBao instances will be configured to use a central, internal VSHN managed Vault or OpenBao to auto-unseal.
By default, OpenBao instances will be configured to use a central, internal VSHN-managed Vault or OpenBao to automatically unseal.

WARNING: If a customer configures an auto-unseal provider, only the service level "besteffort" can be guaranteed.
WARNING: If a customer configures no auto unseal provider, only the service level "besteffort" can be guaranteed.

Supported auto-unseal providers:
Supported auto unseal providers:

AWS KMS::: Configure using `awsKmsSecretRef` pointing to a secret containing AWS credentials and KMS key configuration
Azure Key Vault::: Configure using `azureKeyVaultSecretRef` pointing to a secret containing Azure credentials and Key Vault details
GCP Cloud KMS::: Configure using `gcpKmsSecretRef` pointing to a secret containing GCP credentials and Cloud KMS configuration
Transit (Vault/OpenBao)::: Configure using `transitSecretRef` pointing to a secret containing connection details to another Vault/OpenBao instance

Each secret reference should contain the necessary credentials and configuration for the respective provider. When auto-unseal is configured, OpenBao will automatically unseal after restarts without requiring the unseal keys from `writeUnsealKeysSecretToRef`.
Each secret reference should contain the necessary credentials and configuration for the respective provider. When auto unseal is configured, OpenBao will automatically unseal after restarts without requiring the unseal keys from `writeUnsealKeysSecretToRef`.

If no auto-unseal provider is configured, manual unsealing using the unseal keys is required after each pod restart.
If no automatic unsealing provider is configured, manual unsealing using the unseal keys is required after each pod restart.

Example AWS KMS auto-unseal secret:
Example AWS KMS automatic unseal secret:

```yaml
apiVersion: v1
Expand Down Expand Up @@ -292,16 +292,16 @@ Security Model::
- TLS encryption for all communications
- RBAC policies managed through OpenBao
- Audit logging to persistent storage
- Auto-unseal configuration for OpenBao bootstrap
- auto unseal configuration for OpenBao bootstrap

== Consequences

Positive::

- Simplified deployment with fewer external dependencies
- Built-in consensus and replication reduces operational complexity
- Built-in consensus and replication reduce operational complexity
- Self-contained backup mechanisms using Raft snapshots
- Leverages official OpenBao Helm chart for production readiness
- Leverages the official OpenBao Helm chart for production readiness
- Eliminates external storage dependency management

Negative::
Expand All @@ -315,10 +315,10 @@ Operational Impact::

- Simplified service deployment with reduced external dependencies
- Raft snapshot management and restoration procedures
- Need for OpenBao and Raft consensus expertise in operations team
- Need for OpenBao and Raft consensus expertise in the operations team
- Integration testing with existing AppCat services
- TLS certificate lifecycle management (renewal, rotation)
- Auto-unseal configuration and cluster bootstrap management
- auto unseal configuration and cluster bootstrap management
- Raft cluster health monitoring and node management
- Audit log management and compliance reporting
- ServiceMonitor configuration for Prometheus integration
Expand Down