.. _calm-manual-cli-plugin: 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. .. _ocli-calm-composition-create: Create ^^^^^^^^^^^^^^ Create a new composition with this command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition create -n "name of your application" .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition create -n Composition-A ╒════════════════╤════════════════╤═══════════════╤══════════════════════════╤════════════════╕ │ created_at │ updated_at │ name │ id │ latest_version │ ├────────────────┼────────────────┼───────────────┼──────────────────────────┼────────────────┤ │ 2024-10-02 │ 2024-10-02 │ Composition-A │ 66fd4739ac3bfd8b5dc6ea79 │ │ │ 13:14:33+00:00 │ 13:14:33+00:00 │ │ │ │ ╘════════════════╧════════════════╧═══════════════╧══════════════════════════╧════════════════╛ Update ^^^^^^^^^^^^^^ You can update your existing composition using following command. The only editable attribute of your composition is its name. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition update -n "name of your application" {composition_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition update -n Composition-B 66fd4739ac3bfd8b5dc6ea79 ╒════════════════╤════════════════╤═══════════════╤══════════════════════════╤════════════════╕ │ created_at │ updated_at │ name │ id │ latest_version │ ├────────────────┼────────────────┼───────────────┼──────────────────────────┼────────────────┤ │ 2024-10-02 │ 2024-10-02 │ Composition-B │ 66fd4739ac3bfd8b5dc6ea79 │ │ │ 13:14:33+00:00 │ 13:15:32+00:00 │ │ │ │ ╘════════════════╧════════════════╧═══════════════╧══════════════════════════╧════════════════╛ Get ^^^^^^^^^^^^^^ In order to get existing composition you should use the command below: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition get {composition_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition get 66fd4739ac3bfd8b5dc6ea79 ╒════════════════╤════════════════╤═══════════════╤══════════════════════════╤════════════════╕ │ created_at │ updated_at │ name │ id │ latest_version │ ├────────────────┼────────────────┼───────────────┼──────────────────────────┼────────────────┤ │ 2024-10-02 │ 2024-10-02 │ Composition-B │ 66fd4739ac3bfd8b5dc6ea79 │ │ │ 13:14:33+00:00 │ 13:15:32+00:00 │ │ │ │ ╘════════════════╧════════════════╧═══════════════╧══════════════════════════╧════════════════╛ List ^^^^^^^^^^^^^^ To get all your existing compositions you can use a ``list`` command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition list .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition list ╒═══════════════════════════╤═══════════════════════════╤═════════╤══════════════════════════╤══════════════════╕ │ created_at │ updated_at │ name │ id │ latest_version │ ╞═══════════════════════════╪═══════════════════════════╪═════════╪══════════════════════════╪══════════════════╡ │ 2024-08-06 08:27:44+00:00 │ 2024-08-06 08:27:44+00:00 │ TEST │ 66b1de80cf022f34eba2fd51 │ 1.0.0 │ ├───────────────────────────┼───────────────────────────┼─────────┼──────────────────────────┼──────────────────┤ │ 2024-08-12 09:00:02+00:00 │ 2024-08-12 09:14:18+00:00 │ TestApp │ 66b9cf12cf022f34eba2fd52 │ │ ├───────────────────────────┼───────────────────────────┼─────────┼──────────────────────────┼──────────────────┤ │ 2024-08-12 09:18:32+00:00 │ 2024-08-12 09:18:32+00:00 │ Test234 │ 66b9d368b9a14cb24f15598c │ │ ╘═══════════════════════════╧═══════════════════════════╧═════════╧══════════════════════════╧══════════════════╛ 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. .. _ocli-calm-composition-version-create: 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. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version create -f -v .. tab-item:: Error .. code:: console :class: no-copybutton $ ocli calm composition-version create -f "incorrect.yaml" -v "1.0.0" 66fd4739ac3bfd8b5dc6ea79 Error from Orchestra CALM. Status code 406 Compose file error: mysql which web depends on is not defined .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version create -f "1.yaml" -v "1.0.0" 66fd4739ac3bfd8b5dc6ea79 ╒════════════════╤════════════════╤══════════════════════════╤═════════╤═════════════╤══════════════╤══════════════════════════╤══════════════════╕ │ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │ ├────────────────┼────────────────┼──────────────────────────┼─────────┼─────────────┼──────────────┼──────────────────────────┼──────────────────┤ │ 2024-10-02 │ 2024-10-02 │ 66fd4739ac3bfd8b5dc6ea79 │ 1.0.0 │ │ OK │ 66fd48bb9ee4869dbe1ac115 │ Composition-B │ │ 13:20:59+00:00 │ 13:20:59+00:00 │ │ │ │ │ │ │ ╘════════════════╧════════════════╧══════════════════════════╧═════════╧═════════════╧══════════════╧══════════════════════════╧══════════════════╛ .. _ocli-calm-composition-version-list: List ^^^^^ You can list all existing versions of your composition using the following command. If any versions exist, they will be displayed. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version list {composition_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version list 66b1de80cf022f34eba2fd51 ╒═══════════════════════════╤═══════════════════════════╤══════════════════════════╤═══════════╤═════════════════════╤════════════════╤══════════════════════════╤════════════════════╕ │ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │ ╞═══════════════════════════╪═══════════════════════════╪══════════════════════════╪═══════════╪═════════════════════╪════════════════╪══════════════════════════╪════════════════════╡ │ 2024-08-06 09:25:03+00:00 │ 2024-08-06 09:25:03+00:00 │ 66b1de80cf022f34eba2fd51 │ 1.0.0 │ Flask and redis app │ OK │ 66b1ebefbe05ff2670af746c │ TEST │ ╘═══════════════════════════╧═══════════════════════════╧══════════════════════════╧═══════════╧═════════════════════╧════════════════╧══════════════════════════╧════════════════════╛ Get ^^^^^^^^^^^^^^ In order to get your existing composition version, you use get command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version get {composition_version_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version get 66b1ebefbe05ff2670af746c ╒═══════════════════════════╤═══════════════════════════╤══════════════════════════╤═══════════╤═════════════════════╤════════════════╤══════════════════════════╤════════════════════╕ │ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │ ╞═══════════════════════════╪═══════════════════════════╪══════════════════════════╪═══════════╪═════════════════════╪════════════════╪══════════════════════════╪════════════════════╡ │ 2024-08-06 09:25:03+00:00 │ 2024-08-06 09:25:03+00:00 │ 66b1de80cf022f34eba2fd51 │ 1.0.0 │ Flask and redis app │ OK │ 66b1ebefbe05ff2670af746c │ TEST │ ╘═══════════════════════════╧═══════════════════════════╧══════════════════════════╧═══════════╧═════════════════════╧════════════════╧══════════════════════════╧════════════════════╛ 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: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version get-by-version -v {version} {composition_version_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version get-by-version -v "1.0.0" 66fd4739ac3bfd8b5dc6ea79 ╒════════════════╤════════════════╤══════════════════════════╤═════════╤═════════════╤══════════════╤══════════════════════════╤══════════════════╕ │ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │ ├────────────────┼────────────────┼──────────────────────────┼─────────┼─────────────┼──────────────┼──────────────────────────┼──────────────────┤ │ 2024-10-02 │ 2024-10-02 │ 66fd4739ac3bfd8b5dc6ea79 │ 1.0.0 │ │ OK │ 66fd48bb9ee4869dbe1ac115 │ Composition-B │ │ 13:20:59+00:00 │ 13:20:59+00:00 │ │ │ │ │ │ │ ╘════════════════╧════════════════╧══════════════════════════╧═════════╧═════════════╧══════════════╧══════════════════════════╧══════════════════╛ 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". .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version get-compose-file {composition_version_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version get-compose-file 66fd48bb9ee4869dbe1ac115 services: app: image: qarlm/static-http-response-server:latest environment: RESPONSE: "ok" ports: - '8080:80' 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. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm composition-version update -d {description} {composition_version_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm composition-version update -d "B Composition" 66fd48bb9ee4869dbe1ac115 ╒════════════════╤════════════════╤══════════════════════════╤═════════╤═════════════╤══════════════╤══════════════════════════╤══════════════════╕ │ created_at │ updated_at │ composition_id │ version │ description │ compose_file │ id │ composition_name │ ├────────────────┼────────────────┼──────────────────────────┼─────────┼─────────────┼──────────────┼──────────────────────────┼──────────────────┤ │ 2024-10-02 │ 2024-10-02 │ 66fd4739ac3bfd8b5dc6ea79 │ 1.0.0 │ B │ OK │ 66fd48bb9ee4869dbe1ac115 │ Composition-B │ │ 13:20:59+00:00 │ 13:41:17+00:00 │ │ │ Composition │ │ │ │ ╘════════════════╧════════════════╧══════════════════════════╧═════════╧═════════════╧══════════════╧══════════════════════════╧══════════════════╛ Fleet ------------ Fleet is an entity that allows you to group your Orchestra devices and compositions into ready-to-release batches. .. _ocli-calm-fleet-create: Create ^^^^^^^ In order to create a fleet you need to use command below: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm fleet create -n {name} -d {description} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm fleet create -n TEST_FLEET -d "Testing calm" ╒═══════════════════════════╤═══════════════════════════╤════════════╤════════════════════════╤═══════════╤════════════════╤══════════════════════════╤══════════╤═══════════════════╕ │ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │ ╞═══════════════════════════╪═══════════════════════════╪════════════╪════════════════════════╪═══════════╪════════════════╪══════════════════════════╪══════════╪═══════════════════╡ │ 2024-08-12 10:25:00+00:00 │ 2024-08-12 10:25:00+00:00 │ TEST_FLEET │ Testing calm │ [] │ [] │ 66b9e2fcbe05ff2670af746d │ unknown │ │ ╘═══════════════════════════╧═══════════════════════════╧════════════╧════════════════════════╧═══════════╧════════════════╧══════════════════════════╧══════════╧═══════════════════╛ .. _ocli-calm-fleet-attach: Attach ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. UPDATE 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: .. code:: console $ ocli calm fleet attach {object_kind} {object_id} {fleet_id} when attaching for example a device, the command should look like: .. code:: console $ 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. .. code:: console $ 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. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm fleet attach device {fleet_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm fleet attach device 66b9e2fcbe05ff2670af746d [?] Pick devices you wanna attach to fleet {fleet_id} - {fleet_name}: > [X] 65df0508d1e4df7b262704df - brave_black [ ] 65df0534d1e4df7b262704e1 - priceless_mirzakhani [ ] 65df05831804af86b0cf0349 - peaceful_swartz ╒═══════════════════════════╤═══════════════════════════╤════════════╤════════════════════════╤════════════════════════════════════════════╤════════════════╤══════════════════════════╤══════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╕ │ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │ ╞═══════════════════════════╪═══════════════════════════╪════════════╪════════════════════════╪════════════════════════════════════════════╪════════════════╪══════════════════════════╪══════════╪══════════════════════════════════════════════════════════════════════════════════════════════════╡ │ 2024-08-12 10:25:00+00:00 │ 2024-08-12 10:25:00+00:00 │ TEST_FLEET │ Testing calm with Barb │ ['65df0508d1e4df7b262704df - brave_black'] │ [] │ 66b9e2fcbe05ff2670af746d │ unknown │ {'devices': [{'status': , 'count': 1}], 'compositions': []} │ ╘═══════════════════════════╧═══════════════════════════╧════════════╧════════════════════════╧════════════════════════════════════════════╧════════════════╧══════════════════════════╧══════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╛ 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: .. code:: console $ ocli calm fleet detach {object_kind} {object_id} {fleet_id} For example, to detach a device: .. code:: console $ 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. .. code:: console $ ocli calm fleet detach {object_kind} {fleet_id} When detaching multiple composition versions, the command and its output look like the following example: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm fleet detach composition {fleet_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm fleet detach composition 66b9e2fcbe05ff2670af746d [?] Pick composition versions you want to detach from fleet {fleet_id} - {fleet_name}: > [ ] 66b1ebefbe05ff2670af746c - TEST:1.0.0 ╒═══════════════════════════╤═══════════════════════════╤════════════╤════════════════════════╤════════════════════════════════════════════╤════════════════╤══════════════════════════╤══════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╕ │ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │ ╞═══════════════════════════╪═══════════════════════════╪════════════╪════════════════════════╪════════════════════════════════════════════╪════════════════╪══════════════════════════╪══════════╪══════════════════════════════════════════════════════════════════════════════════════════════════╡ │ 2024-08-12 10:25:00+00:00 │ 2024-08-12 10:25:00+00:00 │ TEST_FLEET │ Testing calm with Barb │ ['66b1ebefbe05ff2670af746c - TEST:1.0.0'] │ [] │ 66b9e2fcbe05ff2670af746d │ unknown │ {'devices': [{'status': , 'count': 1}], 'compositions': []} │ ╘═══════════════════════════╧═══════════════════════════╧════════════╧════════════════════════╧════════════════════════════════════════════╧════════════════╧══════════════════════════╧══════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╛ .. _ocli-calm-fleet-get: Get ^^^^^^^^^^^^^^ To retrieve an existing fleet, use the following command: .. code:: console $ ocli calm fleet get {fleet_id} Delete ^^^^^^^^^^^^^^ To delete an existing fleet, run: .. code:: console $ 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: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm fleet update -d {description} -n {name} {fleet_id} .. tab-item:: Output .. code:: console :class: no-copybutton ╒═══════════════════════════╤═══════════════════════════╤════════════╤═══════════════════════════╤════════════════════════════════════════════╤════════════════╤══════════════════════════╤══════════╤══════════════════════════════════════════════════════════════════════════════════════════════════╕ │ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │ ╞═══════════════════════════╪═══════════════════════════╪════════════╪═══════════════════════════╪════════════════════════════════════════════╪════════════════╪══════════════════════════╪══════════╪══════════════════════════════════════════════════════════════════════════════════════════════════╡ │ 2024-08-12 10:25:00+00:00 │ 2024-08-13 11:08:21+00:00 │ TEST_FLEET │ Updated fleet description │ ['65df0508d1e4df7b262704df - brave_black'] │ [] │ 66b9e2fcbe05ff2670af746d │ unknown │ {'devices': [{'status': , 'count': 1}], 'compositions': []} │ ╘═══════════════════════════╧═══════════════════════════╧════════════╧═══════════════════════════╧════════════════════════════════════════════╧════════════════╧══════════════════════════╧══════════╧══════════════════════════════════════════════════════════════════════════════════════════════════╛ .. _ocli-calm-fleet-list: List ^^^^^^^^^^^^^^ To list all your existing fleets, use the following command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm fleet list .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm fleet list ╒════════════════╤════════════════╤════════════════════╤══════════════╤════════════════════════════╤════════════════════════════╤══════════════════════════╤═══════════════╤══════════════════╕ │ created_at │ updated_at │ name │ description │ devices │ compositions │ id │ status │ deployment_info │ ├────────────────┼────────────────┼────────────────────┼──────────────┼────────────────────────────┼────────────────────────────┼──────────────────────────┼───────────────┼──────────────────┤ │ 2024-09-09 │ 2024-09-09 │ Test9.09 │ test │ [] │ │ 66deec27c1e6bd3a6ec2d2d9 │ UNKNOWN │ │ │ 12:37:59+00:00 │ 12:37:59+00:00 │ │ │ │ │ │ │ │ ├────────────────┼────────────────┼────────────────────┼──────────────┼────────────────────────────┼────────────────────────────┼──────────────────────────┼───────────────┼──────────────────┤ │ 2024-10-01 │ 2024-10-01 │ testWirepas03 │ wirepas app │ ['66ed2f80f1fb4461641368c8 │ ['66fbaa8fe49682f649df5031 │ 66fba9bc35a7d7d20dbee71e │ RECONFIGURING │ {'devices': │ │ 07:50:20+00:00 │ 07:50:20+00:00 │ │ │ - ct-demo-GW-3', │ - testWirepas03:1.0.0'] │ │ │ [{'status': │ │ │ │ │ │ '66ead0284e2bf8f818743b81 │ │ │ │ 'RECONFIGURING', │ │ │ │ │ │ - ct-demo-GW-2'] │ │ │ │ 'count': 2}, │ │ │ │ │ │ │ │ │ │ {'status': │ │ │ │ │ │ │ │ │ │ 'TOTAL', │ │ │ │ │ │ │ │ │ │ 'count': 2}], │ │ │ │ │ │ │ │ │ │ 'compositions': │ │ │ │ │ │ │ │ │ │ [{'status': │ │ │ │ │ │ │ │ │ │ 'RECONFIGURING', │ │ │ │ │ │ │ │ │ │ 'count': 1}]} │ ╘════════════════╧════════════════╧════════════════════╧══════════════╧════════════════════════════╧════════════════════════════╧══════════════════════════╧═══════════════╧══════════════════╛ 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: .. code:: console $ 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. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm registry create -n {name} -d {description} -u {user} password .. tab-item:: Output .. code:: console :class: no-copybutton ocli calm registry create -n TEST -d TEST -u "myregistry.io" password Provide credentials for your registry. Login: mylogintest Password: Provide your password again: ╒═══════════════════════════╤═══════════════════════════╤════════╤═══════════════╤═══════════════════════╤═══════════════════════════════════════════════╤═══════════════╤══════════════════════════╕ │ created_at │ updated_at │ name │ url │ authentication_type │ authentication_data │ description │ id │ ╞═══════════════════════════╪═══════════════════════════╪════════╪═══════════════╪═══════════════════════╪═══════════════════════════════════════════════╪═══════════════╪══════════════════════════╡ │ 2024-08-13 12:28:36+00:00 │ 2024-08-13 12:28:36+00:00 │ TEST │ myregistry.io │ password │ {'login': 'mylogintest', 'password': '12345'} │ TEST │ 66bb517498daf0bc2d2910e0 │ ╘═══════════════════════════╧═══════════════════════════╧════════╧═══════════════╧═══════════════════════╧═══════════════════════════════════════════════╧═══════════════╧══════════════════════════╛ Delete ^^^^^^^^^^^^^^ To delete a registry use the following command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm registry delete {registry_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm registry delete 66fd4ed5ac3bfd8b5dc6ea7a Registry 66fd4ed5ac3bfd8b5dc6ea7a deleted .. warning:: Deleting the registry may make your releases fail. Get ^^^^^^^^^^^^^^ To retrieve an existing registry, use the following command: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm registry get {registry_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm registry get 66fd4ed5ac3bfd8b5dc6ea7a ╒════════════════╤════════════════╤══════╤═══════════════╤═════════════════════════════════════╤═════════════════════╤═════════════╤══════════════════════════╕ │ created_at │ updated_at │ name │ url │ authentication_type │ authentication_data │ description │ id │ ├────────────────┼────────────────┼──────┼───────────────┼─────────────────────────────────────┼─────────────────────┼─────────────┼──────────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ TEST │ myregistry.io │ RegistryAuthenticationType.password │ {'login': 'user', │ TEST │ 66fd4ed5ac3bfd8b5dc6ea7a │ │ 13:47:01+00:00 │ 13:47:01+00:00 │ │ │ │ 'password': 'pass'} │ │ │ ╘════════════════╧════════════════╧══════╧═══════════════╧═════════════════════════════════════╧═════════════════════╧═════════════╧══════════════════════════╛ List ^^^^^^^^^^^^^^ To list all your registries, use: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm registry list .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm registry list ╒════════════════╤════════════════╤══════╤═══════════════╤═════════════════════════════════════╤═════════════════════╤═════════════╤══════════════════════════╕ │ created_at │ updated_at │ name │ url │ authentication_type │ authentication_data │ description │ id │ ├────────────────┼────────────────┼──────┼───────────────┼─────────────────────────────────────┼─────────────────────┼─────────────┼──────────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ TEST │ myregistry.io │ RegistryAuthenticationType.password │ {'login': 'user', │ TEST │ 66fd4ed5ac3bfd8b5dc6ea7a │ │ 13:47:01+00:00 │ 13:47:01+00:00 │ │ │ │ 'password': 'pass'} │ │ │ ╘════════════════╧════════════════╧══════╧═══════════════╧═════════════════════════════════════╧═════════════════════╧═════════════╧══════════════════════════╛ .. note:: Registries cannot be updated. You must delete and recreate them. .. _ocli-calm-release-create: Release ---------- When releasing an application, variable snapshotting is performed. This ensures that the correct set of variables is applied during deployment. How Snapshotting Works: 1. Variable Configuration: Users configure variables, which are considered to be the "latest" version at this stage. 2. Snapshot Creation: Upon releasing a composition, the system creates a snapshot by resolving variables at the device level. 3. Variable Validation: The snapshot is passed to a method that validates and prepares the variables for inclusion in the compose file. 4. 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: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm release create -v {composition_version_id} -f {fleet_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm release create -v {composition_version_id} -f {fleet_id} Release successfully requested. Check your fleet in a few minutes. 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. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm release restart -f {fleet_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm release restart -f 670d25bcc03e6319ada71ea3 [?] Choose a release to be restarted on a fleet 670d25bcc03e6319ada71ea3 - Hello World fleet: Hello World app:1.0.0 - 670d271e57ef8155084d2e0f > Hello World app:1.0.1 - 670d348f0a892f45c2c30da4 Release Hello World app:1.0.1 restarted successfully. Check your fleet in a few minutes. To restart a specific release without going through the interactive selection, use the ``-r`` or ``--release-id`` option followed by the desired release ID. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm release restart -f {fleet_id} -r {release_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm release restart -f {fleet_id} -r {release_id} Release {name} restarted successfully. Check your fleet in a few minutes. 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. .. _ocli-calm-variable-create: Create ^^^^^^^^ You can create variables that are global: .. code:: console $ ocli calm variable create -k {key} -v {value} -d {description} global You can create variables for specific CALM resource: .. code:: console $ 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**. .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm variable create -k {key} -v {value} -d {description} (-r {resource_id}) KIND .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm variable create -k var_a -v 123 -d "a var" global ╒════════════════╤════════════════╤═══════╤═══════╤═════════════╤════════╤═════════════╤════════╤══════════════════╤══════════════════════════╤═════════════════════╕ │ created_at │ updated_at │ key │ value │ description │ kind │ resource_id │ masked │ expand_reference │ id │ overridden_variable │ ├────────────────┼────────────────┼───────┼───────┼─────────────┼────────┼─────────────┼────────┼──────────────────┼──────────────────────────┼─────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ var_a │ 123 │ a var │ global │ │ false │ false │ 66fd5085117951fa403e6c31 │ │ │ 13:54:13+00:00 │ 13:54:13+00:00 │ │ │ │ │ │ │ │ │ │ ╘════════════════╧════════════════╧═══════╧═══════╧═════════════╧════════╧═════════════╧════════╧══════════════════╧══════════════════════════╧═════════════════════╛ .. _ocli-calm-variable-list: 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: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm variable list (-r {resource_id}) KIND .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm variable list global ╒════════════════╤════════════════╤═══════════════════════════╤════════════════════════════════╤═════════════╤════════╤═════════════╤════════╤══════════════════╤══════════════════════════╤═════════════════════╕ │ created_at │ updated_at │ key │ value │ description │ kind │ resource_id │ masked │ expand_reference │ id │ overridden_variable │ │ │ │ │ │ │ │ │ │ │ │ │ ├────────────────┼────────────────┼───────────────────────────┼────────────────────────────────┼─────────────┼────────┼─────────────┼────────┼──────────────────┼──────────────────────────┼─────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ var_b │ ABC │ B var │ global │ │ false │ false │ 66fd50b6eed3cce4774cbcbe │ │ │ 13:55:02+00:00 │ 13:55:02+00:00 │ │ │ │ │ │ │ │ │ │ ├────────────────┼────────────────┼───────────────────────────┼────────────────────────────────┼─────────────┼────────┼─────────────┼────────┼──────────────────┼──────────────────────────┼─────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ var_a │ 123 │ a var │ global │ │ false │ false │ 66fd5085117951fa403e6c31 │ │ │ 13:54:13+00:00 │ 13:54:13+00:00 │ │ │ │ │ │ │ │ │ │ ╘════════════════╧════════════════╧═══════════════════════════╧════════════════════════════════╧═════════════╧════════╧═════════════╧════════╧══════════════════╧══════════════════════════╧═════════════════════╛ 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: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm variable get {variable_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm variable get 66fd50b6eed3cce4774cbcbe ╒════════════════╤════════════════╤═══════════════════════════╤════════════════════════════════╤═════════════╤════════╤═════════════╤════════╤══════════════════╤══════════════════════════╤═════════════════════╕ │ created_at │ updated_at │ key │ value │ description │ kind │ resource_id │ masked │ expand_reference │ id │ overridden_variable │ │ │ │ │ │ │ │ │ │ │ │ │ ├────────────────┼────────────────┼───────────────────────────┼────────────────────────────────┼─────────────┼────────┼─────────────┼────────┼──────────────────┼──────────────────────────┼─────────────────────┤ │ 2024-10-02 │ 2024-10-02 │ var_b │ ABC │ B var │ global │ │ false │ false │ 66fd50b6eed3cce4774cbcbe │ │ │ 13:55:02+00:00 │ 13:55:02+00:00 │ │ │ │ │ │ │ │ │ │ ╘════════════════╧════════════════╧═══════════════════════════╧════════════════════════════════╧═════════════╧════════╧═════════════╧════════╧══════════════════╧══════════════════════════╧═════════════════════╛ .. 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. .. code:: console $ ocli calm variable mask {variable_id} .. code:: console $ 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. .. code:: console :class: no-copybutton $ ocli calm variable list -r 66fa8912b4c08769d7c6a140 composition ╒════════════════╤═══════════════╤═════════════╤ ... ╤════════╤═════════════╤═════════════╤═════════════╕ │ created_at │ updated_at │ key │ ... │ masked │ expand_refe │ id │ overridden_ │ │ │ │ │ ... │ │ rence │ │ variable │ ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ │ 2024-10-01 │ 2024-10-01 09 │ WM_GW_ID │ ... │ false │ false │ 66fbbe7c858 │ │ │ 09:18:52+00:00 │ :18:52+00:00 │ │ ... │ │ │ 6b627788367 │ │ │ │ │ │ ... │ │ │ c5 │ │ ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ ... ... ... ... ... ... ... ... ... ... ... ... ... ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ │ 2024-10-01 │ 2024-10-01 08 │ WM_SERVICES │ ... │ false │ false │ 66fbb7bef95 │ │ │ 08:50:06+00:00 │ :50:06+00:00 │ _MQTT_PASSW │ ... │ │ │ 1624647fa8e │ │ │ │ │ ORD │ ... │ │ │ 38 │ │ ╘════════════════╧═══════════════╧═════════════╧ ... ╧════════╧═════════════╧═════════════╧═════════════╛ Now, lets mask ``WM_SERVICES_MQTT_PASSWORD`` variable to prevent it from being inherited to a fleet and device levels. .. code:: console :class: no-copybutton $ ocli calm variable mask 66fbb7bef951624647fa8e38 ╒════════════════╤═══════════════╤═════════════╤ ... ╤════════╤═════════════╤═════════════╤═════════════╕ │ created_at │ updated_at │ key │ ... │ masked │ expand_refe │ id │ overridden_ │ │ │ │ │ ... │ │ rence │ │ variable │ ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ │ 2024-10-01 │ 2024-10-03 10 │ WM_SERVICES │ ... │ true │ false │ 66fbb7bef95 │ │ │ 08:50:06+00:00 │ :03:17+00:00 │ _MQTT_PASSW │ ... │ │ │ 1624647fa8e │ │ │ │ │ ORD │ ... │ │ │ 38 │ │ ╘════════════════╧═══════════════╧═════════════╧ ... ╧════════╧═════════════╧═════════════╧═════════════╛ And let's list all variables of our composition again. .. code:: console :class: no-copybutton $ ocli calm variable list -r 66fa8912b4c08769d7c6a140 composition ╒════════════════╤═══════════════╤═════════════╤ ... ╤════════╤═════════════╤═════════════╤═════════════╕ │ created_at │ updated_at │ key │ ... │ masked │ expand_refe │ id │ overridden_ │ │ │ │ │ ... │ │ rence │ │ variable │ ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ │ 2024-10-01 │ 2024-10-01 09 │ WM_GW_ID │ ... │ false │ false │ 66fbbe7c858 │ │ │ 09:18:52+00:00 │ :18:52+00:00 │ │ ... │ │ │ 6b627788367 │ │ │ │ │ │ ... │ │ │ c5 │ │ ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ ... ... ... ... ... ... ... ... ... ... ... ... ... ├────────────────┼───────────────┼─────────────┼ ... ┼────────┼─────────────┼─────────────┼─────────────┤ │ 2024-10-01 │ 2024-10-03 10 │ WM_SERVICES │ ... │ true │ false │ 66fbb7bef95 │ │ │ 08:50:06+00:00 │ :03:17+00:00 │ _MQTT_PASSW │ ... │ │ │ 1624647fa8e │ │ │ │ │ ORD │ ... | │ │ 38 │ │ ╘════════════════╧═══════════════╧═════════════╧ ... ╧════════╧═════════════╧═════════════╧═════════════╛ .. note:: **Expand reference** is not currently used and by default it's **False**. Delete ^^^^^^ If you want to delete a variable, use: .. tab-set:: .. tab-item:: Command .. code:: console $ ocli calm variable delete {variable_id} .. tab-item:: Output .. code:: console :class: no-copybutton $ ocli calm variable delete 66fd50b6eed3cce4774cbcbe OK