Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release Policy: Update docs and screenshots #2679

Merged
merged 1 commit into from
Apr 24, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 29 additions & 18 deletions pages/learn/deploy/release-strategy/release-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,45 +7,56 @@ excerpt: Manage the fleet and device release policy

When managing a fleet, you may require devices to be running different releases. By default, fleets follow a rolling release policy where new releases are deployed to all devices in the fleet once successfully built. However, you can customize this behavior, so the fleet or individual devices remain on a fixed release, by utilizing release pinning.

You may define the fleet and device release policies via the [{{ $names.cloud.lower }} dashboard]({{ $links.dashboardUrl }}) or programmatically through the [API][api] or [SDKs][sdk].

__Note:__ It is currently not possible to specify the fleet or device release policy via the {{ $names.cli.lower }}.
You may define the fleet and device release policies via the [{{ $names.cloud.lower }} dashboard]({{ $links.dashboardUrl }}) or programmatically through the [API][api], [SDKs][sdk], or [CLI][cli].

## Pin fleet to a release

In the fleets dashboard, there is a _Release policy_ header. By default, this policy is set to `track latest`, which means that new releases are immediately deployed to all devices in the fleet when built. Expanding this _Release policy_ dropdown menu displays all releases for the fleet, and you can select a specific release to pin the fleet to. When the fleet is pinned, all devices are updated to run the pinned release, and in the future, releases will not be deployed until the _Release policy_ is updated to a newer release or set to `track latest`.
By default, the setting is set to `track latest`, which means that new releases are immediately deployed to all devices in the fleet when built. When the fleet is pinned, all devices that are not currently pinned to a release are updated to run the pinned release, and in the future, releases will not be deployed until the pinned release is updated to a different release or set to `track latest`.

You can set the release the fleet is pinned to via the Releases card on the on the Fleet Summary page.

<img src="/img/common/release-policy/releases_card_dropdown.png" width="100%" alt="Pin fleet to release from Releases card">

This can also be achieved using the `Pin to release` setting on the Fleet settings page.

<img src="/img/common/release-policy/pin_to_release_setting.png" width="100%" alt="Pin fleet to release setting">

The dropdown menu at each of the above locations displays all successful and valid releases for the fleet.

<img src="/img/common/release-policy/mNCaLF8.gif" width="100%" alt="Pin fleet to release">
You can also pin a fleet to a release via the CLI as follows:
vipulgupta2048 marked this conversation as resolved.
Show resolved Hide resolved
- Pin to a specific release: `balena fleet pin <FLEET_SLUG> <RELEASE_COMMIT>`
- Track latest: `balena fleet track-latest <FLEET_SLUG>`

## Pin device to a release

As well as pinning a fleet to a specific release, you may pin individual devices to a specific release. By default, all devices track the fleet release. However, you may wish to run a different release on select devices, for example, a development device or when performing a [canary deployment][canary].
By default, all devices track the fleet release. However, you may wish to run a different release on select devices, for example, a development device or when performing a [canary deployment][canary].

To do so, from the Device dashboard, select the device menu and choose _Pin to release_.
There are several ways to achieve this from the Device dashboard. The dropdown options are identical to the ones when trying to pin the fleet to a release:

<img src="/img/common/release-policy/obsIjdo.png" width="80%" alt="Pin device to release">
- On the Devices page, you can select one or more devices using the checkboxes present on the table. Next, open the `Modify` menu and select the `Pin to release` option.

Selecting _Pin to release_ opens a modal window displaying a list of all successful releases from which you can select a specific release to pin the device to.
<img src="/img/common/release-policy/devices_table_modify.png" width="100%">

<img src="/img/common/release-policy/T3Jy5l1.png" width="60%" alt="Pin to a specific device">
- Alternatively, on hovering over the `Target release` property in the Device summary page, you will see a pencil icon appear. This can be used to pin the release as well.

Once the device has updated, it is shown to be on a _Pinned_ release policy on the fleet dashboard rather than following the release policy of the fleet.
<img src="/img/common/release-policy/devices_target_release_pencil.png" width="100%">

<img src="/img/common/release-policy/SCESUYd.png" width="100%" alt="Device release policy">
- Lastly, the Settings page of a device also has the option to pin the release.

You can also pin multiple devices to a target release in the fleet dashboard by selecting them and choosing the _Pin to release_ option from the _Actions_ menu. Again this action opens a modal window allowing you to choose a specific release to pin the devices to.
<img src="/img/common/release-policy/device_settings.png" width="100%">

<img src="/img/common/release-policy/HKAHHmS.png" width="80%" alt="Pin multiple devices">
Once the device has been pinned to a release and updated, its `Target release` column updates to the pinned release. It will show a pin, rather than just showing the release targetted by the fleet. The `Release policy` column also updates to say `Pinned`.

Using [device tags][device-tags], you can quickly select a group of devices and pin them all to a specific release by [filtering by the device tag][device-filters] and choosing _Pin to release_ from the _Actions_ menu.
<img src="/img/common/release-policy/target_release_pin.png" width="100%" alt="Device release policy">

<img src="/img/common/release-policy/rdKoNe9.png" width="80%" alt="Using tags to pin multiple devices">
You can also pin a device to a release via the CLI as follows:
- Pin to a specific release: `balena device pin <DEVICE_UUID> <RELEASE_COMMIT>`
- Track latest: `balena device track-fleet <DEVICE_UUID>`

__Note:__ For more details about using the API to manage the release policy see the [Fleet Management Masterclass][masterclass].

[masterclass]:/learn/more/masterclasses/fleet-management/#6-release-policy
[canary]:/learn/welcome/production-plan/#canary-deployments
[api]:/reference/api/overview/
[sdk]:/reference/sdk/node-sdk/
[device-tags]:/learn/manage/filters-tags/#device-tags
[device-filters]:/learn/manage/filters-tags/#device-filters
[cli]:/reference/balena-cli/
Binary file removed static/img/common/release-policy/HKAHHmS.png
Binary file not shown.
Binary file removed static/img/common/release-policy/SCESUYd.png
Binary file not shown.
Binary file removed static/img/common/release-policy/T3Jy5l1.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed static/img/common/release-policy/mNCaLF8.gif
Binary file not shown.
Binary file removed static/img/common/release-policy/obsIjdo.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed static/img/common/release-policy/rdKoNe9.png
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.