You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 013dda2
Browse filesBrowse the repository at this point in the historyBrowse files
docs(upgrade): give default-variant operators the HTTPCache freeze
The v1.7 upgrade page says the HTTPCache steps of migration 58 fall to
the operator on the default variant, yet its pre-upgrade checklist
never mentions HTTPCache and the entry offered a check with no action.
Left alone, the upgrade prunes the HTTPCache PackageSource and leaves
http-cache-rd and every tenant release Ready=False for good.
HTTPCache now has its own section carrying the migration's steps, so a
default cluster can freeze its instances, or remove the application
where none exist, before it upgrades.
Assisted-by: LLM
Signed-off-by: Myasnikov Daniil <[email protected]>
Copy file name to clipboardExpand all lines: content/en/docs/next/operations/cluster/upgrade-to-v1.7.md
+84-3Lines changed: 84 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ On every other variant the v1.7 platform release runs platform migrations 54 to
26
26
- Gateway API: check the certificate served on `api.<apex>` and the hostnames of routes in tenant namespaces. See [Gateway API](#gateway-api).
27
27
- VM instances: fix `resources` values that cannot size a VM. See [Smaller changes](#smaller-changes).
28
28
- Kafka: plan a maintenance window for every instance. See [Kafka moves to KRaft](#kafka-moves-to-kraft).
29
-
-`default` variant only: pin the SeaweedFS volume size limit and look for volumes hotplugged on a VM instance only. See [SeaweedFS volume size limit](#seaweedfs-volume-size-limit) and [Declarative volume hotplug](#declarative-volume-hotplug).
29
+
-`default` variant only: pin the SeaweedFS volume size limit, look for volumes hotplugged on a VM instance only, and freeze HTTPCache or remove it from the platform. See [SeaweedFS volume size limit](#seaweedfs-volume-size-limit), [Declarative volume hotplug](#declarative-volume-hotplug) and [HTTPCache](#httpcache).
30
30
- While the platform upgrade runs, do not edit `Kubernetes` resources. See [Worker pools become KubernetesNodes resources](#worker-pools-become-kubernetesnodes-resources).
31
31
32
32
## Platform migrations
@@ -39,7 +39,7 @@ The platform migration version moves from 54, where v1.6 left it, to 60. On ever
39
39
| 55 | Detaches the HelmReleases of the removed FluxCD addon of tenant Kubernetes clusters without uninstalling Flux inside the tenant cluster. See [FluxCD addon removed](#fluxcd-addon-removed). |
40
40
| 56 | Moves the worker pools of every tenant Kubernetes cluster into one `kubernetes-nodes-<cluster>-<pool>` release per pool. See [Worker pools become KubernetesNodes resources](#worker-pools-become-kubernetesnodes-resources). |
41
41
| 57 | Writes `master.volumeSizeLimitMB: 1000` into every SeaweedFS instance that has no valid value of its own. See [SeaweedFS volume size limit](#seaweedfs-volume-size-limit). |
42
-
| 58 | Freezes HTTPCache on the packages artifact the cluster already runs, or removes it from the platform where no instance exists. See [Smaller changes](#smaller-changes). |
42
+
| 58 | Freezes HTTPCache on the packages artifact the cluster already runs, or removes it from the platform where no instance exists. See [HTTPCache](#httpcache). |
43
43
| 59 | Copies volumes that are hotplugged on a running VM instance but missing from its `VirtualMachine` spec into that spec. See [Declarative volume hotplug](#declarative-volume-hotplug). |
44
44
45
45
After the upgrade, the `cozystack-version` ConfigMap shows the version the migrations reached:
@@ -299,10 +299,91 @@ The last line must read `complete` with the same number as the first. If it is m
299
299
300
300
The full check to run before lowering the limit of an instance that holds data is in [SeaweedFS volume size limit: lowering it on an existing instance](https://github.com/cozystack/cozystack/blob/main/docs/operations/seaweedfs-lowering-the-volume-size-limit.md).
301
301
302
+
### HTTPCache
303
+
304
+
The HTTPCache application is removed from the catalog and no new instance can be created. Its PackageSource, `cozystack.http-cache-application`, is no longer part of the platform release, so the upgrade prunes it, and the ArtifactGenerator and both ExternalArtifacts it owns go with it. They are the chart sources of `http-cache-rd` in `cozy-system` and of every tenant `http-cache-<name>` release. Left alone, those releases stay `Ready=False` for good: each instance reads as not ready while its pods keep serving, and `HelmReleaseNotReady` fires where the monitoring agents run.
305
+
306
+
- On every variant except `default`, platform migration 58 handles this. On a cluster that runs an instance, it freezes the application on the packages artifact the cluster already renders from: the instance keeps working and stays manageable, but receives no further updates, security fixes included. On a cluster without one, the migration removes the application from the platform.
307
+
- On the `default` variant nothing does. Before upgrading such a cluster, take the migration's steps yourself with the commands below, while `cozystack-packages` still resolves the release the cluster runs.
308
+
309
+
List the HTTPCache releases. They are selected by chart and by application label, so a release whose chart reference was never rewritten is found too:
310
+
311
+
```bash
312
+
kubectl get helmreleases.helm.toolkit.fluxcd.io --all-namespaces -o json \
or .metadata.labels["apps.cozystack.io/application.kind"] == "HTTPCache")
316
+
| "\(.metadata.namespace)/\(.metadata.name)"'
317
+
```
318
+
319
+
If it prints nothing, remove the application from the platform. Run the commands in this order: the first one waits until the Package is gone, so that a reconcile already in flight does not re-create what the others remove. On a cluster where the application was never installed they change nothing.
An instance that is no longer needed can be deleted before the check, so that the cluster takes this path instead of the freeze.
329
+
330
+
Otherwise, freeze the application. Run the remaining commands in one shell session, because they carry the digest from one step to the next. First read the manifest digest `cozystack-packages` resolves to now:
331
+
332
+
```bash
333
+
src=$(kubectl -n cozy-system get ocirepositories.source.toolkit.fluxcd.io cozystack-packages -o json)
It must print `sha256:` followed by 64 hexadecimal characters. If it prints nothing, `cozystack-packages` has neither a digest ref nor a resolved artifact revision, and there is nothing to freeze on: do not go further until it has one. The freeze also assumes `cozystack-packages` is pinned to a fixed release, since a floating tag re-pointed in place would pin an artifact that no longer carries the chart.
342
+
343
+
Then create the frozen source, point the application at it, and keep the access of instance owners:
The first command creates `cozystack-packages-http-cache`, a copy of `cozystack-packages` pinned to that digest. It keeps the registry, pull secret and verification settings of the original and carries no owner references or Helm metadata, so nothing reconciles or prunes it. The two patches point the PackageSource at the copy and detach it and the Package from the platform release, so the upgrade does not prune them. The ClusterRole keeps the owner of an instance able to change and delete it once v1.7 drops `httpcaches` from `cozy:tenant:admin:base`. After the upgrade, `http-cache-rd` and every release the first listing printed stay `Ready`.
383
+
302
384
### Smaller changes
303
385
304
386
- **VM instances.** `resources.cpu` and `resources.sockets` must be positive whole numbers and `resources.memory` at least `1M`. A value such as `500m`, `1.5` or `0` now fails the render of the release, and a release carrying one fails its next upgrade until the value is fixed, with an error such as `resources.cpu (500m) must be a positive whole number, such as 2`. A value such as `1e1` or `2.`, which used to give the VM one core, now sizes it with the number it spells.
305
-
- **HTTPCache.** The HTTPCache application is removed from the catalog and no new instance can be created. On a cluster that runs one, platform migration 58 freezes it on the packages artifact the cluster already renders from: it keeps working and stays manageable, but receives no further updates, security fixes included. On a cluster without one, the migration removes it from the platform. The `default` variant runs no migration, so check for instances there before upgrading with `kubectl get httpcaches.apps.cozystack.io -A`.
306
387
- **Application definitions.** `ApplicationDefinition.spec.application.release.prefix` must match `^[a-z0-9-]*$`. A definition whose prefix holds a dot or any other character is refused when it is applied, so check definitions that come from external application repositories.
307
388
- **RabbitMQ and Redis TLS** are new and off by default; nothing changes on upgrade until TLS is enabled on an instance.
308
389
- **Keycloak realm name.** The realm is now configurable with `authentication.oidc.realmName`, `cozy` by default. Set it only at install time; see the [Platform Package reference]({{% ref "/docs/next/operations/configuration/platform-package" %}}).
0 commit comments