Skip to main content

Illumio Core 25.1 Install, Configure, Upgrade

Deploy with Helm Chart

To deploy via Helm Chart:

  1. Install Helm. See https://helm.sh/docs/ for a quick start guide and other relevant information.

    According to official Helm documentation, if your version of Helm is lower than 3.8.0, the following command must be executed in the installation environment:

    $ export HELM_EXPERIMENTAL_OCI=1
  2. Prepare an illumio-values.yaml file with the following mandatory parameters set with values that describe this deployment:

    pce_url: URL_PORT # PCE URL with port, e.g. mypce.example.com:8443 
    cluster_id: ILO_CLUSTER_UUID # Cluster ID from PCE, e.g. cc4997c1-40... 
    cluster_token: ILO_CLUSTER_TOKEN # Cluster Token from PCE, e.g. 1_170b... 
    cluster_code: ILO_CODE # Pairing Profile key from PCE, e.g. 1391c... 
    containerRuntime: containerd # Container runtime engine used in cluster, allowed values are [containerd, crio, k3s_containerd] 
    containerManager: kubernetes # Container manager used in cluster, allowed values are [kubernetes, openshift] 

    where URL_PORT, ILO_CLUSTER_UUID, ILO_CLUSTER_TOKEN, and ILO_CODE are placeholders for customer provided variables.

    If you are using a private PKI, you need to add these additional lines to your illumio_values.yaml:

    extraVolumeMounts:
    	- name: root-ca
    	mountPath: /etc/pki/tls/ilo_certs/
    	readOnly: false
    extraVolumes:
    	- name: root-ca
    	configMap:
    		name: root-ca-config
    ignore_cert: true 

    You may also want to include selected optional parameters when installing, for example, with clusterMode: clas to deploy with a CLAS-enhanced Kubelink component. For more information, see Important Optional Parameters.

    Note

    If you want to deploy with CLAS enabled, you must explicitly set the clusterMode Helm Chart parameter. The default is to deploy in legacy (non-CLAS) mode.

  3. Optionally map existing Kubernetes labels to desired Illumio labels by adding a Kubernetes Custom Resource Definition (CRD) label map to your illumio-values.yaml file.

  4. Install the Helm Chart:

    helm install illumio -f illumio-values.yaml oci://quay.io/illumio/illumio --version <ver#> --namespace illumio-system --create-namespace

    Important

    Be sure to specify the version to install with the --version <ver#> option (for example, --version 5.1.0), after confirming that the Illumio Kubernetes Operator version you want to install is supported with your PCE version.

    Verify which PCE versions support the Illumio Core for the Kubernetes version you want to deploy on the Kubernetes Operator OS Support and Dependencies page on the Illumio Support Portal.

    In case the illumio-system namespace already exists, omit the --create-namespace flag.

    Optionally, you can deploy into a custom namespace of your choice instead of the default namespace of illumio-system, The default namespace is overridden for backward compatibility by using the variable namespaceOverride: illumio-system.

    For example, to install into the ilo namespace, specify the namespace with the --namespace option and the --set option specifying namespaceOverride to null:

    helm install illumio -f illumio-values.yaml oci://quay.io/illumio/illumio --version 5.3.0 --namespace ilo --create-namespace --set namespaceOverride=null

    Alternatively, specify the namespace with the --namespace option but also use --set to explicitly set namespaceOverride to ilo:

    helm install illumio -f illumio-values.yaml oci://quay.io/illumio/illumio --version 5.3.0 --namespace ilo --create-namespace --set namespaceOverride=ilo

Note

Kubelink version labeling has changed. Prior to version 3.3.0, Kubelink used a 6-hexit suffix for its release version, like 3.2.1.445a83. In Kubelink 3.3.0 and later, the version suffix is now changed to a numeric build number, like 3.3.0-56.

Important Optional Parameters

Refer to the README file included with the Helm Chart for important deployment information, including additional parameters you can specify in the Helm Chart before installing it.

The following list describes a few important optional parameters to consider using in your illumio-values.yaml file.

