Deployment

Self-hosting with AWS ECS

10min
running the jumpwire engine in your aws account is straightforward with aws elastic container service and the fargate infrastructure the following guide will walk through the creation of an ecs cluster, task definition, and service to run the engine inside your own aws account and vpc note this guide uses the "old experience" for ecs in the aws console this is because at the time of this writing, the "new experience" does not allow for setting container environment variables from the secrets manager a best practice is to store the token provided to the engine as a secret since it is used as an authn/z parameter unless otherwise specified, we are using defaults provided by the aws console when creating resources create cluster for jumpwire engine create a new cluster for the service and task definition to run the jumpwire engine container in this example, we will use serverless fargate infrastructure so we start with a cluster template with networking only minimal configuration here is necessary we are not creating a vpc, because we want to launch our container into an existing vpc, which hosts our private rds database you can also create a new vpc just for the jumpwire engine if desired this cluster is named "jumpwireengine" after a few seconds, the cluster is created and ready for deploying jumpwire but first, we must create a task definition for the engine container create task definition for jumpwire container the next step is to create a task definition that will run the jumpwire engine container the task definition will contain a list of the configurations for ports exposed by the engine, and environment variables necessary to configure the container navigate to "task definitions" in the left navigation, and click "create new task definition" in step 1, select fargate for the launch type compatibility in step 2, enter a name for the task definition, and select linux as the "operating system family" for the "task role" and "task execution role", you can use the "ecstaskexecutionrole", which aws will create for you if it does not exist note if you are storing the jumpwire engine token in secrets manager, you will need to update this role for access to read from secrets manager more on this in the section below next, configure the container to run in the task you can find all the details for running a container that will connect to the frontend and enforce your policies on the jumpwire configuration page it's necessary to expose container ports for proxying connections within the vpc, and set environment variables to configure the engine application you can read more about the configuration here give the container a name, and reference the image listed from the jumpwire configuration page the image url should be something like `registry hub docker com/jumpwire/jumpwire\ latest` set port mappings for the following ports, all as tcp 4000, 3306, 5432, 9568 next set up the environment variables provided to the container while running the following environment variables are required jumpwire config endpoint , jumpwire frontend , and jumpwire token in this example, we are using a secret that securely stores the jumpwire token variable, as it is used to authenticate with the frontend to use a secret, be sure to select "valuefrom" in the middle drop down menu if you are not using secrets manager to store the token, you can also set the value of the environment variable directly to the token value under "storage and logging", check "auto configure cloudwatch logs" the container engine reports informational messages to standard out, and this is helpful for debugging and verifying successful operation to complete the task definition, choose a task size of memory and cpu minimal sizes should be sufficient for running the engine, we recommend 1g of memory and 512 units of cpu click "create" to complete the task definition if you plan to decrypt large numbers of values at query time, more memory will be required create a service for running the jumpwire task definition now we can create a service to run the jumpwire task definition in step 1 select fargate and linux as the service launch type and operating system family, then the definition we just created with the latest revision use the cluster created above and give it a name in step 2 we are using an existing vpc for our network, that also has our private rds instance already running this eliminates the need to peer vpcs for the engine to access the database directly however, you can create a dedicated vpc for the engine if desired we are only deploying into the private subnets in the vpc, as all proxied connections will be coming from within the vpc in step 3 we do not need autoscaling for this service, so skip this step in step 4 review and deploy! verifying deployment and debugging coming soon securing container environment variables aws secrets manager can inject environment variables at runtime for the jumpwire container this will keep sensitive values more secure and allow for a separation of configuration from application definition since the jumpwire token is used by the engine to authenticate with the frontend and authorize access to your policies, it should be treated as a secret secrets are created as key/value pairs in the aws console, but they are stored as a json object in secrets manager as each key in the json can be referenced as an environment variable, it may be convenient to store all of the container environment variables as secrets to simplify configuration to create a new secret to store environment variables, click "store a new secret" from the secrets manager console in step 1 select "other type of secret" enter jumpwire token as a key, and paste the token from your jumpwire configuration page as the value in step 2 give the secret a name we are using dev/jumpwire/engine/token in step 3 keep automatic rotation disabled, which is the default in step 4 review and deploy to use values from the secret as environment variables, choose "valuefrom" in the middle drop down when setting variables in the container definition the value of the environment variable should be set as the arn of the secret you created, plus the name of the key something like arn\ aws\ secretsmanager\ us east 2 1111\ secret\ dev/jumpwire/engine/token aabbcc\ jumpwire token you can find the arn for the secret you created by clicking on the details of the secret, and append with \ jumpwire token to specify the key in the secret to use update the ecstaskexecutionrole that is created by ecs to grant iam permissions for the task to read secrets from secrets manager you can find the role definition under aws iam roles in the console there is an aws managed policy called "secretsmanagerreadwrite" that can be assigned to the role click on "addpermissions" > "attachpolicies" and search for the aws managed policy