Skip to content

Connection resources · Kind catalogue · Examples

ClusterOpenBaoConnection

API version: core.openbaoconfig.io/v1alpha1
Scope: Cluster
Resource: clusteropenbaoconnections.core.openbaoconfig.io
Categories: openbao

ClusterOpenBaoConnection is a cluster-scoped login to an OpenBaoServer owned by the platform team, usable by resources in every namespace its allowedNamespaces selects (spec.connectionRef.kind: ClusterOpenBaoConnection). Unlike OpenBaoConnection it may log in as the operator itself (injected identity or a token file). 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.

Example:

spec:
  serverRef:
    name: openbao
  auth:
    kubernetes:
      role: openbao-config-operator
      injectedIdentity:
        tokenPath: /var/run/secrets/openbao/token
  allowedNamespaces:
    matchLabels:
      openbao.io/platform: "true"

Example

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

On GitHub: clusteropenbaoconnection.yaml, clusteropenbaoconnection-filesystem.yaml, clusteropenbaoconnection-injectedidentity.yaml, generated sample with every field.

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, how to log in and which Kubernetes namespaces may use it.
spec.allowedNamespacesobjectnoLabel selector over Kubernetes namespaces whose resources may reference this connection; a resource in any other namespace gets reason ConnectionDenied. Unset allows no namespace; an empty selector ({}) allows every namespace. Example: {matchLabels: {openbao.io/platform: "true"}}
Constraintsmap type: atomic
spec.allowedNamespaces.matchExpressions[]objectnomatchExpressions is a list of label selector requirements. The requirements are ANDed.
Constraintslist type: atomic
spec.allowedNamespaces.matchExpressions[]objectnoA label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.
spec.allowedNamespaces.matchExpressions[].keystringyeskey is the label key that the selector applies to.
spec.allowedNamespaces.matchExpressions[].operatorstringyesoperator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
spec.allowedNamespaces.matchExpressions[].values[]stringnovalues is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
Constraintslist type: atomic
spec.allowedNamespaces.matchLabelsmap[string]stringnomatchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.
spec.authobjectyesHow the operator logs in to OpenBao for this connection: set exactly one of token, kubernetes, appRole and jwt. Every reference names its Kubernetes 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: secret-id
Constraintslength: >=1
spec.auth.appRole.roleIDSecretRef.namestringyesName of the Secret. Example: openbao-operator-approle
Constraintslength: >=1
spec.auth.appRole.roleIDSecretRef.namespacestringyesKubernetes namespace of the Secret. Example: openbao-operator
Constraintslength: >=1
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: secret-id
Constraintslength: >=1
spec.auth.appRole.secretIDSecretRef.namestringyesName of the Secret. Example: openbao-operator-approle
Constraintslength: >=1
spec.auth.appRole.secretIDSecretRef.namespacestringyesKubernetes namespace of the Secret. Example: openbao-operator
Constraintslength: >=1
spec.auth.jwtobjectnoLog in to an OpenBao jwt auth mount (auth/<mountPath>/login) with a ServiceAccount token: a named ServiceAccount's short-lived token, or the operator's own injected token.
ConstraintsCEL: has(self.serviceAccountRef) || !has(self.audiences) (audiences require serviceAccountRef: an injected identity token gets its audience from its projected volume)
CEL: !has(self.serviceAccountRef) || (has(self.audiences) && size(self.audiences) > 0) (serviceAccountRef requires audiences: a token without them is valid against the Kubernetes API server)
CEL: [has(self.serviceAccountRef),has(self.injectedIdentity)].filter(x,x==true).size() <= 1 (at most one of the fields in [serviceAccountRef injectedIdentity] may be set)
spec.auth.jwt.audiences[]stringnoAudiences of the token requested for serviceAccountRef, required with it and only allowed with it; they must match the jwt role's bound_audiences. An audience the Kubernetes API server accepts is refused. At most 16 entries. Example: ["openbao"]
Constraintsitems: <=16
each item: length: >=1, <=256
spec.auth.jwt.injectedIdentityobjectnoPresent the operator's own ServiceAccount token from a file in its pod. When neither serviceAccountRef nor injectedIdentity is set, injectedIdentity with the default tokenPath is used. Mutually exclusive with serviceAccountRef.
spec.auth.jwt.injectedIdentity.tokenPathstringno"/var/run/secrets/openbao/token"Path of a projected ServiceAccount token file with a dedicated audience in the operator pod, so the token sent to OpenBao is not valid against the Kubernetes API server. The automounted token directory (/var/run/secrets/kubernetes.io/serviceaccount/) is refused. Default: /var/run/secrets/openbao/token, where the chart mounts a token with audience openbao-config-operator.
Constraintspattern: ^(/[^/]+)+$
length: <=512
CEL: !(self + '/').startsWith('/var/run/secrets/kubernetes.io/serviceaccount/') (the automounted ServiceAccount token is a Kubernetes API credential and is never sent to OpenBao)
spec.auth.jwt.mountPathstringno"jwt"Path of the jwt auth mount, without the auth/ prefix. Default: jwt. Example: jwt
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: openbao-config-operator
Constraintslength: >=1
spec.auth.jwt.serviceAccountRefobjectnoServiceAccount, in any namespace, whose short-lived token (TokenRequest) is presented as the JWT. Mutually exclusive with injectedIdentity.
spec.auth.jwt.serviceAccountRef.namestringyesName of the object. Example: openbao-config-operator
Constraintslength: >=1
spec.auth.jwt.serviceAccountRef.namespacestringyesKubernetes namespace of the object. Example: openbao-operator
Constraintslength: >=1
spec.auth.kubernetesobjectnoLog in to an OpenBao kubernetes auth mount (auth/<mountPath>/login) with a ServiceAccount token: a named ServiceAccount's short-lived token, or the operator's own injected token.
ConstraintsCEL: has(self.serviceAccountRef) || !has(self.audiences) (audiences require serviceAccountRef: an injected identity token gets its audience from its projected volume)
CEL: !has(self.serviceAccountRef) || (has(self.audiences) && size(self.audiences) > 0) (serviceAccountRef requires audiences: a token without them is valid against the Kubernetes API server)
CEL: [has(self.serviceAccountRef),has(self.injectedIdentity)].filter(x,x==true).size() <= 1 (at most one of the fields in [serviceAccountRef injectedIdentity] may be set)
spec.auth.kubernetes.audiences[]stringnoAudiences of the token requested for serviceAccountRef, required with it and only allowed with it; they must match the OpenBao role's audience. An audience the Kubernetes API server accepts is refused. At most 16 entries. Example: ["openbao"]
Constraintsitems: <=16
each item: length: >=1, <=256
spec.auth.kubernetes.injectedIdentityobjectnoPresent the operator's own ServiceAccount token from a file in its pod. When neither serviceAccountRef nor injectedIdentity is set, injectedIdentity with the default tokenPath is used. Mutually exclusive with serviceAccountRef.
spec.auth.kubernetes.injectedIdentity.tokenPathstringno"/var/run/secrets/openbao/token"Path of a projected ServiceAccount token file with a dedicated audience in the operator pod, so the token sent to OpenBao is not valid against the Kubernetes API server. The automounted token directory (/var/run/secrets/kubernetes.io/serviceaccount/) is refused. Default: /var/run/secrets/openbao/token, where the chart mounts a token with audience openbao-config-operator.
Constraintspattern: ^(/[^/]+)+$
length: <=512
CEL: !(self + '/').startsWith('/var/run/secrets/kubernetes.io/serviceaccount/') (the automounted ServiceAccount token is a Kubernetes API credential and is never sent to OpenBao)
spec.auth.kubernetes.mountPathstringno"kubernetes"Path of the kubernetes auth mount, without the auth/ prefix. Default: kubernetes. Example: kubernetes
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: openbao-config-operator
Constraintslength: >=1
spec.auth.kubernetes.serviceAccountRefobjectnoServiceAccount, in any namespace, whose short-lived token (TokenRequest) is presented. Mutually exclusive with injectedIdentity.
spec.auth.kubernetes.serviceAccountRef.namestringyesName of the object. Example: openbao-config-operator
Constraintslength: >=1
spec.auth.kubernetes.serviceAccountRef.namespacestringyesKubernetes namespace of the object. Example: openbao-operator
Constraintslength: >=1
spec.auth.tokenobjectnoUse an existing OpenBao token from a Secret or a file in the operator pod. Prefer kubernetes or jwt, which need no long-lived credential.
ConstraintsCEL: [has(self.secretRef),has(self.filesystem)].filter(x,x==true).size() == 1 (exactly one of the fields in [secretRef filesystem] must be set)
spec.auth.token.filesystemobjectnoRead the token from a file in the operator pod, such as an OpenBao agent sink, at every login. A missing file sets reason CredentialsNotFound. Mutually exclusive with secretRef.
spec.auth.token.filesystem.pathstringyesAbsolute path of the token file inside the operator pod; never in the automounted ServiceAccount token directory. Example: /var/run/openbao/token
Constraintspattern: ^(/[^/]+)+$
length: <=512
CEL: !(self + '/').startsWith('/var/run/secrets/kubernetes.io/serviceaccount/') (the automounted ServiceAccount token is a Kubernetes API credential and is never sent to OpenBao)
spec.auth.token.secretRefobjectnoSecret key that holds the OpenBao token. Read at each login, so rotation needs no restart; never stored in status. Mutually exclusive with filesystem.
spec.auth.token.secretRef.keystringyesKey in the Secret's data whose value is used. Example: secret-id
Constraintslength: >=1
spec.auth.token.secretRef.namestringyesName of the Secret. Example: openbao-operator-approle
Constraintslength: >=1
spec.auth.token.secretRef.namespacestringyesKubernetes namespace of the Secret. Example: openbao-operator
Constraintslength: >=1
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