Skip to content

Connection resources · Kind catalogue · Examples

OpenBaoConnection

API version: core.openbaoconfig.io/v1alpha1
Scope: Namespaced
Resource: openbaoconnections.core.openbaoconfig.io
Categories: openbao

OpenBaoConnection is a tenant's login to an OpenBaoServer, usable only by resources in its own Kubernetes namespace through spec.connectionRef. The server must allow this namespace and every requested token audience. It writes nothing to OpenBao: the operator logs in once, caches and renews the token, and reports Ready when login and auth/token/lookup-self succeed. What the connection may configure is bounded by the OpenBao policy of its login role.

Example:

spec:
  serverRef:
    name: openbao
  namespace: team-a
  auth:
    kubernetes:
      role: team-a-operator
      serviceAccountRef:
        name: openbao-config
      audiences: ["openbao"]

Example

examples/core/openbaoconnection.yaml
# 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

On GitHub: openbaoconnection.yaml, generated sample with every field.

Behaviour and permissions

An OpenBaoConnection selects a platform-managed OpenBaoServer and an authentication method. The server must admit the Kubernetes namespace of this connection. Credential and CA references must satisfy the reference rules described in the fields below.

Namespaced connections use their configured identity, never the operator's own ServiceAccount. Use a ClusterOpenBaoConnection when platform administrators deliberately need injected identity. The authentication namespace identifies where login happens; the target namespace identifies where configuration requests run. They need not be the same.

Ready/authenticated status proves the connection checks succeeded. It does not grant access to every OpenBao endpoint: each managed resource can still report PermissionDenied. The OpenBao policy attached to the identity is the effective capability boundary.

Delete dependent managed resources while the operator runs before deleting their connection and server. In-use finalizers preserve those dependencies for cleanup; uninstalling the operator first prevents it from completing that cleanup.

Fields

Defaults below are CRD schema defaults. A blank cell does not imply zero, false or an empty value; see the field description for omission behaviour. Required fields inside an optional object apply only when that object is set.

