How to create an instance¶
To launch an application or an image, Anbox Cloud creates an instance for it. To create and launch an instance, you can use the Anbox Cloud dashboard or the CLI.
Depending on what you need, you can use the either of the following commands to create an instance for a registered application or an image.
amc launch
creates and starts the instance.amc init
only creates the instance.
By default, the instance will run headless.
The following examples demonstrate different ways of launching instances using amc launch
, but you can use amc init
in the same way.
Launch application instances
Before launching an instance for an application, get the ID of the application that for which you want to launch an instance. To do this, run:
amc application ls
This command lists the available applications along their IDs and their published status.
+----------------------+----------------+---------------+--------+-----------+--------+---------------------+
| ID | NAME | INSTANCE TYPE | ADDONS | PUBLISHED | STATUS | LAST UPDATED |
+----------------------+----------------+---------------+--------+-----------+--------+---------------------+
| bdp7kmahmss3p9i8huu0 | candy | a4.3 | ssh | false | ready | 2018-08-14 08:44:41 |
+----------------------+----------------+---------------+--------+-----------+--------+---------------------+
To launch an instance for a published application, run:
amc launch <application_id>
Tip
To know about published applications, see Publish application versions.
The
--vm
flag is not required when you specify an application id. The application has the information about whether a container or a virtual machine is to be created.
The amc launch
command fails if you provide the ID of an application that is not yet published. However, if you have a specific version of an application that has been published, you can specify it to launch the instance successfully:
amc launch --application-version=0 bcmap7u5nof07arqa2ag
Launch a raw instance
You can launch a raw instance from an image. To do so, get the ID of the image by running:
Tip
If you don’t know what a raw instance is, see Application vs. raw instances.
amc image ls
This command lists the available images along with their IDs and status:
+----------------------+---------+--------+----------+----------------------+
| ID | NAME | STATUS | VERSIONS | USED BY |
+----------------------+---------+--------+----------+----------------------+
| bh01n90j1qm6416q0ul0 | default | active | 1 | |
+----------------------+---------+--------+----------+----------------------+
Launch a raw instance by providing the image ID in the following command:
amc launch --raw <image_id>
See Provided Anbox Cloud images for a list of images that are available in Anbox Cloud.
Launch an instance with streaming enabled
since 1.22.0
If you want to stream the visual output from an instance, specify it at the time of instance creation. Otherwise, the instance cannot be streamed. In previous versions of Anbox Cloud, it was only possible to create an instance that has streaming enabled via the Stream Gateway API. The same can now be achieved through the AMS API or the amc
CLI.
To enable streaming for a new instance, simply run:
amc launch --enable-streaming ...
AMS will automatically create a streaming session for the instance. You can find the id of the session as a tag on the instance in the format session=<id>
.
If you want to to further customise the streaming configuration such as display settings or frame rate, use the corresponding arguments: --display-size
, --display-density
and --fps
. For example, to create an instance with a 1080p resolution, a frame rate of 60 and a DPI of 120, run:
amc launch --enable-streaming --display-size=1920x1080 --display-density=120 --fps=60 ...
Launch an instance with a specific name
since 1.22.0
To allow identifying and referencing instances easier you can give them a name at creation time. Names must be unique and can be used with all CLI commands.
To create an instance with a name, run:
amc launch --name=foo ...
This will create an instance with the name “foo” which can then be used in other CLI commands. For example, when opening a shell for interacting with the instance, the following command can be used:
amc shell foo
Launch an instance on a specific node
By default, every instance is scheduled by AMS onto a LXD node. Alternatively, you can launch an instance directly on a specific node:
amc launch --node=lxd0 <application_id>
Note
AMS will still verify that the selected node has enough resources to host the instance. If not, the instance will fail to launch.
Launch an instance with a different Anbox platform
By default, instances start with the webrtc
platform if --enable-graphics
is specified. Otherwise, they start with the null
platform. To select a different platform, specify it with the -p
flag. The platform cannot be changed at runtime and must be selected when the instance is created. For example, you can launch an instance with the webrtc
platform with the following command:
amc launch -p webrtc <application_id>
If you have built your own platform named foo
and you built it via an addon into the instance images, you can launch an instance with the platform the same way:
amc launch -p foo <application_id>
For more information, see Supported platforms and Supported platforms.
Launch an instance with development mode enabled
You can launch instances with additional development features turned on. This development mode must be enabled when an instance is launched, and it cannot be turned off afterwards. You should never enable development mode for instances used in a production environment.
To launch an instance with development mode enabled, add the --devmode
flag to the launch command:
amc launch --devmode <application_id>
Create an instance on the Instances page to launch an instance. The information required for launching an instance depends on whether you are creating the instance from an application or an image.
When you create the instance from an application, the attributes you define for the application decide most of the properties of the instance.
When you create the instance from an image, you can define the properties of the instance during its creation.
Once you create an instance by providing the necessary attributes, you can view the instance and its status on the Instances page.
There may be more advanced scenarios while creating an instance that cannot be performed using the dashboard and may require using the amc
CLI.