Package Operator API

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.

  • 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.

  • Stable

    • The version name is vX where X is an integer.
    • The stable versions of features appear in released software for many subsequent versions.

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

ClusterObjectDeployment is the Schema for the ClusterObjectDeployments API

Example

apiVersion: package-operator.run/v1alpha1
kind: ClusterObjectDeployment
metadata:
  name: example
spec:
  revisionHistoryLimit: 10
  selector: metav1.LabelSelector
  template:
    metadata: metav1.ObjectMeta
    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
        externalObjects:
        - collisionProtection: Prevent
          conditionMappings:
          - destinationType: consetetur
            sourceType: amet
          object:
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: example-deployment
        name: lorem
        objects:
        - collisionProtection: Prevent
          conditionMappings:
          - destinationType: sit
            sourceType: dolor
          object:
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: example-deployment
        slices:
        - sadipscing
      successDelaySeconds: 42
status:
  phase:Pending: null
FieldDescription
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: sed
    externalObjects:
    - collisionProtection: Prevent
      conditionMappings:
      - destinationType: tempor
        sourceType: eirmod
      object:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: example-deployment
    name: elitr
    objects:
    - collisionProtection: Prevent
      conditionMappings:
      - destinationType: nonumy
        sourceType: diam
      object:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: example-deployment
    slices:
    - lorem
  previous:
  - name: previous-revision
  successDelaySeconds: 42
status:
  phase: Pending
FieldDescription
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
  externalObjects:
  - collisionProtection: Prevent
    conditionMappings:
    - destinationType: amet
      sourceType: sit
    object:
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: example-deployment
  objects:
  - collisionProtection: Prevent
    conditionMappings:
    - destinationType: dolor
      sourceType: ipsum
    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: sadipscing
    kind: consetetur
    name: elitr
    namespace: sed
FieldDescription
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: nonumy
    sourceType: diam
  object:
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: example-deployment
FieldDescription
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: tempor
    items:
    - destination: amet
      key: sit
    kind: lorem
    name: dolor
    namespace: ipsum
    optional: "true"
  template: eirmod
status:
  conditions:
  - metav1.Condition
  phase: ObjectTemplateStatusPhase
FieldDescription
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: sadipscing
  config: runtime.RawExtension
  image: consetetur
status:
  phase: Pending
FieldDescription
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:
  revisionHistoryLimit: 10
  selector: metav1.LabelSelector
  template:
    metadata: metav1.ObjectMeta
    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: sed
        externalObjects:
        - collisionProtection: Prevent
          conditionMappings:
          - destinationType: tempor
            sourceType: eirmod
          object:
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: example-deployment
        name: elitr
        objects:
        - collisionProtection: Prevent
          conditionMappings:
          - destinationType: nonumy
            sourceType: diam
          object:
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: example-deployment
        slices:
        - lorem
      successDelaySeconds: 42
status:
  phase:Pending: null
FieldDescription
metadata
metav1.ObjectMeta
spec
ObjectDeploymentSpec		ObjectDeploymentSpec defines the desired state of a ObjectDeployment.
status
ObjectDeploymentStatus		ObjectDeploymentStatus defines the observed state of a 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: dolor
    externalObjects:
    - collisionProtection: Prevent
      conditionMappings:
      - destinationType: sadipscing
        sourceType: consetetur
      object:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: example-deployment
    name: ipsum
    objects:
    - collisionProtection: Prevent
      conditionMappings:
      - destinationType: amet
        sourceType: sit
      object:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: example-deployment
    slices:
    - elitr
  previous:
  - name: previous-revision
  successDelaySeconds: 42
status:
  phase: Pending
FieldDescription
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
  externalObjects:
  - collisionProtection: Prevent
    conditionMappings:
    - destinationType: eirmod
      sourceType: nonumy
    object:
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: example-deployment
  objects:
  - collisionProtection: Prevent
    conditionMappings:
    - destinationType: diam
      sourceType: sed
    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
FieldDescription
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
FieldDescription
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:
  - metav1.Condition
  phase: ObjectTemplateStatusPhase