FieldTypeRequiredDefaultDescriptionValidation
specobjectyesDesired state of the connection: which server, which OpenBao namespace and how to log in.
spec.authobjectyesHow the operator logs in to OpenBao for this connection: set exactly one of token, kubernetes, appRole and jwt. Every referenced Secret or ServiceAccount is in this connection's namespace.
ConstraintsCEL: [has(self.token), has(self.kubernetes), has(self.appRole), has(self.jwt)].filter(x, x).size() == 1 (set exactly one of token, kubernetes, appRole and jwt)
spec.auth.appRoleobjectnoLog in to an OpenBao approle auth mount (auth/<mountPath>/login) with a role ID and secret ID read from Secrets.
spec.auth.appRole.mountPathstringno"approle"Path of the approle auth mount, without the auth/ prefix. Default: approle. Example: approle
Constraintspattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$
length: <=128
spec.auth.appRole.roleIDSecretRefobjectyesSecret key that holds the AppRole role ID (the login `role_id` parameter). Read at each login; never stored in status.
spec.auth.appRole.roleIDSecretRef.keystringyesKey in the Secret's data whose value is used. Example: password
Constraintslength: >=1, <=253
spec.auth.appRole.roleIDSecretRef.namestringyesName of the Kubernetes Secret, in the same namespace as this resource. Example: openbao-credentials
Constraintslength: >=1, <=253
spec.auth.appRole.secretIDSecretRefobjectyesSecret key that holds the AppRole secret ID (the login `secret_id` parameter). Read at each login, so rotation needs no restart; never stored in status.
spec.auth.appRole.secretIDSecretRef.keystringyesKey in the Secret's data whose value is used. Example: password
Constraintslength: >=1, <=253
spec.auth.appRole.secretIDSecretRef.namestringyesName of the Kubernetes Secret, in the same namespace as this resource. Example: openbao-credentials
Constraintslength: >=1, <=253
spec.auth.jwtobjectnoLog in to an OpenBao jwt auth mount (auth/<mountPath>/login) with a short-lived token of a ServiceAccount in this namespace.
ConstraintsCEL: has(self.serviceAccountRef) (serviceAccountRef is required: a namespaced connection never logs in as the operator)
CEL: has(self.audiences) && size(self.audiences) > 0 (audiences is required: a token for the API server audience is a Kubernetes credential and must not be sent to OpenBao)
spec.auth.jwt.audiences[]stringnoAudiences of the requested token; they must match the jwt role's bound_audiences and be listed in the server's allowedAudiences. Required, so the token is never valid against the Kubernetes API server. 1 to 16 entries. Example: ["openbao"]
Constraintsitems: >=1, <=16
each item: length: >=1, <=256
spec.auth.jwt.mountPathstringno"jwt"Path of the jwt auth mount, without the auth/ prefix. Default: jwt. Example: jwt-k8s
Constraintspattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$
length: <=128
spec.auth.jwt.rolestringyesName of the OpenBao jwt auth role to log in with (the login `role` parameter). Example: team-a-operator
Constraintslength: >=1
spec.auth.jwt.serviceAccountRefobjectnoServiceAccount in this namespace whose short-lived token (TokenRequest) is presented as the JWT. Required: a namespaced connection never logs in as the operator itself.
spec.auth.jwt.serviceAccountRef.namestringyesName of the referenced object, in the same namespace as this resource. Example: my-app
Constraintslength: >=1, <=253
spec.auth.kubernetesobjectnoLog in to an OpenBao kubernetes auth mount (auth/<mountPath>/login) with a short-lived token of a ServiceAccount in this namespace.
ConstraintsCEL: has(self.serviceAccountRef) (serviceAccountRef is required: a namespaced connection never logs in as the operator)
CEL: has(self.audiences) && size(self.audiences) > 0 (audiences is required: a token for the API server audience is a Kubernetes credential and must not be sent to OpenBao)
spec.auth.kubernetes.audiences[]stringnoAudiences of the requested token; they must match the OpenBao role's audience and be listed in the server's allowedAudiences. Required, so the token is never valid against the Kubernetes API server. 1 to 16 entries. Example: ["openbao"]
Constraintsitems: >=1, <=16
each item: length: >=1, <=256
spec.auth.kubernetes.mountPathstringno"kubernetes"Path of the kubernetes auth mount, without the auth/ prefix. Default: kubernetes. Example: kubernetes-tenants
Constraintspattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$
length: <=128
spec.auth.kubernetes.rolestringyesName of the OpenBao kubernetes auth role to log in with (the login `role` parameter). Example: team-a-operator
Constraintslength: >=1
spec.auth.kubernetes.serviceAccountRefobjectnoServiceAccount in this namespace whose short-lived token (TokenRequest) is presented. Required: a namespaced connection never logs in as the operator itself.
spec.auth.kubernetes.serviceAccountRef.namestringyesName of the referenced object, in the same namespace as this resource. Example: my-app
Constraintslength: >=1, <=253
spec.auth.tokenobjectnoUse an existing OpenBao token stored in a Secret. Prefer kubernetes or jwt, which need no long-lived credential.
spec.auth.token.secretRefobjectyesSecret key that holds the OpenBao token. Read at each login, so rotation needs no restart; never stored in status.
spec.auth.token.secretRef.keystringyesKey in the Secret's data whose value is used. Example: password
Constraintslength: >=1, <=253
spec.auth.token.secretRef.namestringyesName of the Kubernetes Secret, in the same namespace as this resource. Example: openbao-credentials
Constraintslength: >=1, <=253
spec.authNamespacestringnoAbsolute OpenBao namespace that holds the auth mount used to log in. Unset: log in in the connection's namespace. "": log in at the root namespace and operate in the child namespace set by namespace. Example: team-a
Constraintspattern: ^$|^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$
length: <=256
spec.namespacestringnoBase OpenBao namespace for every request made through this connection; a resource's own namespace field is relative to it. Empty means the root namespace. Example: team-a
Constraintspattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*(/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$
length: <=256
spec.serverRefobjectyesOpenBaoServer to connect to; it supplies the address, CA bundle and limits, and must allow this connection's namespace and token audiences.
spec.serverRef.namestringyesName of the cluster-scoped OpenBaoServer. Example: openbao
Constraintslength: >=1, <=253
statusobjectnoObserved state of the connection: server health copied from the OpenBaoServer and the login result.
status.authenticatedbooleannoTrue when the last login and token lookup (auth/token/lookup-self) succeeded.
status.conditions[]objectnoCurrent state as conditions: Ready is True when the server is Ready and login succeeded; otherwise the reason is, for example, ServerNotReady, Sealed, Unreachable, AuthenticationFailed, CredentialsNotFound or ConnectionDenied.
Constraintslist type: map (keys: type)
status.conditions[]objectnoCondition contains details for one aspect of the current state of this API Resource.
status.conditions[].lastTransitionTimestring (date-time)yeslastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
status.conditions[].messagestringyesmessage is a human readable message indicating details about the transition. This may be an empty string.
Constraintslength: <=32768
status.conditions[].observedGenerationinteger (int64)noobservedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.
Constraintsvalue: >=0
status.conditions[].reasonstringyesreason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
Constraintspattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
length: >=1, <=1024
status.conditions[].statusstringyesstatus of the condition, one of True, False, Unknown.
Constraintsone of: True, False, Unknown
status.conditions[].typestringyestype of condition in CamelCase or in foo.example.com/CamelCase.
Constraintspattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
length: <=316
status.lastProbeTimestring (date-time)noWhen a check last changed this status; checks (about every minute) that find nothing new do not update it.
status.observedGenerationinteger (int64)noThe metadata.generation of this connection that the operator last checked.
status.sealedbooleannoTrue when the server is sealed or not initialized, copied from the OpenBaoServer status.
status.standbybooleannoTrue when the probed node is a standby, copied from the OpenBaoServer status.
status.versionstringnoOpenBao version, copied from the OpenBaoServer status. Example: 2.7.2