VEN Library Setup in the PCE

You can use your PCE cluster as a centralized mechanism for distributing, installing, and upgrading VENs in your environment.

NOTE:

If you are an Illumio Secure Cloud customer, you do not need to set up the VEN Library in the PCE. Illumio Operations performs these tasks and upgrading VENs using the PCE web console and REST API is available for your environment. See VEN Upgrade Using the PCE Web Console for information.

About the VEN Library in the PCE

You can use the PCE web console to install and upgrade VENs in your environment in the following scenarios:

  • To install or upgrade RPM, Debian, and Windows distributions of the VEN software. Other workload operating systems are not supported.
  • The PCE and VEN versions are 18.2 and later.

VEN installation from the PCE does not affect any processes you might already have for installing or upgrading VENs directly on workloads, such as installation or activation/pairing with illumio-ven-ctl. Those processes can continue until and after you decide to use the PCE to install and upgrade VENs.

This topic primarily describes how to use the PCE web console to install and upgrade VENs. However, you can also use the Illumio Core REST API to upgrade (but not install) VENs. See the REST API Developer Guide for information.

VEN Library

Previously, VENs could be deployed from an external VEN repository (VEN repo) or by manually installing the VEN packages directly on your workloads.

From the 18.2.0 release onwards, the PCE can act as a repository for distributing, installing and upgrading the VEN software. The PCE can host multiple VEN versions, allowing you to evaluate and certify new versions of the VEN while continuing to deploy older versions in production.

PCE-based installation and upgrade of VENs replaces the use of the external VEN repo, which is no longer supported for VEN version 18.2.0 or higher. A migration path is available for Illumio Secure Cloud customers and on-premises customers with VEN repos upgrading VENs to 18.2.0.

Using the VEN Library to install and upgrade VENs on your workloads has the following benefits:

  • The VEN software bundle loaded on a PCE is replicated to all PCE core nodes.
  • You can view VEN versions from the VEN Library page in the PCE web console.
  • You can download software on workstations.
  • Multiple versions of VEN software can exist on the PCE.
  • You can specify an initial VEN version in pairing profiles.
  • You can specify a default VEN version when the PCE has multiple VEN versions uploaded.
  • You can add and remove VEN versions from the PCE.
  • You can use the PCE to upgrade all VENs or selected VENs in your environment.

After setting up the VEN software bundle using the PCE control interface illumio-pce-ctl, the VEN Library page is available in the Workloads and VENs > VEN Library menu . From this page, you can download individual VEN packages and view the dependencies and supported OS versions.

NOTE:
You must set an initial VEN version when there is no system default version or an external repository has not been configured. If your PCE has existing pairing profiles created without versions, pairing will fail when use those un-versioned profiles.

Migration to PCE-Based VEN Library

Migration from the central VEN repo or an on-premises VEN repo to the VEN Library should be thoroughly planned and timed to not impact your current operations. Contact Illumio Customer Support for assistance.

PCE Runtime Parameters for PCE-based Installation

After you have migrated from any external VEN repo you might have, remove the following parameters from the PCE runtime_env.yml file:

  • ven_repo_url
  • ven_repo_ips

These parameters are not needed for the PCE-based installation of the VEN. They are deprecated and should no longer be used.

Workflow for VEN Library Setup

You do not have to make any configuration changes or other settings to enable the VEN Library on the PCE.

Loading the VEN bundle into the PCE VEN Library enables the using the PCE web console or Illumio Core REST API to install and upgrade VENs in your environment.

To set up the VEN Library, perform the following high-level tasks:

  1. Upload the VEN upgrade compatibility matrix to the PCE. See Upload VEN Upgrade Compatibility Matrix.

    NOTE:

    The compatibility matrix must be uploaded to the PCE before you upload any VEN software bundles or you will get an error.

  2. Download the version of the VEN software bundle from the Illumio Support site.

    1. On the Illumio Support site (login required), go to Software > Download > VEN – Download.
    2. In the Download VEN page, select the radio button for the VEN version you want to set up. From the table, click the filename link for the “VEN Bundle for PCE-based deployment.”

      TIP:

      Illumio recommends that you verify the checksum of the VEN software bundle after downloading it.

    The VEN software for PCE-based deployment is a zipped tarball (tar file) of a version of VEN software for all supported workload platforms. This tarball is known as a VEN software bundle. The tar file downloads to your local drive.

  3. Repeat step 1 for all the VEN versions you want to distribute to your workloads.

    Additionally, when Illumio releases new versions of the VEN software, plan on repeating these steps when you are ready to deploy that VEN version.

  4. Copy or move the VEN software bundle tar file to a convenient directory on your PCE core node or to any system that your PCE can reach with HTTP, SFTP, or SCP.

    You do not need to unpack the VEN software bundle tar file.

  5. Load the VEN software bundle into one of the PCE core node's VEN Library. From this node, the VEN software bundle is automatically copied to the other nodes.

    See Upload VEN Software Bundle into PCE VEN Library for information.

  6. Install or upgrade VENs:
    1. To install the VEN software on workloads, with the PCE web console, generate a pairing script. See Pairing Profiles and Scripts for information.
    2. To upgrade all VEN workloads or selective workloads, use the PCE web console. See VEN Upgrade Using the PCE Web Console for information.

