Operations & Annotations¶

This guide lists the annotations and labels you can set on managed resources to drive day-2 operations — forcing a reconciliation, triggering maintenance on demand, or overriding deletion protection. It also documents the labels the operator sets itself so you know what is safe to rely on in kubectl -l selectors.

All keys use the k8s.bnerd.com/ prefix.

Summary¶

Key	Kind	Resource	Purpose
`k8s.bnerd.com/reconcile`	annotation	`Nextcloud`, `NextcloudInstance`	Force an immediate reconciliation
`k8s.bnerd.com/run-maintenance`	annotation	`NextcloudInstance`	Run OCC maintenance tasks immediately
`k8s.bnerd.com/force-delete`	label	`NextcloudInstance`	Allow deletion of an assigned pool instance

Force Reconcile¶

Annotation: k8s.bnerd.com/reconcile Applies to: Nextcloud, NextcloudInstance Value: any string; convention is an ISO 8601 timestamp or date +%s. Only changes to the value trigger a reconcile — setting the same value twice is a no-op.

Normal reconciliation runs whenever a relevant spec field changes or on the periodic timer (30 s for NextcloudInstance, 60 s for Nextcloud). Use this annotation to trigger a reconcile immediately in cases where the operator would not otherwise notice a change.

When to use¶

After editing a NextcloudProfile — existing instances don't pick up profile changes automatically
To retry provisioning after a transient error (managed database creation, S3 bucket auto-creation, HelmRelease failure)
After rotating a referenced secret (credentialsSecret) so the new values are read and re-applied
To propagate a Nextcloud spec change to its assigned NextcloudInstance if the sync appears stuck

How to trigger¶

# Force reconcile a NextcloudInstance
kubectl annotate nci my-instance \
  k8s.bnerd.com/reconcile=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --overwrite -n my-namespace

# Force reconcile a Nextcloud (logical resource)
kubectl annotate nc my-tenant \
  k8s.bnerd.com/reconcile=$(date +%s) \
  --overwrite -n my-namespace

A ready-made helper script is shipped with the repository:

./examples/trigger-manual-reconcile.sh nci my-instance my-namespace

Watch the operator logs to confirm the trigger fired — you should see Manual reconciliation triggered for ....

On-Demand Maintenance¶

Annotation: k8s.bnerd.com/run-maintenance Applies to: NextcloudInstance Value: any string; use a fresh timestamp on each run.

By default, periodic OCC maintenance (file cleanup, missing-index checks, etc.) runs once per day during the window configured in spec.maintenance.maintenanceWindow. Set this annotation to run the same tasks immediately, outside the window.

This does not re-run post-upgrade tasks (those are tied to a version change). It runs whichever periodic tasks are enabled in spec.maintenance.tasks.

When to use¶

You want to reclaim disk space or tidy up orphaned files right now without waiting for the window
You just enabled a new task in spec.maintenance.tasks and want to run it once straight away
You are investigating an issue and want fresh output from db:add-missing-indices or similar

How to trigger¶

kubectl annotate nci my-instance \
  k8s.bnerd.com/run-maintenance=$(date +%s) \
  --overwrite -n my-namespace

After the run completes, status.maintenance.lastRunTrigger is set to annotation and status.maintenance.lastRunAt is updated:

kubectl get nci my-instance -o jsonpath='{.status.maintenance}' | jq

See the API reference for the full list of tasks and timeout knobs under spec.maintenance.

For arbitrary occ commands (not just the canned maintenance tasks), use the NextcloudCommand CRD. Where run-maintenance triggers a fixed task set, NextcloudCommand lets you declaratively run any occ invocation with per-command result reporting.

Force Delete¶

Label: k8s.bnerd.com/force-delete=true Applies to: NextcloudInstance

Note: This is a label, not an annotation. Use kubectl label rather than kubectl annotate.

Pool-provisioned NextcloudInstance resources carry a finalizer (k8s.bnerd.com/assigned-instance-protection) and labels linking them to their assigned Nextcloud. Deleting an assigned instance directly is normally blocked with a TemporaryError so that the Nextcloud doesn't end up pointing at a gone backend.

Set k8s.bnerd.com/force-delete=true on the instance to bypass that protection. Use as a last-resort escape hatch: this will leave the assigned Nextcloud in a broken state until you re-point it at another instance or delete it.

When to use¶

The instance is hard-stuck in a failed state and needs to be removed before the Nextcloud can be re-assigned
You are manually draining a pool and intend to delete both the Nextcloud and the instance

How to trigger¶

# Check what the instance is assigned to first
kubectl get nci my-instance -o jsonpath='{.metadata.labels}' | jq

# Override protection and delete
kubectl label nci my-instance k8s.bnerd.com/force-delete=true -n my-namespace
kubectl delete nci my-instance -n my-namespace

The preferred path is to delete the owning Nextcloud first — that clears the assignment and the instance deletes cleanly without the force label.

Operator-Managed Labels (read-only)¶

The operator sets these labels on pool instances and related resources. They are useful for kubectl -l selectors and dashboards — do not edit them by hand.

Label	Set on	Purpose
`k8s.bnerd.com/managed-by`	`NextcloudInstance`	Always `nextcloud-operator` for pool-created instances
`k8s.bnerd.com/pool`	`NextcloudInstance`	Name of the `NextcloudPool` that created it
`k8s.bnerd.com/assigned`	`NextcloudInstance`	`true` / `false` — whether the instance is claimed by a `Nextcloud`
`k8s.bnerd.com/nextcloud`	`NextcloudInstance`	Name of the assigned `Nextcloud` (when assigned)
`k8s.bnerd.com/nextcloud-ns`	`NextcloudInstance`	Namespace of the assigned `Nextcloud`
`k8s.bnerd.com/profile`	`NextcloudInstance`	Profile the pool template referenced

Example queries:

# All unassigned instances in a pool
kubectl get nci -A -l k8s.bnerd.com/pool=my-pool,k8s.bnerd.com/assigned=false

# All instances assigned to a specific Nextcloud
kubectl get nci -A -l k8s.bnerd.com/nextcloud=my-tenant