FieldDescription
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: lorem
  config: runtime.RawExtension
  image: tempor
status:
  phase: Pending
FieldDescription
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.

FieldDescription
revisionHistoryLimit
int32		Number of old revisions in the form of archived ObjectSets to keep.
selector required
metav1.LabelSelector		Selector targets ObjectSets managed by this Deployment.
template required
ObjectSetTemplate		Template to create new ObjectSets from.

Used in:

ClusterObjectDeploymentStatus

ClusterObjectDeploymentStatus defines the observed state of a ClusterObjectDeployment.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions ths object is in.
phase
ObjectDeploymentPhase		This field is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.
collisionCount
int32		Count of hash collisions of the ClusterObjectDeployment.
templateHash
string		Computed TemplateHash.
revision
int64		Deployment revision.

Used in:

ClusterObjectSetPhaseSpec

ClusterObjectSetPhaseSpec defines the desired state of a ClusterObjectSetPhase.

FieldDescription
paused
bool		Disables reconciliation of the ClusterObjectSet.
Only Status updates will still be propagated, but object changes will not be reconciled.
revision required
int64		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.
externalObjects
[]ObjectSetObject		ExternalObjects observed, but not reconciled by this phase.

Used in:

ClusterObjectSetPhaseStatus

ClusterObjectSetPhaseStatus defines the observed state of a ClusterObjectSetPhase.

FieldDescription
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.

FieldDescription
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.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions ths object is in.
phase
ObjectSetStatusPhase		Phase is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.
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.

FieldDescription
sourceType required
string		Source condition type.
destinationType required
string		Destination condition type to report into Package Operator APIs.

Used in:

ControlledObjectReference

ControlledObjectReference an object controlled by this ObjectSet/ObjectSetPhase.

FieldDescription
kind required
string		Object Kind.
group required
string		Object Group.
name required
string		Object Name.
namespace
string		Object Namespace.

Used in:

ObjectDeploymentSpec

ObjectDeploymentSpec defines the desired state of a ObjectDeployment.

FieldDescription
revisionHistoryLimit
int32		Number of old revisions in the form of archived ObjectSets to keep.
selector required
metav1.LabelSelector		Selector targets ObjectSets managed by this Deployment.
template required
ObjectSetTemplate		Template to create new ObjectSets from.

Used in:

ObjectDeploymentStatus

ObjectDeploymentStatus defines the observed state of a ObjectDeployment.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions ths object is in.
phase
ObjectDeploymentPhase		This field is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.
collisionCount
int32		Count of hash collisions of the ObjectDeployment.
templateHash
string		Computed TemplateHash.
revision
int64		Deployment revision.

Used in:

ObjectSetObject

ObjectSetObject is an object that is part of the phase of an ObjectSet.

FieldDescription
object required
unstructured.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.

FieldDescription
paused
bool		Disables reconciliation of the ObjectSet.
Only Status updates will still be propagated, but object changes will not be reconciled.
revision required
int64		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.
externalObjects
[]ObjectSetObject		ExternalObjects observed, but not reconciled by this phase.

Used in:

ObjectSetPhaseStatus

ObjectSetPhaseStatus defines the observed state of a ObjectSetPhase.

FieldDescription
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.

FieldDescription
probes required
[]Probe		Probe configuration parameters.
selector required
ProbeSelector		Selector specifies which objects this probe should target.

Used in:

ObjectSetSpec

ObjectSetSpec defines the desired state of a ObjectSet.

FieldDescription
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.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions ths object is in.
phase
ObjectSetStatusPhase		Phase is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.
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.

FieldDescription
metadata required
metav1.ObjectMeta		Common Object Metadata.
spec required
ObjectSetTemplateSpec		ObjectSet specification.

Used in:

ObjectSetTemplatePhase

ObjectSetTemplatePhase configures the reconcile phase of ObjectSets.

FieldDescription
name required
string		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.
externalObjects
[]ObjectSetObject		ExternalObjects observed, but not reconciled by 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.

