Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history 
Co-authored-by: Sierra Guequierre <[email protected]>
Co-authored-by: James Otting <[email protected]>
  • Loading branch information
@npentrel @sguequierre @Otterverse
3 people committed Aug 16, 2024
1 parent 2e13244 commit e3cb5d4
Show file tree
Hide file tree
Showing 5 changed files with 85 additions and 86 deletions.
Binary file added assets/configure/machine-part-info.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
98 changes: 53 additions & 45 deletions docs/configure/agent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,8 @@ description: "The viam-agent is a self-updating service manager that maintains t
# SMEs: James, Ale
---

The [`viam-agent`](https://github.com/viamrobotics/agent) is a self-updating service manager that maintains the lifecycle for the following system services:
The [`viam-agent`](https://github.com/viamrobotics/agent) is a self-updating service manager that maintains the lifecycle for itself and the following system services:

- `viam-agent`: the main agent program itself
- `viam-server`: the core of the machine
- [`agent-provisioning`](/fleet/provision/): device provisioning subsystem that can set up WiFi and machine configs.
- [`agent-syscfg`](https://github.com/viamrobotics/agent-syscfg): provides various operating system and system configuration tweaks
Expand All @@ -37,7 +36,6 @@ To provision machines using `viam-agent`, see
You can install `viam-agent` using either an existing machine's part ID and API key, or using an existing <file>/etc/viam.json</file> configuration file.

{{< alert title="Important" color="note" >}}
`viam-agent` supports the Linux `x86_64` and `aarch64` architectures only.
Your machine must have `curl` available in order to install `viam-agent`.
{{< /alert >}}

Expand Down Expand Up @@ -89,7 +87,6 @@ For information on managing the service, see [Manage `viam-agent`](/installation
"release_channel": "stable",
"pin_version": "",
"pin_url": "",
"disable_subsystem": false
},
"viam-server": {
"release_channel": "stable",
Expand Down Expand Up @@ -124,38 +121,43 @@ For information on managing the service, see [Manage `viam-agent`](/installation
{
"agent": {
"viam-agent": {
"release_channel": "stable",
"pin_version": "1.2.3",
"pin_url": "http://example/test.binary",
"disable_subsystem": false
},
"viam-server": {
"attributes": {
"fast_start": true
}
},
"agent-provisioning": {
"release_channel": "stable",
"networks": [
{
"type": "wifi",
"ssid": "fallbackNetOne",
"psk": "myFirstPassword",
"priority": 30
},
{
"type": "wifi",
"ssid": "fallbackNetTwo",
"psk": "mySecondPassword",
"priority": 10
}
],
"attributes": {
"hotspot_password": "acme123"
"hotspot_password": "acme123",
"networks": [
{
"type": "wifi",
"ssid": "fallbackNetOne",
"psk": "myFirstPassword",
"priority": 30
},
{
"type": "wifi",
"ssid": "fallbackNetTwo",
"psk": "mySecondPassword",
"priority": 10
}
],
}
},
"agent-syscfg": {
"release_channel": "stable"
"attributes": {
"logging": {
"disable": true,
"system_max_use": "128M",
"runtime_max_use": "96M"
},
"upgrades": {
"type": "all"
}
}
}
}
}
Expand All @@ -171,20 +173,19 @@ Each section primarily controls updates for that subsystem:
<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"??"`. |
| `pin_version` | string | Optional | "Lock" the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | "Lock" the subsystem to a specific binary. If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `disable_subsystem` | boolean | Optional | When set to `true` it disables `viam-agent` subsystem. |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default). |
| `pin_version` | string | Optional | Lock the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |

### `viam-server`

<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `attributes` | object | Optional | <ul><li>`fast_start`: If set to `true`, `viam-agent` will not wait a network connection and check for updates before starting `viam-server`. See [Fast start mode](#fast-start-mode).</li></ul> |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"??"`. |
| `attributes` | object | Optional | <ul><li>`fast_start`: If set to `true`, `viam-agent` will not wait for a network connection nor check for updates before starting `viam-server`. See [Fast start mode](#fast-start-mode).</li></ul> |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"latest"`. |
| `pin_version` | string | Optional | "Lock" the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | "Lock" the subsystem to a specific binary. If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `disable_subsystem` | boolean | Optional | When set to `true` it disables the `viam-server` subsystem. |

#### Fast start mode
Expand All @@ -206,11 +207,10 @@ You can also start `viam-agent` in fast start mode by setting `VIAM_AGENT_FAST_S
<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `networks` | array | Optional | Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks]. |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li></ul> |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"??"`. |
| `pin_version` | string | Optional | "Lock" the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | "Lock" the subsystem to a specific binary. If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks].</li><li>`roaming_mode`: TODO.</li></ul> |
| `release_channel` | string | Optional | `agent-provisioning` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"latest"`. |
| `pin_version` | string | Optional | Lock the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `disable_subsystem` | boolean | Optional | When set to `true` it disables the `agent-provisioning` subsystem. |

#### Networks
Expand All @@ -227,7 +227,7 @@ Additionally, the end user must either **not** provide a primary network or ther
`agent-provisioning` will enter roaming mode only when `roaming_mode` is enabled and no connection can be established to a primary network.
{{< /alert >}}

If configured, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest.
If configured (and roaming_mode is enabled), `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest.
If the highest-priority network is not available or the machine can connect but internet is not available, `viam-agent` will then attempt to connect to the next-highest network, and so on until all configured networks have been tried.
If the machine cannot connect to any network that has internet, it will then enter hotspot mode.
For more information see [Provisioning](/fleet/provision/#how-an-end-user-would-use-it).
Expand All @@ -238,7 +238,7 @@ For more information see [Provisioning](/fleet/provision/#how-an-end-user-would-
| `type` | string | The type of the network. Options: `"wifi"`|
| `ssid` | string | The network's SSID. |
| `psk` | string | The network pass key. |
| `priority` | int | Priority to choose the network with. Values between -999 and 100. Default: `0`. |
| `priority` | int | Priority to choose the network with. Values between -999 and 999. Default: `0`. |

The following configuration defines the connection information and credentials for two WiFi networks named `fallbackNetOne` and `fallbackNetTwo`:

Expand All @@ -249,6 +249,7 @@ The following configuration defines the connection information and credentials f
...
"attributes": {
...
"roaming_mode": true,
"networks": [
{
"type": "wifi",
Expand All @@ -273,22 +274,29 @@ The following configuration defines the connection information and credentials f
<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `release_channel` | string | Optional | `viam-agent` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"??"`. |
| `attributes` | object | Optional | <ul><li>`logging`: parameters for logging<ul>`disable`: when set to `true`, removes any prior tweaks to the logging config and disables the use of defaults??.<li>`system_max_use`: sets the maximum disk space journald will user for persistent log storage. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`runtime_max_use`: sets the runtime/temporary limit. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li></ul></li><li>`upgrades`: Using `upgrades` installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in <FILE>/etc/apt/apt.conf.d/</FILE>, with the latter's Origins-Pattern list being generated automatically from configured repositories on the system, so custom repos (at the time the setting is enabled) will be included.<ul><li>`type`: Configured unattended upgrades for Debian bullseye and bookworm. Options: `""` (no effect), `"disable"` (disables automatic upgrades), `"security"` (only enables updates from sources with security in their codename, ex: bookworm-security), `"all"` (enable updates from all configured sources).</li></ul></li></ul> |
| `release_channel` | string | Optional | `agent-syscfg` is semantically versioned and is tested before release. Releases happen infrequently. When set to `"stable"`, `viam-agent` will automatically upgrade when a new version is released. Options: `"stable"` (default), `"latest"`. |
| `pin_version` | string | Optional | "Lock" the subsystem to a specific version (as provided by the release channel). If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | "Lock" the subsystem to a specific binary. If set, no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `pin_url` | string | Optional | Ignore normal version selection and directly download from the specified URL. If set, no automatic upgrades will be performed until the setting is updated to a new URL (or removed to revert to the release channel). Typically this is only used for testing/troubleshooting. If both `pin_url` and `pin_version` is set, `pin_url` will be used. Default: `""`. |
| `disable_subsystem` | boolean | Optional | When set to `true` it disables the `agent-syscfg` subsystem. |

## Version management for `viam-agent` and `viam-server`

`viam-agent` automatically updates both itself and `viam-server` as new updates are released.
`viam-agent` automatically updates both itself, its subsystems, and `viam-server` as new updates are released.
You can configure update behavior for the Agent and `viam-server` using the [Viam app](https://app.viam.com/).

To use a specific version of `viam-agent` and `viam-server`, you can pin the version.

{{< alert title="Important" color="note" >}}
When `viam-agent` updates either itself or `viam-server`, you must [restart these system services](/installation/manage-viam-agent/) in order to use the new version.
When `viam-agent` updates itself, you must [restart `viam-agent`](/installation/manage-viam-agent/) or reboot in order to use the new version.
When you stop or restart `viam-agent`, the agent will stop or restart `viam-server` as well.
{{< /alert >}}

To use a specific version of `viam-agent` and `viam-server`, you can pin the version.
When `viam-server` updates itself, you must restart `viam-server` in order to use the new version.
You can restart `viam-server` from the machine's part status dropdown to the right of your machine’s name on its page in the Viam app.

{{<imgproc src="configure/machine-part-info.png" resize="500x" declaredimensions=true alt="Restart button on the machine part info dropdown">}}

{{< /alert >}}

For more information on managing `viam-agent` see:

Expand All @@ -308,7 +316,7 @@ These log messages include when `viam-server` is stopped and started, the status

## Next Steps

To see how to provision machines using `viam-agent`, see
To see how to provision machines using `viam-agent`, see:

{{< cards >}}
{{% card link="/fleet/provision/" %}}
Expand Down
Loading

0 comments on commit e3cb5d4

Please sign in to comment.