How to update your license

If the license has expired and/or the platform is in an open circuit:

1. Apply an SSP to shturval-backend.
2. Allow a license change in ClusterConfig.
3. Replace the license in ClusterConfig.
4. Restore the ClusterConfig check.
5. Replace the license in ClusterProfile.
6. For clusters with the Shturval v2 provider, replace the license in ShturvalProvider.
7. Replace the license token in NodeConfigItem.
8. Replace the license token in /etc/std/nci.json on the nodes and the NodeConfig annotation.

If the license has expired in a closed circuit, complete steps 1–5: the SSP, ClusterConfig, and ClusterProfile. After you apply the SSP and restart the pods, the GUI may be unavailable — use the CLI.

Step 1. Apply the shturval-backend SSP #

1. Connect to the management cluster in the console.
2. Save the manifest and apply the SSP:

kubectl apply -f shturval-backend-license.yaml

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: shturval-backend-license
spec:
  shturvalServiceConfigName: shturval-backend
  customvalues:
    license_token: <your parameter value>

3. Confirm the object exists: kubectl get shturvalservicepatch shturval-backend-license.
4. Restart the shturval-backend pods in the shturval-backend namespace and wait until they are ready:

kubectl -n shturval-backend rollout restart deployment shturval-backend
kubectl -n shturval-backend rollout status deployment shturval-backend

Step 2. Allow a license change in ClusterConfig #

Two webhooks of this resource forbid a license change in ClusterConfig on the management cluster. To allow the change:

1. Save the YAML of the objects you will change: the ClusterConfig webhooks, deployment shturval-cluster-manager-cluster-manager, ClusterConfig, ClusterProfile, ShturvalProvider (if the cluster uses the Shturval v2 provider), and NodeConfigItem and NodeConfig (for a closed circuit).

kubectl get mutatingwebhookconfiguration,validatingwebhookconfiguration -o yaml > backup-webhooks.yaml
kubectl -n shturval-cluster-manager get deployment shturval-cluster-manager-cluster-manager -o yaml > backup-cluster-manager.yaml
kubectl get clusterconfig -A -o yaml > backup-clusterconfig.yaml
kubectl get clusterprofile -n kube-system -o yaml > backup-clusterprofile.yaml
kubectl get shturvalprovider -o yaml > backup-provider.yaml
kubectl get nodeconfigitem -o yaml > backup-nci.yaml
kubectl get nodeconfig -o yaml > backup-nodeconfig.yaml

Skip ShturvalProvider if the platform has no Shturval v2 provider. Get NodeConfigItem and NodeConfig of a client cluster with the same get commands and that cluster’s kubeconfig.

2. Allow the change and stop cluster-manager. Remember that both webhooks were failurePolicy: Fail, and remember the previous replica count. Do not change the profile webhook in the same object.

kubectl get mutatingwebhookconfiguration -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .webhooks[*]}{"  "}{.name}{"\t"}{.failurePolicy}{"\n"}{end}{end}'
kubectl get validatingwebhookconfiguration -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .webhooks[*]}{"  "}{.name}{"\t"}{.failurePolicy}{"\n"}{end}{end}'

kubectl patch mutatingwebhookconfiguration <name> --type json -p '[{"op":"test","path":"/webhooks/<index>/name","value":"defaulting-webhook-clusterconfig-v1beta1.cluster.shturval.tech"},{"op":"replace","path":"/webhooks/<index>/failurePolicy","value":"Ignore"}]'
kubectl patch validatingwebhookconfiguration <name> --type json -p '[{"op":"test","path":"/webhooks/<index>/name","value":"vclusterconfig-v1beta1.kb.io"},{"op":"replace","path":"/webhooks/<index>/failurePolicy","value":"Ignore"}]'

kubectl -n shturval-cluster-manager get deployment shturval-cluster-manager-cluster-manager -o jsonpath='{.spec.replicas}{"\n"}'
kubectl -n shturval-cluster-manager scale deployment/shturval-cluster-manager-cluster-manager --replicas=0

kubectl -n shturval-cluster-manager get pods

Step 3. Update the license in ClusterConfig #

ClusterConfig objects of all clusters are available in the management cluster. The object name and its namespace match the cluster name. The license is the spec.license field. See Platform custom resources.

Replace spec.license in the ClusterConfig of the management cluster and of each client cluster. If the license has expired, the GUI is unavailable — use the CLI.

apiVersion: cluster.shturval.tech/v1beta1
kind: ClusterConfig
metadata:
  name: clustername
  namespace: clustername
spec:
  license: <new token>

kubectl patch clusterconfig clustername -n clustername --type merge -p '{"spec":{"license":"<new token>"}}'

Step 4. Restore the ClusterConfig check #

Return the deployment and the webhooks to their previous state.

kubectl -n shturval-cluster-manager scale deployment/shturval-cluster-manager-cluster-manager --replicas=<previous count>
kubectl -n shturval-cluster-manager rollout status deployment/shturval-cluster-manager-cluster-manager --timeout=180s