FieldDescription
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.

FieldDescription
apiVersion required
string
kind required
string
namespace
string
name required
string
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.

FieldDescription
key required
string		JSONPath to value in source object.
destination required
string		JSONPath to destination in which to store copy of the source value.

Used in:

ObjectTemplateSpec

ObjectTemplateSpec specification.

FieldDescription
template required
string		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.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions the templated object is in.
phase
ObjectTemplateStatusPhase		This field is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.

Used in:

PackageProbeKindSpec

PackageProbeKindSpec package probe parameters. selects objects based on Kind and API Group.

FieldDescription
group required
string		Object Group to apply a probe to.
kind required
string		Object Kind to apply a probe to.

Used in:

PackageSpec

PackageSpec specifies a package.

FieldDescription
image required
string		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.

Used in:

PackageStatus

PackageStatus defines the observed state of a Package.

FieldDescription
conditions
[]metav1.Condition		Conditions is a list of status conditions ths object is in.
phase
PackageStatusPhase		This field is not part of any API contract
it will go away as soon as kubectl can print conditions!
When evaluating object state in code, use .Conditions instead.
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.

FieldDescription
name required
string		Name of a previous revision.

Used in:

Probe

Probe defines probe parameters. Only one can be filled.

FieldDescription
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

FieldDescription
rule required
string		CEL rule to evaluate.
message required
string		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.

FieldDescription
type required
string		Condition type to probe for.
status required
string		Condition status to probe for.

Used in:

ProbeFieldsEqualSpec

ProbeFieldsEqualSpec compares two fields specified by JSON Paths.

FieldDescription
fieldA required
string		First field for comparison.
fieldB required
string		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.

FieldDescription
kind required
PackageProbeKindSpec		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.

FieldDescription
name required
string
uid required
types.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:
  - corev1alpha1.ObjectSetProbe
  components: PackageManifestComponentsConfig
  conditionalFiltering:
    conditionalPaths:
    - expression: elitr
      glob: sadipscing
    namedConditions:
    - expression: consetetur
      name: amet
  config:
    openAPIV3Schema: apiextensionsv1.JSONSchemaProps
  images:
  - image: sit
    name: dolor
  phases:
  - class: ipsum
    name: lorem
  scopes:
  - PackageManifestScope
test:
  kubeconform:
    kubernetesVersion: elitr
    schemaLocations:
    - sed
  template:
  - context:
      config: runtime.RawExtension
      environment:
        hyperShift:
          hostedCluster:
            hostedClusterNamespace: sadipscing
            metadata:
              annotations: map[string]string
              labels: map[string]string
              name: amet
              namespace: consetetur
        kubernetes:
          version: tempor
        openShift:
          managed:
            data: map[string]string
          version: lorem
        proxy:
          httpProxy: ipsum
          httpsProxy: dolor
          noProxy: sit
      package:
        image: eirmod
        metadata:
          annotations: map[string]string
          labels: map[string]string
          name: diam
          namespace: nonumy
    name: sed
FieldDescription
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:
  images:
  - digest: eirmod
    image: nonumy
    name: diam
FieldDescription
metadata
metav1.ObjectMeta
spec
PackageManifestLockSpec		PackageManifestLockSpec defines a set of packages that are locked to a specific version.

PackageEnvironment

PackageEnvironment information.

FieldDescription
kubernetes required
PackageEnvironmentKubernetes		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

FieldDescription
hostedCluster required
PackageEnvironmentHyperShiftHostedCluster		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

FieldDescription
metadata required
TemplateContextObjectMeta		TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates.
hostedClusterNamespace required
string		Namespace of HostedCluster components belonging to this HostedCluster object.

Used in:

PackageEnvironmentKubernetes

PackageEnvironmentKubernetes configures kubernetes environments.

FieldDescription
version required
string		Kubernetes server version.

Used in:

PackageEnvironmentManagedOpenShift

PackageEnvironmentManagedOpenShift describes managed OpenShift environments.

