Skip to content

api-reference.md

Latest commit

 

History

History
272 lines (149 loc) · 13.5 KB

api-reference.md

File metadata and controls

272 lines (149 loc) · 13.5 KB

API Reference

Packages

projection.sh/v1

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

Resource Types

ClusterProjection

ClusterProjection mirrors one source object into many destination namespaces.

Appears in:

Field Description Default Validation
apiVersion string projection.sh/v1
kind string ClusterProjection
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 ClusterProjectionSpec
status ClusterProjectionStatus

ClusterProjectionDestination

ClusterProjectionDestination is the cluster-scoped destination spec.

namespaces and namespaceSelector are mutually exclusive (CEL admission) and at least one must be set.

Appears in:

Field Description Default Validation
namespaces string array Namespaces is an explicit list of destination namespaces. Mutually
exclusive with NamespaceSelector. Each entry is a DNS-1123 label;
at least one entry is required when this field is set.		 MinItems: 1
Optional: {}
namespaceSelector LabelSelector NamespaceSelector picks destination namespaces by label. Mutually
exclusive with Namespaces.		 Optional: {}
name string Name in each destination namespace (DNS-1123 subdomain). Defaults to
Source.Name when empty. The same Name is written into every targeted
namespace.		 MaxLength: 253
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional: {}

ClusterProjectionList

ClusterProjectionList contains a list of ClusterProjection.

Field Description Default Validation
apiVersion string projection.sh/v1
kind string ClusterProjectionList
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 ClusterProjection array

ClusterProjectionSpec

ClusterProjectionSpec is the desired state of a cluster-scoped Projection.

A ClusterProjection fans out one source object into many namespaces selected by either an explicit list or a label selector. Cluster-tier authority is required to create one — the chart does NOT aggregate the clusterprojections CRUD verbs into the built-in admin/edit roles.

Appears in:

Field Description Default Validation
source SourceRef Source identifies the object to project.
destination ClusterProjectionDestination Destination configures the fan-out target set and optional rename.
overlay Overlay Overlay applies metadata patches uniformly to every projected copy.
(Per-target overlays are not supported in v0.3.)		 Optional: {}

ClusterProjectionStatus

ClusterProjectionStatus reports the rollup of the most recent reconcile.

Appears in:

Field Description Default Validation
conditions Condition array Conditions: SourceResolved, DestinationWritten, Ready. Optional: {}
destinationName string DestinationName is the resolved name of the destination object,
identical across all targeted namespaces. Populated after the first
successful write; empty before that.		 Optional: {}
namespacesWritten integer NamespacesWritten is the count of namespaces in which the destination
was successfully created or updated during the most recent reconcile.		 Optional: {}
namespacesFailed integer NamespacesFailed is the count of namespaces where the write failed
during the most recent reconcile. The DestinationWritten condition's
message carries a (truncated) list of failed namespace names.		 Optional: {}

Overlay

Overlay applies metadata patches to the projected object on top of what the source carries. Only labels and annotations are mergeable — name and namespace cannot be touched (they are set by the controller from the destination spec).

Appears in:

Field Description Default Validation
labels object (keys:string, values:string) Labels are merged onto the destination's metadata.labels. Overlay
entries win on key conflicts with the source (overlay-last semantics);
source-only and overlay-only keys are kept as-is.		 Optional: {}
annotations object (keys:string, values:string) Annotations are merged onto the destination's metadata.annotations.
Same overlay-wins merge rule as Labels.		 Optional: {}

Projection

Projection mirrors one source object into the Projection's own namespace.

Appears in:

Field Description Default 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

ProjectionDestination

ProjectionDestination configures the rename override for a namespaced Projection.

Appears in:

Field Description Default Validation
name string Name in the destination namespace (DNS-1123 subdomain). Defaults to
Source.Name when empty.		 MaxLength: 253
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional: {}

ProjectionList

ProjectionList contains a list of Projection.

Field Description Default 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 is the desired state of a namespaced Projection.

A Projection mirrors one source object into the Projection's own namespace. It cannot write outside its own namespace — that is what ClusterProjection is for. This narrowness is deliberate: it makes namespace-scoped RBAC on projections.projection.sh a structural confinement, not a policy hint.

Appears in:

Field Description Default Validation
source SourceRef Source identifies the object to project.
destination ProjectionDestination Destination optionally renames the destination. The destination
namespace is implicitly the Projection's own namespace and cannot
be set; for cross-namespace mirroring use ClusterProjection.		 Optional: {}
overlay Overlay Overlay applies metadata patches on top of the projected object. Optional: {}

ProjectionStatus

ProjectionStatus reports the most recent reconcile outcome.

Appears in:

Field Description Default Validation
conditions Condition array Conditions: SourceResolved, DestinationWritten, Ready. Optional: {}
destinationName string DestinationName is the resolved name of the destination object after
applying any rename override (spec.destination.name) or defaulting to
spec.source.name. Populated by the controller after a successful
write; empty before the first reconcile completes.		 Optional: {}

SourceRef

SourceRef identifies the object to project.

Group + Version + Kind name the GVK; Namespace + Name name the object.

Both group and version may be omitted. Empty group means the core group (e.g. ConfigMap, Secret, Service). Empty version means the operator resolves the preferred served version via the RESTMapper on every reconcile, so the source automatically follows version promotions (e.g. CRD v1beta1 → v1; or, hypothetically, core v1 → v2). Set version explicitly to pin.

Appears in:

Field Description Default Validation
group string Group is the API group of the source object. Empty string means the
core group (e.g. ConfigMap, Secret, Service).		 Pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
Optional: {}
version string Version is the API version of the source object within its Group. Omit
to use the RESTMapper's preferred served version (the source
automatically follows version promotions). When set, must match
Kubernetes' canonical version-string shape (vN, vNalphaM,
vNbetaM).		 Pattern: ^$|^v[0-9]+((alpha|beta)[0-9]+)?$
Optional: {}
kind string Kind is the API Kind of the source object (PascalCase). Pattern: ^[A-Z][a-zA-Z0-9]*$
namespace string Namespace where the source object lives. MaxLength: 63
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
name string Name of the source object (DNS-1123 subdomain). MaxLength: 253
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$