API Reference

Packages

catalog.kbind.io/v1alpha1
core.kbind.io/v1alpha1
iam.kbind.io/v1alpha1

catalog.kbind.io/v1alpha1

Package v1alpha1 contains the catalog API for the kbind service layer: the Export and Collection kinds in the catalog.kbind.io group. The catalog is curation on top of the core's raw discovery — human-facing metadata and defaults that turn "a list of CRD names" into "a service you'd choose". These CRDs live on the provider and are read only by the gateway/UI/CLI; the konnector never sees them. See docs/proposals/v2-extended.md.

BindingDefaults

BindingDefaults are the binding fields an Export pre-fills in the generated bundle.

Appears in: - ExportSpec

Field	Description	Default	Validation
`conflictPolicy` ConflictPolicy	conflictPolicy is the default conflict behavior for the generated ClusterBinding.		Enum: [Fail Adopt] Optional: {}
`relatedResources` RelatedResource array	relatedResources are the related-resource selectors for the generated ClusterBinding.		Optional: {}

Collection

Collection groups Exports for UI/CLI browsing. Pure presentation; nothing binds to a Collection.

Field	Description	Validation
`apiVersion` string	`catalog.kbind.io/v1alpha1`
`kind` string	`Collection`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` CollectionSpec		Required: {} Required: {}

CollectionSpec

CollectionSpec is a titled grouping of Exports.

Appears in: - Collection

Field	Description	Validation
`title` string	title is the human-facing name of the group.	MinLength: 1 Required: {} Required: {}
`description` string	description explains the grouping.	Optional: {}
`exports` ExportRef array	exports lists the member Exports by name.	MinItems: 1 Required: {} Required: {}

Export

Export is one curated offering in the provider's catalog: human-facing metadata plus defaults on top of one or more exported APIs. The catalog is derived-from-core-truth: an Export listing an API that is not actually exported (label/boundary) gets a condition and is hidden by the gateway — the export label remains the source of truth, the catalog is presentation and defaults. Lives on the provider; the konnector never sees it.

Field	Description	Validation
`apiVersion` string	`catalog.kbind.io/v1alpha1`
`kind` string	`Export`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ExportSpec		Required: {} Required: {}
`status` ExportStatus		Optional: {}

ExportRef

ExportRef references an Export by name.

Appears in: - CollectionSpec

Field	Description	Default	Validation
`name` string	name of the Export.		MinLength: 1 Required: {} Required: {}

ExportSpec

ExportSpec describes one offering.

Appears in: - Export

Field	Description	Validation
`title` string	title is the human-facing name of the offering.	MinLength: 1 Required: {} Required: {}
`description` string	description explains the offering to a human choosing it.	Optional: {}
`icon` Icon	icon optionally points at an icon for UIs.	Optional: {}
`docs` string	docs optionally links to the offering's documentation.	Optional: {}
`apis` APIRef array	apis lists the exported APIs a binding to this offering syncs, by CRD name on the provider (".").	MinItems: 1 Required: {} Required: {}
`defaults` BindingDefaults	defaults are copied into the generated ClusterBinding of the one-apply bundle.	Optional: {}

ExportStatus

ExportStatus is the observed state of an Export.

Appears in: - Export

Field	Description	Default	Validation
`conditions` Condition array	conditions: Ready (all listed APIs are actually exported).		Optional: {}

Icon

Icon points at an icon image for UIs.

Appears in: - ExportSpec

Field	Description	Default	Validation
`url` string	url of the icon image.		MinLength: 1 Required: {} Required: {}

core.kbind.io/v1alpha1

Package v1alpha1 contains the v2 "slim core" API for kbind: the Connection, ClusterBinding and Binding kinds in the core.kbind.io group. See docs/proposals/v2-slim-core.md for the design.

Resource Types

Binding
ClusterBinding
Connection

APIRef

APIRef identifies an exported API by its CRD name on the provider, i.e. "." (for example "mangodbs.mangodb.io"). Under the OpenAPI schema source there is no CRD object behind the name; it is still just resource + group.

Appears in: - BindingSpec - ExportSpec - GrantSpec

Field	Description	Default	Validation
`name` string	name is the CRD name of the exported API, ".".		MinLength: 1 Required: {} Required: {}

Binding

Binding activates instance sync for one or more exported APIs within its own namespace. Namespaced, following the Role convention. It is the v2 answer to v1's informerScope: Namespaced. Where a ClusterBinding and a Binding cover the same API on the same connection, the ClusterBinding wins.

Field	Description	Validation
`apiVersion` string	`core.kbind.io/v1alpha1`
`kind` string	`Binding`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` BindingSpec		Required: {} Required: {}
`status` BindingStatus		Optional: {}

