Illumio CORE Policy Compute Engine (PCE) Docker container

version c8 v1 Thursday June 17, 2021 12:42

About this container

The container contains a install script that will build a single node Policy Compute Engine (SNC) in a container with the supplied credentials and data. During the run process an encryption key, agreement to the the EULA, a password to set up the demo user account, and the hostname FQDN will be required. This password will be used to access the demo user account. Unless changed in the DOCKERFILE the demo user will have an ID of "demo@illumio.com".

Below in the "starting the container" section you can find a full list fo variables that can be set at runtime to override the default. The runtime variables can be set via "-e" on the command line or via a file using the "--env-file" option(e.g. --env-list env.list).

What is needed to run this Docker container

Docker runtime environment.
An encrypted PCE software bundle deployed to the ./ directory (project root directory).
An encrypted VEN bundle (optional) deployed to the ./ directory.
Full documentation for the Illumio ASP platform can be publically obtained at here: https://docs.illumio.com/.
For shortened notes on what it take to install a PCE in any environment you can reference https://github.com/johnwesterman/illumio_core
Encryption keys to unencrypt the PCE and VEN files provided. If you need encryption keys please contact Illumio.

Background before the build process is started

By default, the PCE will be installed with a host name of pce.test.local. Make sure this host name can be resolved on your local machine by modifying the "hosts" file locally. On a Mac and other Linux machines the file is located at /etc/hosts and should have contents similar to this:

127.0.0.1 localhost pce.test.local

If a different hostname is required you can modify the name by changing --hostname value to the new name of the PCE during initial runtime configuration. This name should be resolvable by any machine accessing the PCE. This means the user accessing the UI as well as the VENs using the PCE s its controlling system.

EULA ACCEPTANCE REQUIRED

The ability to use the following software require you accept the EULA. Found at the bottom of the page. To do that you will need to either set ILLUMIO_ACCEPT_EULA=true in the env.list file. Optionally, you can provide the ILLUMIO_ACCEPT_EULA==true using the 'docker run -e ILLUMIO_ACCEPT_EULA=true' method. Failure to do so with not allow the software to install.

How to build the Docker image

Using the supplied Dockerfile, build the container as follows:

docker build --tag illumio-docker-pce .

The tag name can be anything you want but it will be referenced when you run the container.

ENTRYPOINT

The ENTRYPOINT will be a script: /usr/bin/illumio.sh. This script will start the container, validate variables pass in via command or present in env.list to build the PCE, decrypt, install and configure the software as well as keep the container running until it is manually stopped.

Starting the container

To start the container fully automated run this command:

docker run -it -p 8443:8443 -p 8444:8444 --env-file env.list -e ILLUMIO_ACCEPT_EULA=true -e KEY=[encryption key]-e PCE_PASSWORD=[password] --hostname pce.test.local --name pce illumio-docker-pce

Explanation of the command line arguments:

-it interactive terminal. To run the install in a detached container you can replace -it with -d. Just make sure at least ILLUMIO_ACCEPT_EULA and PCE_PASSWORD are passed as environment variables.
-p 8443:8443 - expose frontend service on localhost - If changing make sure to also alter PCE_FRONTEND_HTTPS_PORT
-p 8444:8444 - expose event service on localhost - If changing make sure to also alter PCE_FRONTEND_EVENT_SERVICE_PORT
--env-file file containing environmental variables used in startup/install scripts. Default file is env.list
-e an environment passed to startup scrips. To fully automate installation ILLUMIO_ACCEPT_EULA=true and PCE_PASSWORD=<password> must be set otherwise install will prompt user.

