Deploy the Assembler in Hyper-V

This guide is only for V2 assemblers being deployed with a virtual machine in Hyper-V. The V1 assembler is no longer supported as of June 30, 2024.

Each assembler you created must be deployed via a virtual machine, and then you can add your technology as a security device in Workbench to complete the full integration. For more information about the Expel Assembler or how it works, see the About the Expel Assembler guide.

Prerequisites

• You must have completed all of the steps in Add a New Assembler for each assembler you wish to deploy.
• You must be using at least Windows 8.1 or later (this is the minimum version we support).
• You will need a small utility from the Libhvee library called kvpctl, which will attach your ignition file config to your virtual machine.
• Precompiled binaries can be found on the project’s releases page: https://github.com/containers/libhvee/releases
• Go to v.0.4.0 and look for kvpctl.exe, then save it to a shared folder or to your local disk; your virtual machine will need to be able to access this file.

Step 1: Download the Ignition File

The ignition file enables the virtual machine to read a configuration file, and to provision the Fedora CoreOS system based on the contents of that file. You will use this file when you configure the virtual machine in Hyper-V.

1. Log in to Workbench.
2. In the side menu, navigate to Organization Settings > Assemblers.
3. Find the assembler you created, leave the file format as JSON, and select Download the CoreOS Ignition File. This action will download a JSON file that you will need in the next section.

You may choose a different file format if you like, but the JSON format is recommended for this type of assembler.

1. Move the file to a shared folder so that it can be accessed by the virtual machine in the next section, or move it to your local disk.
2. Repeat this process for any additional assemblers.

You must keep track of which files came from which assembler, because each assembler has its own unique ignition file.

Step 2: Create an External Virtual Switch

You need to create an external virtual switch so that your virtual machine can connect to networks that are external to the Hyper-V host.

1. Launch Hyper-V Manager from Windows.
2. Select your server from the list on the left side of the screen.
3. In the Actions panel, select Virtual Switch Manager​.
4. Make sure the "New virtual network switch" option is selected in the left panel.
5. Choose External as the type, and select Create Virtual Switch.
6. Follow the prompts to create your virtual switch.

   • Enter a name of your choosing for the virtual switch.
   • Leave all default settings for the Connection type.
   • Leave VLAN ID unchecked.
   • Select Apply.

Step 3: Create the Virtual Machine

You must create the virtual machine first, but you will not be able to start it until you run the kvpctl utility on your ignition file in the next step.

Before you begin, make sure your ignition file and the v0.4.0 kvpctl.exe are in a shared folder or on your local disk, and that your Fedora CoreOS artifact file is unzipped. Your virtual machine will need to access these files.

1. Still in Hyper-V Manager, make sure your server is still selected from the list on the left side of the screen.
2. In the Actions panel, select New > Virtual Machine.
3. Follow the prompts to create your virtual machine.

   • Enter a name of your choosing for the virtual machine.
   • Choose Generation 1 as the generation for the virtual machine.
   • Enter a minimum of 8192 MB (this equals 8 GB) for the startup memory. Leave the Dynamic Memory checkbox unchecked.
   • For Connection, select the virtual switch you created earlier.
   • To connect your virtual hard disk, choose the option to "Use an existing virtual hard disk" and then choose your CoreOS artifact file. Make sure your artifact file is unzipped; using a zipped file does not work.
   • Select Finish.

Step 4: Run the Kvpctl Utility on Your Ignition File

On Hyper-V, the ignition config is presented to the hypervisor in parts. Ignition reads the parts and reassembles them into a single config. You can use the kvpctl add-ign subcommand to create these parts and attach them to the virtual machine, which will then allow you to start it successfully.

• Make sure you know the location of your ignition file before you begin, and that your virtual machine can access that path.
• If you are using multiple virtual machines because you have multiple assemblers to deploy, make sure you use the correct ignition file for each one.

1. Make sure your new virtual machine is not running.
2. Open Windows Powershell (or use Command Prompt) and cd into the directory where you saved the ignition file.
3. Run the following command:

.\kvpctl.exe <name_of_vm> add-ign <path_to_ign_file>

Example:

.\kvpctl.exe ExampleVirtualMachine add-ign C:\Users\ExampleUser\organization-1a2345b6-78c9-01d2-e345-6f7890g1h2i3-assembler-ab1234cd-56ef-78g9-h012-3i4j5k6l789m-ignition-file.json

1. You should see keys being added, like this: added key: ignition.config.0 added key: ignition.config.1 added key: ignition.config.2 added key: ignition.config.3 …

Step 5: Start the Virtual Machine

Now you can start the virtual machine and connect securely to Expel’s platform.

1. In Hyper-V Manager, make sure your server is still selected from the list on the left side of the screen.
2. Find the virtual machine you created.
3. Right-click and select Start to power on the virtual machine.

   • The contents of the ignition file should now display in Powershell as an indication that the startup was successful.
4. Right-click and select Connect… to connect to your virtual machine's console.

Allow 10-15 minutes for this process to complete before moving on to the next step.

Step 6: Verify a “Connected” Status in Workbench

It can take 10 to 15 minutes for the assembler’s status to update in Workbench.

1. Log in to Workbench.
2. In the side menu, navigate to Organization Settings > Assemblers (or, refresh the page if you never logged out).
3. Find your newly created assembler(s) and verify that the status has changed from “Not Yet Connected” to “Connected.”

   • If your assembler(s) still do not show as connected after waiting at least 15 minutes and refreshing the page, see the Troubleshooting section for help.

Step 7: Connect Your Technology

You can now set up your vendor technology in Workbench.

Troubleshooting

Trouble accessing your CoreOS artifact file or creating your virtual machine.

Move the artifact file to your local disk and try again.

Trouble running the kvpctl utility.

• Move the utility and ignition file to your local disk and try again.
• Check the file path in the command to be sure it is correct, and that it is referencing a JSON-formatted file.

The assembler is still not showing as “Connected” after 15 minutes.

• Make sure your machine’s size meets the required minimums (2 virtual CPUs, 8 GB RAM, and 20 GB disk space), and that you did not forget to update the disk space size for the boot disk (Step 3).
• Make sure your firewall is configured properly to allow our outbound ports.

If all firewall and VM settings are correct and you are still unable to connect the assembler, contact Support for help.