BindingSpec

BindingSpec is the spec shared by ClusterBinding and Binding. The only difference between the two kinds is scope (cluster-wide vs. one namespace), which is expressed by the kind, not by a field.

Appears in: - Binding - ClusterBinding

Field	Description	Default	Validation
`connectionRef` ConnectionRef	connectionRef points at the Connection that provides the provider link and credentials for the listed APIs.		Required: {} Required: {}
`apis` APIRef array	apis lists one or more exported CRDs to sync, by CRD name on the provider.		MinItems: 1 Required: {} Required: {}
`conflictPolicy` ConflictPolicy	conflictPolicy controls what happens when a target object already exists. Fail (default) leaves a foreign object untouched and records a conflict; Adopt takes ownership of an un-owned object. Adopt never steals an object already carrying another binding's/consumer's markers.	Fail	Enum: [Fail Adopt]
`relatedResources` RelatedResource array	relatedResources are Secrets/ConfigMaps synced alongside instances of the bound APIs. Not yet synced in the alpha POC.		Optional: {}

BindingStatus

BindingStatus is the observed state shared by ClusterBinding and Binding.

Appears in: - Binding - ClusterBinding

Field	Description	Default	Validation
`boundAPIs` BoundAPI array	boundAPIs is per-API observed state.		Optional: {}
`conditions` Condition array	conditions: Connected, Synced, Conflicts, PermissionDenied, Ready.		Optional: {}

BoundAPI

BoundAPI is the per-API observed state recorded on a binding's status.

Appears in: - BindingStatus

Field	Description	Validation
`name` string	name is the CRD name of the bound API, ".".
`crdHash` string	crdHash is a hash of the schema currently applied on the consumer for this API. Empty until the schema has been installed.	Optional: {}
`conflictCount` integer	conflictCount is the number of objects skipped due to foreign ownership. Per-object detail lives on each object's own condition, not here.	Optional: {}

ClusterBinding

ClusterBinding activates instance sync for one or more exported APIs cluster-wide. Cluster-scoped, following the ClusterRole convention.

