CRD Overview¶

Custom Resource Definitions¶

The Nextcloud Operator provides the following CRDs:

Nextcloud (nc) — Tenant-facing logical resource (namespaced)
NextcloudInstance (nci) — Physical Nextcloud instance resource (namespaced)
NextcloudPool (ncp) — Pre-provisioned instance pool management (cluster-scoped)
NextcloudProfile (ncprofile) — Reusable configuration profiles (cluster-scoped)
SignalingServer (ss) — HPB signaling server backend registration (cluster-scoped)
RecordingServer (rs) — Talk recording server backend registration (cluster-scoped)

API Version: k8s.bnerd.com/v1alpha1

For the full interactive API specification, see the OpenAPI / Swagger page.

API Resources¶

NextcloudInstance Resource¶

Minimal Example¶

apiVersion: k8s.bnerd.com/v1alpha1
kind: NextcloudInstance
metadata:
  name: my-nextcloud
  namespace: default
spec:
  profile: production
  ingress:
    host: cloud.example.com

Complete Example¶

apiVersion: k8s.bnerd.com/v1alpha1
kind: NextcloudInstance
metadata:
  name: production-nextcloud
  namespace: nextcloud
  labels:
    environment: production
spec:
  profile: production
  version: "29"
  replicas: 3

  ingress:
    enabled: true
    host: cloud.company.com
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    tls:
      enabled: true

  database:
    type: postgresql
    managed: true
    postgres:
      replicas: 3
      storage:
        size: 50Gi
      backup:
        enabled: true
        s3:
          bucket: pg-backups
          endpoint: s3.example.com
          credentialsSecret: backup-s3-creds

  redis:
    enabled: true
    credentialsSecret: nextcloud-redis-creds

  s3:
    enabled: true
    credentialsSecret: nextcloud-s3-creds

  backups:
    data:
      enabled: true
      bucket: nextcloud-backups
      endpoint: s3.example.com
      region: eu-central-1
      credentialsSecret: nextcloud-backup-creds
      schedule: "0 3 * * *"
      deleteOnCleanup: false

  admin:
    credentialsSecret: nextcloud-admin-creds

  mail:
    enabled: true
    credentialsSecret: nextcloud-mail-creds

  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 4000m
      memory: 8Gi

  persistence:
    enabled: true
    size: 100Gi
    storageClass: fast-ssd

NextcloudProfile Resource¶

apiVersion: k8s.bnerd.com/v1alpha1
kind: NextcloudProfile
metadata:
  name: high-performance
spec:
  description: High-performance profile for production workloads
  defaults:
    replicaCount: 3
    resources:
      requests:
        cpu: 2000m
        memory: 4Gi
      limits:
        cpu: 8000m
        memory: 16Gi
    persistence:
      enabled: true
      size: 200Gi
      storageClass: fast-ssd
    internalDatabase:
      enabled: false
  helm:
    version: "5.0.0"

API Endpoints¶

Nextcloud Endpoints¶

GET    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextclouds
GET    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextclouds/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextclouds
PUT    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextclouds/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextclouds/{name}

NextcloudInstance Endpoints¶

GET    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextcloudinstances
GET    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextcloudinstances/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextcloudinstances
PUT    /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextcloudinstances/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/namespaces/{namespace}/nextcloudinstances/{name}

NextcloudProfile Endpoints (Cluster-Scoped)¶

GET    /apis/k8s.bnerd.com/v1alpha1/nextcloudprofiles
GET    /apis/k8s.bnerd.com/v1alpha1/nextcloudprofiles/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/nextcloudprofiles
PUT    /apis/k8s.bnerd.com/v1alpha1/nextcloudprofiles/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/nextcloudprofiles/{name}

NextcloudPool Endpoints (Cluster-Scoped)¶

GET    /apis/k8s.bnerd.com/v1alpha1/nextcloudpools
GET    /apis/k8s.bnerd.com/v1alpha1/nextcloudpools/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/nextcloudpools
PUT    /apis/k8s.bnerd.com/v1alpha1/nextcloudpools/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/nextcloudpools/{name}

SignalingServer Endpoints (Cluster-Scoped)¶

GET    /apis/k8s.bnerd.com/v1alpha1/signalingservers
GET    /apis/k8s.bnerd.com/v1alpha1/signalingservers/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/signalingservers
PUT    /apis/k8s.bnerd.com/v1alpha1/signalingservers/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/signalingservers/{name}

RecordingServer Endpoints (Cluster-Scoped)¶

GET    /apis/k8s.bnerd.com/v1alpha1/recordingservers
GET    /apis/k8s.bnerd.com/v1alpha1/recordingservers/{name}
POST   /apis/k8s.bnerd.com/v1alpha1/recordingservers
PUT    /apis/k8s.bnerd.com/v1alpha1/recordingservers/{name}
DELETE /apis/k8s.bnerd.com/v1alpha1/recordingservers/{name}

Using the API¶

With kubectl¶

# Create a Nextcloud instance
kubectl apply -f nextcloudinstance.yaml

# List instances
kubectl get nci -n nextcloud

# Get instance details
kubectl describe nci my-nextcloud -n nextcloud

# Delete instance
kubectl delete nci my-nextcloud -n nextcloud

With Python (Kubernetes Client)¶

from kubernetes import client, config

config.load_kube_config()
api = client.CustomObjectsApi()

# List Nextcloud instances
nextclouds = api.list_namespaced_custom_object(
    group="k8s.bnerd.com",
    version="v1alpha1",
    namespace="default",
    plural="nextclouds"
)

