Update the Keycloak IP address on management clusters

Applies to management clusters only

The following instruction describes how to update the IP address of the Keycloak service on a k0s-based management cluster that uses the dedicated iam-keycloak MetalLB address pool. For details on the pool, see Configure a dedicated Keycloak address pool for a management cluster.

The Kubernetes API server of a k0s-based management cluster obtains its OIDC issuer address from this pool. Therefore, update the address in the pool and let MOSK propagate it. All dependent configuration, including the Keycloak service address, the OIDC issuer URL of the Kubernetes API server, and the Keycloak TLS certificate, is updated automatically.

Warning

The procedure changes the OIDC issuer URL of the cluster and has the following effects:

The control plane nodes of the cluster are cordoned, drained, and restarted one by one.
The Keycloak service becomes unavailable for several minutes.
All issued OIDC tokens are invalidated and all users must log in again.

Plan a maintenance window of about 30 minutes.

To update the Keycloak IP address on a management cluster:

Log in to a node that contains kubeconfig of the required management cluster.

Make sure that the configuration file is in your .kube directory. Otherwise, set the KUBECONFIG environment variable with a full path to the configuration file.
Select the new IP address for the Keycloak service.

The address must belong to the LCM network of the cluster and must not be included in any other MetalLB address pool.
Obtain the name of the MetalLBConfig object of the management cluster and verify whether it contains the iam-keycloak address pool:
```
kubectl get metallbconfig
kubectl get metallbconfig <MetalLBConfigName> -o jsonpath='{range .spec.ipAddressPools[*]}{.name}{"\n"}{end}'
```
If the output does not contain iam-keycloak, which is typical for the clusters that were originally deployed using MOSK 26.1 or earlier, add the pool with the new IP address to the MetalLBConfig object of the cluster as described in Configure a dedicated Keycloak address pool for a management cluster. Then skip the next step by proceeding to verifying the new IP address.
Update the IP address in the iam-keycloak address pool:
1. Open the MetalLBConfig object of the management cluster for editing:
```
kubectl edit metallbconfig <MetalLBConfigName>
```
2. In the ipAddressPools section, replace the IP address of the iam-keycloak pool with the new one:
```
...
spec:
  ipAddressPools:
  ...
  - name: iam-keycloak
    spec:
      addresses:
      - <newKeycloakServiceIpAddress>/32
...
```
  Caution
  
  The pool must contain a single IP address in the /32 notation.
3. Save and exit the object to apply changes.
Wait until the new IP address is propagated to the MetalLB objects, which may take up to 10 minutes, and verify that the new IP address is applied:
```
kubectl -n metallb-system get ipaddresspool iam-keycloak -o jsonpath='{.spec.addresses}{"\n"}'
```
The output must contain the new IP address.

Verify that the Keycloak service uses the new IP address:

kubectl -n kaas get service iam-keycloak-http -o jsonpath='{.status.loadBalancer.ingress[0].ip}{"\n"}'

The output must contain the new IP address.

Verify that the Keycloak TLS certificate is reissued for the new address, which may take a few minutes:
```
kubectl -n kaas get certificateconfiguration keycloak -o jsonpath='{.status.hostname}{"\n"}'
```
The output must contain the new IP address.

Caution

Custom certificates configured using Configure TLS certificates for cluster applications are not regenerated. Therefore, you must reissue the certificate for the new address if the certificate pins the IP address.
Wait until the new IP address is applied to the OIDC configuration of the cluster:
```
kubectl get cluster <mgmtClusterName> -o jsonpath='{.status.providerStatus.oidc.issuerUrl}{"\n"}'
```
The output must contain the new IP address.

Wait until the control plane nodes are restarted and the cluster becomes ready again:

kubectl get cluster <mgmtClusterName> -o jsonpath='{.status.providerStatus.ready}{"\n"}'
kubectl get cluster <mgmtClusterName> -o jsonpath='{.status.providerStatus.oidc.ready}{"\n"}'

Both commands must return true.

Verify that the MOSK management console is accessible with the new Keycloak IP address and certificate.