Update the Keycloak IP address on bare metal clusters

The following instruction describes how to update the IP address of the Keycloak service on 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 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. Open the MetalLBConfig object of the management cluster for editing:

      kubectl edit metallbconfig <MetalLBConfigName>

    2. In the ipAddressPools section, add:

      ...
spec:
  ipAddressPools:
  - name: external
    spec:
      addresses:
      - <pool_start_ip>-<pool_end_ip>
      autoAssign: false
      avoidBuggyIPs: false
...

      In the snippet above, replace the following parameters:

      • <pool_start_ip> - first IP address in the required range

      • <pool_end_ip> - last IP address in the range

    3. 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:
  l2Advertisements:
  - name: default
    spec:
      interfaces:
      - k8s-lcm
      ipAddressPools:
      - default
      - external
...

    4. Save and exit the object to apply changes.

    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
    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 and MOSK objects in 24.1.

      Therefore, do not add the label starting with these releases. On existing clusters updated to these releases, or if added manually, Container Cloud ignores this label.

      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.