Setup

The private cloud runner uses AWS's Cloud Development Kit to create and update a private cloud runner installation. The deployment will create several Cloud Formation stacks for its resources. We recommend installing the runner to a dedicated account, although it is not required.

Several stacks will be deployed. Two stacks manage creating a VPC, and configuring lower level constructs within the network. Then a runner service application deploys all of the resources required to operate the service. Alarms are also set up in Cloudwatch Alarms. These alarms are not tied at this point to a notification.

The installation has been tested with deploying a single runner environment to a single region. While it is a longer term objective to support multiple runners in one region, it is not yet supported.

The deployment requires that two items be set up manually for the deployment to use, a DNS hosted zone in Route53, which the deployment will use to create subdomains, and a KMS key in the target region, which the deployment will use to encrypt certain types of artifacts. The KMS key needs to be a symmetric key.

A CLI is provided by Nextmv to help with the deployment. It is used to list releases and get a release. An installation script is provided as part of the release to apply the release to an existing or new environment.

An update is performed at the same as an installation, using the same configuration as the initial installation. The install package resolves differences and updates only the deltas in the previously installed environment.

1. You have created an AWS account for the deployment
2. You have created a hosted zone defined in that account that Nextmv private runner can use to create subdomains
3. You have created a root KMS key (symmetric)
4. Nextmv CLI is installed and configured
5. Node.js and CDK are already installed
6. Docker is installed and running (required by CDK)
7. You have bootstrapped the CDK in the target region. You must be logged in to AWS at the command line with administrative credentials to perform the bootstrapping.

The installation process downloads a tar file with all required assets. A configuration file defines the behavior of the installation. You must have AWS administrator privileges for the account you are installing to, and you must be authenticated at the command line with some mechanism (IAM, SSO, etc). The installation process assumes that the credentials in the console context are available. If you are using profiles, you can set the AWS_PROFILE environment variable to the profile to use.

1. Create a configuration file. See Installation Configuration File
2. List the releases available. nextmv private list-releases
3. Get the release. You can get the release without specifying an output directory option, in which case it will get it to the current directory. nextmv private get-release nextmv-private-2022-08-24T12.37.41Z
4. Go to the output directory, and cd install
5. There is a script, install.sh to perform the installation. You need to define export two environment variables a. CONFIG_FILE - fully qualified path to the configuration file to use for the install b. REGION - the AWS region you are installing to (ex. eu-west-1)
6. Run ./install.sh

Before you can run an operation you will need to bootstrap the service. This is performed through the Nextmv CLI.

Bootstrapping is a process to establish an initial security context, and can be performed only once. Bootstrapping will produce an API key for the root administrator. Using this root administrator key you can then create additional named administrators, create application API keys, and disable application or administrator API key.

The installation created a public DNS endpoint to access your service. The format of the endpoint is runner.<app id>.<base hosted domain>. For example if in the installation configuration you specified schedule as the appId and foo.bar.io as the hostedZoneName, then the host will be runner.schedule.foo.bar.io. For this service will run on port 8402.

1. Bootstrap the service by running nextmv private bootstrap runner.schedule.foo.bar.io:8402. This creates the root administrator, and adds the key information to your nextmv configuration file.
2. Create an API key by running nextmv private keys create --name <api key name>
3. Optionally create additional named administrators by running nextmv private keys create --admin true --name <api key name>

A set of integration tests are provided as part of the installation. You will need Go installed to run the integration tests.

1. In the release directory, you will see a sample_code subdirectory. Go to sample_code/test_binaries.
2. You will need to copy these binaries into a bucket that was created for you during the install process, it should look like <appId>--nextmv-private-artifact-upload-us-east-1. Run aws s3 sync ./ s3://<your upload bucket>.
3. cd ../clients/integ_test
4. export NM_RUN_HOST=<host-name>:8402. The host name will be runner.<appId>.<configured subdomain>.
5. export NM_TEST_BUCKET=<bucket from step 2>
6. export NM_RUN_POOL_ID=<run pool id from config>
7. go test
8. You should see a pass status

The configuration file is a JSON file defining all required information to perform the installation.

Example

{
  "accountId": "<acountId>",
  "region": "<region>",
  "hostedZoneId": "<hostedZoneId>",
  "hostedZoneName": "<hostedZoneName>",
  "appId": "<appId>",
  "vpcCidrBlock": "<vpcCidrBlock>",
  "numberAzs": "3",
  "kmsRootKeyArn": "<kmsRootKeyArn>",  
  "workerPools": [
    {
      "poolID": "<poolID>",
      "minInstances": 1,
      "maxInstances": 2,
      "instanceType": "m6g.xlarge"
    }
  ]
}

accountId - the account where the private cloud runner will be installed

region - the region of the installation

hostedZoneId - the hosted zone id to use for creating subdomains (found in route53)

hostedZoneName - the hosted zone name to use for creating subdomains

appId - this is an identifier that you define to distinguish this installation. It needs to conform to dns rules since it will be used as part of the subdomain (lower case letters, numbers, dashes)

vpcCidrBlock - this defines the address range for the virtual private cloud that will be created. Ask your network administrator.

numberAzs - this is the number of availability zones. Use 3 unless you have a good reason not to. It defines the availability zones for which subnets are added to the vpc.

kmsRootKeyArn - this is the Amazon resource identifier and can be found in the General configuration section for the key you configured as a prerequisite.

workerPools - This array defines the worker pools to create. There must be at least 1. When you submit runs to be processed, they are assigned to worker pools. By creating multiple worker pools you can give dedicated resources to different applications for example, so one application doesn’t overwhelm the compute resources of another.

• poolID - The identifier for the pool. You will use this when submitting a run for processing.

• minInstances - the minimum number of instances to run in the pool

• maxInstances - the maximum number of instances to run in the pool

• instanceType - the instance type to use. Tested with m6g.xlarge, m6g.2xlarge, m5a.xlarge, m5a.2xlarge. If you are running binaries then they must be compiled for the appropriate architecture (m6g is linux ARM, m5a is linux AMD. We recommend ARM for cost/performance benefits).