Upload the VEN Upgrade Compatibility Matrix

NOTE:

The compatibility matrix must be uploaded to the PCE before you upload any VEN software bundles or you will get an error.

Alternatively, you can run the compatibility matrix upload command in one line with the command to install a VEN software bundle; for example:

sudo -u ilo-pce illumio-pce-ctl ven-software-install bundle_path --compatibility-matrix matrix_file_path

As part of setting up the VEN Library in the PCE, you must upload the VEN upgrade compatibility matrix to the PCE. The compatibility matrix contains information about valid VEN upgrade paths and VEN to PCE version compatibility. To use the PCE web console and the Illumio Core REST API, you must upload this matrix for VEN upgrades to be successful.

In Supercluster, VENs are managed from the PCE they are paired to. You must upload VEN bundles and the compatibility matrix to each PCE.

The compatibility is a zipped tarball (tar file). You do not need to unpack the tar file to install it. The tarball contains a set of JSON files specifying the rules for upgrading VENs in your environment.

You can also view these VEN upgrade rules on the Illumio Support site (log in required). Go to Software > Upgrade > VENUpgrade. In the Upgrade VEN page, select your current VEN version and the version you want to upgrade to. Click Find My Upgrade Path.

IMPORTANT:

Until you upload this file, you can only install VENs on workloads when the VEN version is the same as the version of the PCE managing those VENs. Attempting to upgrade a VEN version, will return the message: “No valid upgrade paths were found for this release.”

To install the compatibility matrix:

  1. Download the VEN upgrade compatibility matrix tar file from the Illumio Support site (log in required). Go to Software > Download > PCE – Download > 21.2. In the table, click the link for the “PCE-VEN Compatibility Matrix.” The file downloads to your local drive.

    TIP:

    Illumio recommends that you verify the checksum of the compatibility matrix file after downloading it.

  2. Copy or move the tar file to a convenient directory on your PCE core node.
  3. To upload the file to the PCE, run this command on the PCE:

    sudo -u ilo-pce illumio-pce-ctl compatibility-matrix-install matrix_file_path

Upload VEN Software Bundle into PCE

NOTE:

Before you upload a VEN software bundle into the PCE, you must first have uploaded the VEN upgrade compatibility matrix. See Upload the VEN Upgrade Compatibility Matrix for information.

Loading the VEN software bundle consists of running illumio-pce-ctl on the PCE command line to load the VEN software bundle into the PCE's VEN Library. The VEN Library is then replicated to the other PCE core nodes.

Loading the VEN software bundle into the PCE's VEN Library is what configures the PCE as the VEN installation and upgrade method.

In Supercluster, VENs are managed from the PCE they are paired to. You must upload VEN bundles and the compatibility matrix to each PCE.

You can only upload VEN software bundles into a PCE that are compatible with that PCE. For example, you cannot upload VEN version 21.2.0 software bundles into a PCE version 19.3.0.

To load a VEN software bundle:

  1. Copy the downloaded VEN software bundles to a convenient location on your PCE core node or to any system that the PCE can access via HTTP, SFTP, or SCP.
  2. To load the VEN software bundle, run the following command on the core node's command line.

    sudo -u ilo-pce illumio-pce-ctl ven-software-install bundle_path

    For example:

    sudo -u ilo-pce illumio-pce-ctl ven-software-release-install protocolAndFqdnOfVenBundleHost/nameOfVenSoftwareBundleFile.tar.bz2

    Where:

    • bundle_path is any of the following locations of the VEN software bundle tar file:
      • The absolute or relative path to the directory on the PCE
      • The HTTP URL to the host and file
      • The SFTP URL to the host and file
      • The SCP URL to the host
    • The filename of the VEN software bundle tar file uses the following format:

      illumio-ven-repo-someVersionStamp.tar.bz2

      Where someVersionStamp is the version and build number of the Illumio Core release.

