Skip to content

Nextcloud Operator

A Kubernetes operator that manages Nextcloud instances declaratively via Custom Resource Definitions. Describe the instance you want in YAML, and the operator provisions the Helm release, databases, secrets, object storage, and backups for you.

Who this is for

Platform Engineers

You are running Kubernetes and want to offer Nextcloud as a self-service product to internal teams or external customers. Start with Architecture, then Pool Provisioning for multi-tenant onboarding.

SaaS / Managed-Service Operators

You operate Nextcloud for many tenants and need fast onboarding, version upgrades, and backups without handwritten Helm values per customer. Start with the Quick Start, then Configuration Profiles and Managed PostgreSQL.

Nextcloud Admins running a single instance

You administer one Nextcloud for your organization and want declarative upgrades, declarative apps, and automated maintenance instead of manual occ commands. Start with Quick Start and Running occ Commands.

Not sure yet?

Follow the Quick Start — it deploys a working Nextcloud in about 10 minutes and shows which CRDs are involved.

Architecture at a glance

flowchart LR
    User([User YAML]) -->|kubectl apply| K8sAPI[(Kubernetes API)]
    K8sAPI --> Operator[Nextcloud Operator<br/>kopf]

    Operator -->|creates| Secrets[Kubernetes Secrets]
    Operator -->|creates| HR[Flux HelmRelease]
    Operator -->|optional| PG[PerconaPGCluster<br/>managed PostgreSQL]
    Operator -->|optional| S3[(S3 bucket<br/>auto-created)]

    HR -->|reconciles| Chart[Nextcloud Helm Chart]
    Chart --> Pods[Nextcloud Pods]
    Chart --> Svc[Services]
    Chart --> Ing[Ingress + TLS]
    Chart --> PVC[PVCs]

    PG --> Pods
    S3 --> Pods
    Secrets --> Pods

    style Operator fill:#6366f1,stroke:#4f46e5,color:#fff
    style HR fill:#16a34a,stroke:#15803d,color:#fff

The operator watches NextcloudInstance resources and translates them into the Kubernetes primitives needed to run Nextcloud: secrets for each credential type, a Flux HelmRelease that deploys the upstream Helm chart, an optional managed PostgreSQL cluster, and an optional auto-provisioned S3 bucket. See Architecture for the full picture.

Why this operator instead of plain Helm?

The upstream Nextcloud Helm chart gets you one instance running. This operator addresses what comes after that:

Concern Plain Helm This Operator
Multi-tenant onboarding Copy-paste values per tenant NextcloudPool keeps pre-warmed instances, ~30s assignment
Credential management Inline or manually-created secrets credentialsSecret references → native External Secrets / Vault / Sealed Secrets
Managed database BYO PostgreSQL or Helm sub-chart database.managed: true auto-provisions HA Percona cluster with backups
Version upgrades Manual helm upgrade + OCC commands Declarative spec.version; resolved via NextcloudVersionMap; post-upgrade migrations run automatically
Maintenance Cron jobs you write yourself spec.maintenance schedules OCC cleanup during your window
App install/config hooks or post-install scripts spec.apps declarative install with version pinning
Status observability helm status + pod logs CRD status subresource, Prometheus metrics, Grafana dashboard
Day-2 recovery Trial and error Annotation-driven reconcile, force-delete, run-maintenance

If you are deploying one Nextcloud and will never touch it again, plain Helm is simpler. If you plan to run it in production for months or for multiple tenants, the operator replaces a growing pile of glue scripts with declarative Kubernetes resources.

CRDs at a glance

CRD Scope Purpose
Nextcloud (nc) Namespaced Tenant-facing resource. References a pool or creates an instance directly.
NextcloudInstance (nci) Namespaced Physical runtime. Creates the HelmRelease, secrets, and managed database.
NextcloudPool (ncp) Cluster Pre-provisioned unassigned instances for fast assignment.
NextcloudProfile (ncprofile) Cluster Reusable configuration templates (production, testing, development, or custom).
NextcloudVersionMap (ncvm) Cluster Maps Nextcloud versions to Helm chart versions and default images.
NextcloudCommand (nccmd) Namespaced Declarative occ command execution with auditable results in status.
SignalingServer (ss) Cluster Talk HPB signaling backend registration.
RecordingServer (rs) Cluster Talk recording backend registration.

API version: k8s.bnerd.com/v1alpha1. See CRD Mental Model for when to use which.

What the operator does for you

  • Deploys Nextcloud instances with a single kubectl apply using production-ready defaults
  • Pool-based provisioning for fast tenant onboarding (~30s vs. ~2min fresh)
  • Managed PostgreSQL with HA, backups, and connection pooling via Percona PG Operator
  • Configuration profiles (built-in + custom CRDs) with a 4-layer override cascade
  • Credential management via credentialsSecret references — compatible with External Secrets, Sealed Secrets, and Vault
  • Declarative app management for Nextcloud Office (Collabora), Talk, Calendar, Contacts, and more
  • OIDC/SSO, Mail/SMTP, S3 primary storage, Redis caching, automated data backups
  • Prometheus ServiceMonitor and Grafana dashboard included
  • Periodic and post-upgrade occ maintenance, triggerable on demand via annotation

Prerequisites

  • Kubernetes 1.24 or newer
  • Flux CD v2 installed and configured (the operator creates HelmRelease resources)
  • An ingress controller and a default StorageClass
  • Optional: Percona PG Operator for managed databases
  • Optional: Prometheus Operator for metrics / ServiceMonitor