# Create instance
body = {
    "apiVersion": "k8s.bnerd.com/v1alpha1",
    "kind": "Nextcloud",
    "metadata": {"name": "my-nextcloud"},
    "spec": {
        "profile": "production",
        "poolSelector": {"matchLabels": {"pool": "default"}}
    }
}

api.create_namespaced_custom_object(
    group="k8s.bnerd.com",
    version="v1alpha1",
    namespace="default",
    plural="nextclouds",
    body=body
)

Field Reference¶

NextcloudInstance Spec Fields¶

Field	Type	Default	Description
`profile`	string	-	Profile to use (`production`, `testing`, `development`, or custom)
`version`	string	`29`	Nextcloud version (Docker tag)
`replicas`	integer	`1`	Number of pod replicas
`ingress`	object	-	Ingress configuration
`database`	object	-	Database configuration
`redis`	object	-	Redis configuration
`s3`	object	-	S3 object storage configuration
`admin`	object	-	Admin credentials
`mail`	object	-	Mail/SMTP configuration
`oidc`	object	-	OIDC/SSO configuration
`resources`	object	-	Resource requests/limits
`persistence`	object	-	Persistent storage configuration
`cronjob`	object	-	Cron job configuration
`livenessProbe`	object	-	Liveness probe overrides
`readinessProbe`	object	-	Readiness probe overrides
`startupProbe`	object	-	Startup probe overrides
`license_key`	string	-	Nextcloud Enterprise license key
`apps`	object	-	Declarative Nextcloud app management
`backups`	object	-	Automated data backup configuration
`helm`	object	-	Helm chart/values overrides

Database Configuration¶

Field	Type	Default	Description
`type`	string	`postgresql`	Database type (`postgresql` or `mysql`)
`managed`	boolean	`false`	Create managed PostgreSQL cluster via Percona PG Operator
`credentialsSecret`	string	-	Secret name with credentials (overrides inline values)
`host`	string	-	Database host (ignored if `credentialsSecret` set)
`port`	integer	`5432`	Database port
`name`	string	`nextcloud`	Database name
`user`	string	`nextcloud`	Database user
`password`	string	-	Database password
`postgres`	object	-	PostgreSQL cluster config (only when `managed: true`)

Data Backup Configuration (`spec.backups.data`)¶

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable automated S3 data backup
`bucket`	string	-	S3 bucket name for backup storage
`endpoint`	string	-	S3-compatible endpoint URL
`region`	string	-	S3 region
`credentialsSecret`	string	-	Secret with backup credentials (keys: `accessKey`, `secretKey`)
`schedule`	string	`"0 3 * * *"`	Cron schedule for backup jobs
`deleteOnCleanup`	boolean	`false`	Delete backup data when instance is deleted

Secret References¶

All credential sections support credentialsSecret. See Secret Management for details.

Section	Secret Keys
`database.credentialsSecret`	`host`, `port`, `name`, `user`, `password`
`redis.credentialsSecret`	`host`, `port`, `password`
`s3.credentialsSecret`	`bucket`, `endpoint`, `region`, `accessKey`, `secretKey`
`admin.credentialsSecret`	`username`, `password`, `email`
`mail.credentialsSecret`	`fromAddress`, `domain`, `smtpHost`, `smtpPort`, `smtpSecure`, `smtpAuthType`, `smtpName`, `smtpPassword`

App Management (`spec.apps`)¶

Declarative Nextcloud app management. See below for supported apps.

Well-Known Apps¶

App key	Configuration	Description
`richdocuments`	`enabled`, `wopiUrl`, `wopiAllowlist`	Nextcloud Office / Collabora
`spreed`	`enabled`, `stunServers`, `turnServers`, `signalingServers`, `recording`	Nextcloud Talk
`calendar`	`enabled`	Nextcloud Calendar
`contacts`	`enabled`	Nextcloud Contacts
`deck`	`enabled`	Nextcloud Deck (Kanban)
`tasks`	`enabled`	Nextcloud Tasks
`notes`	`enabled`	Nextcloud Notes
`mail`	`enabled`	Nextcloud Mail client
`collectives`	`enabled`	Nextcloud Collectives (team wikis)
`whiteboard`	`enabled`	Nextcloud Whiteboard
`forms`	`enabled`	Nextcloud Forms
`admin_audit`	`enabled`	Admin Audit Log
`groupfolders`	`enabled`	Group Folders
`photos`	`enabled`	Nextcloud Photos
`previewgenerator`	`enabled`	Preview Generator

Custom Apps¶

apps:
  custom:
    - appId: files_retention
      enabled: true
    - appId: announcementcenter
      enabled: false

Note

Setting enabled: false disables an app. Removing an app entry entirely does not uninstall it — this prevents accidental data loss.

Status¶

Version Resolution¶

status:
  versionResolution:
    requestedVersion: "32.0.6"
    resolvedVersion: "32.0.6"
    chartVersion: "8.9.1"
    resolvedBy: builtin

Phase Values¶

Pending: Resource created, validation in progress
Creating: Creating secrets, HelmRelease, managed database
Ready: All resources created and HelmRelease reconciled
Updating: Spec change detected, updating resources
Failed: Error occurred (see conditions for details)

RBAC¶

To interact with these resources, you need appropriate RBAC permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: nextcloud-manager
rules:
  - apiGroups: ["k8s.bnerd.com"]
    resources: ["nextclouds", "nextcloudinstances", "nextcloudpools",
                "nextcloudprofiles", "signalingservers", "recordingservers"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]