This guide is only for V2 assemblers being deployed with a virtual machine in AWS EC2 by using Terraform, an infrastructure as code (IaC) tool. 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 have Terraform installed.

Quick Start

Terraform lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. These instructions assume you have working knowledge of Terraform; if you need additional help or context, refer to the Terraform Documentation.

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

Download the Ignition File
Set Up the Terraform Config File for AWS
Set the User Data for the VM
Configure and Spin Up the Virtual Machine
Verify a “Connected” Status in Workbench

To see a full code example, go to the Reference section.

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

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.

Move your ignition file to a remote, secure location such as Google's Cloud Storage. The contents of the ignition file will be stored in plaintext (unencrypted) wherever your Terraform state files are located. Some guidelines:
- Do not store your ignition file in a git repository. The file contains sensitive information and git is not a suitable place for this type of data.
- Be sure to lock down access to the storage location. Only people who need access to the ignition file (and to the Terraform state files if using Terraform Remote State) should have access to the storage location.
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: Set Up the Terraform Config File for AWS

Terraform will use the AWS provider (use this link if you need help with authentication) to configure your infrastructure. You will need to create a Terraform config file if you do not have one (a file name might be terraform.tf), and make sure the file has the following configuration.

The aws provider block is used to configure your AWS authentication credentials.
The region is your AWS region.
Optional: You may add an access_key and secret_key if needed for authentication

provider "aws" {
  region  = "us-east-1"
}

Step 3: Set the User Data for the VM

Use the template_file data source and set the source attribute to the URL where you stored your ignition file. For example, this could be a pre-signed S3 object link if the ignition file is stored in S3. If you are deploying more than one assembler, this step will need to be repeated for each assembler.

data "template_file" "user_data" {
  template = jsonencode({
    ignition = {
      config = {
        replace = {
          source = ""
        }
      },
      version = "3.4.0"
    }
  })
}

Step 4: Configure and Spin Up the Virtual Machine

Use the aws_instance resource to configure your virtual machine with the minimum requirements. If you are deploying more than one assembler, this step will need to be repeated for each assembler.

Go to the Fedora CoreOS downloads page and scroll to the Cloud Launchable section, and click the button for AWS.
In the screen that displays, copy the Amazon Machine Image (AMI) ID for the region you would like to deploy to.
- ami is the AMI ID you just copied.
- machine_type is “t2.medium”, which has the minimum CPU and RAM requirements for an assembler.
- volume_size is "20", which indicates the 20GB minimum disk size required for an assembler.

resource "aws_instance" "assembler" {
  instance_type = "t2.medium"
  ami           = "ami-12345" #Get this from Fedora CoreOS Downloads page
  user_data     = data.template_file.user_data.rendered
  root_block_device {
    volume_size = 20
  }
}

Step 5: 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.

Troubleshooting

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

Make sure your chosen connection has the proper firewall configurations to allow our outbound ports.
Make sure your config file includes the correct region (Step 2).
Make sure your ignition file is at the path specified, and that you are referencing the correct ignition file for your assembler (Step 3).
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, config file, and resource definitions settings are correct and you are still unable to connect the assembler, contact support for help.

Reference

Full Code Example

terraform.tf (config file)

provider "aws" {
  region  = "us-east-1"
}

assembler.tf (resource definitions)

data "template_file" "user_data" {
  template = jsonencode({
    ignition = {
      config = {
        replace = {
          source = ""
        }
      },
      version = "3.4.0"
    }
  })
}

resource "aws_instance" "assembler" {
  instance_type = "t2.medium"
  ami           = "ami-12345" #Get this from Fedora CoreOS Downloads page
  user_data     = data.template_file.user_data.rendered
  root_block_device {
    volume_size = 20
  }
}

Deploy the Assembler in AWS (Terraform)