Update the Keycloak IP address on bare metal clusters

The following instruction describes how to update the IP address of the Keycloak service on baremetal-based management clusters.

Note

The commands below contain the default kaas-mgmt name of the management cluster. If you changed the default name, replace it accordingly. To verify the cluster name, run kubectl get clusters.

To update the Keycloak IP address on a bare metal management cluster:

  1. 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.

  2. Configure the additional external IP address pool for the metallb load balancer service.

    The Keycloak service requires one IP address. Therefore, the external IP address pool must contain at least one IP address.

    1. Create the Subnet object template with the following content:

      apiVersion: ipam.mirantis.com/v1alpha1
      kind: Subnet
      metadata:
        labels:
          cluster.sigs.k8s.io/cluster-name: kaas-mgmt
          ipam/SVC-MetalLB: ""
          kaas.mirantis.com/provider: baremetal
          kaas.mirantis.com/region: region-one
          metallb/address-pool-auto-assign: "false"
          metallb/address-pool-name: external
          metallb/address-pool-protocol: layer2
        name: master-lb-external
        namespace: default
      spec:
        cidr: <pool_cidr>
        includeRanges:
        - <pool_start_ip>-<pool_end_ip>
      

      Note

      The kaas.mirantis.com/region label is removed from all Container Cloud objects in 2.26.0 (Cluster releases 17.1.0 and 16.1.0). Therefore, do not add the label starting these releases. On existing clusters updated to these releases, or if manually added, this label will be ignored by Container Cloud.

      In the template above, replace the following parameters:

      • <pool_start_ip> - first IP address in the desired range.

      • <pool_end_ip> - last IP address in the range.

      • <pool_cidr> - corresponding CIDR address. The only requirement for this CIDR address is that the address range mentioned above must fit into this CIDR. The CIDR address is not used by MetalLB, it is just formally required for Subnet objects.

      Note

      If required, use a different IP address pool name.

    2. Apply the Subnet template created in the previous step:

      kubectl create -f <subnetTemplateName>
      
    3. Open the MetalLBConfigTemplate object of the management cluster for editing:

      kubectl edit <MetalLBConfigTemplateName>
      
    4. Add the external IP address pool name to the L2Advertisements definition. You can add it to the same L2 advertisement as the default IP address pool, or create a new L2 advertisement if required.

      ...
      spec:
        templates:
          l2Advertisements: |
            - name: management-lcm
              spec:
                ipAddressPools:
                  - default
                  - external
                interfaces:
                  - k8s-lcm
            - name: provision-pxe
              spec:
                ipAddressPools:
                  - services-pxe
                interfaces:
                  - k8s-pxe
      ...
      
    5. Save and exit the object to apply changes.

    1. Open the Cluster object for editing:

      kubectl edit cluster <clusterName>
      
    2. Add the following highlighted lines by replacing <pool_start_ip> with the first IP address in the desired range and <pool_end_ip> with the last IP address in the range:

      spec:
        providerSpec:
          value:
            helmReleases:
            - name: metallb
              values:
                configInline:
                  address-pools:
                  - name: default
                    protocol: layer2
                    addresses:
                    - 10.0.0.100-10.0.0.120 // example values
                  - name: external
                    protocol: layer2
                    auto-assign: false
                    addresses:
                    - <pool_start_ip>-<pool_end_ip>
      

      Note

      If required, use a different IP address pool name.

    3. Save and exit the object to apply changes.

  3. Obtain the current Keycloak IP address for reference:

    kubectl -n kaas get service iam-keycloak-http -o jsonpath='{.status.loadBalancer.ingress[0].ip}{"\n"}'
    
  4. Configure the iam-keycloak-http service to listen on one of the IP addresses from the external pool:

    kubectl -n kaas edit service iam-keycloak-http
    

    Add the following annotation to the service:

    kind: Service
    metadata:
      annotations:
        metallb.universe.tf/address-pool: external
    

    Save and exit to apply changes.

  5. Verify that the Keycloak service IP address has changed:

    kubectl -n kaas get service iam-keycloak-http -o jsonpath='{.status.loadBalancer.ingress[0].ip}{"\n"}'
    
  6. Monitor the cluster status to verify that the changes are applied:

    kubectl get cluster kaas-mgmt -o yaml
    

    In the output, monitor the url parameter value in the keycloak field:

    ...
    status:
      providerStatus:
        helm:
          ready: true
          ...
          releases:
          ...
            iam:
              keycloak:
                url: https://<pool_start_ip>
    

    The value of the parameter is typically the first address of the external pool rage.

  7. Once the parameter has updated, delete the old certificate for the former address:

    kubectl delete secret keycloak-tls-certs -n kaas
    

    Note

    The new certificate secret with the same name keycloak-tls-certs will be generated automatically.

  8. Verify the new certificate, once available:

    kubectl get secret keycloak-tls-certs -n kaas -o yaml
    
  9. Restart the iam-keycloak-http pod to ensure that the new certificate is used:

    1. Change the number of the iam-keycloak StatefulSet replicas to 0:

      kubectl -n kaas scale statefulsets iam-keycloak --replicas=0
      
    2. Wait until the READY column has 0/0 pods:

      kubectl -n kaas get statefulsets iam-keycloak
      
    3. Change the number of the iam-keycloak StatefulSet replicas back to 3:

      kubectl -n kaas scale statefulsets iam-keycloak --replicas=3
      
    4. Wait until the READY column has at least 1/3 pods:

      kubectl -n kaas get statefulsets iam-keycloak
      
  10. Verify that the IP address in the status.providerStatus.oidc.issuerUrl field of the Cluster object has changed:

    kubectl get cluster kaas-mgmt -o jsonpath='{.status.providerStatus.oidc.issuerUrl}{"\n"}'
    

    If it still contains the old IP address, update it manually:

    kubectl edit cluster kaas-mgmt
    

    Under spec.providerSpec.value.kaas.management.helmReleases, update the values.api.keycloak.url field inside the iam Helm object definition:

    spec:
      providerSpec:
        value:
          kaas:
            management:
              helmReleases:
                - name: iam
                  values:
                    api:
                      keycloak:
                        url: https://<newKeycloakServiceIpAddress>
    

    Save and exit to apply changes.

  11. Wait a few minutes until issuerUrl is changed and OIDC is ready.

    • To verify issuerUrl:

      kubectl get cluster kaas-mgmt -o jsonpath='{.status.providerStatus.oidc.issuerUrl}{"\n"}'
      
    • To verify OIDC readiness:

      kubectl get cluster kaas-mgmt -o jsonpath='{.status.providerStatus.oidc.ready}{"\n"}'
      
  12. Verify that the Container Cloud and MKE web UIs are accessible with the new Keycloak IP address and certificate.