This guide is only for V2 assemblers being deployed with a virtual machine in AWS EC2. 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.

Quick Start

Setup includes the following steps (click any step for detailed instructions):

Download the CoreOS Ignition File
Import and Configure the CoreOS Ignition File
Configure and Spin Up the Virtual Machine
Verify a “Connected” Status in Workbench
Delete Temporary Outbound Connections

Step 1: Download the CoreOS Ignition File from Workbench

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 AWS.

Log in to Workbench.
In the side menu, navigate to Organization Settings > Assemblers.
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.

Repeat this process for any additional assemblers. Important: you must keep track of the files, and which came from which assembler, because each assembler has its own unique ignition file.

Step 2: Import and Configure the CoreOS Ignition File

Assembler ignition files are too large to be used in-line during AWS instance creation. Instead, we recommend placing the ignition file on S3 and referencing a remote source for the ignition file. Note that the ignition file and means of sharing it only need to exist upon first boot.

The steps are as follows:

Create or choose an existing S3 bucket in AWS to host the Ignition file. (See Creating a bucket for more information.)
Click on your bucket in the list, and drop or upload the CoreOS Ignition file you got from Workbench into the S3 bucket.
Click on the file name and select the Object actions drop down > Share with a presigned URL.
Generate a short-lived pre-signed URL in AWS and save it, as you will need it later. (See Sharing objects with presigned URLs for more information.)
- Note: We recommend setting the pre-signed URL to expire after at least 10 minutes in order to give yourself enough time to get through the AWS instance creation process, and for the instance to retrieve the ignition file from your bucket. Please ensure you have already completed the steps in our Add a New Assembler documentation and have configured your firewall rules (security group).

Step 3: Configure and Spin Up the Virtual Machine

Now that you have a pre-signed URL, you can create and spin up your virtual machine in EC2.

First, you need to get an AMI ID.
- Go to Fedora CoreOS.
- Scroll to Cloud Launchable > AWS.
- Click the list button.
- Choose the AMI ID that corresponds to your deployment region and copy it to a safe place; you will need the ID later in this section.
Navigate to EC2 in AWS.
Select Launch Instance
Name your instance.
Search the Application and OS Images catalog for the AMI ID you chose, and then select the Community AMIs tab.
Select an instance type.
- Remember that your VM must have, at minimum, 2 virtual CPUs, 8 GB RAM, and 20 GB disk space.
- You may choose any machine configuration you wish, as long as it meets these minimum requirements. An example of one you may select would be t2.large.
Under Key Pair, choose Proceed without a key pair. A key pair is not required for this configuration.
Under Network Settings, you should have already configured your firewall rules (security group) when you completed the Add a New Assembler documentation. Select Select existing security group and choose the group you created.
Under Configure Storage, ensure it is 20 GB. Leave the Root Volume at the default value.
Expand the Advanced Details section and scroll down to User data. Paste the following JSON object in the field, being sure to include the pre-signed URL you generated in Step 2 as the source.

{
  "Ignition": {
    "config": {
      "replace": {
        "source": "YOUR_PRE-SIGNED-URL"
      }
    },
    "version": "3.3.0"
  }
}

Select Launch Instance.

Step 4: Verify a “Connected” Status in Workbench

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

Log in to Workbench.
In the side menu, navigate to Organization Settings > Assemblers (or, refresh the page if you never logged out).
Find your newly created assembler(s) and verify that the status has changed from “Not Yet Connected” to “Connected.”
- If the status has not updated yet, make sure you have waited at least 15 minutes, then refresh the page and check again.

Step 5: Delete Temporary Outbound Connections

In the Add a New Assembler documentation, you added additional temporary outbound connections as part of the firewall configuration. Now that your instance has booted and there is a connection to Workbench, these temporary IP addresses can be removed and all traffic will securely go through the Expel platform. Please ensure the two non-temporary outbound connections remain in place (34.149.216.90 and 34.107.163.233).

Troubleshooting

If your assembler is still not showing as “Connected” after 15 minutes:

Make sure you have the proper firewall configurations to allow our outbound ports as specified in Add a New Assembler. If you did not have your security group (firewall) configured correctly when you launched the instance, you will have to restart the virtual machine.
Make sure your chosen machine’s size meets the required minimums (2 virtual CPUs, 8 GB RAM, and 20 GB disk space).

If all firewall and machine size settings are correct and you are still unable to connect the assembler, contact your Expel Engagement Manager for help.

Deploy the Assembler in AWS