Variables that can be overridden by setting the environment variable using '-e' option. Also, can add the variables in a file like env.list above:
- KEY - Encryption key proivided by illumio personnelused to allow extraction of software for use by trusted users.
- PCE_ADMIN_ACCOUNT - Initial admin account to access the PCE. (default - 'demo@illumio.com')
- PCE_PASSWORD - Password to access the PCE admin account.
- PCE_EMAIL_ADDRESS - Emails sent using this email address. (default - 'noreply@illumio.com').
- PCE_FULLNAME - Name that appears in the system for the admin account. (default - 'Demo Account').
- LOGIN_BANNER - Banner on the login page. (default - 'You are the force').
- PCE_FRONTEND_HTTPS_PORT - PCE port used for agent (VEN -Virtual Enforcment Node) connectivity and UI if PCE_FRONTEND_MANAGEMENT_HTTPS_PORT not set. If set just VEN connectivity. (default - 8443)
- PCE_FRONTEND_EVENT_SERVICE_PORT - PCE port used sa long lived connection to VEN to push policy updates. (default - 8444)
- PCE_FRONTEND_MANAGEMENT_HTTPS_PORT - PCE port used to access the UI if set otherwise UI uses PCE_FRONTEND_HTTPS_PORT. (default - 8443)
- EXTERNAL_IP - If testing ENFORCEMENT this variable MUST be set to the IP address of the node running the PCE container or the IP address used when resolving PCE_FQDN
--hostname - sets the docker hostname AND the FQDN of the PCE console. Change if you want to change the FQDN that will be used by the software
--name - sets the docker name
illumio-docker-pce - name of the docker image which comes from the docker build step.

If you do not provide a password for PCE_PASSWORD or a value of true for ILLUMIO_ACCEPT_EULA at runtime you will be asked to accept the EULA and/or enter a password during the installation of the software. If you do supply PCE_PASSWORD and ILLUMIO_ACCEPT_EULA as environment variables the system should run installation steps and finish in 3-5 minutes without user intervention.

Using the Policy Engine

The startup process completes in around 5 minutes to come to a fully running state. Wait these few minutes for the container to start. Once the process is complete and the PCE is fully up and operational you can use a web browser to connect to PCE GUI if using the default PCE_FQDN at this URL:

https://pce.test.local:8443/

If you need you want to change the name of the URL FQDN change the --hostname in the initial docker run command. Make sure the hostname is resolvable. If not using an interactive console check the logs for the following: "Installation of PCE environment is completed." This will indicate that the system has finished startup.

Build script

The entire container build, run, install and setup can be run from a single script provide in this build environment. You will find the commands described above inside the script "build.sh". Running this script will run through each of the steps to build this docker image into a running policy compute engine ready to be used to pair VENs and build policy in a test environment.

The build.sh script will automatically include the docker build and run EULA acceptance requirements.

This script takes one arguments:

the initial password for the demo user account

Usage: build.sh USER_PASSWORD KEY

Starting and stopping the PCE

After the initial Docker run you may want to stop the PCE using:

docker stop pce

To restart the PCE:

docker start [-ai] pce

Stopping and starting the PCE in this way will use the original container created above with all the persistent data needed to run the PCE. Once the container is started it will try to start itself. This can take a few minutes to come up. If you find that the system is not operational you can run the folliwng "docker exec" command

"/opt/illumio-pce/illumio-pce-ctl start" - Start all the processes of the PCE
"/opt/illumio-pce/illumio-pce-ctl stop" - stop all the processes of the PCE
"/opt/illumio-pce/illumio-pce-ctl restart" - stop all the processes of the PCE
"/opt/illumio-pce/illumio-pce-ctl status" - Displays the operational status of PCE
"/opt/illumio-pce/illumio-pce-ctl status -sv" - Displays the operational status of all the compnents of the PCE

Sample of the exact docker command:

docker exec -it pce /opt/illumio-pce/illumio-pce-ctl start

How can I access my PCE from the command line

Execute the following command:

docker exec -it pce bash

Copying files to the PCE container

docker cp <filename> pce:/some/path

About the volumes used

This image will automatically create two docker volumes.

/var/lib/illumio
/var/log/illumio

Software installed

Directories for installing software:

./ - this will be copied to /home/ilo-pce, any encrypted files in there will be installed. It is also the place to put VEN bundles where they will be installed using ven-software-install. All encrypted VEN bundles in the directory will be installed.

A note on operational scale

This container is intended for a test environment and solely to test feature functionality. It is not intended to scale beyond a test of 5-10 workloads. When creating the environment you will need to insure you have allocated enough resources to run the software. Allocating 4-6GB of RAM, 4+ cores and 100G of hard disk space in the shared environment is recommended.

A note on the Docker build environment

This software was developed inside of Docker using standard Docker images to build the latest LTS version of Policy Compute Engine. Doing these steps creates various images in the Docker environment. If those images are no longer needed you can delete them. If you want to build things from scratch delete all related images and rebuild this image and run a fresh container.

Ducati

Install / Use

README