Instances

An application instance is a representation of a version and optional configuration (options/parameters). Instances are the mechanism by which a run is made. When you make a new run, the app determines which instance to use and then uses the executable code associated to the version for the run.

Examples include:

• You want to use different optimization logic for different regions.
• You want to test two different app version/configuration combinations.
• You want to have different environments for staging and production. You can specify one instance for staging, and one for production.
• You want to give each developer their own instance so they can push their working code to their own endpoints.

There is an initial instance on an app created for the developer's convenience.

• Subscription apps. The latest instance. It is always assigned the most recently published version.
• Custom apps. The devint instance. It is not associated to any version. It is always assigned the most recently pushed executable code. This is a reserved instance, so it cannot be deleted.

Create an instance

To create an instance, define the desired instance ID. You can add an optional configuration, via options. After, you can use the following interfaces:

• Console. Go to Console, and open your app. Add a new instance from the Instances tabs. Fill in the fields.

  

• Nextmv CLI. Anywhere on your machine, run the following command:

nextmv app instance create \
    --app-id $APP_ID \
    --version-id $VERSION_ID \
    --instance-id "myInstance" \
    --description "An optional description" \
    --name "An optional name" \
    --options "key1=value1,key2=value2"

Use the -e, --execution-class flag to specify an execution class.

• Cloud API. Make sure your NEXTMV_API_KEY is exported as an environment variable. The API uses Bearer Authentication.

  POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances

  Create new instance.

  Create new application instance for a specified version.

  View API details

curl -sS -L -X POST \
    "https://api.cloud.nextmv.io/v1/applications/$APP_ID/instances" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $NEXTMV_API_KEY" \
    -d "{
      \"id\": \"myInstance\",
      \"version_id\": \"$VERSION_ID\",
      \"application_id\": \"$APP_ID\",
      \"name\": \"An optional name\",
      \"description\": \"An optional description\",
      \"configuration\": {
          \"options\": {
            \"key1\": \"value1\",
            \"key2\": \"value2\"
          }
        }
    }" | jq

Use the configuration.execution_class field to specify an execution class.

Default instances

An app always requires an instance to execute a run. If you do not specify an instance, the app will use its default instance. If no default instance is configured, the run will fail.

• Subscription apps. The latest instance is the default instance as well. You can update the default instance if desired.
• Custom apps. There is no default instance configured. You can specify a default instance if desired. Otherwise you must specify the instance ID for each run. This can be done easily from any interface: Nextmv CLI, Python SDK, Cloud API, etc.

To configure the default instance you can use the following interfaces:

• Console. Go to Console, and open your app. Open the Details tab. Edit the app and update the details.

  

• Nextmv CLI. Anywhere on your machine, run the following command:

nextmv app update \
    --app-id $APP_ID \
    --instance-id $INSTANCE_ID \
    --description "A new description"

Delete an instance

Delete an instance using the following interfaces:

• Nextmv CLI. Anywhere on your machine, run the following command:

nextmv app instance delete \
    --app-id $APP_ID \
    --instance-id $INSTANCE_ID \
    --confirm

• Cloud API. Make sure your NEXTMV_API_KEY is exported as an environment variable. The API uses Bearer Authentication.

  DELETEhttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances/{instance_id}

  Delete instance.

  Delete application instance, specified by application and instance ID.

  View API details

curl -sS -L -X DELETE \
    "https://api.cloud.nextmv.io/v1/applications/$APP_ID/instances/$INSTANCE_ID" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $NEXTMV_API_KEY"

Update an instance

Update an instance (configuration, version, name, description, etc...) using the following interfaces:

• Console. Go to Console, and open your app. Open the Instances tab. Click on the instance and the Edit button.

• Nextmv CLI. Anywhere on your machine, use the app instance update subcommand.

• Cloud API. Make sure your NEXTMV_API_KEY is exported as an environment variable. The API uses Bearer Authentication.

  PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances/{instance_id}

  Update an instance.

  Update application instance information with defined data, specified by application and instance ID.

  View API details

Configuration

An instance can be assigned a specific configuration. The configuration is composed of:

• execution_class (optional). Defined as a string.
• options (optional). Defined as an object with a set of key=value pairs.

A sample configuration is as follows:

{
  "configuration": {
    "execution_class": "8c16gb12h",
    "options": {
      "solve.duration": "10s",
      "solve.iterations": "20"
    }
  }
}

Execution class

The execution_class specifies the type of machine that the instance will run on. When not specified, the default execution class is used. Please refer to the execution classes documentation for more information.

Options

options specifiy the parameters to use for the instance. They can be considered as runner flags. Your app should use these options to configure the run.

Your app should be enabled to parse CLI flags using a single dash. Examples of this include:

• -solve.duration=10s is a valid CLI flag when running the Go mip template locally.

go run . -runner.input.path input.json -runner.output.path output.json -solve.duration 10s

• -duration 30 and -provider cbc are valid CLI flags when running the Python pyomo template locally.

python3 main.py -input input.json -output output.json -duration 30 -provider cbc

Nextmv Cloud will parse the options configuration and pass it to the app as CLI flags using a single dash. Thus, the options are converted as:

• solve.duration=10s 👉 -solve.duration=10s
• duration=30 👉 -duration=30
• provider=cbc 👉 -provider=cbc

Options are also known as parameters. Options can be added to, edited on, and removed from an instance at any time. Any run made with an instance will preserve the options used.

There is a precedence (hierarchy) for how options are applied for remote runs.

1. Run payload options, when running an app remotely with Nextmv CLI, Python SDK, Cloud API or Console.
2. Configuration set on the instance.
3. Default model value.

For example, you create a new run on an app with the following characteristics:

• Run payload options set to solve.duration="3s"
• Run made to instance with options solve.duration="5s"
• Associated version has latest executable code with default options: solve.duration="10s"

In the example, the duration for that run will be 3s. If the options block were removed from the run payload, the duration would be 5s. If a different instance was used for the run that had no options set, and there were no options specified in the payload, the duration would be 10s.

There are various ways to handle options for a run.

• When an instance is created, you can pass in the options, using Console, Nextmv CLI and Cloud API.
• Similarly, you can update an instance and change its options, using the same interfaces.
• When running an app remotely, you can pass in the options when using any of the interfaces: Nextmv CLI, Python SDK, Cloud API and Console. Go to this section to see examples.