Skip to main content

Illumio Core 24.5 Install, Configure, Upgrade

Upgrade to CLAS Architecture

A Cluster Local Actor Store (CLAS) mode is introduced into the architecture of Illumio Core for Kubernetes 5.0.0.

Important

To use CLAS, your PCE must be upgraded to Core 23.5.10 or later.

The CLAS architecture brings two major changes to the typical Illumio Core policy model:

  • The definition of a workload is fundamentally changed. In a legacy, non-CLAS environment, a container workload is a Pod. In CLAS, a workload is now the Kubernetes Workload resource (such as Deployment, StatefulSet, ReplicaSet, DaemonSet, and so on), which typically includes multiple Pods that can change in amount during the lifetime of the workload. As such, CLAS workloads are called Kubernetes Workloads, to distinguish them from non-CLAS Container Workloads.

  • ClusterIP services change from Virtual Services to workloads. NodePort and LoadBalancer services remain as Virtual Services in the PCE. The ClusterIP part of a NodePort or LoadBalancer service also exists as a Kubernetes Workload and is linked with the Virtual Service.

Illumio recommends writing a policy using labels. In addition to being impractical, it is not even possible to write a policy for individual Pods. It was (and still is) possible to use Virtual Services in the policy explicitly in rule writing, but Illumio nevertheless recommends using labels.

Important

The CLAS architecture is supported only in Illumio Core for Kubernetes versions 5.0.0 and later

Pre-upgrade Policy Check

All policies for your Kubernetes environments must be expressed using labels. In the rare case that policies are using Virtual Service objects, those policies must be changed to label-based policies.

ClusterIP Services as Kubernetes Workloads

ClusterIP services are modeled as workloads in the CLAS environment. If you had a policy written with "Virtual Services Only," that policy will not apply to Kubernetes Workloads (including ClusterIP Services) after the upgrade to CLAS. All rules that apply to ClusterIP Services must be changed to "Use Workloads" before upgrading to CLAS, which needs Destination Services to be specified. This setting also causes ports to be populated from Virtual Services to the rule. So, at least one port number must be filled in when writing this rule.

To keep the old functionality of PCE synchronizing the ports of the ClusterIP Service, the CLAS now performs this operation. When the rule arrives at Kubelink/CLAS, ports will be replaced by the current ports of the ClusterIP Services. The port replacement includes all ports from the Service. If the Service has two ports, it is not possible to include one without including the other.

Because Services are now Kubernetes Workloads, the "All Workloads" flag in a rule will include all Services. Do not use "All Workloads" as a Destination in a rule. Use a more specific label instead that targets the Service.

All rules that include a label of at least one ClusterIP service will have specified ports internally replaced. However, this is not reflected in PCE UI, where the rule still displays ports.

Upgrade Strategy

Illumio Core for Kubernetes 5.x is backward-compatible and supports both CLAS and legacy non-CLAS mode operation.

This is controlled by the clusterMode parameter specified in the Helm Chart installation yaml file. The default value is legacy, meaning that after the upgrade, the software operates in the legacy, non-CLAS mode.

The PCE supporting Illumio Core for Kubernetes 5.0.0 and later (PCE version 23.5.0+A1 and later) also supports both CLAS and non-CLAS modes of operation. Illumio recommends that, after the software upgrade, the migration to CLAS be performed one cluster at a time.

The CLAS implementation uses the configuration parameter clusterMode set to clas or legacy to turn on (or off) CLAS mode in the cluster, respectively, when installing. When upgrading an existing non-CLAS cluster to CLAS, set clusterMode, to migrateLegacyToClas. When reverting (or downgrading) CLAS to non-CLAS, set clusterMode to migrateClasToLegacy.

Upgrade Steps (on Each Kubernetes Cluster)

Be sure to perform all steps in this procedure on each existing Kubernetes cluster that you want to upgrade to CLAS mode.

  1. Prepare the values.yaml file with all required parameters. Refer to Deploy with Helm Chart.

  2. Upgrade Illumio Core for Kubernetes to version 5.1.0 or later. Refer to Upgrade and Uninstall Helm Chart Deployments.

  3. Verify the upgrade was successful.

  4. Perform a pre-upgrade policy check (see Pre-upgrade Policy Check above).

  5. Set the "illumio-system" namespace to Visibility Only enforcement mode.

  6. Consider setting all cluster nodes into Visibility Only enforcement mode. This step compromises security and will open traffic to/from your protected applications. On the other hand, any policy errors will not result in an application outage.

  7. Migrate the cluster to CLAS mode:

    1. Add clusterMode: migrateLegacyToClas parameter-value pair to your values.yaml.

    2. Perform helm upgrade command:

      helm upgrade <nameofyourhelmdeployment> -n illumio-system -f <yourvalues.yaml> oci://quay.io/illumio/illumio --version 5.1.0

      Important

      Be sure to explicitly specify the version to upgrade to with the --version <ver#> option (for example, --version 5.1.0), after confirming that the product version you want to upgrade to is supported with your PCE version. Verify which PCE versions support the Illumio Core for Kubernetes version you want to deploy at the Kubernetes Operator OS Support and Dependencies page on the Illumio Support Portal.

  8. Refresh the Container Cluster page so that the Kubernetes Workloads tab now appears along with the Container Workloads tab.

  9. Check that all C-VEN pods and the Kubelink pod have restarted.

  10. This cluster is now running in migration mode, Container Workloads are still present, and new Kubernetes Workloads (CLAS-enabled) are populated.

  11. Check if the policy sync status of all Kubernetes Workloads and Peer Workloads is "Active." Some container workloads may be in an Active state, while others are Syncing — this is expected. Check if traffic still works. If something goes wrong, revert the cluster to non-CLAS mode with the following procedure, otherwise, go to the next Step:

    1. Specify clusterMode: migrateClasToLegacy parameter-value pair in your values.yaml.

    2. Perform helm upgrade command:

      helm upgrade <nameofyourhelmdeployment> -n illumio-system -f <yourvalues.yaml> oci://quay.io/illumio/illumio --version 5.1.0

    3. Refresh the Container Cluster page so the Container Workloads tab appears along with the Kubernetes Workloads tab

    4. Wait until Container Workloads and peers are Active, and traffic is working as expected.

    5. Change the clusterMode parameter to legacy in values.yaml -- or delete the variable (because the default parameter value is legacy).

    6. Perform the helm upgrade command:

      helm upgrade <nameofyourhelmdeployment> -n illumio-system -f <yourvalues.yaml> oci://quay.io/illumio/illumio --version 5.1.0

    7. Verify that Kubernetes Workloads were deleted, that Container Workloads are in a Synced state, and that traffic is working as expected.

  12. Set the cluster to CLAS mode:

    1. Change clusterMode: clas in values.yaml.

    2. Perform the helm upgrade command:

      helm upgrade <nameofyourhelmdeployment> -n illumio-system -f <yourvalues.yaml> oci://quay.io/illumio/illumio --version 5.1.0

  13. Check that the Kubelink Pod restarted.

  14. The cluster is now running in the CLAS mode. All Container Workloads from this cluster will no longer be visible on the PCE. Instead, the PCE will display only a list of Kubernetes Workloads (Deployments, etc.).

  15. Set all nodes into original enforcement mode if they were previously changed to visibility only.

Important

Before using your CLAS cluster, ensure that you have written mandatory infrastructure rules to enable proper operation. See Rules and Traffic Considerations with CLAS for details on these mandatory rules.