package-operator/package-operator

Operator for packaging and managing a collection of arbitrary Kubernetes objects to install software on one or multiple clusters.

Package Operator

---

Package Operator is an open source operator for Kubernetes, managing packages as collections of arbitrary objects, to install and maintain applications on one or multiple clusters.

---

• Project Status
• Features
• Documentation
• Getting in touch
• Contributing
• License

---

Project Status

Package Operator is used in production and the concepts proven.

The Core APIs are generally stable and breaking changes should only happen in exceptional circumstances.
Be careful to check the change notes for alpha and beta APIs.

Features

• No Surprises
  • Ordered Installation and Removal
  • Operating Transparency
• Extensible
  • Declarative APIs
  • Plug and Play
• Cheap Failures and Easy Recovery
  • Rollout History
  • Rollback

Documentation

Package Operator documentation is available on package-operator.run.

The source of this website is our website repository which is hosted via Netifly, Hugo and using the Doks template.

Getting in touch

Our mailing lists:

• pko-devel for development discussions.
• pko-users for discussions among users and potential users.

Contributing

Thank you for taking time to help to improve Package Operator!

Please see CONTRIBUTING.md for instructions on how to contribute.

License

Package Operator is Apache 2.0 licensed.

package-operator's Issues

BUG: mage deploy tries to deploy nonexistent tag of package-operator-manager

I typed:

./mage deploy

expected Package Operator to deploy to my kind cluster.

But it timed out due to pull attempt on a tag that does not exist:

It tried to pull:

quay.io/package-operator/package-operator-manager:f3f48ec

But the quay.io list of tags currently looks like this:

package build --push: DENIED: requested access to the resource is denied

I'm trying to build a simple package and push it to a registry, but I'm met with an error around authentication.

$ kubectl package build -t ghcr.io/jbpratt/pko-demo-nginx --push ./nginx/
Error: building from source: exporting package to image: push: Post "https://ghcr.io/v2/jbpratt/pko-demo-nginx/blobs/uploads/": GET https://ghcr.io/token?scope=repository%3Ajbpratt%2Fpko-demo-nginx%3Apull&scope=repository%3Ajbpratt%2Fpko-demo-nginx%3Apush%2Cpull&service=ghcr.io: DENIED: requested access to the resource is denied

$ kubectl package build -t ghcr.io/jbpratt/pko-demo-nginx ./nginx/ --output nginx.tar

$ podman load -i nginx.tar
Getting image source signatures
Copying blob 3133c22db8d5 done   |
Copying config a2271a7654 done   |
Writing manifest to image destination
Loaded image: ghcr.io/jbpratt/pko-demo-nginx:latest

$ podman push ghcr.io/jbpratt/pko-demo-nginx:latest
Getting image source signatures
Copying blob 3133c22db8d5 done   |
Copying config a2271a7654 done   |
Writing manifest to image destination

$ kubectl package build -t ghcr.io/jbpratt/pko-demo-nginx --push ./nginx/
Error: building from source: exporting package to image: push: Head "https://ghcr.io/v2/jbpratt/pko-demo-nginx/manifests/latest": GET https://ghcr.io/token?scope=repository%3Ajbpratt%2Fpko-demo-nginx%3Apull&scope=repository%3Ajbpratt%2Fpko-demo-nginx%3Apush%2Cpull&service=ghcr.io: UNAUTHORIZED: authentication required

After authenticating with crane, the package is pushed correctly.

$ crane auth login ghcr.io -u jbpratt -p xxxxx
2023/11/21 08:00:28 logged in via /var/home/bpratt/.docker/config.json
$ kubectl package build -t ghcr.io/jbpratt/pko-demo-nginx --push ./nginx/

This just seems like an upstream issue with crane and my assumption that podman credentials would be correctly used, but maybe it is worth documenting this nuance.

multiline strings in package image are interpreted as template

I have a package that includes a PrometheusRule resource. Here is an excerpt:

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  labels:
    app.kubernetes.io/component: operator
    app.kubernetes.io/name: observability-operator-rules
    app.kubernetes.io/part-of: observability-operator
    prometheus: k8s
    role: alert-rules
  name: observability-operator-rules
