API Reference
The Package Operator APIs are an extension of the Kubernetes API using CustomResourceDefinitions
. These new APIs can be interacted with like any other Kubernetes object using e.g. kubectl
.
APIs follow the same API versioning guidelines as the main Kubernetes project.
Versioning principles.
Taken from the Kubernetes API versioning documentation:
Alpha
- The version names contain alpha (for example,
v1alpha1
). - The software may contain bugs. Enabling a feature may expose bugs. A feature may be disabled by default.
- The support for a feature may be dropped at any time without notice.
- The API may change in incompatible ways in a later software release without notice.
- The software is recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
- The version names contain alpha (for example,
Beta
- The version names contain beta (for example,
v2beta3
). - The software is well tested. Enabling a feature is considered safe. Features are enabled by default.
- The support for a feature will not be dropped, though the details may change.
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, migration instructions are provided. Schema changes may require deleting, editing, and re-creating API objects. The editing process may not be straightforward. The migration may require downtime for applications that rely on the feature.
- The software is not recommended for production uses. Subsequent releases may introduce incompatible changes. If you have multiple clusters which can be upgraded independently, you may be able to relax this restriction.
- The version names contain beta (for example,
Stable
- The version name is
vX
whereX
is an integer. - The stable versions of features appear in released software for many subsequent versions.
- The version name is
Group versions
package-operator.run/v1alpha1
Package v1alpha1 contains API Schema definitions for the v1alpha1 version of the core Package Operator API group, containing basic building blocks that other auxiliary APIs can build on top of.
- ClusterObjectDeployment
- ClusterObjectSet
- ClusterObjectSetPhase
- ClusterObjectSlice
- ClusterObjectTemplate
- ClusterPackage
- ObjectDeployment
- ObjectSet
- ObjectSetPhase
- ObjectSlice
- ObjectTemplate
- Package
ClusterObjectDeployment
ClusterObjectDeployment is the Schema for the ClusterObjectDeployments API
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectDeployment
metadata:
name: example
spec:
paused: true
revisionHistoryLimit: 10
selector:
matchLabels:
test: test
template:
metadata:
labels:
test: test
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
phases:
- class: ipsum
name: lorem
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: sit
sourceType: dolor
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
slices:
- amet
successDelaySeconds: 42
status:
collisionCount: 42
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
controllerOf:
- group: elitr
kind: sadipscing
name: sed
namespace: diam
revision: 42
templateHash: consetetur
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ClusterObjectDeploymentSpec | ClusterObjectDeploymentSpec defines the desired state of a ClusterObjectDeployment. |
status ClusterObjectDeploymentStatus | ClusterObjectDeploymentStatus defines the observed state of a ClusterObjectDeployment. |
ClusterObjectSet
ClusterObjectSet reconciles a collection of objects through ordered phases and aggregates their status.
ClusterObjectSets behave similarly to Kubernetes ReplicaSets, by managing a collection of objects and being itself mostly immutable. This object type is able to suspend/pause reconciliation of specific objects to facilitate the transition between revisions.
Archived ClusterObjectSets may stay on the cluster, to store information about previous revisions.
A Namespace-scoped version of this API is available as ObjectSet.
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectSet
metadata:
name: example
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
lifecycleState: Active
phases:
- class: eirmod
name: nonumy
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: lorem
sourceType: tempor
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
slices:
- ipsum
previous:
- name: previous-revision
successDelaySeconds: 42
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
controllerOf:
- group: amet
kind: sit
name: consetetur
namespace: sadipscing
remotePhases:
- name: dolor
uid: 3490a790-05f8-4bd7-8333-1001c49fccd2
revision: 42
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ClusterObjectSetSpec | ClusterObjectSetSpec defines the desired state of a ClusterObjectSet. |
status ClusterObjectSetStatus | ClusterObjectSetStatus defines the observed state of a ClusterObjectSet. |
ClusterObjectSetPhase
ClusterObjectSetPhase is an internal API, allowing a ClusterObjectSet to delegate a
single phase to another custom controller. ClusterObjectSets will create subordinate
ClusterObjectSetPhases when .class
is set within the phase specification.
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectSetPhase
metadata:
name: example
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: sed
sourceType: elitr
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
paused: true
previous:
- name: previous-revision
revision: 42
status:
conditions:
- status: "True"
type: Available
controllerOf:
- group: nonumy
kind: diam
name: eirmod
namespace: tempor
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ClusterObjectSetPhaseSpec | ClusterObjectSetPhaseSpec defines the desired state of a ClusterObjectSetPhase. |
status ClusterObjectSetPhaseStatus | ClusterObjectSetPhaseStatus defines the observed state of a ClusterObjectSetPhase. |
ClusterObjectSlice
ClusterObjectSlice is referenced by ObjectSets or ObjectDeployments and contain objects to limit the size of ObjectSet and ObjectDeployments when big packages are installed. This is necessary to work around the etcd object size limit of ~1.5MiB and to reduce load on the kube-apiserver.
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectSlice
metadata:
name: example
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: ipsum
sourceType: lorem
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
objects required[]ObjectSetObject |
ClusterObjectTemplate
ClusterObjectTemplate contain a go template of a Kubernetes manifest. The manifest is then templated with the sources provided in the .Spec.Sources. The sources can come from objects from any namespace or cluster scoped objects.
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectTemplate
metadata:
name: example
spec:
sources:
- apiVersion: sit
items:
- destination: sed
key: elitr
kind: amet
name: sadipscing
namespace: consetetur
optional: true
template: dolor
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
controllerOf:
group: nonumy
kind: diam
name: eirmod
namespace: tempor
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ObjectTemplateSpec | ObjectTemplateSpec specification. |
status ObjectTemplateStatus | ObjectTemplateStatus defines the observed state of a ObjectTemplate ie the status of the templated object. |
ClusterPackage
ClusterPackage defines a cluster scoped package installation.
Example
apiVersion: package-operator.run/v1alpha1
kind: ClusterPackage
metadata:
name: example
spec:
component: ipsum
config: {}
image: lorem
paused: true
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
revision: 42
unpackedHash: dolor
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec PackageSpec | PackageSpec specifies a package. |
status PackageStatus | PackageStatus defines the observed state of a Package. |
ObjectDeployment
ObjectDeployment is the Schema for the ObjectDeployments API
Example
apiVersion: package-operator.run/v1alpha1
kind: ObjectDeployment
metadata:
name: example
namespace: default
spec:
paused: true
revisionHistoryLimit: 10
selector:
matchLabels:
test: test
template:
metadata:
labels:
test: test
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
phases:
- class: amet
name: sit
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: sadipscing
sourceType: consetetur
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
slices:
- elitr
successDelaySeconds: 42
status:
collisionCount: 42
conditions:
- message: ""
reason: Available
status: "True"
type: Available
controllerOf:
- group: nonumy
kind: diam
name: eirmod
namespace: tempor
revision: 42
templateHash: sed
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ObjectDeploymentSpec | ObjectDeploymentSpec defines the desired state of an ObjectDeployment. |
status ObjectDeploymentStatus | ObjectDeploymentStatus defines the observed state of an ObjectDeployment. |
ObjectSet
ObjectSet reconciles a collection of objects through ordered phases and aggregates their status.
ObjectSets behave similarly to Kubernetes ReplicaSets, by managing a collection of objects and being itself mostly immutable. This object type is able to suspend/pause reconciliation of specific objects to facilitate the transition between revisions.
Archived ObjectSets may stay on the cluster, to store information about previous revisions.
A Cluster-scoped version of this API is available as ClusterObjectSet.
Example
apiVersion: package-operator.run/v1alpha1
kind: ObjectSet
metadata:
name: example
namespace: default
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
lifecycleState: Active
phases:
- class: ipsum
name: lorem
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: sit
sourceType: dolor
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
slices:
- amet
previous:
- name: previous-revision
successDelaySeconds: 42
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
controllerOf:
- group: elitr
kind: sadipscing
name: sed
namespace: diam
remotePhases:
- name: consetetur
uid: 3490a790-05f8-4bd7-8333-1001c49fccd2
revision: 42
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ObjectSetSpec | ObjectSetSpec defines the desired state of a ObjectSet. |
status ObjectSetStatus | ObjectSetStatus defines the observed state of a ObjectSet. |
ObjectSetPhase
ObjectSetPhase is an internal API, allowing an ObjectSet to delegate a single phase to another custom controller.
ObjectSets will create subordinate ObjectSetPhases when .class
within the phase specification is set.
Example
apiVersion: package-operator.run/v1alpha1
kind: ObjectSetPhase
metadata:
name: example
namespace: default
spec:
availabilityProbes:
- probes:
- cel:
message: Object must be named Hans
rule: self.metadata.name == "Hans"
condition:
status: "True"
type: Available
fieldsEqual:
fieldA: .spec.fieldA
fieldB: .status.fieldB
selector:
kind:
group: apps
kind: Deployment
selector:
matchLabels:
app.kubernetes.io/name: example-operator
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: eirmod
sourceType: nonumy
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
paused: true
previous:
- name: previous-revision
revision: 42
status:
conditions:
- status: "True"
type: Available
controllerOf:
- group: lorem
kind: tempor
name: ipsum
namespace: dolor
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ObjectSetPhaseSpec | ObjectSetPhaseSpec defines the desired state of a ObjectSetPhase. |
status ObjectSetPhaseStatus | ObjectSetPhaseStatus defines the observed state of a ObjectSetPhase. |
ObjectSlice
ObjectSlice is referenced by ObjectSets or ObjectDeployments and contain objects to limit the size of ObjectSets and ObjectDeployments when big packages are installed. This is necessary to work around the etcd object size limit of ~1.5MiB and to reduce load on the kube-apiserver.
Example
apiVersion: package-operator.run/v1alpha1
kind: ObjectSlice
metadata:
name: example
namespace: default
objects:
- collisionProtection: Prevent
conditionMappings:
- destinationType: amet
sourceType: sit
object:
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-deployment
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
objects required[]ObjectSetObject |
ObjectTemplate
ObjectTemplate contain a go template of a Kubernetes manifest. This manifest is then templated with the sources provided in the .Spec.Sources. The sources can only come from objects within the same nampespace as the ObjectTemplate.
Example
apiVersion: package-operator.run/v1alpha1
kind: ObjectTemplate
metadata:
name: example
namespace: default
spec:
sources:
- apiVersion: sadipscing
items:
- destination: eirmod
key: nonumy
kind: elitr
name: diam
namespace: sed
optional: true
template: consetetur
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
controllerOf:
group: lorem
kind: tempor
name: ipsum
namespace: dolor
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec ObjectTemplateSpec | ObjectTemplateSpec specification. |
status ObjectTemplateStatus | ObjectTemplateStatus defines the observed state of a ObjectTemplate ie the status of the templated object. |
Package
Package defines a namespaced package installationn.
Example
apiVersion: package-operator.run/v1alpha1
kind: Package
metadata:
name: example
namespace: default
spec:
component: amet
config: {}
image: sit
paused: true
status:
conditions:
- message: Latest Revision is Available.
reason: Available
status: "True"
type: Available
revision: 42
unpackedHash: consetetur
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec PackageSpec | PackageSpec specifies a package. |
status PackageStatus | PackageStatus defines the observed state of a Package. |
ClusterObjectDeploymentSpec
ClusterObjectDeploymentSpec defines the desired state of a ClusterObjectDeployment.
Field | Description |
---|---|
revisionHistoryLimit int32 | Number of old revisions in the form of archived ObjectSets to keep. |
selector requiredmetav1.LabelSelector | Selector targets ObjectSets managed by this Deployment. |
template requiredObjectSetTemplate | Template to create new ObjectSets from. |
paused bool | If Paused is true, the object and its children will not be reconciled. |
Used in:
ClusterObjectDeploymentStatus
ClusterObjectDeploymentStatus defines the observed state of a ClusterObjectDeployment.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
collisionCount int32 | Count of hash collisions of the ClusterObjectDeployment. |
templateHash string | Computed TemplateHash. |
revision int64 | Deployment revision. |
controllerOf []ControlledObjectReference | ControllerOf references the owned ClusterObjectSet revisions. |
Used in:
ClusterObjectSetPhaseSpec
ClusterObjectSetPhaseSpec defines the desired state of a ClusterObjectSetPhase.
Field | Description |
---|---|
paused bool | Disables reconciliation of the ClusterObjectSet. Only Status updates will still be propagated, but object changes will not be reconciled. |
revision requiredint64 | Revision of the parent ObjectSet to use during object adoption. |
previous []PreviousRevisionReference | Previous revisions of the ClusterObjectSet to adopt objects from. |
availabilityProbes []ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
objects required[]ObjectSetObject | Objects belonging to this phase. |
Used in:
ClusterObjectSetPhaseStatus
ClusterObjectSetPhaseStatus defines the observed state of a ClusterObjectSetPhase.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
controllerOf []ControlledObjectReference | References all objects controlled by this instance. |
Used in:
ClusterObjectSetSpec
ClusterObjectSetSpec defines the desired state of a ClusterObjectSet.
Field | Description |
---|---|
lifecycleState ObjectSetLifecycleState | Specifies the lifecycle state of the ClusterObjectSet. |
previous []PreviousRevisionReference | Previous revisions of the ClusterObjectSet to adopt objects from. |
phases []ObjectSetTemplatePhase | Reconcile phase configuration for a ObjectSet. Phases will be reconciled in order and the contained objects checked against given probes before continuing with the next phase. |
availabilityProbes []ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
successDelaySeconds int32 | Success Delay Seconds applies a wait period from the time an Object Set is available to the time it is marked as successful. This can be used to prevent false reporting of success when the underlying objects may initially satisfy the availability probes, but are ultimately unstable. |
Used in:
ClusterObjectSetStatus
ClusterObjectSetStatus defines the observed state of a ClusterObjectSet.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
revision int64 | Computed revision number, monotonically increasing. |
remotePhases []RemotePhaseReference | Remote phases aka ClusterObjectSetPhase objects. |
controllerOf []ControlledObjectReference | References all objects controlled by this instance. |
Used in:
ConditionMapping
ConditionMapping maps one condition type to another.
Field | Description |
---|---|
sourceType requiredstring | Source condition type. |
destinationType requiredstring | Destination condition type to report into Package Operator APIs. |
Used in:
ControlledObjectReference
ControlledObjectReference an object controlled by this object.
Field | Description |
---|---|
kind requiredstring | Object Kind. |
group requiredstring | Object Group. |
name requiredstring | Object Name. |
namespace string | Object Namespace. |
Used in:
- ClusterObjectDeploymentStatus
- ClusterObjectSetPhaseStatus
- ClusterObjectSetStatus
- ObjectDeploymentStatus
- ObjectSetPhaseStatus
- ObjectSetStatus
- ObjectTemplateStatus
ObjectDeploymentSpec
ObjectDeploymentSpec defines the desired state of an ObjectDeployment.
Field | Description |
---|---|
revisionHistoryLimit int32 | Number of old revisions in the form of archived ObjectSets to keep. |
selector requiredmetav1.LabelSelector | Selector targets ObjectSets managed by this Deployment. |
template requiredObjectSetTemplate | Template to create new ObjectSets from. |
paused bool | If Paused is true, the object and its children will not be reconciled. |
Used in:
ObjectDeploymentStatus
ObjectDeploymentStatus defines the observed state of an ObjectDeployment.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
collisionCount int32 | Count of hash collisions of the ObjectDeployment. |
templateHash string | Computed TemplateHash. |
revision int64 | Deployment revision. |
controllerOf []ControlledObjectReference | ControllerOf references the owned ObjectSet revisions. |
Used in:
ObjectSetObject
ObjectSetObject is an object that is part of the phase of an ObjectSet.
Field | Description |
---|---|
object requiredunstructured.Unstructured | |
collisionProtection CollisionProtection | Collision protection prevents Package Operator from working on objects already under management by a different operator. |
conditionMappings []ConditionMapping | Maps conditions from this object into the Package Operator APIs. |
Used in:
ObjectSetPhaseSpec
ObjectSetPhaseSpec defines the desired state of a ObjectSetPhase.
Field | Description |
---|---|
paused bool | Disables reconciliation of the ObjectSet. Only Status updates will still be propagated, but object changes will not be reconciled. |
revision requiredint64 | Revision of the parent ObjectSet to use during object adoption. |
previous []PreviousRevisionReference | Previous revisions of the ObjectSet to adopt objects from. |
availabilityProbes []ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
objects required[]ObjectSetObject | Objects belonging to this phase. |
Used in:
ObjectSetPhaseStatus
ObjectSetPhaseStatus defines the observed state of a ObjectSetPhase.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
controllerOf []ControlledObjectReference | References all objects controlled by this instance. |
Used in:
ObjectSetProbe
ObjectSetProbe define how ObjectSets check their children for their status.
Field | Description |
---|---|
probes required[]Probe | Probe configuration parameters. |
selector requiredProbeSelector | Selector specifies which objects this probe should target. |
Used in:
ObjectSetSpec
ObjectSetSpec defines the desired state of a ObjectSet.
Field | Description |
---|---|
lifecycleState ObjectSetLifecycleState | Specifies the lifecycle state of the ObjectSet. |
previous []PreviousRevisionReference | Previous revisions of the ObjectSet to adopt objects from. |
phases []ObjectSetTemplatePhase | Reconcile phase configuration for a ObjectSet. Phases will be reconciled in order and the contained objects checked against given probes before continuing with the next phase. |
availabilityProbes []ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
successDelaySeconds int32 | Success Delay Seconds applies a wait period from the time an Object Set is available to the time it is marked as successful. This can be used to prevent false reporting of success when the underlying objects may initially satisfy the availability probes, but are ultimately unstable. |
Used in:
ObjectSetStatus
ObjectSetStatus defines the observed state of a ObjectSet.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
revision int64 | Computed revision number, monotonically increasing. |
remotePhases []RemotePhaseReference | Remote phases aka ObjectSetPhase objects. |
controllerOf []ControlledObjectReference | References all objects controlled by this instance. |
Used in:
ObjectSetTemplate
ObjectSetTemplate describes the template to create new ObjectSets from.
Field | Description |
---|---|
metadata requiredmetav1.ObjectMeta | Common Object Metadata. |
spec requiredObjectSetTemplateSpec | ObjectSet specification. |
Used in:
ObjectSetTemplatePhase
ObjectSetTemplatePhase configures the reconcile phase of ObjectSets.
Field | Description |
---|---|
name requiredstring | Name of the reconcile phase. Must be unique within a ObjectSet. |
class string | If non empty, the ObjectSet controller will delegate phase reconciliation to another controller, by creating an ObjectSetPhase object. If set to the string “default” the built-in Package Operator ObjectSetPhase controller will reconcile the object in the same way the ObjectSet would. If set to any other string, an out-of-tree controller needs to be present to handle ObjectSetPhase objects. |
objects []ObjectSetObject | Objects belonging to this phase. |
slices []string | References to ObjectSlices containing objects for this phase. |
Used in:
ObjectSetTemplateSpec
ObjectSetTemplateSpec defines an object set. WARNING: when modifying fields in ObjectSetTemplateSpec also update validation rules in (Cluster)ObjectSetSpec.
Field | Description |
---|---|
phases []ObjectSetTemplatePhase | Reconcile phase configuration for a ObjectSet. Phases will be reconciled in order and the contained objects checked against given probes before continuing with the next phase. |
availabilityProbes []ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
successDelaySeconds int32 | Success Delay Seconds applies a wait period from the time an Object Set is available to the time it is marked as successful. This can be used to prevent false reporting of success when the underlying objects may initially satisfy the availability probes, but are ultimately unstable. |
Used in:
ObjectTemplateSource
ObjectTemplateSource defines a source for a template.
Field | Description |
---|---|
apiVersion requiredstring | |
kind requiredstring | |
namespace string | |
name requiredstring | |
items required[]ObjectTemplateSourceItem | |
optional bool | Marks this source as optional. The templated object will still be applied if optional sources are not found. If the source object is created later on, it will be eventually picked up. |
Used in:
ObjectTemplateSourceItem
ObjectTemplateSourceItem defines a source item for an object template.
Field | Description |
---|---|
key requiredstring | JSONPath to value in source object. |
destination requiredstring | JSONPath to destination in which to store copy of the source value. |
Used in:
ObjectTemplateSpec
ObjectTemplateSpec specification.
Field | Description |
---|---|
template requiredstring | Go template of a Kubernetes manifest |
sources required[]ObjectTemplateSource | Objects in which configuration parameters are fetched |
Used in:
ObjectTemplateStatus
ObjectTemplateStatus defines the observed state of a ObjectTemplate ie the status of the templated object.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions the templated object is in. |
controllerOf ControlledObjectReference | ControllerOf references the templated object. |
Used in:
PackageProbeKindSpec
PackageProbeKindSpec package probe parameters. selects objects based on Kind and API Group.
Field | Description |
---|---|
group requiredstring | Object Group to apply a probe to. |
kind requiredstring | Object Kind to apply a probe to. |
Used in:
PackageSpec
PackageSpec specifies a package.
Field | Description |
---|---|
image requiredstring | the image containing the contents of the package this image will be unpacked by the package-loader to render the ObjectDeployment for propagating the installation of the package. |
config runtime.RawExtension | Package configuration parameters. |
component string | Desired component to deploy from multi-component packages. |
paused bool | If Paused is true, the package and its children will not be reconciled. |
Used in:
PackageStatus
PackageStatus defines the observed state of a Package.
Field | Description |
---|---|
conditions []metav1.Condition | Conditions is a list of status conditions ths object is in. |
unpackedHash string | Hash of image + config that was successfully unpacked. |
revision int64 | Package revision as reported by the ObjectDeployment. |
Used in:
PreviousRevisionReference
PreviousRevisionReference references a previous revision of an ObjectSet or ClusterObjectSet.
Field | Description |
---|---|
name requiredstring | Name of a previous revision. |
Used in:
Probe
Probe defines probe parameters. Only one can be filled.
Field | Description |
---|---|
condition ProbeConditionSpec | ProbeConditionSpec checks whether or not the object reports a condition with given type and status. |
fieldsEqual ProbeFieldsEqualSpec | ProbeFieldsEqualSpec compares two fields specified by JSON Paths. |
cel ProbeCELSpec | ProbeCELSpec uses Common Expression Language (CEL) to probe an object. CEL rules have to evaluate to a boolean to be valid. See: https://kubernetes.io/docs/reference/using-api/cel https://github.com/google/cel-go |
Used in:
ProbeCELSpec
ProbeCELSpec uses Common Expression Language (CEL) to probe an object. CEL rules have to evaluate to a boolean to be valid. See: https://kubernetes.io/docs/reference/using-api/cel https://github.com/google/cel-go
Field | Description |
---|---|
rule requiredstring | CEL rule to evaluate. |
message requiredstring | Error message to output if rule evaluates to false. |
Used in:
ProbeConditionSpec
ProbeConditionSpec checks whether or not the object reports a condition with given type and status.
Field | Description |
---|---|
type requiredstring | Condition type to probe for. |
status requiredstring | Condition status to probe for. |
Used in:
ProbeFieldsEqualSpec
ProbeFieldsEqualSpec compares two fields specified by JSON Paths.
Field | Description |
---|---|
fieldA requiredstring | First field for comparison. |
fieldB requiredstring | Second field for comparison. |
Used in:
ProbeSelector
ProbeSelector selects a subset of objects to apply probes to. e.g. ensures that probes defined for apps/Deployments are not checked against ConfigMaps.
Field | Description |
---|---|
kind requiredPackageProbeKindSpec | Kind and API Group of the object to probe. |
selector metav1.LabelSelector | Further sub-selects objects based on a Label Selector. |
Used in:
RemotePhaseReference
RemotePhaseReference remote phases aka ObjectSetPhase/ClusterObjectSetPhase objects to which a phase is delegated.
Field | Description |
---|---|
name requiredstring | |
uid requiredtypes.UID |
Used in:
manifests.package-operator.run/v1alpha1
Package v1alpha1 contains API Schema definitions for the v1alpha1 version of the manifests API group, containing file-based manifests for the packaging infrastructure.
PackageManifest
PackageManifest defines the manifest of a package.
Example
apiVersion: manifests.package-operator.run/v1alpha1
kind: PackageManifest
metadata:
name: example
namespace: default
spec:
availabilityProbes: []
components: {}
config:
openAPIV3Schema:
properties:
testProp:
type: string
type: object
constraints:
- platform:
- Kubernetes
platformVersion:
name: Kubernetes
range: '>=1.20.x'
uniqueInScope: {}
dependencies:
- image:
name: my-pkg
package: my-pkg.my-repo
range: '>=2.1'
filter:
conditions:
- expression: has(environment.openShift)
name: isOpenShift
paths:
- expression: cond.isOpenShift && environment.openShift.version.startsWith('4.15')
glob: openshift/v4.15/**
images:
- image: quay.io/package-operator/test-stub:v1.11.0
name: test-stub
phases:
- class: hosted-cluster
name: deploy
repositories:
- file: ../myrepo.yaml
image: quay.io/package-operator/my-repo:latest
scopes:
- Cluster
- Namespaced
test:
kubeconform:
kubernetesVersion: v1.29.5
schemaLocations:
- https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{.NormalizedKubernetesVersion}}-standalone{{.StrictSuffix}}/{{.ResourceKind}}{{.KindSuffix}}.json
template:
- context:
config:
testProp: Hans
environment:
hyperShift:
hostedCluster:
hostedClusterNamespace: clusters-banana
metadata:
name: banana
namespace: clusters
kubernetes:
version: v1.29.5
openShift:
managed:
data:
test: test
version: v4.13.2
proxy:
httpProxy: http://proxy_server_address:port
httpsProxy: https://proxy_server_address:port
noProxy: .example.com,.local,localhost
package:
image: quay.io/package-operator/test-stub-package:v1.11.0
metadata:
name: test
name: lorem
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec PackageManifestSpec | PackageManifestSpec represents the spec of the packagemanifest containing the details about phases and availability probes. |
test PackageManifestTest | PackageManifestTest configures test cases. |
PackageManifestLock
PackageManifestLock allows locking packages to specific versions.
Example
apiVersion: manifests.package-operator.run/v1alpha1
kind: PackageManifestLock
metadata:
name: example
namespace: default
spec:
dependencies:
- digest: sha256:00e48c32b3cdcf9e2c66467f2beb0ef33b43b54e2b56415db4ee431512c406ea
image: quay.io/package-operator/remote-phase-package
name: my-pkg
version: v1.12.3
images:
- digest: sha256:00e48c32b3cdcf9e2c66467f2beb0ef33b43b54e2b56415db4ee431512c406ea
image: quay.io/package-operator/remote-phase-package
name: my-pkg
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
spec PackageManifestLockSpec | PackageManifestLockSpec defines a set of packages that are locked to a specific version. |
Repository
Repository is the k8s resource that represents a package repository.
Example
apiVersion: manifests.package-operator.run/v1alpha1
kind: Repository
metadata:
name: example
namespace: default
Field | Description |
---|---|
metadata metav1.ObjectMeta |
RepositoryEntry
RepositoryEntry contains metadata on one image belonging to the repository.
Example
apiVersion: manifests.package-operator.run/v1alpha1
data:
constraints:
- platform:
- Kubernetes
platformVersion:
name: Kubernetes
range: '>=1.20.x'
uniqueInScope: {}
digest: dolor
image: ipsum
name: amet
versions:
- sit
kind: RepositoryEntry
metadata:
name: example
namespace: default
Field | Description |
---|---|
metadata metav1.ObjectMeta | |
data requiredRepositoryEntryData | RepositoryEntryData is the part of RepositoryEntry containing the actual data. |
PackageEnvironment
PackageEnvironment information.
Field | Description |
---|---|
kubernetes requiredPackageEnvironmentKubernetes | Kubernetes environment information. This section is always set. |
openShift PackageEnvironmentOpenShift | OpenShift environment information. This section is only set when OpenShift is detected. |
proxy PackageEnvironmentProxy | Proxy configuration. Only available on OpenShift when the cluster-wide Proxy is enabled. https://docs.openshift.com/container-platform/latest/networking/enable-cluster-wide-proxy.html |
hyperShift PackageEnvironmentHyperShift | HyperShift specific information. Only available when installed alongside HyperShift. https://github.com/openshift/hypershift |
Used in:
PackageEnvironmentHyperShift
PackageEnvironmentHyperShift contains HyperShift specific information. Only available when installed alongside HyperShift. https://github.com/openshift/hypershift
Field | Description |
---|---|
hostedCluster requiredPackageEnvironmentHyperShiftHostedCluster | Contains HyperShift HostedCluster specific information. This information is only available when installed alongside HyperShift within a HostedCluster Namespace. https://github.com/openshift/hypershift |
Used in:
PackageEnvironmentHyperShiftHostedCluster
PackageEnvironmentHyperShiftHostedCluster contains HyperShift HostedCluster specific information. This information is only available when installed alongside HyperShift within a HostedCluster Namespace. https://github.com/openshift/hypershift
Field | Description |
---|---|
metadata requiredTemplateContextObjectMeta | TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates. |
hostedClusterNamespace requiredstring | The control-plane namespace of this hosted cluster. Note: This should actually be named HostedControlPlaneNamespace, but renaming would change our template API. |
nodeSelector map[string]string | NodeSelector when specified in HostedCluster.spec.nodeSelector, is propagated to all control plane Deployments and Stateful sets running management side. Note: Upstream docs of this field specify that changing it will re-deploy existing control-plane workloads. This is not something that PKO currently supports. |
Used in:
PackageEnvironmentKubernetes
PackageEnvironmentKubernetes configures kubernetes environments.
Field | Description |
---|---|
version requiredstring | Kubernetes server version. |
Used in:
PackageEnvironmentManagedOpenShift
PackageEnvironmentManagedOpenShift describes managed OpenShift environments.
Field | Description |
---|---|
data requiredmap[string]string | Data key-value pairs describing details of the Managed OpenShift environment. |
Used in:
PackageEnvironmentOpenShift
PackageEnvironmentOpenShift configures openshift environments.
Field | Description |
---|---|
version requiredstring | OpenShift server version. |
managed PackageEnvironmentManagedOpenShift | ManagedOpenShift environment information. This section is only set when a managed OpenShift cluster is detected. This includes Red Hat OpenShift Dedicated, Red Hat OpenShift Service on AWS (ROSA) and Azure Red Hat OpenShift (ARO) and their Hosted Control Plane variants. |
Used in:
PackageEnvironmentProxy
PackageEnvironmentProxy configures proxy environments. On OpenShift, this config is taken from the cluster Proxy object. https://docs.openshift.com/container-platform/4.13/networking/enable-cluster-wide-proxy.html
Field | Description |
---|---|
httpProxy string | HTTP_PROXY |
httpsProxy string | HTTPS_PROXY |
noProxy string | NO_PROXY |
Used in:
PackageManifestConstraint
PackageManifestConstraint configures environment constraints to block package installation.
Field | Description |
---|---|
platformVersion PackageManifestPlatformVersionConstraint | PackageManifestPlatformVersionConstraint enforces that the platform matches the given version range. This constraint is ignored when running on a different platform. e.g. a PlatformVersionConstraint OpenShift>=4.13.x is ignored when installed on a plain Kubernetes cluster. Use the Platform constraint to enforce running on a specific platform. |
platform []PlatformName | Valid platforms that support this package. |
uniqueInScope PackageManifestUniqueInScopeConstraint | Constraints this package to be only installed once in the Cluster or once in the same Namespace. |
Used in:
PackageManifestDependency
PackageManifestDependency uses a solver to find the latest version package image.
Field | Description |
---|---|
image PackageManifestDependencyImage | Resolves the dependency as a image url and digest and commits it to the PackageManifestLock. |
Used in:
PackageManifestDependencyImage
PackageManifestDependencyImage represents a dependency image found by the solver.
Field | Description |
---|---|
name requiredstring | Name for the dependency. |
package requiredstring | Package FQDN |
range requiredstring | Semantic Versioning 2.0.0 version range. |
Used in:
PackageManifestFilter
PackageManifestFilter is used to conditionally render objects based on CEL expressions.
Field | Description |
---|---|
conditions []PackageManifestNamedCondition | Reusable CEL expressions. Can be used in ‘package-operator.run/condition’ annotations. They are evaluated once per package. |
paths []PackageManifestPath | Adds CEL conditions to file system paths matching a glob pattern. If a single condition matching a file system object’s path evaluates to false, the object is ignored. |
Used in:
PackageManifestImage
PackageManifestImage specifies an image tag to be resolved.
Field | Description |
---|---|
name requiredstring | Image name to be use to reference it in the templates |
image requiredstring | Image identifier (REPOSITORY[:TAG]) |
Used in:
PackageManifestLockDependency
PackageManifestLockDependency defines a dependency of this package.
Field | Description |
---|---|
name requiredstring | Image name to be use to reference it in the templates |
image requiredstring | Image identifier (REPOSITORY[:TAG]) |
digest requiredstring | Image digest |
version requiredstring | Version of the dependency that has been chosen. |
Used in:
PackageManifestLockImage
PackageManifestLockImage contains information about a resolved image.
Field | Description |
---|---|
name requiredstring | Image name to be use to reference it in the templates |
image requiredstring | Image identifier (REPOSITORY[:TAG]) |
digest requiredstring | Image digest |
Used in:
PackageManifestLockSpec
PackageManifestLockSpec defines a set of packages that are locked to a specific version.
Field | Description |
---|---|
images required[]PackageManifestLockImage | List of resolved images |
dependencies []PackageManifestLockDependency | List of resolved dependency images. |
Used in:
PackageManifestNamedCondition
PackageManifestNamedCondition is a reusable named CEL expression. It is injected as a variable into the CEL evaluation environment, and its value is set to the result of Expression (“true”/“false”).
Field | Description |
---|---|
name requiredstring | A unique name. Must match the CEL identifier pattern: [_a-zA-Z][_a-zA-Z0-9]* |
expression requiredstring | A CEL expression with a boolean output type. Has access to the full template context. |
Used in:
PackageManifestPath
PackageManifestPath is used to conditionally render package objects based on their path.
Field | Description |
---|---|
glob requiredstring | A file system path glob pattern. Syntax: https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.3.4#Match |
expression requiredstring | A CEL expression with a boolean output type. Has access to the full template context and named conditions. |
Used in:
PackageManifestPhase
PackageManifestPhase defines a package phase.
Field | Description |
---|---|
name requiredstring | Name of the reconcile phase. Must be unique within a PackageManifest |
class string | If non empty, phase reconciliation is delegated to another controller. If set to the string “default” the built-in controller reconciling the object. If set to any other string, an out-of-tree controller needs to be present to handle ObjectSetPhase objects. |
Used in:
PackageManifestPlatformVersionConstraint
PackageManifestPlatformVersionConstraint enforces that the platform matches the given version range. This constraint is ignored when running on a different platform. e.g. a PlatformVersionConstraint OpenShift>=4.13.x is ignored when installed on a plain Kubernetes cluster. Use the Platform constraint to enforce running on a specific platform.
Field | Description |
---|---|
name requiredPlatformName | Name of the platform this constraint should apply to. |
range requiredstring | Semantic Versioning 2.0.0 version range. |
Used in:
PackageManifestRepository
PackageManifestRepository contains information about one package repository which could be loaded either from a local file or from a container image.
Field | Description |
---|---|
file string | References a file in the filesystem to load. |
image string | References an image in a container image registry. |
Used in:
PackageManifestSpec
PackageManifestSpec represents the spec of the packagemanifest containing the details about phases and availability probes.
Field | Description |
---|---|
scopes required[]PackageManifestScope | Scopes declare the available installation scopes for the package. Either Cluster, Namespaced, or both. |
phases required[]PackageManifestPhase | Phases correspond to the references to the phases which are going to be the part of the ObjectDeployment/ClusterObjectDeployment. |
availabilityProbes []corev1alpha1.ObjectSetProbe | Availability Probes check objects that are part of the package. All probes need to succeed for a package to be considered Available. Failing probes will prevent the reconciliation of objects in later phases. |
config PackageManifestSpecConfig | Configuration specification. |
images required[]PackageManifestImage | List of images to be resolved |
components PackageManifestComponentsConfig | Configuration for multi-component packages. If this field is not set it is assumed that the containing package is a single-component package. |
filter PackageManifestFilter | Used to filter objects and files based on CEL expressions. |
constraints []PackageManifestConstraint | Constraints limit what environments a package can be installed into. e.g. can only be installed on OpenShift. |
repositories []PackageManifestRepository | Repository references that are used to validate constraints and resolve dependencies. |
dependencies []PackageManifestDependency | Dependency references to resolve and use within this package. |
Used in:
PackageManifestSpecConfig
PackageManifestSpecConfig configutes a package manifest.
Field | Description |
---|---|
openAPIV3Schema apiextensionsv1.JSONSchemaProps | OpenAPIV3Schema is the OpenAPI v3 schema to use for validation and pruning. |
Used in:
PackageManifestTest
PackageManifestTest configures test cases.
Field | Description |
---|---|
template []PackageManifestTestCaseTemplate | Template testing configuration. |
kubeconform PackageManifestTestKubeconform | PackageManifestTestKubeconform configures kubeconform testing. |
Used in:
PackageManifestTestCaseTemplate
PackageManifestTestCaseTemplate template testing configuration.
Field | Description |
---|---|
name requiredstring | Name describing the test case. |
context TemplateContext | Template data to use in the test case. |
Used in:
PackageManifestTestKubeconform
PackageManifestTestKubeconform configures kubeconform testing.
Field | Description |
---|---|
kubernetesVersion requiredstring | Kubernetes version to use schemas from. |
schemaLocations []string | OpenAPI schema locations for kubeconform defaults to: - https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{ .NormalizedKubernetesVersion }}-standalone{{ .StrictSuffix }}/{{ .ResourceKind }}{{ .KindSuffix }}.json - https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json |
Used in:
RepositoryEntryData
RepositoryEntryData is the part of RepositoryEntry containing the actual data.
Field | Description |
---|---|
image requiredstring | OCI host/repository and name. e.g. quay.io/xxx/xxx |
digest requiredstring | Image digest uniquely identifying this image. |
versions required[]string | Semver V2 versions that are assigned to the package. |
constraints []PackageManifestConstraint | Constraints of the package. |
name string | Name of the package. |
Used in:
TemplateContext
TemplateContext is available within the package templating process.
Field | Description |
---|---|
package requiredTemplateContextPackage | Package object. |
config runtime.RawExtension | Configuration as presented via the (Cluster)Package API after admission. |
environment requiredPackageEnvironment | Environment specific information. |
Used in:
TemplateContextObjectMeta
TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates.
Field | Description |
---|---|
name requiredstring | |
namespace requiredstring | |
labels requiredmap[string]string | |
annotations requiredmap[string]string |
Used in:
TemplateContextPackage
TemplateContextPackage represents the (Cluster)Package object requesting this package content.
Field | Description |
---|---|
metadata requiredTemplateContextObjectMeta | TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates. |
image requiredstring | Image as presented via the (Cluster)Package API after admission. |
Used in: