Deploy with Helm Chart
To deploy via Helm Chart:
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
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
, andILO_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.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.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 specifyingnamespaceOverride
tonull
: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 setnamespaceOverride
toilo
: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.