API Reference¶

Packages¶

projection.sh/v1

projection.sh/v1¶

Package v1 contains API Schema definitions for the projection v1 API group

Resource Types¶

Projection
ProjectionList

DestinationRef¶

DestinationRef identifies where the projected object should be written. Invariant: namespace and namespaceSelector are mutually exclusive. Enforced at admission time by the CEL rule below (requires k8s 1.32+) and, as defense-in-depth, also by the reconciler.

Appears in: - ProjectionSpec

Field	Description	Validation
`namespace` string	Namespace to project into. Defaults to the Projection's own namespace. Mutually exclusive with NamespaceSelector.	MaxLength: 63 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` Optional: {}
`namespaceSelector` LabelSelector	NamespaceSelector selects namespaces to project into by label. Mutually exclusive with Namespace.	Optional: {}
`name` string	Name in the destination namespace. Defaults to Source.Name. DNS-1123 subdomain: lowercase alphanumerics, '-', and '.', up to 253 chars.	MaxLength: 253 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$` Optional: {}

Overlay¶

Overlay is applied on top of the source object's metadata before writing to the destination. Overlay entries win on key conflicts with the source.

Appears in: - ProjectionSpec

Field	Description	Default	Validation
`labels` object (keys:string, values:string)	Labels are merged with the source object's metadata.labels before writing to the destination. Keys set here win on conflict with source labels.		Optional: {}
`annotations` object (keys:string, values:string)	Annotations are merged with the source object's metadata.annotations before writing to the destination. Keys set here win on conflict with source annotations. Note: the controller always overwrites projection.sh/owned-by to its own bookkeeping value; attempts to set it here are ignored.		Optional: {}

Projection¶

Projection mirrors one Kubernetes object from a source location to one or more destination namespaces, declaratively and conflict-safely. Source edits propagate to destinations in ~100 ms via dynamic watches. Destinations carry a projection.sh/owned-by annotation the controller uses to refuse overwriting resources it did not create.

Appears in: - ProjectionList

Field	Description	Validation
`apiVersion` string	`projection.sh/v1`
`kind` string	`Projection`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ProjectionSpec
`status` ProjectionStatus

ProjectionList¶

ProjectionList contains a list of Projection.

Field	Description	Validation
`apiVersion` string	`projection.sh/v1`
`kind` string	`ProjectionList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` Projection array

ProjectionSpec¶

ProjectionSpec specifies which source object to mirror, where to write it, and what metadata overlays to apply.

Appears in: - Projection

Field	Description	Validation
`source` SourceRef	Source is the object to project from.
`destination` DestinationRef	Destination controls where the projected object is written.	Optional: {}
`overlay` Overlay	Overlay applies metadata patches on top of the projected object.	Optional: {}

ProjectionStatus¶

ProjectionStatus reports the most recent reconcile outcome via three conditions: SourceResolved, DestinationWritten, and Ready.

Appears in: - Projection

Field	Description	Default	Validation
`conditions` Condition array	Conditions reflect the current state of the projection. The controller sets type "Ready" to True once the destination has been written, or False with a reason describing why not.		Optional: {}

SourceRef¶

SourceRef identifies the Kubernetes object to project from.

Appears in: - ProjectionSpec

Field	Description	Validation
`apiVersion` string	APIVersion of the source object. Three forms accepted: - "v1" — core group, pinned to v1. - "apps/v1" — named group, pinned to v1. - "apps/" — named group, RESTMapper-preferred served version. The unpinned form follows the cluster: when a CRD author promotes v1beta1→v1, projection picks up the new preferred version on the next reconcile rather than reporting SourceResolutionFailed. The "" sentinel is invalid without a group prefix (no "*" form for the core group, which has stable versions); enforced in the reconciler since the regex is permissive for simplicity.	MinLength: 1 Pattern: `^([a-z0-9.-]+/)?(v[0-9]+((alpha\\|beta)[0-9]+)?\\|\*)$` Required: {}
`kind` string	Kind of the source object, e.g. "ConfigMap".	MinLength: 1 Pattern: `^[A-Z][A-Za-z0-9]*$` Required: {}
`name` string	Name of the source object. DNS-1123 subdomain: lowercase alphanumerics, '-', and '.', up to 253 chars. Matches the permissive form Kubernetes uses for most named objects (ConfigMap, Secret, Deployment, Pod, …).	MaxLength: 253 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$` Required: {}
`namespace` string	Namespace of the source object.	MaxLength: 63 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` Required: {}