diff --git a/cmd/gitops-migrate/README.md b/cmd/gitops-migrate/README.md index 4c51b3c9a7..b843285e8f 100644 --- a/cmd/gitops-migrate/README.md +++ b/cmd/gitops-migrate/README.md @@ -4,13 +4,13 @@ This directory contains the `gitops-migrate` tool, designed leading up to the `4 # 4.74 YAML Changes -The `4.74` release moves GitOps YAML keys: `self_service`, `categories`, `labels_exclude_any`, `labels_include_any` and `setup_experience` from the software files ([example](https://github.com/fleetdm/fleet/blob/c9a02741950f6510f9f1be48a2c19bc524417f70/cmd/fleetctl/gitops-migrate/testdata/mozilla-firefox.yml#L2-L9)) to the team files ([example](https://github.com/fleetdm/fleet/blob/c9a02741950f6510f9f1be48a2c19bc524417f70/it-and-security/teams/workstations.yml#L47-L70)). +The `4.74` release moves GitOps YAML keys: `self_service`, `categories`, `labels_exclude_any`, and `labels_include_any` from the software files ([example](https://github.com/fleetdm/fleet/blob/c9a02741950f6510f9f1be48a2c19bc524417f70/cmd/fleetctl/gitops-migrate/testdata/mozilla-firefox.yml#L2-L9)) to the team files ([example](https://github.com/fleetdm/fleet/blob/c9a02741950f6510f9f1be48a2c19bc524417f70/it-and-security/teams/workstations.yml#L47-L70)). # Installation -## Method 1: Download the Binary (Recommended) +## Download the Binary -Download the appropriate binary for your operating system and architecture: +1. Download the appropriate binary for your operating system and architecture: | Operating System | Architecture | Download Link | | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -21,112 +21,45 @@ Download the appropriate binary for your operating system and architecture: | `linux` | `amd64` | [Download](https://download.fleetdm.com/tools/gitops-migrate-linux-amd64)([Hash](https://download.fleetdm.com/tools/gitops-migrate-linux-amd64.sha256)) | | `linux` | `arm64` | [Download](https://download.fleetdm.com/tools/gitops-migrate-linux-arm64)([Hash](https://download.fleetdm.com/tools/gitops-migrate-linux-arm64.sha256)) | -## Method 2: Go Install +2. Rename the file `gitops-migrate` with no extension. -[Install Go](https://go.dev/doc/install) and install `gitops-migrate` by running: +3. Move the file to the root of your Fleet GitOps directory. For example, the root of our GitOps directory is [/it-and-security](https://github.com/fleetdm/fleet/tree/main/it-and-security). -```shell -$ go install github.com/fleetdm/fleet/v4/cmd/gitops-migrate@latest -``` +4. Open terminal and navigate to your Fleet GitOps directory. -You can verify the installation was successful by running `gitops-migrate usage` which should display the help text. +5. Make the binary file executable. For example, on Linux and macOS use `chmod +x gitops-migrate`. -> [!NOTE] -> If the `go install` is successful but you're not able to run `gitops-migrate`, you may need to add your `GOBIN` directory to `PATH` in the way appropriate for your operating system ([Windows](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/), [Mac](https://medium.com/@B-Treftz/macos-adding-a-directory-to-your-path-fe7f19edd2f7), [Linux](https://pimylifeup.com/ubuntu-add-to-path/)). The path to add can be found by running: `go env GOBIN`. +6. Verify the installation was successful by running `./gitops-migrate usage` which should display the help text. -# Running the Migration +# Running the migration + +When manipulating YAML files with this tool, the output will always alphabetize the keys and remove all comments. The migration will unfold in two primary steps: `format` and `migrate`. -> [!IMPORTANT] -> If your GitOps files are version-controlled (stored in GitHub or similar) it is recommended to perform these steps in order, opening a pull request, moving through your standard review process and merging that pull request **before** moving to the next step. - ## Step 1: Format -### Overview - -When manipulating YAML files with this tool, the output will always alphabetize the keys. This means the following YAML file: -```yaml -a: [] -c: [] -b: [] -``` -Will become: -```yaml -a: [] -b: [] -c: [] -``` - -This _can_ mean, if your GitOps files are version-controlled (stored in GitHub or similar), you could see a very large number of changed lines which might make it more difficult to spot the **actual** transformations. - -Considering the above, we recommend running the `gitops-migrate` `format` command **before** performing the migration. - -### Steps - -Run the `gitops-migrate` tool, specifying the `format` command followed by the path to your GitOps YAML files. - -**Linux/Mac:** -```bash -# If 'gitops-migrate' is in the current working directory. -$ ./gitops-migrate format ./fleet_gitops -# If 'gitops-migrate' is in PATH. -$ gitops-migrate format ./fleet_gitops -``` - -**Windows:** -```powershell -# If 'gitops-migrate' is in the current working directory. -PS> .\gitops-migrate format .\fleet_gitops -# If 'gitops-migrate' is in PATH. -PS> gitops-migrate format .\fleet_gitops -``` - -Your YAML files should now all be alphabetized! - -> [!TIP] -> It's recommended to pause here, commit changes, then open a pull request for the formatting changes _only_. Then move onto the next section once that pull request has been reviewed and merged. +1. Run `./gitops-migrate format ./`. +2. Commit the resulting changes to your repo. ## Step 2: Migrate -### Overview +1. Run `./gitops-migrate migrate ./`. -Now we'll run the `gitops-migrate` `migrate` command which will: -- Perform a backup of your GitOps files, outputting an archive to your operating system's `TEMP` directory (**the path to this backup will be shown at the start of the output of the command, be sure to take note of it**). -- Migrate all YAML files in the provided directory (changes outlined [above](#474-yaml-changes)). - -### Steps - -Run the `gitops-migrate` tool, specifying the `migrate` command and the path to your GitOps YAML files. - -**Linux/Mac**: -```bash -# If 'gitops-migrate' is in the current working directory. -$ ./gitops-migrate migrate ./gitops_files -# If 'gitops-migrate' is in PATH. -$ gitops-migrate migrate ./gitops_files -``` - -**Windows:** -```powershell -# If 'gitops-migrate' is in the current working directory. -PS> .\gitops-migrate migrate .\gitops_files -# If 'gitops-migrate' is in PATH. -PS> gitops-migrate migrate .\gitops_files -``` - -### Did it work? - -**In the command output,** you should see messages like the following: +In the command output, you should see messages like the following: ```shell > Successfully applied transforms to team file. ┣━ [Team File]=>[it-and-security/teams/workstations.yml] ┗━ [Count]=>[39] ``` +2. Commit the resulting changes to your repo. + +## Confirm + In cases where the _team_ file previously contained software packages which referenced software files containing the fields [described above](#474-yaml-changes), you can spot-check the results by confirming these fields are now present in the software packages array items, right alongside the `path` key(s). -**When looking at a `git diff`** you should see changes similar to the following: +When looking at a `git diff` you should see changes similar to the following: **Software file (`./slack.yml`):** ```diff @@ -151,33 +84,3 @@ software: + labels_include_any: + - "Debian-based Linux hosts" ``` - -### Help, something has gone wrong! - -In the event you've attempted the migration and encounter any issues, you can quickly revert your GitOps file states by simply restoring the backup taken automatically during the `migrate` process. - -To do this, locate the backup archive path in the log output: - -```bash -> Performing Fleet GitOps file backup. -┣━ [Source]=>[fleet_gitops] -┗━ [Destination]=>[/tmp/fleet-gitops-1916163188/fleet-gitops-backup-8-31-2025_4-47-29.tar.gz] # <-- Here -``` - -Then simply run the `gitops-migrate` `restore` command to restore this backup, specifying the **archive** path as the first arg and the path to restore the archive **to** as the second arg: - -**Linux/Mac**: -```bash -# If 'gitops-migrate' is in the current working directory. -$ ./gitops-migrate restore /tmp/fleet-gitops-1916163188/fleet-gitops-backup-8-31-2025_4-47-29.tar.gz ./fleet_gitops -# If 'gitops-migrate' is in PATH. -$ gitops-migrate restore /tmp/fleet-gitops-1916163188/fleet-gitops-backup-8-31-2025_4-47-29.tar.gz ./fleet_gitops -``` - -**Windows:** -```powershell -# If 'gitops-migrate' is in the current working directory. -PS> .\gitops-migrate restore 'C:\Users\am\AppData\Local\Temp\fleet-gitops-1916163188/fleet-gitops-backup-8-31-2025_4-47-29.tar.gz' .\fleet_gitops -# If 'gitops-migrate' is in PATH. -PS> gitops-migrate restore 'C:\Users\am\AppData\Local\Temp\fleet-gitops-1916163188/fleet-gitops-backup-8-31-2025_4-47-29.tar.gz' .\fleet_gitops -```