What is Pack Operator?

Pack Operator is a Kubernetes controller that manages the lifecycle of Packs and Helm chart releases. It turns each Pack definition into a Helm release, validates and applies changes, and records the result on the same resource. See Helm and Helm charts in Kubernetes for the relationship between these components.

Most users see operator results through Kubchi. This page is for users who maintain Pack manifests, inspect cluster status, or need to find why a change was not applied.

Pack Operator is already available for Kubchi and Pack resources in Kubit's managed Kubernetes clusters. Contact Kubit support to connect Kubchi to another cluster and install the operator there. Installation requires chart-repository access, cluster configuration, and cluster-level permissions.

Pack Operator may also enable features such as Secret synchronization. This page covers only behavior related to the Pack resource.

When a Pack is created or changed, the operator:

1. Validates the Pack structure, repository, chart, version, and renderable values.
2. Compares the desired Helm state with the current release in the cluster.
3. Installs or upgrades the release when a change exists.
4. Writes the exact chart version, Helm revision, result, and error to Pack status.
5. Records an event such as SuccessfulApply, AppliedWithErrors, or ApplyFailed on the resource.

If the current and desired states match, the operator performs no extra operation and keeps the Pack in the Applied phase. Applying the same manifest again does not create another release revision in this state.

The Applied phase means the operator applied the defined state. Also inspect workloads, pods, alerts, and events to verify application health. A successful Helm operation alone does not guarantee that the application is ready to serve requests.

The Failed phase means validation or apply did not finish. Details are stored in status.error and resource events. In this phase, status.desired may show the state the operator attempted to apply.

The Unmanaged phase is recorded when spec.managed: false. The operator does not validate, install, or upgrade the Pack in this state. Use it only when another tool owns the Helm release and you accept responsibility for preventing configuration drift.

Before accepting a spec change, Pack Operator checks Helm output and the required access. A change may be rejected before apply when the chart cannot be found, no version matches the constraint, a Vault value cannot be decrypted, or Helm output is invalid.

Use kubit helm-template to inspect a change without installing it. Use kubit helm-diff to compare it with the current release.

Automatic upgrades use these Pack fields:

spec:
  chart:
    version: '~=1.4'
    autoUpgrade: true
    autoUpgradeDelay: 1h

When the repository index is refreshed, the operator finds a new compatible version. Exact versions do not enter the automatic-upgrade queue. The delay can combine days, hours, minutes, and seconds, such as 1d2h30m.

If the chart has a pack-migrations.yaml file, the operator applies matching migrations to the Pack definition before the normal upgrade path. If an automatic migration fails, the error is logged and the normal upgrade continues. Check sensitive version changes first with kubit pack migrate. See Pack migrations for migration chains and value conversion.

To run the Helm upgrade path again without changing the manifest:

kubit -n my-project pack force-upgrade my-app

To restart the workloads owned by the Pack:

kubit -n my-project pack rollout-restart my-app

force-upgrade runs the Helm upgrade path again, while rollout-restart only restarts Pack workloads. Before using either command in production, account for a short outage or simultaneous pod starts.

When dependent-resource restarts are enabled in the cluster, this annotation restarts the Pack and its Deployment or StatefulSet workloads after the named resources change:

metadata:
  annotations:
    pack-operator.k8s.kubit.ir/watch-to-redeploy: configmap/app-config, secret/app-secret

Only configmap/NAME and secret/NAME are accepted, and each resource must be in the Pack namespace. Separate several resources with whitespace, commas, or semicolons. Changes are processed after a short delay so nearby updates do not cause repeated restarts.

First inspect the resource and its events:

kubectl -n my-project get pack my-app -o yaml
kubectl -n my-project describe pack my-app

Then check these items in order:

1. status.phase and status.error.
2. The configured repository and the Pack's access to it.
3. A compatible chart version in the repository.
4. Variables, Vault values, and the values structure.
5. kubit helm-template and kubit helm-diff output.
6. Events and the workloads created by Helm.

Do not copy status, resourceVersion, uid, or finalizer into the source Pack manifest. Kubernetes and the operator manage these fields. If the error is caused by access or global operator configuration, send Kubit support the status.error, cluster name, namespace, and Pack name. Do not send passwords, tokens, or decrypted Vault text.