kubectl patch mutatingwebhookconfiguration <name> --type json -p '[{"op":"test","path":"/webhooks/<index>/name","value":"defaulting-webhook-clusterconfig-v1beta1.cluster.shturval.tech"},{"op":"replace","path":"/webhooks/<index>/failurePolicy","value":"Fail"}]'
kubectl patch validatingwebhookconfiguration <name> --type json -p '[{"op":"test","path":"/webhooks/<index>/name","value":"vclusterconfig-v1beta1.kb.io"},{"op":"replace","path":"/webhooks/<index>/failurePolicy","value":"Fail"}]'

Step 5. Update the license in ClusterProfile #

Cluster profiles (ClusterProfile) are available in the kube-system namespace of the management cluster. The license is the spec.license field. A change of spec.license in ClusterConfig does not update profiles automatically. See What cluster profiles (ClusterProfile) are.

Changing a profile does not apply the changes to client clusters that are already created.

In the GUI, changing default-client-cluster-profile is blocked. Update this profile in the CLI. Do not change the other profile fields. If the license has expired, the GUI is unavailable.

apiVersion: cluster.shturval.tech/v1beta1
kind: ClusterProfile
metadata:
  name: <profile-name>
  namespace: kube-system
spec:
  license: <new token>

kubectl patch clusterprofile <profile-name> -n kube-system --type merge -p '{"spec":{"license":"<new token>"}}'

Step 6. Update the license in ShturvalProvider #

This step is only for the Shturval v2 provider. A new host downloads the shturvald package from the r.shturval.tech registry: login user, password spec.licenseToken. This password is not written to /etc/std/nci.json on the node. See Creating a ShturvalProvider.

Replace the license in every ShturvalProvider in the management cluster.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: ShturvalProvider
metadata:
  name: <provider-name>
spec:
  licenseToken: <new token>

kubectl patch shturvalprovider <provider-name> --type merge -p '{"spec":{"licenseToken":"<new token>"}}'

Step 7. Update the token in NodeConfigItem #

In an open circuit the license is in NodeConfigItem (NCI) generic-init-config, in the Container Runtime section: registry r.shturval.tech, field Repository authorization (spec.runtimecfg.registries[].license).

Write Basic, a space, and the command output into the field. The whole string user:<license> is encoded: the registry login is user, and the password is the license.

echo -n 'user:<license>' | base64 -w 0

Update the NCI in the management cluster and in each client cluster of the platform. The client cluster kubeconfig is stored in the management cluster, in Secret <cluster-name>-kubeconfig in namespace <cluster-name>. See Access to child clusters.

kubectl get nodeconfigitem generic-init-config -o yaml

Step 8. Update the file on nodes that are already running #

In an open circuit, check the node’s authorization to the registry and update the license in /etc/std/nci.json if it differs from the new one. Do this for every node in all clusters. Connect to the cluster node and check the node’s authorization to the registry:

sudo grep -c Authorization /etc/containerd/certs.d/<registry-name>/hosts.toml

In an open circuit, <registry-name> is r.shturval.tech. If the command prints 0, the node does not send a license to the registry, and you do not need to change /etc/std/nci.json. shturvald takes the license from the NCI and writes it to hosts.toml. A number greater than zero means the token is stored in the file. Then replace it in /etc/std/nci.json, as follows:

1. Before you replace the token, copy /etc/std/nci.json.
2. Open /etc/std/nci.json. Find the old token and replace it with the new one. It is stored in the password line, in an address https://user:<token>@, and in a value "license": "Basic ...".
3. Write the file and set mode 0600.
4. On the node, calculate the sha256 of the file and write the sum. The node.shturval.tech/initchecksum annotation is on the NodeConfig with the node’s name. The NodeConfig name matches the node name. Paste the sum from the sha256sum output, the characters before the space.

On each cycle shturvald calculates the sha256 of /etc/std/nci.json and compares it with this annotation. After you edit the file, the sum changes, so write the new sum. Otherwise configuration application stops (ConfigApplied=False, reason ChecksumMismatch). See Configuration application cycle in the shturval-node-config service.

On the node:

sudo sha256sum /etc/std/nci.json

In the cluster:

kubectl annotate nodeconfig <node-name> node.shturval.tech/initchecksum=<sum> --overwrite

Check the license on the About the system page (the start page of the web interface). If the node sends the license to the registry, also check that the new authorization is applied on the node: on the node page, the Node Configuration tab does not show Not applied, and the Authorization line in /etc/containerd/certs.d/<registry-name>/hosts.toml matches the license field in the NCI. The output contains the token. In the cluster, READY for this node’s NodeConfig must be True:

kubectl get nodeconfig <node-name>

Also confirm that both ClusterConfig webhooks are failurePolicy: Fail again and that the replica count of deployment shturval-cluster-manager-cluster-manager is back to its previous value.