THATDOT / PRODUCT / NOVELTY DOCS / CONFIGURATION GUIDE

Novelty Configuration Guide

AWS user?

AWS users can subscribe to thatDot Novelty on the AWS Marketplace. Follow the step by step instructions found on our Quick Start page.

Set Up:

What you’ll need to setup:

  • A VPC (if you don’t already have one)
  • An EFS volume, if you’re running the container on Fargate, and you want persistence (past the lifetime of the ECS task). You’ll also need a security group that exposes the NFS port (2049).
  • An ECS cluster (Fargate or EC2)
  • An IAM role with write access to the Marketplace Metering service.

An example ECS task definition (with persistence):

An example task definition is available here and shown below.

{
  "family": "thatDot-categorical-anomaly-detector",
  "executionRoleArn": "ecsTaskExecutionRole",  
  "taskRoleArn": "your_ecs_role_with_metering_permissions_here",
  "containerDefinitions": [
    {
      "name" : "service",
      "image": "117940112483.dkr.ecr.us-east-1.amazonaws.com/759ec6c5-b08e-4d5b-b461-191ccda296a0/cg-1139974230/novelty:v0.9-latest",
      "mountPoints": [
        {
          "containerPath": "/var/thatdot",
          "sourceVolume": "efs-drive"
        }
      ]
    }
  ],
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "memory": "6144",
  "cpu": "2048",
  "volumes": [
    {
      "efsVolumeConfiguration":{
        "fileSystemId": "your_efs_id_here"
      },
      "name": "efs-drive"
    }
  ]
}

You can configure a task definition via:

  • Command-line, w/ `aws ecs register-task-definition` and the above JSON
  • AWS Console web UI, by clicking on the “Configure via JSON” button when creating a new ECS task, and pasting in the above JSON
  • AWS Console web UI, by web forms, clicking boxes, and selecting things from drop-downs.

Create a role to run the ECS Task

You’ll need a role to run the service as. It will need permission to make calls to the AWS Marketplace Metering service.

  • Go to the “Identity and Access Management (IAM)” section in the AWS Console: https://console.aws.amazon.com/iam/
  • Click “Create role”
  • Under “Or select a service to view its use cases”, click “Elastic Container Service”, and then “Elastic Container Service Task” under “Select your use case”. Click “Next: Permissions”
  • Search for “AWSMarketplaceMetering” in the “Filter policies” box, put checkmarks next to both “AWSMarketplaceMeteringFullAccess” and “AWSMarketplaceMeteringRegisterUsage”. Hit “Next” a couple times, to get to the “Review” page.
  • Give your new role a name, and a description, and click “Create role” to finish

ECS Setup

First, you’ll need an ECS cluster to run your tasks on.

  • Go to the “ECS” service in AWS console: http://console.aws.amazon.com/ecs
  • You should be taken to the “Clusters” page under the “Amazon ECS” section.
  • Click the “Create Cluster” button.
  • Your choices are Fargate, or EC2 instances.:
  • Pick a name for the cluster, and create a VPC for the tasks in it to run in (if you don’t already have one)
  • If you want to use persistence, you’ll need a security group that allows NFS access to the EFS drive. In the AWS console, go to VPCs. In the left-hand menu, under the “SECURITY” section, click on “Security Groups”. Click on “Create security group”. Give it a name like “NFS”, and select the VPC referenced above in the drop-down. Under “Inbound rules”, click on “Add rule”. Under the “Type” drop-down, select “NFS”. For Source, you can select “Custom” in in the drop-down, and enter the CIDR block for your VPC. This range will need to include the IP your Docker container (ECS task) is running at. Click the “Create security group” button at the bottom.

To create a task definition in the web UI:

  • Go to the “ECS” service in AWS console: http://console.aws.amazon.com/ecs
  • Click “Task Definitions” in the left-hand menu panel.
  • Click the “Create new Task Definition” button.
  • Chose what kind of cluster you want your task to run on, Fargate or EC2, and hit “Next step”
  • Select a name for your task. For “Task Role”, select the name of the role you created above. Select how much RAM and vCPUs you want to allocate for this task.
If you want to add persistence (otherwise skip to “Add a container definition”):
  • Scroll down past “Add container” for now (we’ll come back to that), to the “Volumes” section. Click Add volume.
  • Change the “Volume type” “Bind Mount” to “EFS” in the drop-down.
  • If you don’t already have an EFS volume available in the “File system ID” drop-down, you can click the link to go to the EFS Console and create one.
  • Click “Create file system”
  • Give it a name, and select the same VPC as the one the ECS Cluster you created above is in. Click “Customize”.Click “Create”
  • In here you can decide if you want automatic backups, and encryption. Click “Next”.
  • Ensure that the VPC selected is the one referenced above. Remove the existing security groups from the subnets it’s in, and select the “NFS” security group created above, to allow access to NFS port 2049. Click “Next”.
  • Click “Next” again past the “File system policy” page. Click “Create”.
  • Back in the “Add volume” form of the “create task” UI, your new EFS volume should be available in the “File system ID” drop-down. Select it.
  • Give them a volume a name. You will reference it by this name in the next step. Click “Add”.
  • Scroll back up to “Add a container”
Add a container definition
  • Click “Add a container”
  • Give the container a name.
  • Paste in the URL for the Docker image. You can get this from the “View container image details” link at the bottom of the Launch page for your subscription. Currently it’s 117940112483.dkr.ecr.us-east-1.amazonaws.com/759ec6c5-b08e-4d5b-b461-191ccda296a0/cg-1139974230/novelty:v0.9-latest
  • If you want persistence storage, scroll down to “Storage and Logging”. For the “Source volume” drop-down under “Mount Points”, select the name you set for the EFS volume above. For the “Container path”, put /var/thatdot
  • Click “Add”
  • Scroll down to the bottom. Click “Create”

To run the ECS Task you created:

  • In the Elastic Container Service section of AWS console, click “Task Definitions” in the left-hand menu section.
  • Click on the task definition for the thatDot Categorical Anomaly Detector docker image you created.
  • Select the desired revision of the task definition.
  • Under the “Actions” drop-down, select “Run Task”.
  • For launch type, select “FARGATE” (if you made a Fargate cluster)
  • For Platform version, selecet “1.4.0” (“LATEST” will select 1.3.0, which does not support EFS volumes).
  • For Cluster VPC, select your VPC from above.
  • Select the desired subnet(s) (corresponding to availability zones) you wish your task to run in.
  • Next to “security groups”, hit the “Edit” button. For the inbound rule, in the “Type” column, click on “HTTP” on the drop-down and scroll up to “Custom TCP”. For the “Port range” column, put “8080”. Hit “Save”.
  • Hit “Run Task”
  • You should be taken to the running task listing page for your cluster, with a green box saying “Created tasks successfully” at the top. You should see your just-launched task with the the status “PROVISIONING” in the table at the bottom.
  • Click on the id of the task, which should be a long hexadecimal string, in the “Task” column of the table.
  • In the network section of that task info page, observe the task’s Public IP.
  • Navigate to http://your_tasks_ip:8080 for the Categorical Anomaly Detector’s UI view, and to /docs at that same URL for API endpoint documentation.