FieldDescription
data required
map[string]string		Data key-value pairs describing details of the Managed OpenShift environment.

Used in:

PackageEnvironmentOpenShift

PackageEnvironmentOpenShift configures openshift environments.

FieldDescription
version required
string		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

FieldDescription
httpProxy
string		HTTP_PROXY
httpsProxy
string		HTTPS_PROXY
noProxy
string		NO_PROXY

Used in:

PackageManifestConditionalFiltering

PackageManifestConditionalFiltering is used to conditionally render objects based on CEL expressions.

FieldDescription
namedConditions
[]PackageManifestNamedCondition		Reusable CEL expressions. Can be used in ‘package-operator.run/condition’ annotations.
They are evaluated once per package.
conditionalPaths
[]PackageManifestConditionalPath		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:

PackageManifestConditionalPath

PackageManifestConditionalPath is used to conditionally render package objects based on their path.

FieldDescription
glob required
string		A file system path glob pattern.
Syntax: https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.3.4#Match
expression required
string		A CEL expression with a boolean output type.
Has access to the full template context and named conditions.

Used in:

PackageManifestImage

PackageManifestImage specifies an image tag to be resolved.

FieldDescription
name required
string		Image name to be use to reference it in the templates
image required
string		Image identifier (REPOSITORY[:TAG])

Used in:

PackageManifestLockImage

PackageManifestLockImage contains information about a resolved image.

FieldDescription
name required
string		Image name to be use to reference it in the templates
image required
string		Image identifier (REPOSITORY[:TAG])
digest required
string		Image digest

Used in:

PackageManifestLockSpec

PackageManifestLockSpec defines a set of packages that are locked to a specific version.

FieldDescription
images required
[]PackageManifestLockImage		List of resolved 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”).

FieldDescription
name required
string		A unique name. Must match the CEL identifier pattern: [_a-zA-Z][_a-zA-Z0-9]*
expression required
string		A CEL expression with a boolean output type.
Has access to the full template context.

Used in:

PackageManifestPhase

PackageManifestPhase defines a package phase.

FieldDescription
name required
string		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:

PackageManifestSpec

PackageManifestSpec represents the spec of the packagemanifest containing the details about phases and availability probes.

FieldDescription
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.
conditionalFiltering
PackageManifestConditionalFiltering		Used to conditionally render objects based on CEL expressions.

Used in:

PackageManifestSpecConfig

PackageManifestSpecConfig configutes a package manifest.

FieldDescription
openAPIV3Schema
apiextensionsv1.JSONSchemaProps		OpenAPIV3Schema is the OpenAPI v3 schema to use for validation and pruning.

Used in:

PackageManifestTest

PackageManifestTest configures test cases.

FieldDescription
template
[]PackageManifestTestCaseTemplate		Template testing configuration.
kubeconform
PackageManifestTestKubeconform		PackageManifestTestKubeconform configures kubeconform testing.

Used in:

PackageManifestTestCaseTemplate

PackageManifestTestCaseTemplate template testing configuration.

FieldDescription
name required
string		Name describing the test case.
context
TemplateContext		Template data to use in the test case.

Used in:

PackageManifestTestKubeconform

PackageManifestTestKubeconform configures kubeconform testing.

FieldDescription
kubernetesVersion required
string		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:

TemplateContext

TemplateContext is available within the package templating process.

FieldDescription
package required
TemplateContextPackage		Package object.
config
runtime.RawExtension		Configuration as presented via the (Cluster)Package API after admission.
environment required
PackageEnvironment		Environment specific information.

Used in:

TemplateContextObjectMeta

TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates.

FieldDescription
name required
string
namespace required
string
labels required
map[string]string
annotations required
map[string]string

Used in:

TemplateContextPackage

TemplateContextPackage represents the (Cluster)Package object requesting this package content.

FieldDescription
metadata required
TemplateContextObjectMeta		TemplateContextObjectMeta represents a simplified version of metav1.ObjectMeta for use in templates.
image required
string		Image as presented via the (Cluster)Package API after admission.

Used in:

Template Functions →