Field	Description	Validation
`apiVersion` string	`core.kbind.io/v1alpha1`
`kind` string	`ClusterBinding`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` BindingSpec		Required: {} Required: {}
`status` BindingStatus		Optional: {}

ConflictPolicy

Underlying type: string

ConflictPolicy is the behavior for pre-existing target objects.

Appears in: - BindingDefaults - BindingSpec - GrantSpec

Field	Description
`Fail`	ConflictPolicyFail leaves a foreign target object untouched and records the collision as a conflict. This is the default.
`Adopt`	ConflictPolicyAdopt takes ownership of an un-owned target object.

Connection

Connection is the link to one provider cluster. It owns the credentials and schema delivery, and surfaces what the provider exports. Cluster-scoped.

Field	Description	Validation
`apiVersion` string	`core.kbind.io/v1alpha1`
`kind` string	`Connection`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ConnectionSpec		Required: {} Required: {}
`status` ConnectionStatus		Optional: {}

ConnectionRef

ConnectionRef references a Connection by name. Connection is cluster-scoped, so no namespace is needed.

Appears in: - BindingSpec

Field	Description	Default	Validation
`name` string	name of the Connection.		MinLength: 1 Required: {} Required: {}

ConnectionSpec

ConnectionSpec defines the desired provider link.

Appears in: - Connection

Field	Description	Default	Validation
`kubeconfigSecretRef` SecretKeyRef	kubeconfigSecretRef points at the Secret holding the provider kubeconfig. Immutable. The only credential reference in the core.		Required: {} Required: {}
`schema` SchemaPolicy	schema controls how exported APIs reach the consumer.	{ }	Optional: {}
`autoBind` boolean	autoBind, when true, makes the konnector maintain a managed ClusterBinding (named after this Connection) covering all exported APIs.	false

ConnectionStatus

ConnectionStatus is the observed state of a Connection.

Appears in: - Connection

Field	Description	Validation
`remoteClusterUID` string	remoteClusterUID is the identity of the provider cluster, pinned on first connect and immutable thereafter. A Secret later pointing at a different cluster is rejected rather than silently re-homing synced objects.	Optional: {}
`localClusterUID` string	localClusterUID is the identity of the consumer cluster, pinned on first connect and immutable thereafter.	Optional: {}
`activeSchemaSource` SchemaSource	activeSchemaSource is the schema source actually in effect after resolving "Auto" (CRD or OpenAPI). The binding uses it to decide whether the Connection already installed the CRDs (OpenAPI) or it should pull them (CRD).	Optional: {}
`exportedAPIs` ExportedAPI array	exportedAPIs is the discovery result: APIs exported to these credentials.	Optional: {}
`conditions` Condition array	conditions: SecretValid, Connected, SchemaInSync, Ready.	Optional: {}

ExportedAPI

ExportedAPI describes one API the provider exports to these credentials.

Appears in: - ConnectionStatus

Field	Description	Default	Validation
`name` string	name is the CRD name of the exported API, ".".
`group` string	group of the exported API.
`resource` string	resource is the plural resource name of the exported API.
`scope` ResourceScope	scope is whether the API is Namespaced or Cluster scoped.
`versions` string array	versions are the served versions of the exported API.

PullPolicy

Underlying type: string

PullPolicy selects which exported APIs are installed on the consumer.

Appears in: - SchemaPolicy

Field	Description
`Bound`	PullPolicyBound installs only APIs referenced by a binding.
`All`	PullPolicyAll installs every exported API.
`None`	PullPolicyNone never installs CRDs.

RelatedResource

RelatedResource selects auxiliary objects (Secrets/ConfigMaps) to sync alongside the bound instances.

Appears in: - BindingDefaults - BindingSpec - GrantSpec

Field	Description	Validation
`group` string	group of the related resource. Empty string for the core group.
`resource` string	resource is the plural resource name. Only "secrets" and "configmaps" are permitted in core.	Enum: [secrets configmaps] Required: {} Required: {}
`direction` SyncDirection	direction the related resource flows.	Enum: [FromProvider FromConsumer] Required: {} Required: {}
`selector` RelatedResourceSelector	selector restricts which objects are synced. Only labelSelector and named selectors are supported in core (no JSONPath reference-following).	Optional: {}

RelatedResourceSelector

RelatedResourceSelector restricts which related objects are synced.

Appears in: - RelatedResource

Field	Description	Default	Validation
`labelSelector` LabelSelector	labelSelector selects related objects by label.		Optional: {}
`names` string array	names selects related objects by exact name.		Optional: {}

SchemaPolicy

SchemaPolicy controls schema source, pull and update behavior.

Appears in: - ConnectionSpec

Field	Description	Default	Validation
`source` SchemaSource	source selects how schemas are obtained: Auto - CRD if readable on the provider, else OpenAPI (default). CRD - read apiextensions CRDs verbatim. OpenAPI - synthesize CRDs from discovery + /openapi/v3.	Auto	Enum: [Auto CRD OpenAPI]
`pullPolicy` PullPolicy	pullPolicy selects which exported APIs are installed: Bound - only APIs referenced by a Binding/ClusterBinding (default). All - every exported API readable by the credentials. None - never install CRDs (user/extension manages them).	Bound	Enum: [Bound All None]
`updatePolicy` UpdatePolicy	updatePolicy selects whether installed schemas follow provider changes: Always - follow provider schema changes (default). Once - pin at first pull.	Always	Enum: [Always Once]

SchemaSource

Underlying type: string

SchemaSource selects how schemas are obtained from the provider.

Appears in: - ConnectionStatus - SchemaPolicy

Field	Description
`Auto`	SchemaSourceAuto probes CRD first, falls back to OpenAPI.
`CRD`	SchemaSourceCRD reads apiextensions CRDs from the provider.
`OpenAPI`	SchemaSourceOpenAPI synthesizes CRDs from discovery + /openapi/v3.

SecretKeyRef

SecretKeyRef references a key within a Secret. The Secret must live in the konnector's designated namespace; a cluster-scoped Connection may not reach into arbitrary namespaces (privilege-escalation guard, see proposal F1).

Appears in: - ConnectionSpec

Field	Description	Default	Validation
`namespace` string	namespace of the Secret. Must be the konnector's designated namespace.		MinLength: 1 Required: {} Required: {}
`name` string	name of the Secret.		MinLength: 1 Required: {} Required: {}
`key` string	key within the Secret holding the kubeconfig.	kubeconfig

SyncDirection

Underlying type: string

SyncDirection is the direction a related resource is synced.

Appears in: - RelatedResource

Field	Description
`FromProvider`	FromProvider syncs the related resource provider -> consumer.
`FromConsumer`	FromConsumer syncs the related resource consumer -> provider.

UpdatePolicy

Underlying type: string

UpdatePolicy selects whether installed schemas track provider changes.

Appears in: - SchemaPolicy

Field	Description
`Always`	UpdatePolicyAlways follows provider schema changes.
`Once`	UpdatePolicyOnce pins the schema at first pull.

iam.kbind.io/v1alpha1

Package v1alpha1 contains the issuance/identity API for the kbind service layer: the Grant kind in the iam.kbind.io group. A Grant is the typed record of "identity X was issued credentials Y for export Z" — the anchor for revocation, audit and the reaper. Kept out of catalog.kbind.io so that group stays purely presentation+defaults. Lives on the provider; the konnector never sees it. See docs/proposals/v2-extended.md.

Resource Types

Grant

Grant

Grant records that an identity was issued credentials for an export. The gateway creates it with the export's API list and defaults resolved in (issuance is a stable record even if the catalog entry changes later); the issuer controller provisions the tenancy boundary, ServiceAccount, RBAC and token from the spec and reports the artifacts in status. Deleting the Grant revokes: the issuer's cleanup finalizer unwinds everything it provisioned.

Field	Description	Validation
`apiVersion` string	`iam.kbind.io/v1alpha1`
`kind` string	`Grant`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` GrantSpec		Required: {} Required: {}
`status` GrantStatus		Optional: {}

