Scaling Collabora Online on Kubernetes when one server is no longer enough
When one Collabora Online server can no longer carry your Nextcloud or other WOPI host users, a platform team has two supported routes to more than one pod: the COOL Controller and the official Helm chart. Both depend on WOPISrc-aware routing, because every user editing a document must reach the same pod, and a load balancer that ignores the WOPISrc parameter will split a session across pods and break collaborative editing. The COOL Controller is the component for memory-based scaling and for moving documents between pods, which the chart alone does not do. The chart, by contrast, disables horizontal pod autoscaling and sets replicas manually, so the replica count is a decision your team owns and changes through configuration.
Before either path applies, the Kubernetes cluster itself has to be built and run to your standard: control plane high availability, identity integration, secrets handling and etcd backups are prerequisites, not features of Collabora Online. Plan the cluster's upgrade cadence early, since Kubernetes ships roughly three minor releases a year and you will need to track which minor versions remain supported. Confirm with Collabora which Helm chart and controller versions match your Collabora Online branch before you pin them. The free CODE Docker image is suited to testing, home use or small teams and is not recommended for production, so a production cluster should run a supported Collabora Online deployment. The server code is licensed under MPL-2.0, which you should confirm with your legal team against your own distribution and modification plans. Review the Collabora Online Helm chart README before you decide how many replicas you will start with.
Why the Helm chart turns off autoscaling and what the controller must solve
The official Helm chart README states that horizontal pod autoscaling is disabled because scaling breaks collaborative editing and copy and paste. Replica counts are therefore set by hand, and the load balancer in front of the pods must route by the WOPISrc parameter so that every user editing one document reaches the same pod. A standard autoscaler adds and removes pods based on CPU or memory pressure without regard to which documents live where. For Collabora Online, a pod that is removed takes its open document sessions with it, and a new pod has no sessions to share. Any scaling design therefore starts from the session, not from the pod count.
That leaves the controller with a specific job: move or drain work between pods without splitting a document session. Memory is the signal this topic focuses on because each open document consumes it for as long as it stays loaded, and large spreadsheets and presentations make that consumption uneven across pods. A controller that reads memory per pod can decide when a pod is under pressure, and when a pod is idle enough to be drained at night or on weekends. Before you rely on that model, confirm with Collabora's COOL Controller documentation how it migrates documents, how it elects a leader, and which memory metric it reads and how often. This page does not claim those details.
The chart's recommended production limits of 8 CPU cores and 8000 MiB of memory per pod, with requests of 4 cores and 6000 MiB, are the sizing baseline to validate, not a guarantee of capacity for your users. Test those values against your document mix, including the large files your teams actually open, before you set replica counts or memory thresholds for the controller. Record the memory each pod holds at your expected peak, and confirm whether the controller's thresholds fit inside the limits you set. If they do not, a fixed replica count may serve you better than automated scaling.
Fixed replica count or controller-managed scaling, by situation
When usage is predictable and stays within a known range through the working day, a fixed replica count set in the Helm chart is usually the simplest choice. The chart disables horizontal pod autoscaling because scaling breaks collaborative editing and copy and paste, so replicas are set by hand and the load balancer must route by the WOPISrc parameter so every user editing one document reaches the same pod. With a steady base, you size the replica count once from measured concurrency, then monitor memory and session counts to confirm the assumption still holds.
- Fewer moving parts: Only the chart, the ingress and the WOPISrc routing need to be maintained, with no controller to upgrade or debug.
- Predictable capacity: Each pod runs with the chart's production resource settings, so you know what the cluster reserves at all times.
- Planned replica changes: Adding a pod is a deliberate change through the chart values, reviewed and rolled out during a maintenance window.
- Headroom instead of automation: You carry spare capacity for growth and incident response, which costs idle compute every hour of the day.
- Monitoring as the trigger: Set alerts on memory and active sessions so a manual increase happens before users notice slow editing.
Before settling on a fixed count, confirm with your own measurements that the peak is flat enough that the spare capacity does not become the dominant cost.
When most editing happens during business hours and nights and weekends are close to idle, a fixed count sized for the peak runs mostly empty. The COOL Controller is designed for this pattern: it can scale on memory and scale pods down at night and on weekends, and it can migrate documents between pods when capacity changes. That benefit only pays off if the savings outweigh the extra component you must install, upgrade and troubleshoot. Treat the controller as a tool to evaluate, not a default.
- Where the savings come from: Compare the idle hours of a fixed peak-sized deployment against your real usage curve before counting controller savings.
- Scaling on memory: Confirm which memory signal the controller uses and whether it reacts quickly enough to a morning surge.
- Scale-down risk: Verify how sessions are moved or ended when pods are removed at night, since a scale-down that interrupts a late editing session is a user-visible failure.
- Extra platform work: Plan for the controller's installation, its permissions in the cluster and its upgrade cycle alongside the chart.
- Schedule ownership: Decide who changes the night and weekend schedule, and how holidays and unplanned events are handled.
Before relying on scale-down or document migration, confirm the controller's exact behavior in the target version in a test cluster, and rehearse a peak with live editing sessions.
Hosting providers and SaaS products often serve many WOPI hosts, tenants or customers from shared Collabora capacity. Here, load is less a single curve than the sum of several independent curves, which can make a fixed count look reasonable at the aggregate level while individual tenants still see contention. The controller becomes more attractive when aggregate demand moves in ways a single planner cannot track, but tenant isolation, routing and allow lists become the harder problems. Scaling does not solve these, so design them first.
- Routing per tenant: WOPISrc routing must keep every document on one pod, and the Nextcloud administration manual's guidance on restricting WOPI requests to known server addresses still applies to each host.
- Isolation decisions: Decide whether tenants share pods or get dedicated deployments, since shared pods make one tenant's large spreadsheets affect others.
- Capacity reporting: Measure load per tenant so you can justify replica changes and bill or allocate capacity fairly.
- Migration exposure: Document migration between pods touches many tenants at once, so test it under realistic mixed load before enabling it broadly.
- Support boundaries: Agree on who owns scaling incidents when a tenant's application and the Collabora layer both show symptoms.
Before committing, confirm with Collabora and in a staging environment how the controller handles multiple WOPI hosts in your version, and whether a fixed, per-tenant pool is simpler to operate.
Configuration options and when each one fits
This table compares the main configuration choices for running Collabora Online on Kubernetes, from a fixed replica count to controller-driven scaling and scheduled scale-down. Read each row as a decision: what it controls, the conditions where it suits your load, and what to confirm in the chart README and controller documentation before you commit. The main takeaway is that the chart's own guidance favors manually set replicas, so any automation needs a clear reason and a tested document-migration path.
| Option | What it controls | When it fits | What to confirm before choosing it |
|---|---|---|---|
| Fixed replica count set through the chart | Number of Collabora Online pods that stay running at all times | Steady user load with predictable peaks, and teams that want the simplest failure model | Replica value key and the chart README guidance on manual replica counts for your chart version |
| COOL Controller with memory-based scaling | Adds or removes pods based on memory use rather than a fixed count | Large or variable document workloads where memory pressure, not request count, is the limit | Which memory thresholds the controller uses, how it moves open documents between pods, and the controller documentation for your release |
| Scheduled scale-down for nights and weekends | Lowers the replica count during set off-hours windows | Organizations with clear idle periods and no overnight editing or scheduled batch conversions | Schedule syntax, minimum replicas during off-hours, and whether open sessions are drained or migrated first |
| Ingress choice (Nginx, HAProxy or OpenShift Router) | Which proxy terminates traffic and applies WOPISrc-based routing | Nginx, HAProxy or OpenShift Router is already your standard edge component | Annotation or configuration needed to route by the WOPISrc parameter and WebSocket timeout settings for that ingress |
| Per-pod resource requests and limits | CPU and memory reserved and capped for each Collabora Online pod | Every production deployment, since sizing drives how many documents one pod holds | Chart defaults against the recommended production values for your expected concurrency and largest spreadsheets |
| Umbrella chart values | Holds the replica, scaling, ingress, resource and WOPI host settings together | Teams deploying Collabora Online alongside other charts in one release or GitOps repository | Exact value keys in the Collabora Online chart and any parent chart, and how overrides are merged per environment |
| WOPI host allow list | Which Nextcloud or other WOPI host addresses may reach the servers | Any deployment behind a network boundary or with multiple WOPI hosts | Source addresses of your WOPI hosts, including after any ingress or load balancer address change |
Setup sequence for the umbrella chart, with checks at each step
This sequence takes a cluster from a supported, highly available base to a Collabora Online deployment where the COOL Controller is installed through the umbrella chart and every editor of one document reaches the same pod. Each step ends with a check you can record before moving on.
Confirm the cluster is supported and highly available
The platform team confirms the Kubernetes distribution is CNCF conformant and running a minor version that the project still maintains, using the releases page to check end-of-life dates. They confirm a highly available control plane, with at least three control plane nodes and a TCP load balancer in front of kube-apiserver, and that etcd has an odd member count and a tested backup plan. Done when the team can show the version, the control plane node count and a successful etcd snapshot restore test in a non-production environment. Confirm exact version support windows on the Kubernetes release pages before you commit.
Confirm the ingress controller and WOPISrc routing
Choose the ingress controller that the Collabora Online chart supports, such as Nginx, HAProxy or the OpenShift Router, and confirm how it can route by the WOPISrc parameter so that all requests for one document go to one pod. Check the chart README for the exact annotations or configuration keys, because the routing behavior depends on them. Done when a test request with two different WOPISrc values lands on two different backends and two requests with the same WOPISrc value land on the same backend. Stop here if the ingress cannot route on that parameter.
Install the Collabora Online chart with fixed replicas
The platform engineer installs the Collabora Online Helm chart with horizontal pod autoscaling left disabled and the replica count set manually, because the chart README states that scaling breaks collaborative editing and copy and paste. Set CPU and memory requests and limits from the README values, which list 4 cores and 6000 MiB as requests and 8 cores and 8000 MiB as limits for production pods, and confirm them against your own sizing. Done when all pods are Ready, the replica count matches the values file, and each pod reports its resource settings with
kubectl describe pod.Install the COOL Controller through the umbrella chart
Install the COOL Controller using the umbrella chart, following the controller documentation for the chart version that matches your Collabora Online release. Confirm how the controller is configured for memory-based scaling, leader election and document migration between pods, and keep the settings that control scale-down at night and weekends in version control. Done when the controller pod is Running, the leader election lease names one active leader, and the controller logs show it reading the Collabora pods. Record the chart and image versions used, since the controller and Collabora Online must be upgraded together.
Configure the WOPI allow list and HTTPS
The Nextcloud or other WOPI host administrator adds the Collabora Online server URL to the WOPI configuration and restricts WOPI requests to the addresses of the Collabora servers or ingress, as the Nextcloud administration manual recommends. Use the same protocol for the Collabora URL as for the host, preferably HTTPS, and confirm certificate trust between the two systems. Done when the host's Office settings show the Collabora server as reachable, and a request from an address outside the allow list is refused. Confirm the allow list format in the controller and chart documentation, since the exact keys vary.
Validate with a shared test document
The QA lead opens a test document from the WOPI host with several test accounts at the same time, including a spreadsheet and a presentation, and checks that all editors connect to the same pod through the pod logs or the controller view. They test copy and paste between sessions, make edits from each account, and confirm that every change appears for every editor. Then they trigger a controlled pod restart or scale event outside working hours and confirm that the session is migrated or reconnects without losing edits. Done when the test results and log excerpts are saved as the baseline for operations.
Securing the cluster that runs Collabora Online
The COOL Controller adds moving parts to the cluster: an API that can change replica counts, secrets that hold credentials, and pods that open documents from users. Each card below is a control to set and check before the scaling design goes live, and together they cover who can change the cluster, how its secrets are protected, how the pods run, who can reach them, and how fixes reach production.
Authenticate platform operators
Decide how people reach the Kubernetes API before anyone touches replica counts. Kubernetes does not create user objects; it relies on X.509 client certificates, bearer tokens such as OpenID Connect and JWT, webhook token authentication or an authenticating proxy. Choose one method for operators, disable shared static credentials, and confirm that the identity provider's group claims map to the roles that can scale the Collabora deployment.
Encrypt Secrets at rest
Secrets are stored unencrypted in etcd by default. Any credential the Collabora deployment or the Nextcloud WOPI connection uses, including TLS material and registry pull credentials, sits in that store until you change it. Enable encryption at rest for the Secrets resource, or load credentials from an external store through the Secrets Store CSI Driver. Then confirm that etcd snapshots used for backup are protected the same way.
Scope RBAC to scaling actions
Limit who can change the replica count, the resource requests and limits, and the COOL Controller settings. Grant those verbs to a small operator group on the Collabora namespace only, and keep list and watch access to Secrets with the fewest principals possible. Review bindings after each team change, because a single role that can patch the Deployment or StatefulSet can also remove the memory limits that keep one document from starving its neighbors.
Enforce Pod Security Standards
Apply a Pod Security Standards level to the namespace that runs the Collabora pods, starting with the restricted profile where the image allows it. Check that the pods run as non-root, drop unneeded Linux capabilities and do not mount host paths. Test the setting in audit or warn mode first, because a pod that fails admission will stop a scale-up at the moment a busy period needs more capacity.
Restrict WOPI requests by source
Limit WOPI traffic to the Collabora endpoint so that only the Nextcloud server and the approved ingress addresses can reach it. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers and using the same protocol, preferably HTTPS, for the Collabora server URL as for the Nextcloud installation. Record the allowed addresses in the ingress configuration and recheck them whenever nodes or load balancers change.
Patch from Collabora advisories
Subscribe to Collabora's security advisories and track the branch your cluster runs. The 25.04 release notes record that 25.04.7.5, released January 29, 2026, fixed CVE-2026-23623, and that package signing keys were updated for RPM and DEB users. Set a rollout procedure that pins the image tag, tests a canary pod, and verifies new signing keys before a rolling restart reaches every replica.
What scaling Collabora Online on Kubernetes costs and asks of your team
What drives the effort of scaling Collabora Online on Kubernetes?
The main drivers are how mature your cluster already is, how many WOPI hosts will call Collabora, how the routing layer is set up, and how much controller testing your scaling rules need. A cluster with monitoring, GitOps delivery and tested ingress takes less time to extend than a first Kubernetes platform. Each additional WOPI host adds integration and allow list work, since every host must reach the same routing rules. Routing setup is driven by your ingress choice (Nginx, HAProxy or OpenShift Router are the options named in the Helm chart README) and by whether WOPISrc-aware balancing is already in place. Controller testing covers memory thresholds, document migration between pods and scale-down windows, and it grows with the number of scenarios you need to prove. Ask for each of these to be listed separately in the written scope.
Can a small platform team run Collabora Online on Kubernetes alone?
A small team can run it if it already operates Kubernetes confidently and has someone who owns ingress, certificates and upgrades. The Collabora Online Helm chart README states that horizontal pod autoscaling is disabled because scaling breaks collaborative editing and copy and paste, so replica counts are set manually and routing must keep every user editing one document on the same pod. Engineers also need to understand the controller's leader election, the scale-down schedule and how upgrades interact with open sessions. If those skills are thin, a fixed replica count may be the safer first step, and a partner can help you decide which path fits your team.
What do Collabora's paid plans include compared with CODE?
CODE is the free edition, released roughly once a month as a rolling release, and Collabora describes it as suited to testing, home use or small teams but not recommended for production. The Business plan costs 3 euros per user per month for up to 99 users, according to Collabora's pricing page, and includes long term support, a service level agreement, signed security updates and customer portal access. The Enterprise plan, for 100 or more users, is quoted with volume discounts and adds integration support, customization services and roadmap input. Subscription fees are recurring and paid to Collabora, so they sit alongside, not inside, any implementation fee for the Kubernetes work. Confirm the current terms directly with Collabora before budgeting.
How long does scaling Collabora Online on Kubernetes take?
The duration depends on the same factors that drive effort: cluster maturity, the number of WOPI hosts, the routing design and the number of controller scenarios to test. Most engagements are fixed-scope, so the timeline is agreed in writing before work starts and tied to named deliverables. A cluster that already has tested ingress, certificates and a staging environment will move faster than one that needs those built first. Ask for the timeline to show separate phases for routing, controller installation, load testing, scale-down verification and handover. DeployOpen does not publish fixed durations, and any timeline follows from the written scope.
What does your team need to provide for a Collabora Online scaling project?
Your team typically provides the following inputs:
- Cluster access with the namespace, RBAC and Pod Security Standards settings the deployment needs
- DNS records for the Collabora server URL and a named owner for changes to them
- TLS certificates for the Collabora and ingress endpoints, following the protocol guidance in the Nextcloud administration manual, which recommends HTTPS
- Test documents in the formats your users rely on, including docx, xlsx and pptx
- Change windows for staging and production, including agreed times for controller tests and upgrades
- Named contacts in the WOPI host teams who can confirm allow list entries
Missing any of these usually delays the schedule, so ask for a written list of inputs with the quote.
Do you need the COOL Controller to scale Collabora Online on Kubernetes?
No. A fixed replica count is enough when your load is steady, your peak is predictable and you can accept manual changes to replica numbers. The controller becomes worth evaluating when usage varies sharply across the day or week, when you want memory-based scaling, or when you need documents to move between pods during scale-down. Each of those adds moving parts that your team must test and operate, including leader election and migration behavior. Start by measuring real concurrency and memory use under your own workload, then decide. The Helm chart README sets production limits of 8 CPU cores and 8000 MiB of memory per pod with requests of 4 cores and 6000 MiB, which is a useful baseline for that measurement.
What happens to open editing sessions during scale-down and upgrades?
Open editing sessions are the main risk when pods change, because the Helm chart README warns that scaling breaks collaborative editing and copy and paste. The controller's document migration is designed to move documents between pods during scale-down, but you should verify its behavior in your own environment rather than assume it. Test scale-down at night and on weekends with active sessions, confirm that users see no loss of unsaved edits, and check that WOPISrc routing still sends each document to one pod afterward. Schedule Collabora upgrades in the same change windows, and confirm the upgrade path with Collabora before you start.
Does DeployOpen quote the scaling work from a fixed scope?
Yes. Most DeployOpen engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. A quote follows from that written scope, so the more clearly you define your WOPI hosts, cluster state, routing requirements and controller test cases, the more precise the quote will be. DeployOpen does not publish a price list. Ongoing support, upgrades and continuous testing are available as retainers if you want help after handover.
The Kubernetes foundation the chart depends on and what to confirm
Before the Collabora Online chart goes near a cluster, the platform team needs a Kubernetes minor version that is still maintained. The project supports the three most recent minor releases, and as of September 2026 those were 1.37, 1.36 and 1.35, with end-of-life dates of October 28, 2027, June 28, 2027 and February 28, 2027 respectively, according to the Kubernetes releases page. Kubernetes ships roughly three minor releases a year on a cycle of about 14 weeks, so a version that is current at design time can leave support during the rollout. Check the Kubernetes releases page on the day you sign off the plan, and build the upgrade of the cluster into the schedule for the Collabora Online change window rather than treating it as a separate project.
The control plane has to be upgraded in the order the version skew policy sets: kube-apiserver first, one minor version at a time, then kube-controller-manager, kube-scheduler and the kubelets. Kubelets may run up to three minor versions behind the API server, which gives room to plan node rotations, but it does not make skipping steps safe. For resilience, the kubeadm high availability guide describes a stacked topology (etcd on the control plane nodes) and an external etcd topology, both with at least three control plane nodes and a TCP load balancer in front of kube-apiserver on port 6443. Confirm with your distribution vendor which topology and load balancer it supports, and whether the Collabora pods will reach the API server through that same endpoint.
etcd is where the cluster state lives, so it sets the recovery limit for everything running on top. Kubernetes documentation calls for an odd number of etcd members and recommends five members in production, and it requires a backup plan. Confirm that snapshots are taken with etcdctl snapshot save, stored off the cluster, and restored in a rehearsal with etcdutl, not only written. Also confirm that Secrets are encrypted at rest, because the Secrets good practices page notes they are stored unencrypted in etcd by default. Collabora's WOPI and TLS credentials will sit in Secrets, so this check belongs in the foundation review rather than the application review.
Limits to confirm in your environment before you commit
The COOL Controller sits between Kubernetes, the Collabora Online chart and your users' editing sessions, so each limit below depends on versions and settings you choose. Confirm these items with Collabora and your Kubernetes distribution before you commit to a design, and record the answers in your sizing and change records.
Controller and Kubernetes version support
Confirm which Collabora Online releases and which Kubernetes minor versions the COOL Controller supports in the release you plan to deploy. Kubernetes maintains only its three most recent minor releases, so a controller build that lags behind your cluster will force an upgrade you did not schedule. Ask Collabora for the support matrix in writing, and check that it matches the Kubernetes version your platform team will run for the life of the project.
Memory-based scaling behavior
Confirm that the controller scales on memory the way the topic describes in your target release, including how it measures memory per pod, the thresholds it uses and how long it waits before adding or removing a replica. Run a test with synthetic load that resembles your largest documents. Scaling decisions that react too slowly will leave editors waiting, and decisions that react too quickly will move sessions while people are still typing.
Scale-down schedules and off-hours windows
Confirm how the night and weekend scale-down schedule handles the time zone of your users, daylight saving changes and public holidays. Check what happens when a user opens a document just before the scale-down window closes. A schedule that reduces replicas while sessions are still open can interrupt editing, so test the boundary behavior with a live session rather than assuming the schedule is safe.
Document migration with active editors
Confirm how the controller moves documents between pods while people are editing them. Ask whether migration pauses or drops WebSocket connections, how long a document stays unavailable, and whether unsaved changes survive the move. Test migration with several editors in one document and with a large spreadsheet, because the failure mode for a shared document is more visible to users than a single-user session.
WebSocket timeouts and ingress settings
Confirm the proxy and ingress timeouts your controller and chosen ingress (Nginx, HAProxy or OpenShift Router) require for long editing sessions. Idle WebSocket connections that a proxy closes early will show up as lost sessions. Check that the ingress passes the WOPISrc parameter so that routing stays document-aware, and confirm the timeout values in the chart and ingress configuration before the first production test.
Per-pod limits and Kubernetes conformance
Confirm that the chart's production limits of 8 CPU cores and 8000 MiB of memory per pod fit your largest documents and your user counts, and that your node sizes leave room for them. Then confirm that the Kubernetes distribution you chose is listed as conformant with the CNCF program, since the conformance check covers the APIs the controller depends on. CNCF reports over 90 Certified Kubernetes offerings, so ask the vendor for the conformance entry for the exact version.
How DeployOpen scopes and delivers Collabora Online scaling on Kubernetes
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Collabora Online scaling on Kubernetes with the COOL Controller, we start from your concurrency, document mix and cluster constraints, then agree the scope in writing before any work begins.
How we scope
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- The written scope names the Kubernetes distribution, ingress controller, WOPI hosts and Collabora Online branch in use.
- Scoping records which workloads will scale with the COOL Controller and which will keep a fixed replica count.
How we build
- We install the COOL Controller and the Collabora Online umbrella chart in your cluster, with values reviewed per environment.
- We configure WOPISrc-aware routing at your ingress so every request for a document reaches the same pod.
- We test leader election, document migration between pods and scale-down windows against your own usage pattern before go-live.
How we hand over
- You receive the chart values, controller configuration and routing rules under version control in your environment.
- Runbooks cover scale-down schedules, failover behavior, rollback steps and how to read scaling and migration events.
- Knowledge transfer sessions walk your platform team through upgrades, Kubernetes version skew and the decision points we documented.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- A retainer can cover Collabora Online point releases, Kubernetes minor upgrades and security advisory review.
- Ask any quote to separate one-time build work from recurring support, so budgets reflect both.
