From ef3a0d58e532ada62d0073c085eb80c3efbc207f Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 5 Dec 2024 14:36:05 +0100 Subject: [PATCH] Update deploy section (#3732) --- docs/manage/_index.md | 32 +- docs/manage/deploy/one-to-many.md | 154 ------- docs/manage/deploy/setup.md | 9 - docs/manage/{deploy => fleet}/_index.md | 4 +- .../{deploy => fleet}/provision/_index.md | 2 +- .../provision/provision-setup.md | 0 .../{deploy => fleet}/provision/provision.md | 0 docs/manage/fleet/reuse-configuration.md | 419 ++++++++++++++++++ docs/manage/fleet/setup.md | 20 + docs/manage/software/_index.md | 10 + .../ota.md => software/deploy-packages.md} | 23 +- .../update.md => software/update-packages.md} | 19 +- 12 files changed, 493 insertions(+), 199 deletions(-) delete mode 100644 docs/manage/deploy/one-to-many.md delete mode 100644 docs/manage/deploy/setup.md rename docs/manage/{deploy => fleet}/_index.md (71%) rename docs/manage/{deploy => fleet}/provision/_index.md (99%) rename docs/manage/{deploy => fleet}/provision/provision-setup.md (100%) rename docs/manage/{deploy => fleet}/provision/provision.md (100%) create mode 100644 docs/manage/fleet/reuse-configuration.md create mode 100644 docs/manage/fleet/setup.md create mode 100644 docs/manage/software/_index.md rename docs/manage/{deploy/ota.md => software/deploy-packages.md} (80%) rename docs/manage/{deploy/update.md => software/update-packages.md} (89%) diff --git a/docs/manage/_index.md b/docs/manage/_index.md index 87bc8dd361..11d93e4daf 100644 --- a/docs/manage/_index.md +++ b/docs/manage/_index.md @@ -9,26 +9,28 @@ open_on_desktop: true overview: true --- -You can use Viam's cloud-based fleet management tools to monitor and manage access to your fleet of {{< glossary_tooltip term_id="smart-machine" text="smart machines" >}}. -Use these tools as you create and scale a new fleet of smart machines, or integrate Viam to manage and add functionality like data management to your existing fleet. + + + + diff --git a/docs/manage/deploy/one-to-many.md b/docs/manage/deploy/one-to-many.md deleted file mode 100644 index 0135bd7aad..0000000000 --- a/docs/manage/deploy/one-to-many.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "Configure multiple similar machines" -linkTitle: "Configure many machines" -weight: 40 -type: "docs" -tags: ["data management", "data", "services"] -images: ["/how-tos/one-to-many/new-fragment.png"] -description: "Viam has a built-in tool called fragments for using the same configuration on multiple machines." -aliases: - - /use-cases/one-to-many/ -languages: [] -viamresources: [] -platformarea: ["fleet"] -level: "Beginner" -date: "2024-08-09" -# updated: "" # When the tutorial was last entirely checked -cost: "0" ---- - -Viam has a built-in tool called _{{< glossary_tooltip term_id="fragment" text="fragments" >}}_ for using the same configuration on multiple machines. -A fragment can configure just one resource a machine uses, or all the resources it uses. -If most of your machines are similar but not identical, you can use fragments and then manually add modifications for individual machines. - -When you update a fragment, it updates the configurations of all machines that use that fragment. - -{{< alert title="In this page" color="tip" >}} - -1. [Create a configuration fragment](#create-a-fragment) -1. [Apply a fragment to multiple machines](#add-a-fragment-to-multiple-machines) -1. [Modify an otherwise identical configuration](#modify-a-fragment) - -{{< /alert >}} - -For information on provisioning many machines, see [Provisioning](/fleet/provision/). - -## Create a fragment - -{{< table >}} -{{% tablestep link="/configure/" %}} -**1. Configure one machine** - -Start by configuring one of your machines. - -In the [Viam app](https://app.viam.com), use the **CONFIGURE** tab to build a configuration for all components and services you want to use on all your machines. - -{{}} - -{{% /tablestep %}} -{{% tablestep %}} -**2. Copy the raw JSON** - -In your machine's **CONFIGURE** tab, switch to **JSON** and copy the raw JSON. - -{{}} - -{{% /tablestep %}} -{{% tablestep link="/fleet/fragments/" %}} -**3. Create a fragment** - -On the **FLEET** page, go to the [**FRAGMENTS** tab](https://app.viam.com/fragments). - -Click **Create fragment**, and paste the copied JSON configuration into it. - -Set your privacy settings. -There are three options for this: - -- **Public:** Any user inside or outside of your organization will be able to view and use this fragment. -- **Private:** No user outside of your organization will be able to view or use this fragment. -- **Unlisted:** Any user inside or outside of your organization, with a direct link, will be able to view and use this fragment. - -Click **Save**. - -If you want to edit the fragment later, do it from this screen. - -{{}} - -{{% /tablestep %}} -{{% tablestep %}} -{{}} -**4. Delete the original configuration (optional)** - -Now that the configuration is saved as a fragment, you can delete each resource in the original config from your machine and _replace the config with the fragment_ in the next step. -In this way, you can keep all your machines up to date whenever you change the fragment. - -{{% /tablestep %}} -{{< /table >}} - -## Add a fragment to multiple machines - -With your fragment created, you can add it to as many machines as you'd like. -You can do this manually, as described here, or using [provisioning](/fleet/provision/). - -{{< table >}} -{{% tablestep %}} -{{}} -**1. Add the fragment to one machine** - -On your machine's **CONFIGURE** tab, click the **+** button and select **Insert fragment**. -Search for your fragment and add it. - -Click **Save** in the upper right corner of the screen. - -{{% /tablestep %}} -{{% tablestep %}} -{{}} -**2. Repeat for each machine** - -Repeat step 1 for each of the machines that you want to configure in the same way. - -If some of your machines have slight differences, you can still add the fragment and then add fragment overwrites in the next section. - -{{% /tablestep %}} -{{< /table >}} - -## Modify fragment settings - -If your machines are similar but not identical, you can use a fragment with all of them, and then [overwrite parts of it](/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment) to customize select fields of the configuration without modifying the upstream fragment. - -{{% alert title="Note" color="note" %}} -If you modify fields within a fragment, your modifications will act as overwrites. -If you later update the upstream fragment, your modifications will still apply. -{{% /alert %}} - -{{< table >}} -{{% tablestep link="/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment" %}} -{{}} - - - -**1. Edit your machine's config** - -Go to the **CONFIGURE** tab of the machine whose config you want to modify, and make your edits just as you would edit a non-fragment resource. - -You can click the **{}** button to switch to advanced view and see the changes. - -Don't forget to **Save**. - -{{% /tablestep %}} -{{% tablestep %}} -**2. Check your machine's logs** - -After configuring fragment overwrites, check your machine's [**LOGS** tab](/cloud/machines/#logs). -If there are problems with overwrites to the fragment, the overwrites will not be partially applied and the configuration changes will not take effect until the configuration is fixed. - -{{% /tablestep %}} -{{% tablestep %}} -{{}} -**3. (Optional) Revert fragment modifications** - -If you need to restore the original fragment, click the **...** in the upper right corner of the card you modified, and click **Revert changes**. -Now, the fragment will be identical to the upstream fragment. - -{{% /tablestep %}} -{{< /table >}} diff --git a/docs/manage/deploy/setup.md b/docs/manage/deploy/setup.md deleted file mode 100644 index 4aebae2a27..0000000000 --- a/docs/manage/deploy/setup.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -linkTitle: "Set up many devices" -title: "Set up many devices" -weight: 30 -layout: "docs" -type: "docs" -no_list: true -description: "TODO" ---- diff --git a/docs/manage/deploy/_index.md b/docs/manage/fleet/_index.md similarity index 71% rename from docs/manage/deploy/_index.md rename to docs/manage/fleet/_index.md index b8c6e9bcf8..51e04a4e40 100644 --- a/docs/manage/deploy/_index.md +++ b/docs/manage/fleet/_index.md @@ -1,6 +1,6 @@ --- -linkTitle: "Deploy" -title: "Deploy" +linkTitle: "Deploy fleet" +title: "Deploy fleet" weight: 10 layout: "empty" type: "docs" diff --git a/docs/manage/deploy/provision/_index.md b/docs/manage/fleet/provision/_index.md similarity index 99% rename from docs/manage/deploy/provision/_index.md rename to docs/manage/fleet/provision/_index.md index 050a571cc5..089b671c03 100644 --- a/docs/manage/deploy/provision/_index.md +++ b/docs/manage/fleet/provision/_index.md @@ -1,7 +1,7 @@ --- linkTitle: "Provision devices" title: "Provision devices using viam-agent" -weight: 40 +weight: 25 layout: "docs" type: "docs" no_list: true diff --git a/docs/manage/deploy/provision/provision-setup.md b/docs/manage/fleet/provision/provision-setup.md similarity index 100% rename from docs/manage/deploy/provision/provision-setup.md rename to docs/manage/fleet/provision/provision-setup.md diff --git a/docs/manage/deploy/provision/provision.md b/docs/manage/fleet/provision/provision.md similarity index 100% rename from docs/manage/deploy/provision/provision.md rename to docs/manage/fleet/provision/provision.md diff --git a/docs/manage/fleet/reuse-configuration.md b/docs/manage/fleet/reuse-configuration.md new file mode 100644 index 0000000000..41ce3db004 --- /dev/null +++ b/docs/manage/fleet/reuse-configuration.md @@ -0,0 +1,419 @@ +--- +title: "Reuse machine configuration on many machines" +linkTitle: "Reuse machine configuration" +weight: 10 +type: "docs" +tags: ["data management", "data", "services"] +images: ["/how-tos/one-to-many/new-fragment.png"] +description: "Reuse the machine configuration from one machine for multiple machines." +aliases: + - /use-cases/one-to-many/ +languages: [] +viamresources: [] +platformarea: ["fleet"] +level: "Beginner" +date: "2024-08-09" +# updated: "" # When the tutorial was last entirely checked +cost: "0" +--- + +{{< alert title="Note" color="note" >}} +Does this belong here or in Build & integrate? +{{< /alert >}} + +If most of your machines use the same setup, you can use a {{< glossary_tooltip term_id="fragment" text="fragment" >}}, like a cookie cutter, to configure the machines in the same way. +Fragments are a way of sharing and managing [machine configurations](/configure/) across multiple machines. + +For example, if you have a fleet of rovers that uses the same hardware, you could use a fragment to configure the motors, base component, camera, and all other resources for all rovers. +If some of the rovers have a slightly different configuration, you can overwrite the configuration for just those {{< glossary_tooltip term_id="resource" text="resources" >}} of those rovers. + +If one rover has an arm attached, you can add the rover configuration fragment (including the motors, camera, and base components), and then configure the arm on just that one rover. + +## Create a fragment + +You must be an [organization owner](/cloud/rbac/#permissions) to create fragments for an organization. + +{{< table >}} +{{% tablestep link="/configure/" %}} +**1. Configure one machine** + +Start by configuring one of your machines. + +In the [Viam app](https://app.viam.com), use the **CONFIGURE** tab to build a configuration for all resources you want to use on all your machines. + +{{}} + +{{% /tablestep %}} +{{% tablestep %}} +**2. Copy the raw JSON** + +In your machine's **CONFIGURE** tab, switch to **JSON** and copy the raw JSON. + +{{}} + +{{% /tablestep %}} +{{% tablestep link="/fleet/fragments/" %}} +**3. Create a fragment** + +On the **FLEET** page, go to the [**FRAGMENTS** tab](https://app.viam.com/fragments). + +Click **Create fragment**, and paste the copied JSON configuration into it. + +Set your privacy settings. +There are three options for this: + +- **Public:** Any user inside or outside of your organization will be able to view and use this fragment. +- **Private:** No user outside of your organization will be able to view or use this fragment. +- **Unlisted:** Any user inside or outside of your organization, with a direct link, will be able to view and use this fragment. + +Click **Save**. + +If you want to edit the fragment later, do it from this screen. + +{{}} + +{{% /tablestep %}} +{{% tablestep %}} +{{}} +**4. Delete the original configuration (optional)** + +Now that the configuration is saved as a fragment, you can delete each resource in the original config from your machine and _replace the config with the fragment_ in the next step. +By using the new fragment, all your machines will use the exact same configuration. + +{{% /tablestep %}} +{{< /table >}} + +## Add the fragment to multiple machines + +With your fragment created, you can add it to all machines that should have it. + +In the following, you will see how to add a fragment manually. If you are working in a factory setting and need to set up devices before they reach the end user, you can also fragments while [provisioning](/fleet/provision/) your fleet. + +{{< table >}} +{{% tablestep %}} +{{}} +**1. Add the fragment to one machine** + +On your machine's **CONFIGURE** tab, click the **+** button and select **Insert fragment**. +Search for your fragment and add it. + +Click **Save** in the upper right corner of the screen. + +{{% /tablestep %}} +{{% tablestep %}} +{{}} +**2. Repeat for each machine** + +Repeat step 1 for each of the machines that you want to configure in the same way. + +If some of your machines have slight differences, you can still add the fragment and then add fragment overwrites in the next section. + +{{% /tablestep %}} +{{< /table >}} + +## Modify fragment settings on a machine + +If some of your machines are similar but not identical, you can use a fragment with all of them and then overwrite parts of the configuration to customize it **without modifying the upstream fragment**. + +For example, consider a fleet of rovers that all have the same motors, wheels, and base but a few rovers have a different camera than most. +You can configure a fragment that has the motors, wheels, base on the rovers as well as the camera that is used on most rovers. +For the rovers that have a different camera, you would then add the fragment and overwrite the camera configuration. + +If you or a collaborator later modify fields within the upstream fragment, your modifications will still apply. +For example if you changed the default camera configuration in the fragment to be a different camera model, your modified rovers would still overwrite the camera model set by the fragment. + +{{< table >}} +{{% tablestep link="/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment" %}} + + + +**1. Edit your machine's config** + +{{< tabs >}} +{{% tab name="Config Builder" %}} + +Go to the **CONFIGURE** tab of the machine whose config you want to modify, and make your edits just as you would edit a non-fragment {{< glossary_tooltip term_id="resource" text="resource" >}}. + +You can click the **{}** button to switch to advanced view and see the changes. + +Click **Save**. + +{{}} + +{{% /tab %}} +{{% tab name="JSON" %}} + +You can modify fragment fields in your machine's raw JSON config by using [update operators](https://www.mongodb.com/docs/manual/reference/operator/update/positional/#---update-). +Viam supports all update operators except for `$setOnInsert`, `$`, `$[]`, and `$[]`. + +To configure fragment overwrites manually instead of using the builder UI: + +1. Navigate to your machine's **CONFIGURE** tab. +2. Switch to **JSON** mode. +3. Add a top-level section called `"fragment_mods"` (alongside the other top-level sections like `"components"` and `"fragments"`): + +{{< tabs >}} +{{% tab name="Template" %}} + +```json {class="line-numbers linkable-line-numbers"} + "fragment_mods": [ + { + "fragment_id": "", + "mods": [ + { + + } + ] + } + ], +``` + +{{% /tab %}} +{{% tab name="Full example" %}} +This example assumes the fragment with ID `abcd7ef8-fa88-1234-b9a1-123z987e55aa` contains a motor configured with `"name": "motor1"`. + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [], + "fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "components.motor1.attributes.max_rpm": 1818, + "components.motor1.attributes.pins.a": 30, + "components.motor1.attributes.board": "local" + } + }, + { + "$unset": { + "components.motor1.attributes.pins.pwm": 0 + } + } + ] + } + ], + "fragments": ["abcd7ef8-fa88-1234-b9a1-123z987e55aa"] +} +``` + +{{% /tab %}} +{{< /tabs >}} + +4. Edit the `fragment_id` value to match the ID of the fragment you want to modify, for example `"12345678-1a2b-9b8a-abcd987654321"`. +5. Add any update operators you'd like to apply to the fragment to the `mods` section. + Click to view each example: + +{{< expand "Change the name and attributes of a component" >}} +This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to make the following changes to the attributes of a motor named `motor1`: + +- Sets the `max_rpm` to `1818`. +- Changes the name of `motor1` to `my_motor`. + Note that this does not affect the other mods; you still use `motor1` for them. +- Sets the pin number for pin `a` to `30`. +- Sets the name of the board associated with this motor to `local`. + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "components.motor1.attributes.max_rpm": 1818, + "components.motor1.name": "my_motor", + "components.motor1.attributes.pins.a": 30, + "components.motor1.attributes.board": "local" + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Remove an attribute" >}} +This example uses [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/update/unset/#mongodb-update-up.-unset) to remove the pin number set for the `pwm` pin, so the motor no longer has a PWM pin set. +In other words, it deletes the `pwm` pin field. + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$unset": { + "components.motor1.attributes.pins.pwm": 0 + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Modify dependencies" >}} +This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to assign a new list of dependencies to a component named `rover_base2`. + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "components.rover_base2.attributes.depends_on": ["local", "motor1"] + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Change motor pins from A and B to PWM and DIR" >}} +This example uses [`$rename`](https://www.mongodb.com/docs/manual/reference/operator/update/rename/) to make the following changes to the attributes of a motor named `motor1` in the fragment: + +- Retrieves the pin number for pin `a` and assigns that value to the PWM pin. + Deletes the `pins.a` field. +- Retrieves the pin number for pin `b` and assigns that value to the DIR pin. + Deletes the `pins.b` field. + +_`$rename` is for changing an attribute's key, not its value. +If you want to change the `name` of a component (for example, `motor1`), use `$set`, as shown in the change the name of a component example._ + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$rename": { + "components.motor1.attributes.pins.a": "components.motor1.attributes.pins.pwm", + "components.motor1.attributes.pins.b": "components.motor1.attributes.pins.dir" + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Change a camera path" >}} +This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to change the video path for a camera named `camera-one` in the fragment: + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "components.camera-one.attributes.video_path": "0x11100004a12345" + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Modify data sync settings" >}} +This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to change the sync interval for a [data management service](/services/data/) named `data-management` in the fragment: + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "services.data-management.attributes.sync_interval_mins": "0.5" + } + } + ] + } +], +``` + +{{< /expand >}} +{{< expand "Pin a module version" >}} +This example uses [`$set`](https://www.mongodb.com/docs/manual/reference/operator/update/set/#mongodb-update-up.-set) to set [version update settings for a module](/registry/modular-resources/#configuration) named `custom-sensor` in the fragment: + +```json {class="line-numbers linkable-line-numbers"} +"fragment_mods": [ + { + "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa", + "mods": [ + { + "$set": { + "modules.custom-sensor.version": "1.8.0" + } + } + ] + } +], +``` + +Here are the version options: + +- To update with new minor releases of the same major release branch, use `"^"`, for example `"^1"` +- To update with new patch releases of the same minor release branch, use `"~"`, for example `"~1.8"` +- To always update with the latest release, use `"latest"` +- To pin to a specific release, use `""`, for example `"1.8.3"` + +{{< /expand >}} + +6. Click **Save** in the upper right corner of the page to save your new configuration. +7. To check that your mods are working, view your machine's debug configuration. + In **Builder** mode on the **CONFIGURE** tab, select the **...** (Actions) menu to the right of your main part's name in the left-hand panel and click the **View debug configuration** option to view the full configuration file. + +{{% /tab %}} +{{< /tabs >}} + +{{% alert title="Support Notice" color="note" %}} + +Fragment overwrites are currently _not_ supported for modifying [triggers](/configure/triggers/). + +{{% /alert %}} + +{{% /tablestep %}} +{{% tablestep %}} +**2. Check your machine's logs** + +After configuring fragment overwrites, check your machine's [**LOGS** tab](/cloud/machines/#logs). + +If there are problems with overwrites to the fragment, the overwrites will not be partially applied and the configuration changes will not take effect until the configuration is fixed. + +{{% /tablestep %}} +{{% tablestep %}} +{{}} +**3. (Optional) Revert fragment modifications** + +If you need to restore the original fragment, click the **...** in the upper right corner of the card you modified, and click **Revert changes**. +Now, the fragment will be identical to the upstream fragment. + +{{% /tablestep %}} +{{< /table >}} + +## Update a fragment + +You and your collaborators can edit a fragment at any time. + +If you've already deployed the fragment to one or more machines, the Viam app updates the configuration on each deployed machine that uses that fragment. +You can see the number of machines using your fragment from the [fragments page](https://app.viam.com/fragments) in the Viam app. + +{{< alert title="Test updates first" color="caution" >}} +Be cautious when making changes to fragments that have been deployed to production machines. + +We recommend that you create a duplicate fragment, make your desired change to that second fragment, and then deploy that fragment to one or more test machines that are configured identically to your production machines. + +Once you are confident that your configuration change works as expected, you can safely make the same change to the fragment in use on your production fleet, and the Viam app will deploy that change to all machines using that fragment. +{{< /alert >}} + +## Example fragments + +For an example of a fragment that configures multiple components and services, see the [Viam Rover fragment](https://app.viam.com/fragment?id=3e8e0e1c-f515-4eac-8307-b6c9de7cfb84). + +For an example of creating a fragment and using it to configure a fleet of machines, see the [air quality fleet tutorial](/tutorials/control/air-quality-fleet/). diff --git a/docs/manage/fleet/setup.md b/docs/manage/fleet/setup.md new file mode 100644 index 0000000000..020eb1e11e --- /dev/null +++ b/docs/manage/fleet/setup.md @@ -0,0 +1,20 @@ +--- +linkTitle: "Configure system settings" +title: "Configure machine operating system settings" +weight: 20 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- + +{{< alert title="Note" color="note" >}} +Does this belong here or in Build & integrate? +{{< /alert >}} + + +## Configure operating system settings + +agent-syscfg + +## Configure networks diff --git a/docs/manage/software/_index.md b/docs/manage/software/_index.md new file mode 100644 index 0000000000..baedc2b35b --- /dev/null +++ b/docs/manage/software/_index.md @@ -0,0 +1,10 @@ +--- +linkTitle: "Deploy software" +weight: 20 +layout: "empty" +type: "docs" +empty_node: true +open_on_desktop: true +header_only: true +empty_node: true +--- diff --git a/docs/manage/deploy/ota.md b/docs/manage/software/deploy-packages.md similarity index 80% rename from docs/manage/deploy/ota.md rename to docs/manage/software/deploy-packages.md index 30576c4060..d7ad398657 100644 --- a/docs/manage/deploy/ota.md +++ b/docs/manage/software/deploy-packages.md @@ -1,13 +1,12 @@ --- linkTitle: "Deploy packages" title: "Deploy software packages to machines (OTA)" -weight: 10 +weight: 30 layout: "docs" type: "docs" no_list: true -description: "TODO" images: ["/registry/module-puzzle-piece.svg"] -description: "You can use a fragment to deploy software packages to many machines, as well as to keep those software packages versioned." +description: You can use a fragment to deploy software packages and ML models to many machines, as well as to update deployed versions of those software packages and ML models." languages: [] viamresources: [] platformarea: ["registry", "fleet"] @@ -18,7 +17,11 @@ cost: "0" --- Viam has a built-in tool called _{{< glossary_tooltip term_id="fragment" text="fragments" >}}_ for using the same configuration on multiple machines. -You can use a fragment to deploy software packages to many machines, as well as to keep those software packages versioned. +You can use a fragment to deploy software packages and ML models to many machines, as well as to update deployed versions of those software packages and ML models. + +For example, you can configure a fragment with one resource, like a speech detection service. +Add the fragment to all machines that need the speech detection service. +As you improve the speech detection service, you can specify the version to deploy and all machines will reconfigure themselves to use the version specified in the update. ## Create a fragment @@ -29,7 +32,7 @@ You can use a fragment to deploy software packages to many machines, as well as Start by adding a new machine in the [Viam app](https://app.viam.com). You do not need to follow the setup instructions. -Use the **CONFIGURE** tab to add the component or service you want to deploy across your machines. +Use the **CONFIGURE** tab to add the resource you want to deploy to your machines. {{}} @@ -75,11 +78,7 @@ We only created this machine to easily generate the JSON config for the fragment ## Add the fragment to multiple machines -With your fragment created, you can add it to as many machines as you'd like: - -{{< alert title="Tip" color="tip" >}} -You can add multiple fragments to one machine. -{{< /alert >}} +With your fragment created, add it to all machines that need it: {{< table >}} {{% tablestep %}} @@ -91,6 +90,10 @@ Search for your fragment and add it. Click **Save** in the upper right corner of the screen. +{{< alert title="Tip" color="tip" >}} +You can add multiple fragments to one machine. +{{< /alert >}} + {{% /tablestep %}} {{% tablestep %}} {{}} diff --git a/docs/manage/deploy/update.md b/docs/manage/software/update-packages.md similarity index 89% rename from docs/manage/deploy/update.md rename to docs/manage/software/update-packages.md index 84a1c06fad..73136f6e7d 100644 --- a/docs/manage/deploy/update.md +++ b/docs/manage/software/update-packages.md @@ -1,25 +1,26 @@ --- linkTitle: "Update packages" title: "Update packages" -weight: 10 +weight: 40 layout: "docs" type: "docs" no_list: true -description: "TODO" +description: "As new versions of software modules or ML models become available, you can update the deployed version on all machines in one go." --- -## Testing Strategies +If you have already [deployed a package](/manage/deploy/deploy-package/), you can inspect fragment you have created. +The JSON object for the deployed package has a `version` field. -If you inspect the fragment you have created, you will notice it contains a `version` field. +As new versions of software modules or ML models become available, you can update the deployed version in one go using the fragment. -As you develop new versions of your software, your machines will continue to use the version of the software that you have configured in the fragment. +We strongly recommend that you test updates on a subset of machines before deploying it to all machines. -We generally recommend that you test updates on a subset of machines before deploying it to all machines. +## Test updates -You can either create a second fragment that you add to a subset of machines, or manually overwrite the version of the package for a subset of machines: +You can either create a second fragment that you add to a subset of machines, or manually overwrite the version of the package for a subset of machines. {{< tabs >}} -{{< tab name="A second fragment" >}} +{{< tab name="A second fragment (recommended)" >}} {{< table >}} {{% tablestep %}} @@ -136,6 +137,8 @@ Don't forget to **Save**. All machines configured with your fragment will update when they next check for configuration updates. +## Check machine status + To check when your machines have last updated their configuration, iterate over your machines using the Fleet Management API, connect to each machine, and use the [`GetMachineStatus` method](/appendix/apis/robot/#getmachinestatus). The following example script iterates over all machines in a given location and if it can connect to the machines, it prints their status information.