GrantSpec

GrantSpec is the issuance request/record.

Appears in: - Grant

Field	Description	Validation
`identity` Identity	identity is who the credentials were issued to.	Required: {} Required: {}
`exportName` string	exportName records which catalog Export this Grant was issued for.	MinLength: 1 Required: {} Required: {}
`apis` APIRef array	apis is the export's API list resolved at issuance time, by CRD name on the provider ("."). The issuer scopes RBAC to exactly these.	MinItems: 1 Required: {} Required: {}
`conflictPolicy` ConflictPolicy	conflictPolicy is the export's default conflict policy resolved at issuance time, copied into the generated bundle's ClusterBinding.	Enum: [Fail Adopt] Optional: {}
`relatedResources` RelatedResource array	relatedResources are the export's related-resource selectors resolved at issuance time. They flow into the bundle's ClusterBinding and widen the issued RBAC (secrets/configmaps in the declared direction).	Optional: {}

GrantStatus

GrantStatus reports what the issuer provisioned.

Appears in: - Grant

Field	Description	Validation
`namespace` string	namespace is the per-consumer tenancy boundary on the provider.	Optional: {}
`serviceAccount` string	serviceAccount is the name of the issued ServiceAccount (in namespace).	Optional: {}
`tokenSecret` string	tokenSecret is the name of the long-lived SA token Secret (in namespace). The gateway reads it to assemble the bundle's kubeconfig.	Optional: {}
`conditions` Condition array	conditions: Ready (credentials provisioned and token populated).	Optional: {}

Identity

Identity is the consumer identity credentials were issued to. The tenancy key is issuer+"/"+subject, so the same human gets the same boundary on re-bind.

Appears in: - GrantSpec

Field	Description	Validation
`subject` string	subject is the stable identity key, "#" for OIDC.	MinLength: 1 Required: {} Required: {}
`displayName` string	displayName is a human-facing name (e.g. email), informational only.	Optional: {}
`groups` string array	groups the identity carried at issuance, informational only.	Optional: {}