spec:
  groups:
  - name: observability-operator.rules
    rules:
    - alert: Observability Operator controller reconcile errors
      annotations:
        description: |
          Observability Operator controller - {{ $labels.controller }} fails to reconcile.
          Inspect the observability-operator log for potential root causes.
        summary: Observability Operator controller - {{ $labels.controller }} fails to reconcile
      expr: |
        increase(controller_runtime_reconcile_errors_total{job="observability-operator"}[15m]) > 0
      for: 15m
      labels:
        severity: warning

It seems like package-operator tries to interpret the multiline description as a template. This results in:

Status:
  Conditions:
    Last Transition Time:  2022-11-29T14:53:42Z
    Message:               Unpack job in progress
    Observed Generation:   1
    Reason:                Unpacking
    Status:                False
    Type:                  Unpacked
    Last Transition Time:  2022-11-29T14:53:44Z
    Message:               parsing yaml from /package/operator/resources.yaml: parsing template from yaml document at index 6: template: yaml#6:20: undefined variable "$labels"
    Observed Generation:   1
    Reason:                LoadError
    Status:                True
    Type:                  Invalid
  Phase:                   Invalid

Allow referencing a configmap directly as a (Cluster)Package config (bypassing `ObjectTemplate`s)

I'd like to propose the idea of being able to bypass the control that ObjectTemplates provide in the sources section, and reference a ConfigMap directly to splat the values in as parameters to be templated. In our case, we don't need the added complexities of managing each field within the configmap but instead just want to directly apply them as is.

apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-config
  namespace: integration
data:
  namespace: production-namespace
  image: quay.io/yourusername/wizard:stable
  app: wizard

apiVersion: package-operator.run/v1alpha1
kind: ClusterPackage
metadata:
  name: wizard-bundle
spec:
  image: quay.io/yourusername/wizard-bundle:latest
  configMapRef:
    name: myapp-config
    namespace: integration

which would effectively resolve to

apiVersion: package-operator.run/v1alpha1
kind: ClusterPackage
metadata:
  name: wizard-bundle
spec:
  image: quay,io/yourusername/wizard-bundle:latest
  config:
    namespace: production-namespace
    image: quay.io/yourusername/wizard:stable
    app: wizard

Improve `package-operator-manager` log messages

I created a malformed package and am a very new user. I tried to get information from the package-operator-manager and indeed found an error. However the message was not very helpful. Maybe this can be improved?
Seems like the right way is to look at the status of the respective [Cluster]Package. Even such a hint from the manager would be helpful I think.

Log message:

1.6697180513561141e+09	ERROR	Reconciler error	{"controller": "clusterpackage", "controllerGroup": "package-operator.run", "controllerKind": "ClusterPackage", "ClusterPackage": {"name":"example"}, "namespace": "", "name": "example", "reconcileID": "b4c62ea1-cf43-4ce5-9eaf-39c553e3ae00", "error": "Operation cannot be fulfilled on clusterpackages.package-operator.run \"example\": StorageError: invalid object, Code: 4, Key: /registry/package-operator.run/clusterpackages/example, ResourceVersion: 0, AdditionalErrorMsg: Precondition failed: UID in precondition: 7dda66fb-4650-48c0-90ca-b54652b74ada, UID in object meta: "}
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).reconcileHandler
	sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:326
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).processNextWorkItem
	sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:273
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).Start.func2.2
	sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:234

Use private registry

Hello! I'm trying to use a private container registry for my package, but I can't make package-operator-manager pull the image properly. It's there an special configuration or spec field to allow this? Thank you.

Stuck with obscure error "Error: initializing dev environment: creating k8s clients" again

I tried setting my CONTAINER_RUNTIME=podman. This works with a non-dev-mode deploy. But then I set it back to docker. This is failing and I really can't tell what in GoInstall(kind) is dying...

package-operator main $ ./mage dev:deploy
Running target: Dev:Deploy
Running dependency: main.Dev.Load
Running dependency: main.Dev.Setup
Running dependency: main.Dev.init
Running dependency: determineContainerRuntime
Running dependency: main.Dependency.Kind
Error: initializing dev environment: creating k8s clients: creating new ctrl client: Get "https://127.0.0.1:54458/api?timeout=32s": dial tcp 127.0.0.1:54458: connect: connection refused

Any ideas on what's wrong or what to do to debug?