Example

The following example assumes you have copied the VEN software bundle into /var/tmp on you PCE:

# sudo -u ilo-pce illumio-pce-ctl ven-software-release-install /var/tmp/illumio-ven-repo-someVersionStamp.tar.bz2
Reading /opt/pce_config/etc/runtime_env.yml.
Validating VEN release tarball file contents:
    Valid.
Deploying VEN release tarball to 'PCE's IP address' .

Committing tarball manifest information to database.
Are you sure you want to continue? [yes/no]: yes
Release version_of_bundle Successful.

HTTP and SCP Examples

These examples show HTTP and SCP URLs on the illumio-pce-ctl ven-software-release-install command:

  • HTTP:

    sudo -u ilo-pce illumio-pce-ctl ven-software-release-install http://myVENrepohost.BigCo.com/myRepoDir/pcerepo/illumio-ven-repo- someVersionStamp.tar.bz2
  • SCP:

    sudo -u ilo-pce illumio-pce-ctl ven-software-release-install scp://[email protected]:illumio-ven-repo- someVersionStamp.tar.bz2

Set Default VEN Version in Library

You can set a default version of the VEN software for all workloads or for selected pairing profiles. You can use both methods simultaneously. For example:

  • Set a default VEN version for all workloads when you are ready to roll out that specific version.
  • Create a separate pairing profile with a specific VEN version for test, evaluation, and certification before general rollout.

Set Default VEN Version for All Workloads

To define the default VEN version for all workloads, run this command on the PCE:

sudo -u ilo-pce illumio-pce-ctl ven-software-release-set-default release 

Where:

release is a release identifier like 19.3.0-6623. The PCE uses the default release to determine what release of the VEN to install when you pair a VEN with a workload. You can override the default release for specific pairing profiles. To obtain release IDs, run the illumio-pce-ctl ven-software-releases-list command.

Set Default VEN Version for Specific Pairing Profile

You can selectively set a VEN version for specific pairing profiles. The profiles that have a defined VEN version create pairing profiles that install that specific VEN version on the workload. Other pairing profiles that have no VEN version set are unaffected.

To set a pairing profile's VEN version, see Configure a Pairing Profile.

For information about pairing scripts, see prepare Scripts.

Remove a Release from the VEN Library

To remove a VEN version from the VEN Library on the PCE, run this command on the PCE:

sudo -u ilo-pce illumio-pce-ctl ven-software-release-delete release 

Where:

release is a release identifier like 19.3.0-6623. To obtain release IDs, run the illumio-pce-ctl ven-software-releases-list command.

IMPORTANT:

To remove a VEN version from the PCE database, the PCE cannot be using that VEN version in pairing profiles and it cannot be set as the default VEN version for pairing with workloads. When your orgs no longer use that VEN version, the ven-software-release-delete command will remove the VEN software bundle from the PCE file system.

View the VEN Library in the PCE

The VEN loading process with illumio-pce-ctl ven-software-release-install prints its success or failure when it completes. You can also verify the successful loading in the following ways:

  • In the PCE web console, look at the VEN Library. Navigate to Workloads and VENs > VEN Library to see that the bundle has been loaded.
  • On the PCE command line, run the following command:

    sudo -u ilo-pce illumio-pce-ctl ven-software-releases-list

PCE Maintenance for VEN Library

These are some points to consider about backing up and modifying your PCE cluster for the PCE-based deployment model.

About PCE Backups

Be sure that your backup included the PCE's VEN library and is not earlier than when you loaded the VEN software bundles into the PCE's VEN Library. If you restore from an earlier backup, you need to either reload the VEN library or redeploy from an existing core node.

About Complete PCE failure

In case of a catastrophic failure of the PCE cluster, after rebuilding or reinstalling the cluster, reload the VEN software bundles into a PCE core node's VEN library.

VEN-related Maintenance Commands on PCE

The illumio-pce-ctl control script has options for VEN maintenance, such as add new VEN software bundle, remove VEN version, and delete VEN version. See the illumio-pce-ctl --help details.

Some of the options for distributing VENs from the PCE show org-id, org-list, and other organization-related arguments. None of the organization-related options or arguments options are needed for distributing VENs from your on-premises PCE and do not need to be specified.