Why a Collabora Online Helm chart upgrade needs its own plan
Upgrading a cluster that runs the collabora-online umbrella chart and the COOL Controller changes two things at once: the Collabora Online version that serves documents and the controller that decides which pod each open document is routed to. Those two components, along with the Kubernetes version under them, must be checked together before any rollout starts, because a chart release can assume controller behavior and a controller release can assume a Kubernetes API. The work is harder than a single-binary upgrade because people are editing while it happens, so the plan has to protect the documents that are open, not only the servers that host them.
The chart pins the Collabora Online version it deploys, and the COOL Controller manages document routing across the pods, so the target is a matched set rather than two independent version numbers. Confirm the exact chart version, controller version and Collabora Online application version against the release notes and the chart README at the time of the work, since these move on their own schedules. Record the current versions of all three, read the changes between each current and target version, and note any change to leader election, replica handling or restart behavior. The official chart README is the first place to check how replicas are set and how the load balancer must route by the WOPISrc parameter, because those settings determine what a rolling restart does to live sessions.
What changes in the chart and controller, and what each change asks of you
This table lists the chart and controller behaviors that affect an upgrade, what each one means for a running deployment, and the action to take before or during the change window. Read each row against the release notes for your target version, since the specific controller changes depend on that version.
| Change | Impact | Action needed |
|---|---|---|
| Rolling restart behavior in COOL Controller 1.4.1 | Earlier builds could leave an editor unresponsive for the full termination grace period during a rolling restart. In 1.4.1, open documents move to a pod that stays as soon as the restart begins. | Confirm your current controller version. If you run a build older than 1.4.1, schedule the upgrade before relying on rolling restarts during editing hours, and test a restart with an open document. |
| Horizontal pod autoscaling disabled | The chart README states that scaling breaks collaborative editing and copy and paste, so autoscaling is turned off and replica counts are set by hand. | Remove any autoscaler you attached to the deployment, and set replica counts in your values file based on your own capacity testing. |
| WOPISrc-aware load balancing | The README requires the load balancer to route by the WOPISrc parameter so all users editing one document reach the same pod. | Check your ingress rules after the upgrade and confirm that requests for one document always land on the same pod. Test with two users opening the same file. |
| Production resource limits | The README recommends limits of 8 CPU cores and 8000 MiB of memory per pod, with requests of 4 cores and 6000 MiB. | Compare these values with your current values file. Confirm that your nodes can schedule the requests and that your sizing tests support the number of pods you plan to run. |
| Supported ingress controllers | The chart supports Nginx, HAProxy and OpenShift Router ingress. Other controllers need separate validation. | Confirm which ingress controller you run and check its configuration against the chart README before the upgrade. Test WOPI traffic after the change. |
| Leader election changes | Leader election behavior can change between controller releases, which affects which instance handles coordination during a restart. | Read the COOL Controller release notes for your target version and confirm the specific election changes. Plan a test restart in a staging cluster. |
| Monitoring rule updates | Alert rules and dashboards written for an older controller may miss new metrics or fire on renamed ones. | Read the release notes for metric or label changes, update your alert rules, and confirm that alerts still fire in a test scenario. |
What to inventory and back up before the upgrade starts
The chart upgrade is only as safe as the record of what it replaces. Each card below names an artifact to capture, the state it protects, and the person who should sign off on it before any pod restarts.
Chart values and rendered manifests
Record the exact values.yaml used for the current release, plus the rendered manifests from helm template for both the old and the new chart version. Diff them before the upgrade so unexpected changes to replica counts, resource requests, image tags or ingress annotations are visible. The platform engineer who owns the Helm release should keep these files in version control, tagged to the running release.
COOL Controller and Collabora Online versions
Write down the running COOL Controller version, the Collabora Online app image tag, and the Kubernetes minor version of the cluster. Compare these against the COOL Controller release notes before choosing a target, because a fix in one controller release can change how rolling restarts behave. The platform lead should confirm the target pair is supported together.
Ingress and WOPISrc routing rules
List every ingress, load balancer and proxy rule that routes by the WOPISrc parameter, including the Nginx, HAProxy or OpenShift Router configuration in front of the chart. A rule that routes on a different key can send users editing one document to different pods during a restart. The network or ingress owner should record the rules and test that one document always resolves to one pod.
etcd snapshot before the change
Take an etcdctl snapshot save backup of the control plane etcd cluster before any node or chart change, and confirm it can be read back with etcdutl. The snapshot protects the cluster objects that the chart creates, not the open documents themselves. The Kubernetes platform team owns this step and should record the snapshot path, timestamp and restore owner in the change ticket.
Kubernetes Secrets and encryption at rest
Secrets used by the deployment, such as WOPI host credentials, TLS material and any proof key references, are stored unencrypted in etcd by default. Before the upgrade, confirm that encryption at rest is configured for the Secrets resource and that the chart does not write new plaintext copies. The security engineer should check RBAC so only the release's service account can list and watch these Secrets.
Staging cluster that mirrors production
Run the upgrade first on a staging cluster that uses the same ingress type, WOPISrc routing, WOPI host integration and monitoring rules as production. Use a real WOPI host test document set and a second browser session to confirm that editing survives a rolling restart. The release manager should sign off on the staging results and the Prometheus alert rules before production starts.
The upgrade sequence for the chart and controller, with checks and rollback points
This sequence moves the collabora-online chart and COOL Controller forward in an order that protects open documents, keeps a known-good Helm revision and etcd snapshot available at every stage, and ends with monitoring that matches the new release.
Confirm target versions in release notes and README
Before changing anything, read the COOL Controller release notes and the collabora-online chart README for the target versions. Record the Collabora Online app version, the controller version and the chart version as a pinned set, and note any changed values keys, leader election behavior and replica or ingress guidance. Confirm that the chart README still states that horizontal pod autoscaling is disabled and that replicas are set manually, and that the load balancer routes by the WOPISrc parameter. Done when the pinned version set and the list of values changes are written into the change record and signed off by the person who owns the WOPI host integration.
Upgrade staging and run document tests
Deploy the pinned chart and controller versions to a staging cluster that mirrors production ingress, replica count and the WOPI host configuration. Run a fixed document test set covering docx, xlsx, pptx, PDF and any formats your users rely on, including simultaneous editing by two users on the same file. Compare rendering, save and co-editing results with the current production behavior. Done when the test log shows no fidelity or save regressions that the document owners have accepted in writing.
Snapshot etcd and export values and manifests
On the production cluster, take an etcd snapshot with etcdctl snapshot save and verify it with the etcd tooling your platform team uses for restores. Export the current Helm values, the rendered manifests from helm get manifest, the controller configuration and the ingress resources to version control. Confirm that the Secrets referenced by the release are backed up through your secrets process, since Kubernetes stores Secrets unencrypted in etcd by default unless encryption at rest is configured. Done when the snapshot file, the exported values and the manifest bundle are stored off-cluster and a restore procedure has been named for the team.
Check version skew before touching the control plane
Compare the cluster's kube-apiserver version with the Kubernetes version skew policy and the minimum Kubernetes version the new controller release supports, as stated in its release notes. Upgrade the control plane only when the skew policy or the controller requires it, and then move one minor version at a time, with kube-apiserver first, followed by kube-controller-manager, kube-scheduler and the kubelets. Done when kubectl reports the server version and every node reports a kubelet version inside the allowed skew, and the decision is recorded. If no control plane change is needed, record that the check passed and move on.
Apply the controller and chart with manual replicas
Run helm upgrade against the pinned chart version using the reviewed values file, keeping the replica count set explicitly in values because autoscaling is disabled. Let the controller finish its startup before routing new sessions to the upgraded pods. Save the new release revision number. Rollback point: if the upgrade fails or the pods do not become ready, run helm rollback to the previous revision, then confirm that the previous revision's manifest is back in place. Done when all Collabora pods report ready, the controller reports healthy and the release history shows the new revision as deployed.
Verify open documents move during a test rolling restart
In staging or a controlled production window, open documents in several sessions, including a session on each replica where possible, and start a rolling restart of the Collabora deployment. Confirm that each editor moves to a pod that stays up as soon as the restart begins, and that no editor stays unresponsive for the termination grace period. COOL Controller 1.4.1 corrected this behavior, so a result that shows unresponsive editors suggests an older controller or a configuration problem. Done when the test log shows each open document moved, saved and remained editable, and the result is recorded against the pinned version set.
Update monitoring rules for the new release
Review the alert rules and dashboards that watch Collabora pods, controller health, WOPI request errors and memory use against the chart's production resource guidance of 8 CPU cores and 8000 MiB per pod, with requests of 4 cores and 6000 MiB. Update metric names, labels or thresholds that changed in the new release, and add an alert for controller restarts during a rolling update. Test each alert by triggering it in staging. Done when every rule loads without error, each test alert fires and clears, and the on-call team has confirmed the runbook entries.
Roll out to production and keep the rollback path open
Repeat the verified sequence in production during an agreed change window, starting from the snapshot and exported values taken earlier. Watch document saves, WOPI errors and pod readiness through the first editing sessions after the change. Keep the previous Helm revision and the etcd snapshot available until the owners of the document workflows accept the result. Done when production reports the new release as deployed, sample documents save correctly across at least one rolling restart, and the change record is closed with the final version set, revision number and monitoring sign-off.
Which Kubernetes versions constrain the upgrade
The cluster version sets the ceiling for any COOL Controller or collabora-online chart upgrade, because both run as Kubernetes workloads and depend on the API the cluster exposes. Before you change the controller or the chart, record the current minor version of the control plane and of every node pool. The Kubernetes version skew policy requires that kube-apiserver is upgraded one minor version at a time and before kube-controller-manager, kube-scheduler and the kubelets. Kubelets may run up to three minor versions older than kube-apiserver, which means a node pool can lag the control plane without blocking the controller, but only within that window.
The Kubernetes project maintains the three most recent minor releases. As of September 2026, those were 1.37 (end of life October 28, 2027), 1.36 (June 28, 2027) and 1.35 (February 28, 2027), according to the Kubernetes releases page. Kubernetes ships roughly three minor releases a year on a cycle of about 14 weeks, so a cluster that was supported when you planned the upgrade can fall out of support before the controller rollout finishes. Check the support window on the day you schedule the change, not the day you started planning, and treat an unsupported cluster as a prerequisite to fix before the Collabora change.
Confirm two things with your platform team before you set a date. First, which Kubernetes distribution runs the cluster, since managed and vendor distributions may ship a different patch cadence or lag upstream minor releases. Second, whether the distribution is listed as a Certified Kubernetes offering under the CNCF conformance program, which checks that required APIs are supported. Record the answers in the change ticket, along with the target minor version for the cluster, so that the controller upgrade is not planned against a version your distribution does not support.
What makes a Collabora Online chart upgrade take longer
This table lists the factors that most often stretch a collabora-online chart and COOL Controller upgrade, with the reason each one matters and what to check before scheduling the work. Read each row as a question to answer for your own environment, since the same change can be small on a single small cluster and large across several production clusters.
| Driver | Why it matters | What to check |
|---|---|---|
| Concurrent open documents and pods | Rolling restarts move open documents to other pods, so the more documents and pods in play, the more editing sessions must be handled safely during the change. | Count peak concurrent open documents per pod and confirm the replica count you set manually, since horizontal pod autoscaling is disabled in the chart. |
| Custom ingress or proxy rules that depend on WOPISrc | Load balancers must route by the WOPISrc parameter so all users editing one document reach the same pod. Rules that do not do this can split a session during an upgrade. | Review Nginx, HAProxy or OpenShift Router rules, confirm WOPISrc routing survives the new chart values, and test a document edited across a restart. |
| Kubernetes version gap | Kubernetes upgrades must go one minor version at a time, with the API server first, so a large gap adds intermediate control plane steps before the chart change can start. | Compare your cluster version with the supported minor versions on kubernetes.io/releases and plan each intermediate step with its own checks. |
| etcd and Secrets setup | Upgrade preparation depends on a working etcd backup, and Secrets are stored unencrypted in etcd by default, so chart values that reference Secrets may need changes or encryption at rest. | Confirm a tested etcd snapshot exists, check whether encryption at rest is configured, and review which Secrets the chart reads and who can list or watch them. |
| Monitoring rules and dashboards | Alerts and dashboards built for the previous chart or controller version can fire falsely or go silent after metric names or labels change. | Compare metric names and labels in the new release with your alert rules and dashboards, and rewrite any that no longer match. |
| Integration testing with the WOPI host | Nextcloud Office or another WOPI host must still open, edit and save documents after the change, and a working server can still fail with a host that relies on a specific setup. | Prepare test documents in the formats you use, run open, edit and save tests against the upgraded server, and record results before and after. |
| Number of clusters and environments | Each cluster or environment needs its own preparation, testing and rollback, so effort grows with every extra copy of the setup, even when the chart is identical. | List every cluster, staging and production environment that runs the chart, and decide whether they are upgraded in sequence with a test pass between each. |
How to test documents and roll back a failed upgrade
Test the upgrade by moving real documents while pods are restarting, not just by checking that the pods came up. A clean helm upgrade and healthy pods do not prove that a user in the middle of an edit keeps their session. The test plan should open and edit representative files in docx, xlsx and pptx, plus at least one PDF and one ODF file, across several pods at once. Then run a forced rolling restart of the collabora-online deployment while those sessions are open. The key check is the one the COOL Controller 1.4.1 fix targets: as soon as the restart begins, the editor should move to a pod that stays and remain responsive, rather than sitting frozen until the termination grace period ends. Record which pod each session lands on before and after the restart, and confirm that edits typed during the move are saved.
Next, verify the WOPI host path, because a chart upgrade can change routing without changing the pods. Confirm that the WOPI allow list on the Nextcloud side still matches the Collabora server URL and protocol, and that the Nextcloud administration manual's guidance on restricting WOPI requests to the Collabora server IP addresses still holds after the new ingress or load balancer settings. Open the same document from two browsers and confirm both reach the same pod, since the Helm chart requires load balancers to route by the WOPISrc parameter. Check that the monitoring rules you updated for the new release still fire on a deliberate fault. Ask your ingress team to confirm how the Controller's leader election behaves during the test, because a leadership change during a restart is the scenario most likely to surprise you.
What teams ask about cost, time and effort before hiring help
What drives the cost of a COOL Controller and Helm chart upgrade?
The cost follows the amount of change and the risk the change carries, not the chart version number alone. The main drivers are how many clusters and environments are involved, how much your values files and ingress setup have diverged from the chart defaults, whether the COOL Controller version changes along with the chart, and how many WOPI hosts and integrations must be retested afterward. Monitoring rule updates and the number of document types your users rely on also add work. Ask for a written scope that lists each environment, each integration to test, and whether the work covers a staging run and a production rollout as separate steps. Quotes for this kind of work are one-time effort, while any ongoing upgrade coverage is a separate recurring arrangement that should be priced on its own line.
How long does a Collabora Online Helm upgrade take to complete?
The duration depends on the number of environments, the size of the gap between your current and target chart and app versions, and how many maintenance windows your organization can grant. A single cluster with a clean values file and one WOPI host usually moves faster than several clusters with custom ingress rules and multiple integrated platforms. Time also depends on how quickly your team can provide cluster access, approve change windows and confirm test results. Do not rely on a general estimate. Request a timeline in the written scope, with each stage (inventory, staging upgrade, document testing, production rollout and monitoring check) listed separately so you can see where your own team's availability affects the dates.
What does the internal team need to provide for an upgrade?
Expect to provide access and time more than engineering effort. The work typically needs a named contact who can approve changes, read and write access to the target Kubernetes namespace and the chart release, access to the ingress or load balancer configuration, and a maintenance window that allows open documents to be moved. A test WOPI host is essential. This is a staging instance of the platform, such as Nextcloud, with its own allow list and test accounts, so that editing can be verified before production changes. Also provide the current values files, the list of integrated platforms, and the monitoring tools that will need updated rules. Confirm each item in the written scope so responsibilities are clear on both sides.
Can our own platform team upgrade the COOL Controller and Helm chart?
Many platform teams can perform the upgrade with the official chart documentation, provided they have Kubernetes experience and time to test. The usual stalls are predictable: leader election behavior changes that were not expected, rolling restarts that leave editors unresponsive if the controller version is not current, load balancers that do not route by the WOPISrc parameter so that co-editors land on different pods, and monitoring rules that quietly stop matching renamed metrics. Teams also tend to stall when no one owns the test WOPI host or the rollback steps. Before starting, read the chart README and the COOL Controller release notes for the versions in question, and decide who will verify documents after each stage.
Does DeployOpen take over ongoing upgrades under a retainer?
Yes, DeployOpen offers ongoing support, upgrades and continuous testing as retainers. A retainer generally covers recurring work that follows the upgrade cadence of the chart and controller, such as planning each release, applying changes in staging, verifying documents and integrations, and preparing monitoring updates for production. Because the scope of a retainer depends on how many environments you run and how often you want to adopt new versions, ask for a written proposal that states the included services, response expectations, the environments covered and what falls outside the agreement. Retainer fees are recurring, while larger one-time changes such as a cluster migration are usually scoped separately.
How is an upgrade scoped and what should a written scope contain?
DeployOpen scopes most engagements as fixed-scope work, which means the scope, deliverables and timelines are agreed in writing before work starts. A useful written scope for this topic names the chart and controller versions in place and the target versions, lists every cluster, namespace and environment, identifies each WOPI host and integration to test, and states the test cases for document editing, co-editing, copy and paste, and format fidelity. It should also cover the rollback approach, the monitoring rules to update, the handover documentation and what the client must provide. Ask for explicit exclusions so you know what is not included, such as changes to the underlying Kubernetes version or etcd operations, which are separate pieces of work.
How DeployOpen scopes, delivers and supports the upgrade
DeployOpen plans and carries out the upgrade of the COOL Controller and the collabora-online Helm chart inside your own Kubernetes clusters. Each engagement starts from a written scope that names the chart and app versions, the open-document behavior you need to protect and the monitoring rules that must change.
How we scope
- Inventory your current chart version, COOL Controller version and Collabora Online app version before agreeing the target.
- Record which leader election and restart behavior your cluster relies on, and confirm it with your platform team.
- Agree in writing which monitoring rules, dashboards and alerts are updated, and who signs off on each change.
How we build
- Rehearse the chart and controller upgrade in a non-production cluster that mirrors your ingress and WOPISrc routing.
- Test a rolling restart with open documents and confirm editors reconnect to a pod that stays up.
- Document each values file change, rollback step and version pin so the upgrade can be repeated by your own team.
How we hand over
- Deliver the updated Helm values, runbook and rollback procedure in your own repository and change process.
- Walk your operators through a live restart, the expected editor behavior during it and the signals that mean to stop.
- Provide a record of tests run, versions deployed and open items that remain with your team.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer if your team wants DeployOpen to carry future chart and controller releases.
- Ask for a quote based on the written scope, which covers the cluster count, environments and monitoring changes involved.