Flat Networks: networkType

To add support for flat network CNIs in addition to the default (where pods run on an overlay network), an optional networkType parameter is now available in the Helm Chart where you can specify flat or overlay type. The default value is overlay.

CLAS Mode: clusterMode

Starting in Illumio Core for Kubernetes versions 5.0.0 and later, a Cluster Local Actor Store (CLAS) mode is introduced into the Kubelink architecture. Use the optional clusterMode parameter to configure Kubelink when first installing a new cluster, or when migrating an existing cluster.

When installing, set clusterMode to clas or legacy in your illumio-values.yaml file to turn on (or leave off) CLAS mode in the cluster, respectively. The default setting for clusterMode is legacy (non-CLAS). To enable CLAS in a new cluster, you must explicitly include clusterMode:clas in the illumio-values.yaml file 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.

Important

To upgrade to CLAS, follow the procedure described in Upgrade to CLAS Architecture.

Illumio recommends enabling (or migrating to) CLAS-enabled clusters to take advantage of this architecture's benefits. For more information about CLAS, see the Cluster Local Actor Store (CLAS) section.

CLAS Degraded Mode: disableDegradedMode and degradedModePolicyFail

If the connection between Kubelink and the PCE becomes unavailable, a CLAS-enabled Kubelink can still serve policies to C-VEN (and therefore to its Kubernetes Workloads and pods). When a PCE interruption is detected, a CLAS-enabled Kubelink enters a degraded mode.

By default, degraded mode is enabled in CLAS clusters. You can disable degraded mode by explicitly setting the parameter/value pair disableDegradedMode: true in illumio-values.yaml, and performing a helm upgrade.

In degraded mode, new Pods of existing Kubernetes Workloads get the latest policy version cached in CLAS storage. When Kubelink detects a new Kubernetes Workload labeled the same way and in the same namespace as an existing Kubernetes Workload, Kubelink delivers the existing, cached policy to Pods of this new Workload.

If Kubelink cannot find a cached policy (that is, when labels of a new Workload do not match the labels of any existing Workload in the same namespace), Kubelink delivers a "fail open" or "fail closed" policy based on the Helm Chart parameter degradedModePolicyFail setting, as specified in the illumio-values.yaml file when installing (or upgrading).

The default parameter value of degradedModePolicyFail is open, which opens the firewall of new Pods. The closed value means the firewall of new Pods is programmed to block all network connectivity.

The precise behavior of closed depends on the Cluster Workload Profile's Enforcement setting: all connectivity is blocked only if the Enforcement of the namespace is set to Full.

By default, degraded mode is enabled in CLAS clusters. You can disable degraded mode by explicitly setting the parameter/value pair disableDegradedMode: true in illumio-values.yaml, and performing a helm upgrade.

When degraded mode is disabled, Kubelink/CLAS does not deliver policy based on matching labels. Kubelink continues to run, and delivers the cached policy to existing Kubernetes Workloads, but does not deliver policy to new Workloads. Kubelink continues to attempt re-establishing communication with the PCE.

After the PCE becomes available again, it restarts, synchronizes policy and labels, and then continues normal operation.

Note

If the PCE becomes inaccessible due to database restoration or maintenance, and Kubelink has disabled degraded mode, you are advised to restart Kubelink by deleting its Pod to synchronize the current state.

CLAS etcd Internal Storage Size: sizeGi

Kubelink in CLAS mode uses etcd as a local cache for policy and runtime data. The Helm Chart parameter storage.sizeGi sets the size in GB of this ephemeral storage. Set the parameter under storage in the illumio-values.yaml for a cluster, as shown in the following example:

storage:
  registry: "docker.io/bitnami"
  repo: "etcd"
  imageTag: "3.5.7"
  imagePullPolicy: "IfNotPresent"
  sizeGi: 1

The default value is 1, for 1 GB, which should be enough for a cluster with under 1000 Kubernetes workloads. If a cluster is bigger and you increase memory limits for C-VEN and Kubelink, then increase the etcd internal storage size with this parameter.