Skip to content

Commit 83ef88a

Browse files
docs(upgrade): give default-variant operators the HTTPCache freeze
The v1.7 upgrade guide says the default variant runs no platform migration and leaves HTTPCache to the operator, but only offers a command to list instances. Upgrading such a cluster prunes the HTTPCache PackageSource and the chart sources it owns, which leaves http-cache-rd and every tenant HTTPCache release Ready=False for good while the pods keep serving. The new HTTPCache section gives those operators the steps migration 58 takes on every other variant: remove the application where no instance exists, or freeze it on the packages artifact the cluster already runs and keep the tenant admin grant that v1.7 drops from cozy:tenant:admin:base. The commands, names and selectors are those of migration 58 at the v1.7.0 tag. The checklist and the migrations table now point at the section, which replaces the HTTPCache bullet under Smaller changes. This is #764's change as merged with the corrections from #781, in next/ and, with the rewrite release_next.sh applies, in v1.7/. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent 91b4c12 commit 83ef88a

2 files changed

Lines changed: 168 additions & 6 deletions

File tree

‎content/en/docs/next/operations/cluster/upgrade-to-v1.7.md‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ On every other variant the v1.7 platform release runs platform migrations 54 to
3434
- VM disks: let running imports finish. See [VM disks](#vm-disks).
3535
- VM instances: fix `resources` values that cannot size a VM. See [Smaller changes](#smaller-changes).
3636
- Kafka: plan a maintenance window for every instance. See [Kafka moves to KRaft](#kafka-moves-to-kraft).
37-
- `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).
37+
- `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).
3838
- While the platform upgrade runs, do not edit `Kubernetes` resources. See [Worker pools become KubernetesNodes resources](#worker-pools-become-kubernetesnodes-resources).
3939

4040
## Platform migrations
@@ -47,7 +47,7 @@ The platform migration version moves from 54, where v1.6 left it, to 61. On ever
4747
| 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). |
4848
| 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). |
4949
| 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). |
50-
| 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). |
50+
| 58 | Freezes HTTPCache on the packages artifact the cluster already runs, or removes it from the platform where no instance exists. See [HTTPCache](#httpcache). |
5151
| 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). |
5252
| 60 | Carries the release line of every FoundationDB release's `cluster.version` over to the new `version` value, and records the FoundationDB, OpenSearch, Kubernetes and KubernetesNodes releases that need attention in the `cozystack.io/migration-60-needs-attention` annotation of the `cozystack-version` ConfigMap. See [FoundationDB](#foundationdb) and [Image overrides](#image-overrides). |
5353

@@ -363,10 +363,91 @@ The last line must read `complete` with the same number as the first. If it is m
363363

364364
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).
365365

366+
### HTTPCache
367+
368+
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.
369+
370+
- 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.
371+
- 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.
372+
373+
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:
374+
375+
```bash
376+
kubectl get helmreleases.helm.toolkit.fluxcd.io --all-namespaces -o json \
377+
| jq -r '.items[]
378+
| select(.spec.chartRef.name == "cozystack-http-cache-application-default-http-cache"
379+
or .metadata.labels["apps.cozystack.io/application.kind"] == "HTTPCache")
380+
| "\(.metadata.namespace)/\(.metadata.name)"'
381+
```
382+
383+
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.
384+
385+
```bash
386+
kubectl delete packages.cozystack.io cozystack.http-cache-application --ignore-not-found
387+
kubectl -n cozy-system delete helmreleases.helm.toolkit.fluxcd.io http-cache-rd --ignore-not-found --wait=false
388+
kubectl delete applicationdefinitions.cozystack.io http-cache --ignore-not-found
389+
kubectl -n cozy-system delete secret -l owner=helm,name=http-cache-rd --ignore-not-found
390+
```
391+
392+
An instance that is no longer needed can be deleted before the check, so that the cluster takes this path instead of the freeze.
393+
394+
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:
395+
396+
```bash
397+
src=$(kubectl -n cozy-system get ocirepositories.source.toolkit.fluxcd.io cozystack-packages -o json)
398+
digest=$(printf '%s' "$src" | jq -r '
399+
.spec.ref.digest
400+
// ((.status.artifact.revision // "") | capture("@(?<d>sha256:[0-9a-f]{64})$").d)
401+
// empty')
402+
echo "$digest"
403+
```
404+
405+
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.
406+
407+
Then create the frozen source, point the application at it, and keep the access of instance owners:
408+
409+
```bash
410+
printf '%s' "$src" | jq --arg name cozystack-packages-http-cache --arg digest "$digest" '
411+
{
412+
apiVersion: .apiVersion,
413+
kind: .kind,
414+
metadata: {
415+
name: $name,
416+
namespace: .metadata.namespace,
417+
labels: { "platform.cozystack.io/no-delete": "true" },
418+
annotations: { "platform.cozystack.io/frozen": "http-cache" }
419+
},
420+
spec: (.spec | .ref = { digest: $digest })
421+
}' | kubectl apply --filename -
422+
423+
kubectl patch packagesources.cozystack.io cozystack.http-cache-application --type=merge \
424+
-p '{"metadata":{"annotations":{"helm.sh/resource-policy":"keep","meta.helm.sh/release-name":null,"meta.helm.sh/release-namespace":null},"labels":{"app.kubernetes.io/managed-by":null}},"spec":{"sourceRef":{"name":"cozystack-packages-http-cache"}}}'
425+
426+
kubectl patch packages.cozystack.io cozystack.http-cache-application --type=merge \
427+
-p '{"metadata":{"annotations":{"meta.helm.sh/release-name":null,"meta.helm.sh/release-namespace":null},"labels":{"app.kubernetes.io/managed-by":null}}}'
428+
429+
kubectl apply --filename - <<'YAML'
430+
apiVersion: rbac.authorization.k8s.io/v1
431+
kind: ClusterRole
432+
metadata:
433+
name: cozy:tenant:admin:http-cache-frozen
434+
labels:
435+
rbac.cozystack.io/aggregate-to-tenant-admin: "true"
436+
platform.cozystack.io/no-delete: "true"
437+
annotations:
438+
platform.cozystack.io/frozen: http-cache
439+
rules:
440+
- apiGroups: ["apps.cozystack.io"]
441+
resources: ["httpcaches"]
442+
verbs: ["create", "update", "patch", "delete"]
443+
YAML
444+
```
445+
446+
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`.
447+
366448
### Smaller changes
367449

368450
- **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.
369-
- **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`.
370451
- **Application definitions.** `ApplicationDefinition.spec.release.prefix` must match `^[a-z0-9-]*$`. A definition whose prefix holds a dot or any other character is refused when it is created, so check definitions that come from external application repositories.
371452
- **RabbitMQ and Redis TLS** are new and off by default; nothing changes on upgrade until TLS is enabled on an instance.
372453
- **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

Comments
 (0)