Connections¶
Field reference for OpenBaoServer, OpenBaoConnection and ClusterOpenBaoConnection, the
three core.openbaoconfig.io/v1alpha1 kinds that decide where the operator sends requests and how
it logs in. Facts come from api/core/v1alpha1, internal/connection and
internal/controller/core. To set up a first connection step by step, use
connect to OpenBao; for the generated schema of every field, use the
API reference.
| kind | scope | created by | role |
|---|---|---|---|
OpenBaoServer |
cluster | platform team | the only place that sets the address, CA bundle, timeout and rate limit; decides which namespaces and audiences tenants may use |
OpenBaoConnection |
namespaced | tenant or platform team, in the tenant namespace | a login usable only by resources in its own namespace; every Secret and ServiceAccount it names is in that namespace |
ClusterOpenBaoConnection |
cluster | platform team | a login usable by resources in the namespaces its allowedNamespaces selects; may log in as the operator itself |
None of the three writes to OpenBao. Resources reference a connection with
spec.connectionRef: {kind, name}; kind defaults to OpenBaoConnection, and both fields are
immutable.
OpenBaoServer¶
# The platform team declares the OpenBao server once. Tenants in namespaces labelled
# openbaoconfig.io/tenant=true may connect to it with OpenBaoConnections that request the openbao token audience;
# the Kubernetes API server's own audiences are always refused.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoServer
metadata:
name: openbao
spec:
address: https://openbao.openbao.svc:8200
caBundle:
configMapRef:
namespace: openbao
name: openbao-ca
allowedNamespaces:
matchLabels:
openbaoconfig.io/tenant: "true"
allowedAudiences:
- openbao
rateLimit:
qps: 50
burst: 100
requestTimeout: 30s
Spec¶
| field | type | default | rules |
|---|---|---|---|
address |
string | required | URL of the OpenBao API without /v1 and without user:password@; at most 2048 characters; must start with https:// unless allowInsecureHTTP is true |
allowInsecureHTTP |
boolean | false |
allow an http:// address; tokens, login JWTs and secret inputs then cross the network in clear text |
caBundle.secretRef |
{namespace, name, key} |
PEM CA bundle in a Secret; key defaults to ca.crt. Exactly one of secretRef and configMapRef |
|
caBundle.configMapRef |
{namespace, name, key} |
PEM CA bundle in a ConfigMap, for example one filled by trust-manager | |
allowedNamespaces |
label selector | unset | Kubernetes namespaces whose OpenBaoConnections may use this server. Unset allows none; {} allows all. Does not restrict ClusterOpenBaoConnections |
allowedAudiences |
list of strings, at most 16, unique | token audiences an OpenBaoConnection may request; every audience the connection asks for must be listed |
|
rateLimit.qps |
integer, 1 to 100000 | sustained requests per second, shared by every connection to the server | |
rateLimit.burst |
integer, 1 to 100000 | the value of qps |
requests allowed at once above the sustained rate |
requestTimeout |
duration | 60s |
maximum time of one request |
Unset rateLimit means no client-side limit.
Status¶
The status fields (conditions, version, sealed, standby, lastProbeTime) and the Ready reasons are
listed in status and events.
The operator probes sys/seal-status and sys/health in the root namespace, without a token,
every 1 to 1.2 minutes, and when the server or its CA bundle Secret or ConfigMap
changes. A probe that finds nothing new writes nothing.
Connection spec¶
Fields shared by OpenBaoConnection and ClusterOpenBaoConnection:
| field | type | default | rules |
|---|---|---|---|
serverRef.name |
string | required | the OpenBaoServer to use |
namespace |
string | "" (root) |
base OpenBao namespace of every request through the connection; a resource's spec.namespace is relative to it. Segments separated by /, no leading or trailing slash, no . or .. segments, at most 256 characters |
authNamespace |
string or unset | unset | absolute OpenBao namespace that holds the auth mount used to log in |
auth |
object | required | exactly one of token, kubernetes, appRole and jwt |
allowedNamespaces |
label selector | unset | ClusterOpenBaoConnection only: Kubernetes namespaces whose resources may reference it. Unset allows none; {} allows all |
namespace and authNamespace¶
authNamespace |
login, lookup-self at login, and renew-self happen in | typical use |
|---|---|---|
| unset | namespace |
the auth mount lives in the connection's own namespace |
"" |
the root namespace | one auth mount in the root namespace serves every tenant namespace |
team-a |
team-a |
the auth mount lives in a namespace other than the one being configured |
The status probe checks the token with auth/token/lookup-self in namespace, not in
authNamespace, so the identity's policy must allow that path in the connection namespace
(OpenBao policy). A resource that was acquired in one namespace
and whose connection later resolves to another stops with NamespaceChanged and writes nothing.
Authentication methods¶
| method | fields | credential |
|---|---|---|
token |
secretRef: {name, key} |
an OpenBao token in a Secret of the connection namespace |
kubernetes |
mountPath (default kubernetes), role, serviceAccountRef: {name}, audiences |
a TokenRequest token of a ServiceAccount in the connection namespace |
jwt |
mountPath (default jwt), role, serviceAccountRef: {name}, audiences |
the same token, presented to a jwt auth mount |
appRole |
mountPath (default approle), roleIDSecretRef: {name, key}, secretIDSecretRef: {name, key} |
role ID and secret ID from Secrets of the connection namespace |
For kubernetes and jwt, serviceAccountRef and audiences (1 to 16 entries) are required.
| method | fields | credential |
|---|---|---|
token |
exactly one of secretRef: {namespace, name, key} and filesystem: {path} |
a token in a Secret, or a token file in the operator pod, such as an agent sink |
kubernetes |
mountPath (default kubernetes), role, at most one of serviceAccountRef: {namespace, name} and injectedIdentity: {tokenPath}, audiences |
a TokenRequest token of a named ServiceAccount, or the operator's own projected token |
jwt |
mountPath (default jwt), role, as for kubernetes |
the same token, presented to a jwt auth mount |
appRole |
mountPath (default approle), roleIDSecretRef and secretIDSecretRef, each {namespace, name, key} |
role ID and secret ID from Secrets |
audiences is required with serviceAccountRef and allowed only with it. With neither
serviceAccountRef nor injectedIdentity, the connection uses injectedIdentity with the
default tokenPath, /var/run/secrets/openbao/token.
Mount paths match ^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$, at most 128
characters, without the auth/ prefix.
Credential sources¶
| source | fields | kinds | read |
|---|---|---|---|
| Secret | auth.token.secretRef, auth.appRole.*SecretRef |
both | at every login, so a rotated Secret needs no restart |
| TokenRequest | serviceAccountRef and audiences |
both | a new token, valid for 10 minutes, for each login |
| injected identity | injectedIdentity.tokenPath |
ClusterOpenBaoConnection |
the file at every login; the chart mounts it with injectedIdentity.projectedToken |
| token file | auth.token.filesystem.path |
ClusterOpenBaoConnection |
the file at every login; a changed modification time replaces the cached client |
A missing Secret, key or file sets the connection's reason CredentialsNotFound. Credentials are
never stored in status.
Examples¶
# A tenant connection logs in as a ServiceAccount of its own namespace with a TokenRequest token for the
# OpenBao audience. The OpenBaoServer must select this namespace and allow the audience. Injected identity and file
# sources exist only on ClusterOpenBaoConnection.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
name: openbao
namespace: team-a
spec:
serverRef:
name: openbao
namespace: tenants/team-a
auth:
kubernetes:
role: team-a-configurer
serviceAccountRef:
name: openbao-configurer
audiences:
- openbao
# The platform team's connection logs in to the Kubernetes auth mount as a dedicated ServiceAccount of the operator
# namespace, with a short-lived TokenRequest token for the openbao audience, which the OpenBao role must expect.
# Resources in namespaces labelled openbaoconfig.io/platform=true use it with connectionRef kind
# ClusterOpenBaoConnection. The -injectedidentity and -filesystem variants log in as the operator itself.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
name: platform-sa
spec:
serverRef:
name: openbao
auth:
kubernetes:
mountPath: kubernetes
role: platform-configurer
serviceAccountRef:
namespace: openbao-config-operator
name: platform-configurer
audiences:
- openbao
allowedNamespaces:
matchLabels:
openbaoconfig.io/platform: "true"
# The operator logs in as itself with the token of the projected volume the chart mounts by default
# (injectedIdentity.projectedToken). The OpenBao role must bind the operator's ServiceAccount and the audience
# set in injectedIdentity.projectedToken.audience (default openbao-config-operator).
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
name: platform
spec:
serverRef:
name: openbao
auth:
kubernetes:
role: openbao-config-operator
injectedIdentity:
tokenPath: /var/run/secrets/openbao/token
allowedNamespaces:
matchLabels:
openbaoconfig.io/platform: "true"
---
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
name: platform-jwt
spec:
serverRef:
name: openbao
auth:
jwt:
mountPath: jwt-k8s
role: openbao-config-operator
injectedIdentity:
tokenPath: /var/run/secrets/openbao/token
allowedNamespaces:
matchLabels:
openbaoconfig.io/platform: "true"
# The token is read from a file in the operator pod at every login, such as the token sink of an agent sidecar
# that keeps it renewed (for example one injected through the chart's podAnnotations).
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
name: platform-agent
spec:
serverRef:
name: openbao
auth:
token:
filesystem:
path: /vault/secrets/token
allowedNamespaces:
matchLabels:
openbaoconfig.io/platform: "true"
Tenant boundary rules¶
The resolver enforces these rules before any credential is read or requested. CEL rejects most of them at admission too; the resolver applies them again when validation was bypassed.
| rule | enforced by | result |
|---|---|---|
a resource uses an OpenBaoConnection of its own namespace only |
resolver (lookup in the resource's namespace) | ConnectionNotReady (not found) |
a resource uses a ClusterOpenBaoConnection only if its allowedNamespaces selects the resource's namespace; unset selects none |
resolver | resource ConnectionDenied |
an OpenBaoConnection uses a server only if the server's allowedNamespaces selects its namespace; unset selects none |
resolver | connection ConnectionDenied |
every audience of an OpenBaoConnection is in the server's allowedAudiences |
resolver | connection ConnectionDenied |
no audience is one the Kubernetes API server accepts: https://kubernetes.default.svc, https://kubernetes.default.svc.cluster.local, kubernetes.default.svc, rke2, k3s, the service account issuer discovered at start-up, and the chart's apiServerAudiences |
resolver, for both connection kinds, and for the aud claim of token files |
connection ConnectionDenied |
| a namespaced Kubernetes or JWT login names a ServiceAccount and audiences | CEL and resolver | rejected at admission |
the automounted ServiceAccount token (/var/run/secrets/kubernetes.io/serviceaccount/) is never sent |
CEL on tokenPath and filesystem.path; resolver checks the path and the file identity again at every login |
rejected |
| a namespaced connection never uses the operator's identity or files | the OpenBaoConnection schema has no injectedIdentity or filesystem field |
not expressible |
A failed issuer discovery is logged, and the built-in and configured audiences stay denied. When
the configuration or login of a ClusterOpenBaoConnection fails, a resource that uses it sees only
"ClusterOpenBaoConnection <name> is not ready (see its status)"; the platform's Secret,
ServiceAccount and file names stay on the connection's own status.
TLS and the CA bundle¶
| behaviour | detail |
|---|---|
| trust | with caBundle set, the bundle replaces the system roots for that server; unset uses the operator image's system roots |
| reload | a change to the CA bundle Secret or ConfigMap re-queues the server and its connections and replaces their cached clients |
| minimum version | TLS 1.2 |
| invalid bundle | a bundle with no valid PEM certificate fails the client |
| proxies | HTTP_PROXY and HTTPS_PROXY are ignored: only the OpenBaoServer decides where tokens are sent |
| redirects | never followed; a 3xx answer is an error |
Connections have no TLS settings of their own.
Connection status¶
A connection copies version, sealed and standby from its server and adds authenticated; the fields are
listed in status and events, and the Ready reasons in
conditions of connections and servers.
The connection controller checks every 1 to 1.2 minutes, and when the connection, its
server, a referenced Secret or (for an OpenBaoConnection) its namespace labels change. Resources
wait with ConnectionNotReady while their connection is not Ready for its current generation.
The gauge openbao_connection_ready{kind,namespace,name} is 1 while a connection is Ready.
Client behaviour¶
The operator keeps one authenticated client per connection. The client is replaced when the connection or server generation changes, or when the value of a credential input changes: the content of a referenced Secret or CA bundle, or a token file's modification time. An edit that changes only a Secret's labels or annotations keeps the client. How the client renews, logs in again, retries and revokes its token is in client cache; the timings are in constants and timings.
Every request carries the header X-Openbao-Config-Resource: <group>/<kind>/<namespace>/<name> of
the resource it serves (ADR 0022).
Finalizers and deletion¶
| object | finalizer | held while |
|---|---|---|
OpenBaoConnection, ClusterOpenBaoConnection |
openbaoconfig.io/connection-in-use |
a resource that references it still holds the engine finalizer openbaoconfig.io/finalizer, that is, still has an OpenBao object to delete |
OpenBaoServer |
openbaoconfig.io/server-in-use |
a connection references it |
While a connection is being deleted it keeps serving its last working client for those
deletions, even after its credentials are gone, so deleting a whole Kubernetes Namespace removes
the OpenBao objects first and the connection last. If the Namespace terminates and the connection
is already gone, the resource releases its finalizer with an Orphaned event and the OpenBao
object stays.