Kickoff documentation for Orbit Release Process (#5544)

* Kickoff documentation for Orbit releasing * Fixes to the github action * Missing follow redirect on curl * Run osqueryd --version to verify before uploading artifacts * Use cmd as shell for windows-latest runner * Final set of changes to the guide
2026-04-21 13:37:30 +00:00 · 2022-05-13 07:15:29 -03:00 · 2022-05-13 07:15:29 -03:00 · 74dfdcb882
commit 74dfdcb882
parent 961f0ffc10
7 changed files with 377 additions and 41 deletions
--- a/.github/workflows/generate-desktop-targets.yml
+++ b/.github/workflows/generate-desktop-targets.yml
@ -7,6 +7,10 @@ on:
    paths:
      # The workflow can be triggered by modifying FLEET_DESKTOP_VERSION env.
      - '.github/workflows/generate-desktop-targets.yml'
+  pull_request:
+    paths:
+      # The workflow can be triggered by modifying FLEET_DESKTOP_VERSION env.
+      - '.github/workflows/generate-desktop-targets.yml'
  workflow_dispatch:

 env:
--- a/.github/workflows/generate-osqueryd-app-tar-gz.yml
+++ b/.github/workflows/generate-osqueryd-app-tar-gz.yml
@ -1,37 +0,0 @@
-name: Generate osqueryd.app.tar.gz for Orbit
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      # The workflow can be triggered by modifying OSQUERY_VERSION env.
-      - '.github/workflows/generate-osqueryd-app-tar-gz.yml'
-  pull_request:
-    paths:
-      # The workflow can be triggered by modifying OSQUERY_VERSION env.
-      - '.github/workflows/generate-osqueryd-app-tar-gz.yml'
-  workflow_dispatch:
-
-env:
-  OSQUERY_VERSION: 5.2.3
-
-permissions:
-  contents: read
-
-jobs:
-  generate:
-    runs-on: macos-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
-
-      - name: Generate osqueryd.app.tar.gz
-        run: |
-          make osqueryd-app-tar-gz out-path=. version=$OSQUERY_VERSION
-
-      - name: Upload osqueryd.app.tar.gz
-        uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # v2
-        with:
-          name: osqueryd.app.tar.gz
-          path: osqueryd.app.tar.gz
--- a/.github/workflows/generate-osqueryd-targets.yml
+++ b/.github/workflows/generate-osqueryd-targets.yml
@ -0,0 +1,79 @@
+name: Generate osqueryd targets for Orbit
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # The workflow can be triggered by modifying OSQUERY_VERSION env.
+      - '.github/workflows/generate-osqueryd-targets.yml'
+  pull_request:
+    paths:
+      # The workflow can be triggered by modifying OSQUERY_VERSION env.
+      - '.github/workflows/generate-osqueryd-targets.yml'
+  workflow_dispatch:
+
+env:
+  OSQUERY_VERSION: 5.2.3
+
+permissions:
+  contents: read
+
+jobs:
+  generate-macos:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
+
+      - name: Generate osqueryd.app.tar.gz
+        run: |
+          make osqueryd-app-tar-gz out-path=. version=$OSQUERY_VERSION
+
+      - name: Upload osqueryd.app.tar.gz
+        uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # v2
+        with:
+          name: osqueryd.app.tar.gz
+          path: osqueryd.app.tar.gz
+
+  generate-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
+
+      - name: Download and extract osqueryd for linux
+        run: |
+          curl -L https://pkg.osquery.io/linux/osquery-${{ env.OSQUERY_VERSION }}_1.linux_x86_64.tar.gz --output osquery-${{ env.OSQUERY_VERSION }}_1.linux_x86_64.tar.gz
+          tar xf osquery-${{ env.OSQUERY_VERSION }}_1.linux_x86_64.tar.gz
+          chmod +x ./opt/osquery/bin/osqueryd
+          ./opt/osquery/bin/osqueryd --version
+
+      - name: Upload osqueryd for linux
+        uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # v2
+        with:
+          name: osqueryd
+          path: opt/osquery/bin/osqueryd
+
+  generate-windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
+
+      - name: Download osquery msi for Windows
+        shell: bash
+        run: |
+          curl -L https://pkg.osquery.io/windows/osquery-${{ env.OSQUERY_VERSION }}.msi --output osquery-${{ env.OSQUERY_VERSION }}.msi
+
+      - name: Extract osqueryd.exe for Windows
+        shell: cmd
+        run: |
+          msiexec /a osquery-${{ env.OSQUERY_VERSION }}.msi /qb TARGETDIR=C:\temp
+          C:\temp\osquery\osqueryd\osqueryd.exe --version
+
+      - name: Upload osqueryd for Windows
+        uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # v2
+        with:
+          name: osqueryd.exe
+          path: C:\temp\osquery\osqueryd\osqueryd.exe
--- a/.gitignore
+++ b/.gitignore
@ -57,9 +57,10 @@ package-lock.json
 .terraform.lock*
 terraform.tfstate*

-# generated installers
+# generated orbit installers and artifacts
 fleet-osquery*
 desktop.app.tar.gz
+osqueryd.app.tar.gz
 desktop.tar.gz

 # residual files when running the cpe command
--- a/3
+++ b/3
@ -284,7 +284,7 @@ db-backup:
 db-restore:
 	./tools/backup_db/restore.sh

-# Generate osqueryd.tar.gz bundle from osquery.io.
+# Generate osqueryd.app.tar.gz bundle from osquery.io.
 #
 # Usage:
 # make osqueryd-app-tar-gz version=5.1.0 out-path=.
@ -299,6 +299,7 @@ endif
 	rm -rf $(TMP_DIR)/osquery_pkg_payload_expanded
 	mkdir -p $(TMP_DIR)/osquery_pkg_payload_expanded
 	tar xf $(TMP_DIR)/osquery_pkg_expanded/Payload --directory $(TMP_DIR)/osquery_pkg_payload_expanded
+	$(TMP_DIR)/osquery_pkg_payload_expanded/opt/osquery/lib/osquery.app/Contents/MacOS/osqueryd --version
 	tar czf $(out-path)/osqueryd.app.tar.gz -C $(TMP_DIR)/osquery_pkg_payload_expanded/opt/osquery/lib osquery.app
 	rm -r $(TMP_DIR)

--- a/orbit/README.md
+++ b/orbit/README.md
@ -4,7 +4,12 @@

 Orbit is an [osquery](https://github.com/osquery/osquery) runtime and autoupdater. With Orbit, it's easy to deploy osquery, manage configurations, and stay up to date. Orbit eases the deployment of osquery connected with a [Fleet server](https://github.com/fleetdm/fleet), and is a (near) drop-in replacement for osquery in a variety of deployment scenarios.

-Orbit is the recommended agent for Fleet. But Orbit can be used with or without Fleet, and Fleet can be used with or without Orbit.
+Orbit is the recommended agent for Fleet. But Orbit can be used with or without Fleet, and Fleet can
+be used with or without Orbit.
+
+# Documentation
+
+- [Releasing Orbit](docs/Releasing-Orbit.md)

 ## Try Orbit

@ -232,7 +237,16 @@ Use the "Add or remove programs" dialog to remove Orbit.

 #### Linux

-Run the [cleanup script](./tools/cleanup/cleanup_linux.sh).
+Uninstall the package with the corresponding package manager:
+
+- Ubuntu
+```sh
+sudo apt remove fleet-osquery -y
+```
+- CentOS
+```sh
+sudo rpm -e fleet-osquery-X.Y.Z.x86_64
+```

 #### macOS

--- a/orbit/docs/Releasing-Orbit.md
+++ b/orbit/docs/Releasing-Orbit.md
@ -0,0 +1,274 @@
+# Releasing Orbit
+
+What we call "Orbit" is actually a group of components:
+1. Orbit executable: Orbit is the director of the orchestra. It manages itself all the other components.
+2. Osquery executable/bundle.
+3. "Fleet Desktop" application: Renders Fleet's tray icon on the user desktop session and provides transparency to the end-user about what Fleet collects from the device.
+
+# Auto-update
+
+Orbit runs an auto-updater routine that polls a [TUF](https://theupdateframework.io/) server for new
+updates in any of the three
+components mentioned above. Each component (also known as "target") can be updated independently. This document aims to
+describe all the steps needed to release a new version of each target.
+
+## Methodolody
+
+Our TUF server provides two channels, `edge` and `stable`.
+- `stable` is what all users in production use.
+- `edge` is used to verify updates before releasing to `stable`.
+
+At a high level, the following steps are used to release updates:
+
+1. The new update/s are first pushed to the `edge` channel.
+2. Smoke testing is used to verify the updates are working as expected.
+3. The new update/s are then pushed to the `stable` channel.
+4. Same as (2), smoke testing is used to verify the updates are working as expected.
+
+# Actors
+
+In all the steps described herein, there are two actors:
+- Team member "Updater" pushing the updates. This actor requires:
+    1. Authorized signing keys for pushing new updates on the TUF repository.
+    2. Write access to the TUF server (to update https://tuf.fleetctl.com).
+    3. Write privileges to the [fleet](https://github.com/fleetdm/fleet) repository to create pull
+       requests and trigger Github Actions.
+- Team member "Verifier" verifying/testing the pushed updates.
+
+The majority of the steps are run by the "Updater" team member, unless stated otherwise.
+
+# Updating Orbit
+
+## 1. Edge Release
+
+### Setup
+
+The Verifier will setup a CentOS, Ubuntu, Windows and macOS hosts with Orbit running from the `edge` channel:
+```sh
+fleetctl package --type=pkg --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --orbit-channel edge
+fleetctl package --type=msi --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --orbit-channel edge
+fleetctl package --type=deb --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --orbit-channel edge
+fleetctl package --type=rpm --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --orbit-channel edge
+```
+
+> NOTE: The fleetctl version to use should be the latest released version, installed via `sudo npm install -g fleetctl`.
+
+### Steps
+
+Assuming version `vX.Y.Z` is being released.
+
+1. Run `make changelog-orbit` to generate the `orbit/CHANGELOG.md` changes for Orbit.
+2. Edit `orbit/CHANGELOG.md` accordingly.
+3. Checkout a new branch (we generally use `prepare-orbit-vX.Y.Z`), commit the changes and tag the repository:
+```sh
+git checkout -b prepare-orbit-vX.Y.Z
+git add -u
+git commit -m "Prepare changes for Orbit vX.Y.Z"
+git tag orbit-vX.Y.Z
+```
+4. Push the branch and the tag:
+```sh
+git push origin prepare-orbit-vX.Y.Z
+git push origin --tags
+```
+5. After pushing the branch, create a pull request.
+6. The pushed tag will trigger a new build of the following Github Action:
+   [goreleaser-orbit.yaml](https://github.com/fleetdm/fleet/actions/workflows/goreleaser-orbit.yaml).
+7. If the above Github Action ran successfully then a new "DRAFT" release will be created for Orbit
+   vX.Y.Z: https://github.com/fleetdm/fleet/releases.
+8. Download and extract the assets (one for each platform Orbit supports).
+9. Push the downloaded+extracted assets to the `edge` channel on our TUF repository (https://tuf.fleetctl.com/):
+```sh
+# Having extracted the asset for Linux in `./orbit-linux`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target orbit \
+    --platform linux \
+    --name ./orbit-linux \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Linux in `./orbit-darwin`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target orbit \
+    --platform macos \
+    --name ./orbit-darwin \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Windows in `./orbit.exe`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target orbit \
+    --platform windows \
+    --name ./orbit.exe \
+    --version X.Y.Z -t X.Y -t X -t edge
+```
+
+### Verification
+
+Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
+Verifier can run `SELECT * from orbit_info;` live query on the hosts, which will provide the orbit version (confirming the update was successful).
+
+Once orbit has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
+
+## 2. Stable Release
+
+### Setup
+
+Verifier runs the same setup as `edge`, but without setting the `--orbit-channel` flag (the default value is `stable`).
+
+### Steps
+
+Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
+
+### Verification
+
+Verification is the same as with the `edge` case.
+
+# Updating Osquery
+
+## 1. Edge Release
+
+### Setup
+
+The Verifier will setup a CentOS, Ubuntu, Windows and macOS host with `osqueryd` that uses the `edge` channel:
+```sh
+fleetctl package --type=pkg --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --osqueryd-channel edge
+fleetctl package --type=msi --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --osqueryd-channel edge
+fleetctl package --type=deb --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --osqueryd-channel edge
+fleetctl package --type=rpm --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --osqueryd-channel edge
+```
+
+> NOTE: The fleetctl version to use should be the latest released version, installed via `sudo npm install -g fleetctl`.
+
+### Steps
+
+Assuming version `vX.Y.Z` is being released.
+
+1. Checkout a branch and edit the `OSQUERY_VERSION` env variable in `.github/workflows/generate-osqueryd-targets.yml`.
+2. Push and create a pull request.
+3. Once the pull request is created a Github Action will be triggered
+   [generate-osqueryd-targets.yml](https://github.com/fleetdm/fleet/actions/workflows/generate-osqueryd-targets.yml).
+   It generates the osqueryd targets for macOS, Windows and Linux as artifacts.
+4. Download the artifacts from the previous step and push them to the `edge` channel:
+```sh
+# Having extracted the asset for Linux in `./osqueryd`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target osqueryd \
+    --platform linux \
+    --name ./osqueryd \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Linux in `./osqueryd.app.tar.gz`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target osqueryd \
+    --platform macos-app \
+    --name ./osqueryd.app.tar.gz \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Windows in `./osqueryd.exe`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target osqueryd \
+    --platform windows \
+    --name ./osqueryd.exe \
+    --version X.Y.Z -t X.Y -t X -t edge
+```
+
+### Verification
+
+Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
+Verifier can run `SELECT * from osquery_info;` live query on the hosts, which will provide the osquery version (confirming the update was successful).
+
+Once osqueryd has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
+
+## 2. Stable Release
+
+### Setup
+
+Verifier runs the same setup as `edge`, but without setting the `--osqueryd-channel` flag (the default value is `stable`).
+
+### Steps
+
+Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
+
+### Verification
+
+Verification is the same as with the `edge` case.
+
+# Updating Fleet Desktop
+
+## 1. Edge Release
+
+### Setup
+
+The Verifier will setup a CentOS, Ubuntu, Windows and macOS host with `desktop` that uses the `edge` channel:
+```sh
+fleetctl package --type=pkg --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --desktop-channel edge
+fleetctl package --type=msi --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --desktop-channel edge
+fleetctl package --type=deb --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --desktop-channel edge
+fleetctl package --type=rpm --fleet-url=https://fleet.example.com --enroll-secret=<...> --fleet-desktop --desktop-channel edge
+```
+
+> NOTE: The fleetctl version to use should be the latest released version, installed via `sudo npm install -g fleetctl`.
+
+### Steps
+
+Assuming version `vX.Y.Z` is being released.
+
+1. Checkout a branch and edit the `FLEET_DESKTOP_VERSION` env variable in `.github/workflows/generate-desktop-targets.yml`.
+2. Push and create a pull request.
+3. Once the pull request is created a Github Action will be triggered
+   [generate-desktop-targets.yml](https://github.com/fleetdm/fleet/actions/workflows/generate-desktop-targets.yml).
+   It generates the desktop targets for macOS, Windows and Linux as artifacts.
+4. Download the artifacts from the previous step and push them to the `edge` channel:
+```sh
+# Having extracted the asset for Linux in `./desktop.tar.gz`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target desktop \
+    --platform linux \
+    --name ./desktop.tar.gz \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Linux in `./desktop.app.tar.gz`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target desktop \
+    --platform macos \
+    --name ./desktop.app.tar.gz \
+    --version X.Y.Z -t X.Y -t X -t edge
+
+# Having extracted the asset for Windows in `./fleet-desktop.exe`
+fleetctl updates add \
+    --path $STAGING_TUF_PATH_LOCATION \
+    --target desktop \
+    --platform windows \
+    --name ./fleet-desktop.exe \
+    --version X.Y.Z -t X.Y -t X -t edge
+```
+
+### Verification
+
+Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
+
+Currently, there's no direct way to verify the auto-update for the Fleet Desktop application.
+One way to verify is to check for `INF exiting due to successful update` in the Orbit logs.
+
+Once the Fleet Desktop Application has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
+
+## 2. Stable Release
+
+### Setup
+
+Verifier runs the same setup as `edge`, but without setting the `--desktop-channel` flag (the default value is `stable`).
+
+### Steps
+
+Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
+
+### Verification
+
+Verification is the same as with the `edge` case.