CALM CLI Plugin¶
The CALM CLI Plugin allows you to manage containerized applications, compositions, fleets, registries, releases, and environment variables for your orchestration needs. This guide explains how to use the CLI commands to create, update, retrieve, and manage these entities within the Orchestra ecosystem.
Composition (from Docker Compose) or Containerized Application: This refers to an application that is packaged within a Docker container. It can be deployed using a Dockerfile, which includes instructions on connecting external components to the container’s hardware controls. In the context of CALM, this specifically refers to an application that operates on an edge device.
Composition¶
A composition is an object that contains information about your application and helps you keep all its versions in one place.
Create¶
Create a new composition with this command:
$ ocli calm composition create -n "name of your application"
Update¶
You can update your existing composition using following command. The only editable attribute of your composition is its name.
$ ocli calm composition update -n "name of your application" {composition_id}
Get¶
In order to get existing composition you should use the command below:
$ ocli calm composition get {composition_id}
List¶
To get all your existing compositions you can use a list command:
$ ocli calm composition list
Composition version¶
For existing composition you can create one or more composition’s versions. Composition version is an object containing version number, description of your version and docker compose file you have to attach when creating a new version. Composition version must be linked to an existing composition.
Note
Make sure to use semantic versioning.
Create¶
To create a new version of your composition, use the following command.
During the process of creation of a new version for your composition, an initial validation of your Docker Compose file will occur. If the validation fails, you will see an error message as a result.
If the Docker Compose file passes validation, you will receive a success message.
$ ocli calm composition-version create -f <path to docker compose .yaml file> -v <version e.g. 1.0.0> <composition_id>
List¶
You can list all existing versions of your composition using the following command. If any versions exist, they will be displayed.
$ ocli calm composition-version list {composition_id}
Get¶
In order to get your existing composition version, you use get command:
$ ocli calm composition-version get {composition_version_id}
Get by version¶
If you need to retrieve a particular version of existing composition you can use its ID and version to get the version of your composition:
$ ocli calm composition-version get-by-version -v {version} {composition_version_id}
Get compose file¶
You can download compose file attached to your composition version. It will be saved in your $CWD under a name of “docker_compose.yml”.
$ ocli calm composition-version get-compose-file {composition_version_id}
Update version¶
You can update composition’s version - the only editable field is description. Once version is created, you cannot edit it’s name of compose file.
$ ocli calm composition-version update -d {description} {composition_version_id}
Fleet¶
Fleet is an entity that allows you to group your Orchestra devices and compositions into ready-to-release batches.
Create¶
In order to create a fleet you need to use command below:
$ ocli calm fleet create -n {name} -d {description}
Attach¶
Compositions and devices must be attached to your fleet in order to make a release.
You can attach one object - either composition or device using following command:
$ ocli calm fleet attach {object_kind} {object_id} {fleet_id}
when attaching for example a device, the command should look like:
$ ocli calm fleet attach device {device_id} {fleet_id}
To ease the interaction with many devices belonging to Orchestra or composition versions already created, you can use attach command. This is an interactive command that displays attachable (not attached yet) objects.
$ ocli calm fleet attach {object_kind} {fleet_id}
So when trying to attach composition versions to your fleet, the command and its output should look like below.
The output of this command is an interactive selector of devices. Navigate using arrow up/arrow down and select devices to attach by clicking space on your keyboard.
Confirm your selection by clicking Enter.
$ ocli calm fleet attach device {fleet_id}
Detach¶
You can detach a device or a composition from your fleet, either individually or in batch mode.
Warning
Detaching device stops and deletes all compositions from this fleet running on the device.
Warning
Detaching composition stops and deletes this composition (if it is deployed) from all the devices in this fleet.
To detach a single object, use the following command:
$ ocli calm fleet detach {object_kind} {object_id} {fleet_id}
For example, to detach a device:
$ ocli calm fleet detach device {device_id} {fleet_id}
If you want to detach multiple objects at once, use the detach command. This command opens an interactive selector for you to choose which objects to detach.
$ ocli calm fleet detach {object_kind} {fleet_id}
When detaching multiple composition versions, the command and its output look like the following example:
$ ocli calm fleet detach composition {fleet_id}
Get¶
To retrieve an existing fleet, use the following command:
$ ocli calm fleet get {fleet_id}
Delete¶
To delete an existing fleet, run:
$ ocli calm fleet delete {fleet_id}
Update¶
You can update the name or description of a fleet using the following command. Either the -d (description) or -n (name) option must be included:
$ ocli calm fleet update -d {description} -n {name} {fleet_id}
List¶
To list all your existing fleets, use the following command:
$ ocli calm fleet list
Registry¶
Registry is the place where you store your images. Sometimes they get pulled from official hubs like Docker or Github but very often there’s a need to give access to private registry.
Create¶
To create a new registry, use the following command:
$ ocli calm registry create -n {name} -d {description} -u {url} {TYPE}
Where TYPE can be either insecure or password.
For an insecure registry, only the -n, -d, and -u parameters are required. For a password-protected registry, you will be prompted to enter your credentials.
$ ocli calm registry create -n {name} -d {description} -u {user} password
Delete¶
To delete a registry use the following command:
$ ocli calm registry delete {registry_id}
Warning
Deleting the registry may make your releases fail.
Get¶
To retrieve an existing registry, use the following command:
$ ocli calm registry get {registry_id}
List¶
To list all your registries, use:
$ ocli calm registry list
Note
Registries cannot be updated. You must delete and recreate them.
Release¶
When releasing an application, variable snapshotting is performed. This ensures that the correct set of variables is applied during deployment.
How Snapshotting Works:
Variable Configuration: Users configure variables, which are considered to be the “latest” version at this stage.
Snapshot Creation: Upon releasing a composition, the system creates a snapshot by resolving variables at the device level.
Variable Validation: The snapshot is passed to a method that validates and prepares the variables for inclusion in the compose file.
Applying Variables: Only the necessary variables are applied to the compose file for the release.
Create: Making a Release¶
Once your fleet (devices and compositions) is ready for deployment, and you want to release the application to your devices, use the following command:
$ ocli calm release create -v {composition_version_id} -f {fleet_id}
Option composition-version-id is optional - if you do not provide it, interactive model will be used.
Restart¶
The restart command is useful in two scenarios:
Troubleshooting: If your application encounters problems, restarting it can often resolve the issue.
Applying Updates: After updating variables or making other configuration changes, restarting the application ensures that all devices receive the latest settings.
$ ocli calm release restart -f {fleet_id}
To restart a specific release without going through the interactive selection, use the -r or --release-id option followed by the desired release ID.
$ ocli calm release restart -f {fleet_id} -r {release_id}
Variables¶
Variables allow you to customize Docker Compose environment variables based on your specific needs. They function by keys, meaning variables with the same key will override each other depending on their context.
Variables can exist in different contexts:
Device: Specific to an individual device.
Fleet: Applied to a group of devices.
Composition: Related to a particular application composition.
Global: Applies universally across all devices and compositions.
Variables follow an inheritance hierarchy. The order of inheritance is:
Global > Composition > Fleet > Device.
This means that more specific contexts (like a device) can override variables from broader contexts (like global), if the same key is used.
Variables can be masked to prevent them from being inherited. When a variable is masked, it blocks inheritance to lower-level contexts, allowing more control over which variables are applied.
Create¶
You can create variables that are global:
$ ocli calm variable create -k {key} -v {value} -d {description} global
You can create variables for specific CALM resource:
$ ocli calm variable create -k {key} -v {value} -d {description} -r {resource_id} KIND
where KIND is one of:
composition
fleet
device
Variables inheritance order is: Global > Composition > Fleet > Device.
$ ocli calm variable create -k {key} -v {value} -d {description} (-r {resource_id}) KIND
List¶
If you want to get a set of variables that are going to be used for specific resource, you can use the command below:
$ ocli calm variable list (-r {resource_id}) KIND
That’s an example set of three variables for a device. As you can see, there is a DEVICE variable PASSWORD that overrides FLEET variable PASSWORD.
Device also gets variables of the fleet it is assigned to. In this case, it’s gonna gest TEST variable with value TEST.
Global variables are also taken for this particular device.
Get¶
If you want to get a variable, use:
$ ocli calm variable get {variable_id}
Note
Please note that get does not tell you what’s the inheritance of a variable because it has no context of how that variable is used - for example for a device in a fleet.
Mask/unmask inheritance¶
If you want to temporarily disable a variable, you can mask it to prevent it from being used when determining the set of variables for a CALM resource. Masking a variable stops it from being inherited from higher-level contexts, giving you more control over which variables are applied in different contexts.
$ ocli calm variable mask {variable_id}
$ ocli calm variable unmask {variable_id}
Warning
After a variable gets masked, it is no longer considered active. If I mask a fleet variable 66bb6744daf77a7a82e29d84 from the example above, it’s no longer given to the device variables set.
First, lets list the variables in our composition.
Now, lets mask WM_SERVICES_MQTT_PASSWORD variable to prevent it from being inherited to a fleet and device levels.
And let’s list all variables of our composition again.
Note
Expand reference is not currently used and by default it’s False.
Delete¶
If you want to delete a variable, use:
$ ocli calm variable delete {variable_id}