diff --git a/_docs-sources/patcher/index.md b/_docs-sources/patcher/index.md index 56109ec962..71ca19ff2d 100644 --- a/_docs-sources/patcher/index.md +++ b/_docs-sources/patcher/index.md @@ -38,36 +38,11 @@ If you purchased and deployed our [Reference Architecture](https://gruntwork.io/ ### Patcher Report -In `v0.2.x`, the only available command is `patcher report`. This is a read-only version of Patcher that shows the changelog per module and its usages. After running patcher report you will end up in the 'Modules View', similar to the screenshot below. +The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages. -![Patcher Report screenshot](/img/guides/stay-up-to-date/patcher/patcher-report.png) - -#### Navigation commands - -1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: - -![Patcher Usages screenshot](/img/guides/stay-up-to-date/patcher/patcher-usages.png) - - -2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. - -![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-changelogs.png) - -:::info -Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. - -::: - -![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-no-changelogs.png) - - -### CIS AWS v1.5 Upgrade - -In `v0.1.x`, the only command available is `patcher upgrade cis`. This will upgrade your service catalogs to the latest -module versions in the context of CIS v1.5. - -For the CIS AWS Foundations Benchmark v1.5 upgrade, refer to [the upgrade guide](https://docs.gruntwork.io/guides/stay-up-to-date/cis/cis-1.5.0/). +### Patcher Update +The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders. ## Debugging @@ -75,5 +50,4 @@ All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, ``` patcher report --loglevel debug -``` - +``` \ No newline at end of file diff --git a/_docs-sources/patcher/running-patcher/report.md b/_docs-sources/patcher/running-patcher/report.md new file mode 100644 index 0000000000..69ea10f830 --- /dev/null +++ b/_docs-sources/patcher/running-patcher/report.md @@ -0,0 +1,26 @@ +# Patcher Report + +The `patcher report` command is a read-only version of Patcher that shows the changelog per module and its usages. + +After scanning for dependencies, Patcher will show you the 'Modules View', similar to the screenshot below. + +![Patcher Report screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-overview-futd.png) + +### Navigation commands + +1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: + +![Patcher Usages screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-usages.png) + +2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. + +![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-changelog.png) + +:::info +Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. + +::: + +![Patcher No Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-no-changelog.png) + + diff --git a/_docs-sources/patcher/running-patcher/update.md b/_docs-sources/patcher/running-patcher/update.md new file mode 100644 index 0000000000..11d840f771 --- /dev/null +++ b/_docs-sources/patcher/running-patcher/update.md @@ -0,0 +1,106 @@ +# Patcher Update + +The Patcher update command allows you to update some or all of the module dependencies in the current folder and any child folders. + +The update command supports two modes: **interactive mode** and **non-interactive mode**. + +## Interactive Mode + +In interactive mode, the update command lets you selectively update dependencies one module at time. + +Example usage: +``` +patcher update prod +``` + +After scanning for dependencies, Patcher will show you the 'Modules View'. + +If all the dependencies are fully up to date, then Patcher shows a tick in the "Up to date" column. + +![Patcher update screenshot showing dependendency that is fully up to date](/img/guides/stay-up-to-date/patcher/patcher-update-overview-futd.png) + +If Patcher can update one or more usages of a module to a newer version, then Patcher offers two options: + +* "Hit «ENTER» to update all usages to the next safe version." + +* "Hit «b» to update all usages to the next version, even if it's a breaking change." + +![Patcher Update screenshot showing dependency that can be updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-update-available.png) + +Pressing `ENTER` will update all the usages of that module to either the highest version before the next closest breaking change or the latest version of the dependecy, whichever is encountered first. + +Pressing `b` will update all the usages of that module to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. + +After updating the "Up to date" column is changed to show "Updated". This indicates that at least one of the dependencies on that module have been updated. + +![Patcher Update screenshot showing dependency that has been updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-updated.png) + +When you quit Patcher, it writes the details of all the updates to stdout in YAML format, for example: + +![Patcher Update screenshot showing YAML output](/img/guides/stay-up-to-date/patcher/patcher-update-yaml-output.png) + +### Navigation commands + +1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: + +![Patcher Usages screenshot showing module with multiple usages](/img/guides/stay-up-to-date/patcher/patcher-update-usages-update-available.png) + +2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. + +![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-update-changelog.png) + +:::info +Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. + +::: + +![Patcher No Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-update-no-changelog.png) + +## Non-Interactive Mode + +In non-interactive mode, Patcher updates all module dependencies in the current folder (and child folders) according to the specified update strategy. + +Non-interactive mode supports both the `next-safe` and `next-breaking` update strategies. + +### Next Safe (Default) + +Using the [next safe update strategy](/patcher/update-strategies#next-safe-update-strategy-default), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version **before** that breaking change. Otherwise, it will update the dependencies the latest version of that module. + +Example usage: +``` +patcher update --non-interactive --update-strategy next-safe +``` +Or just +``` +patcher update --non-interactive +``` + +### Next Breaking + +Using the [next-breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module. + +If Patcher updates a dependency to a breaking version, a `README-TO-COMPLETE-UPDATE.md` is written into the folder containing the dependendency. The `README-TO-COMPLETE-UPDATE.md` file contains a release note extract for each dependency in that folder that was updated to a breaking change. + +Example usage: +``` +patcher update --non-interactive --update-strategy next-breaking +``` + +## Support for Third Party Modules + +Starting in `0.3.3`, Patcher provides limited support for updating third party modules, this includes your own modules. The updates to third party module are limited to bumping the semver patch version. + +Third party modules are supported in both interactive mode and non-interactive mode. + +For example, the [terraform-aws-modules/terraform-aws-vpc](https://github.com/terraform-aws-modules/terraform-aws-vpc) module has two recent change: `4.0.2` and `5.0.0`. + +And in `infrastructure-live/prod` there is a dependency on `terraform-aws-vpc/vpc`: +- `prod/us-east-1/prod/vpc/terragrunt.hcl` currently uses `4.0.0` + +Patcher can update this dependency to `4.0.2` but because this only requires bumping the semver patch version. + +![Screenshot of third party module dependency usages with updates available](/img/guides/stay-up-to-date/patcher/patcher-update-usages-3p-update-available.png) + +Patcher cannot update from `4.0.x` to `5.0.0` and will instead show a `?` in the "Up to date" column and the message "Patcher can not determine an update plan for this dependency". + +![Screenshot of third party module dependency that cannot be updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-no-plan.png) diff --git a/_docs-sources/patcher/running-patcher/upgrade.md b/_docs-sources/patcher/running-patcher/upgrade.md new file mode 100644 index 0000000000..632015eebe --- /dev/null +++ b/_docs-sources/patcher/running-patcher/upgrade.md @@ -0,0 +1,10 @@ +# Patcher Upgrade + +## CIS AWS v1.5 Upgrade + +The `patcher upgrade cis` command is only available in `v0.1.x`. + +This will upgrade your service catalogs to the latest module versions in the context of CIS v1.5. + +For the CIS AWS Foundations Benchmark v1.5 upgrade, refer to [the upgrade guide](https://docs.gruntwork.io/guides/stay-up-to-date/cis/cis-1.5.0/). + diff --git a/_docs-sources/patcher/telemetry.md b/_docs-sources/patcher/telemetry.md new file mode 100644 index 0000000000..b25ec3b67a --- /dev/null +++ b/_docs-sources/patcher/telemetry.md @@ -0,0 +1,26 @@ +# Telemetry + +Patcher uses [sentry.io](https://sentry.io) for application performance monitoring and error tracking. This data helps us catch bugs quickly and improve Patcher. + +### Anonymous UUID + +When you first run Patcher, we generate an anonymous UUID for that Patcher install. + +This UUID is stored in `~/.patcher/config.json` and the same UUID will be sent each time you run Patcher. + +Example `config.json` file: +``` +// NOTE: Changing this file requires a restart of Patcher. +{ + // Unique id used for correlating telemetry sent from this instance. + // Do not edit this value. + "telemetry-reporter-id": "a8884e6a-da99-43e3-86d0-f92a3605d731" +} +``` + +### Opting Out + +You can opt out of sending telemetry data by setting the `PATCHER_TELEMETRY_OPT_OUT` environment variable to `true`. +```bash +export PATCHER_TELEMETRY_OPT_OUT=true +``` diff --git a/_docs-sources/patcher/update-strategies.md b/_docs-sources/patcher/update-strategies.md new file mode 100644 index 0000000000..87008562ce --- /dev/null +++ b/_docs-sources/patcher/update-strategies.md @@ -0,0 +1,97 @@ +# Update Strategies + +Patcher supports two update strategies: **next safe** and **next breaking**. Theses update strategy determines how Patcher will behave if it encounters a breaking change that it cannot patch. + +For example, the Gruntwork `terraform-aws-security/custom-iam-entity` module has two recent breaking changes: `0.62.0` and `0.65.0`. + +And in `infrastructure-live/dev` there are 2 dependencies on `terraform-aws-security/custom-iam-entity`: +- `_global/ops-admin-role/terragrunt.hcl` currently uses `0.65.6` +- `_global/website-ci-cd-access/terragrunt.hcl` currently use `0.61.0` + +## "Next Safe" Update Strategy (Default) + +The **next safe** strategy will update a dependency to either the highest version **before the next closest breaking change** or the latest version of the dependency, whichever is encountered first. + +So if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version before that breaking change and stop. Otherwise, if no breaking chnages are encountered it will update the dependencies the latest version of that module. + +For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: +- `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version + - There are no breaking changes between `0.65.6` and `0.68.2` +- `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.61.1`, the highest version before `0.62.0` + - `0.62.0` is the next highest version that contains a breaking change which requires manual intervention + +This is an example of the YAML that Patcher writes to `stdout` describing these updates: + +```yaml + successful_updates: + - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.65.6 + updated_version: v0.68.2 + - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.61.0 + updated_version: v0.61.1 + next_breaking_version: + version: v0.62.0 + release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 +``` + +## "Next Breaking" Update Strategy + +The **next breaking** strategy will update a dependency to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. + +So if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, if no breaking chnages are encountered it will update the dependencies the latest version of that module. + +This may result in an update that requires manual intervention. If so, Patcher will provide additional information to help you understand what needs to be done. + +Patcher does this by writing a `README-TO-COMPLETE-UPDATE.md` into the folder containing the dependendency. If more than one dependency in a folder has been update to a breaking version, then the `README-TO-COMPLETE-UPDATE.md` file will contain a release note extracts for each breaking change in that folder. + +For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: +- `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version + - There are no breaking changes between `0.65.6` and `0.68.2` +- `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.62.0`, the next highest version with a breaking change that requires manual intervention. + +If any of the dependencies were updated to a breaking version, then the YAML that Patcher writes to `stdout` describing these updates will include a `manual_steps_you_must_follow` section listing the generated `README-TO-COMPLETE-UPDATE.md` files, for example: + +```yaml + successful_updates: + - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.65.6 + updated_version: v0.68.2 + - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.61.0 + updated_version: v0.62.0 + next_breaking_version: + version: v0.62.0 + release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 + manual_steps_you_must_follow: + - instructions_file_path: ~/-infrastructure-live/dev/_global/website-ci-cd-access/README-TO-COMPLETE-UPDATE.md +``` + +This is the `README-TO-COMPLETE-UPDATE.md` written into `dev/_global/website-ci-cd-access`: + +```markdown +# custom-iam-entity v0.61.0 -> v0.62.0 (2023.06.05 12:26:30) + +Updated dependency custom-iam-entity in ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl to version v0.62.0, which contains breaking changes. You MUST follow the instructions in the release notes to complete this update safely: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 + +Here are the release notes for version v0.62.0: + + +## Description +**Terraform 1.1 upgrade**: We have verified that this repo is compatible with Terraform `1.1.x`! + - From this release onward, we will only be running tests with Terraform `1.1.x` against this repo, so we recommend updating to `1.1.x` soon! + - We have also updated the minimum required version of Terraform to `1.0.0`. While our repos might continue to be compatible with pre-1.0.0 version of Terraform, we are no longer making any guarantees of that. + - Once all Gruntwork repos have been upgraded to work with `1.1.x`, we will publish a migration guide with a version compatibility table and announce it all via the Gruntwork Newsletter. +``` \ No newline at end of file diff --git a/docs/patcher/index.md b/docs/patcher/index.md index f43ac0a5c7..171304ffc8 100644 --- a/docs/patcher/index.md +++ b/docs/patcher/index.md @@ -38,36 +38,11 @@ If you purchased and deployed our [Reference Architecture](https://gruntwork.io/ ### Patcher Report -In `v0.2.x`, the only available command is `patcher report`. This is a read-only version of Patcher that shows the changelog per module and its usages. After running patcher report you will end up in the 'Modules View', similar to the screenshot below. +The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages. -![Patcher Report screenshot](/img/guides/stay-up-to-date/patcher/patcher-report.png) - -#### Navigation commands - -1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: - -![Patcher Usages screenshot](/img/guides/stay-up-to-date/patcher/patcher-usages.png) - - -2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. - -![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-changelogs.png) - -:::info -Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. - -::: - -![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-no-changelogs.png) - - -### CIS AWS v1.5 Upgrade - -In `v0.1.x`, the only command available is `patcher upgrade cis`. This will upgrade your service catalogs to the latest -module versions in the context of CIS v1.5. - -For the CIS AWS Foundations Benchmark v1.5 upgrade, refer to [the upgrade guide](https://docs.gruntwork.io/guides/stay-up-to-date/cis/cis-1.5.0/). +### Patcher Update +The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders. ## Debugging @@ -77,11 +52,9 @@ All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, patcher report --loglevel debug ``` - - diff --git a/docs/patcher/running-patcher/report.md b/docs/patcher/running-patcher/report.md new file mode 100644 index 0000000000..18493f6f0a --- /dev/null +++ b/docs/patcher/running-patcher/report.md @@ -0,0 +1,34 @@ +# Patcher Report + +The `patcher report` command is a read-only version of Patcher that shows the changelog per module and its usages. + +After scanning for dependencies, Patcher will show you the 'Modules View', similar to the screenshot below. + +![Patcher Report screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-overview-futd.png) + +### Navigation commands + +1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: + +![Patcher Usages screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-usages.png) + +2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. + +![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-changelog.png) + +:::info +Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. + +::: + +![Patcher No Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-report-no-changelog.png) + + + + + diff --git a/docs/patcher/running-patcher/update.md b/docs/patcher/running-patcher/update.md new file mode 100644 index 0000000000..806cf2a90a --- /dev/null +++ b/docs/patcher/running-patcher/update.md @@ -0,0 +1,114 @@ +# Patcher Update + +The Patcher update command allows you to update some or all of the module dependencies in the current folder and any child folders. + +The update command supports two modes: **interactive mode** and **non-interactive mode**. + +## Interactive Mode + +In interactive mode, the update command lets you selectively update dependencies one module at time. + +Example usage: +``` +patcher update prod +``` + +After scanning for dependencies, Patcher will show you the 'Modules View'. + +If all the dependencies are fully up to date, then Patcher shows a tick in the "Up to date" column. + +![Patcher update screenshot showing dependendency that is fully up to date](/img/guides/stay-up-to-date/patcher/patcher-update-overview-futd.png) + +If Patcher can update one or more usages of a module to a newer version, then Patcher offers two options: + +* "Hit «ENTER» to update all usages to the next safe version." + +* "Hit «b» to update all usages to the next version, even if it's a breaking change." + +![Patcher Update screenshot showing dependency that can be updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-update-available.png) + +Pressing `ENTER` will update all the usages of that module to either the highest version before the next closest breaking change or the latest version of the dependecy, whichever is encountered first. + +Pressing `b` will update all the usages of that module to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. + +After updating the "Up to date" column is changed to show "Updated". This indicates that at least one of the dependencies on that module have been updated. + +![Patcher Update screenshot showing dependency that has been updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-updated.png) + +When you quit Patcher, it writes the details of all the updates to stdout in YAML format, for example: + +![Patcher Update screenshot showing YAML output](/img/guides/stay-up-to-date/patcher/patcher-update-yaml-output.png) + +### Navigation commands + +1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: + +![Patcher Usages screenshot showing module with multiple usages](/img/guides/stay-up-to-date/patcher/patcher-update-usages-update-available.png) + +2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. + +![Patcher Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-update-changelog.png) + +:::info +Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. + +::: + +![Patcher No Changelogs screenshot](/img/guides/stay-up-to-date/patcher/patcher-update-no-changelog.png) + +## Non-Interactive Mode + +In non-interactive mode, Patcher updates all module dependencies in the current folder (and child folders) according to the specified update strategy. + +Non-interactive mode supports both the `next-safe` and `next-breaking` update strategies. + +### Next Safe (Default) + +Using the [next safe update strategy](/patcher/update-strategies#next-safe-update-strategy-default), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version **before** that breaking change. Otherwise, it will update the dependencies the latest version of that module. + +Example usage: +``` +patcher update --non-interactive --update-strategy next-safe +``` +Or just +``` +patcher update --non-interactive +``` + +### Next Breaking + +Using the [next-breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module. + +If Patcher updates a dependency to a breaking version, a `README-TO-COMPLETE-UPDATE.md` is written into the folder containing the dependendency. The `README-TO-COMPLETE-UPDATE.md` file contains a release note extract for each dependency in that folder that was updated to a breaking change. + +Example usage: +``` +patcher update --non-interactive --update-strategy next-breaking +``` + +## Support for Third Party Modules + +Starting in `0.3.3`, Patcher provides limited support for updating third party modules, this includes your own modules. The updates to third party module are limited to bumping the semver patch version. + +Third party modules are supported in both interactive mode and non-interactive mode. + +For example, the [terraform-aws-modules/terraform-aws-vpc](https://github.com/terraform-aws-modules/terraform-aws-vpc) module has two recent change: `4.0.2` and `5.0.0`. + +And in `infrastructure-live/prod` there is a dependency on `terraform-aws-vpc/vpc`: +- `prod/us-east-1/prod/vpc/terragrunt.hcl` currently uses `4.0.0` + +Patcher can update this dependency to `4.0.2` but because this only requires bumping the semver patch version. + +![Screenshot of third party module dependency usages with updates available](/img/guides/stay-up-to-date/patcher/patcher-update-usages-3p-update-available.png) + +Patcher cannot update from `4.0.x` to `5.0.0` and will instead show a `?` in the "Up to date" column and the message "Patcher can not determine an update plan for this dependency". + +![Screenshot of third party module dependency that cannot be updated](/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-no-plan.png) + + + diff --git a/docs/patcher/running-patcher/upgrade.md b/docs/patcher/running-patcher/upgrade.md new file mode 100644 index 0000000000..3225846d07 --- /dev/null +++ b/docs/patcher/running-patcher/upgrade.md @@ -0,0 +1,18 @@ +# Patcher Upgrade + +## CIS AWS v1.5 Upgrade + +The `patcher upgrade cis` command is only available in `v0.1.x`. + +This will upgrade your service catalogs to the latest module versions in the context of CIS v1.5. + +For the CIS AWS Foundations Benchmark v1.5 upgrade, refer to [the upgrade guide](https://docs.gruntwork.io/guides/stay-up-to-date/cis/cis-1.5.0/). + + + + diff --git a/docs/patcher/telemetry.md b/docs/patcher/telemetry.md new file mode 100644 index 0000000000..d15bb8ced1 --- /dev/null +++ b/docs/patcher/telemetry.md @@ -0,0 +1,34 @@ +# Telemetry + +Patcher uses [sentry.io](https://sentry.io) for application performance monitoring and error tracking. This data helps us catch bugs quickly and improve Patcher. + +### Anonymous UUID + +When you first run Patcher, we generate an anonymous UUID for that Patcher install. + +This UUID is stored in `~/.patcher/config.json` and the same UUID will be sent each time you run Patcher. + +Example `config.json` file: +``` +// NOTE: Changing this file requires a restart of Patcher. +{ + // Unique id used for correlating telemetry sent from this instance. + // Do not edit this value. + "telemetry-reporter-id": "a8884e6a-da99-43e3-86d0-f92a3605d731" +} +``` + +### Opting Out + +You can opt out of sending telemetry data by setting the `PATCHER_TELEMETRY_OPT_OUT` environment variable to `true`. +```bash +export PATCHER_TELEMETRY_OPT_OUT=true +``` + + + diff --git a/docs/patcher/update-strategies.md b/docs/patcher/update-strategies.md new file mode 100644 index 0000000000..8a3482921b --- /dev/null +++ b/docs/patcher/update-strategies.md @@ -0,0 +1,104 @@ +# Update Strategies + +Patcher supports two update strategies: **next safe** and **next breaking**. Theses update strategy determines how Patcher will behave if it encounters a breaking change that it cannot patch. + +For example, the Gruntwork `terraform-aws-security/custom-iam-entity` module has two recent breaking changes: `0.62.0` and `0.65.0`. + +And in `infrastructure-live/dev` there are 2 dependencies on `terraform-aws-security/custom-iam-entity`: +- `_global/ops-admin-role/terragrunt.hcl` currently uses `0.65.6` +- `_global/website-ci-cd-access/terragrunt.hcl` currently use `0.61.0` + +## "Next Safe" Update Strategy (Default) + +The **next safe** strategy will update a dependency to either the highest version **before the next closest breaking change** or the latest version of the dependency, whichever is encountered first. + +So if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version before that breaking change and stop. Otherwise, if no breaking chnages are encountered it will update the dependencies the latest version of that module. + +For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: +- `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version + - There are no breaking changes between `0.65.6` and `0.68.2` +- `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.61.1`, the highest version before `0.62.0` + - `0.62.0` is the next highest version that contains a breaking change which requires manual intervention + +This is an example of the YAML that Patcher writes to `stdout` describing these updates: + +```yaml + successful_updates: + - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.65.6 + updated_version: v0.68.2 + - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.61.0 + updated_version: v0.61.1 + next_breaking_version: + version: v0.62.0 + release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 +``` + +## "Next Breaking" Update Strategy + +The **next breaking** strategy will update a dependency to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. + +So if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, if no breaking chnages are encountered it will update the dependencies the latest version of that module. + +This may result in an update that requires manual intervention. If so, Patcher will provide additional information to help you understand what needs to be done. + +Patcher does this by writing a `README-TO-COMPLETE-UPDATE.md` into the folder containing the dependendency. If more than one dependency in a folder has been update to a breaking version, then the `README-TO-COMPLETE-UPDATE.md` file will contain a release note extracts for each breaking change in that folder. + +For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: +- `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version + - There are no breaking changes between `0.65.6` and `0.68.2` +- `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.62.0`, the next highest version with a breaking change that requires manual intervention. + +If any of the dependencies were updated to a breaking version, then the YAML that Patcher writes to `stdout` describing these updates will include a `manual_steps_you_must_follow` section listing the generated `README-TO-COMPLETE-UPDATE.md` files, for example: + +```yaml + successful_updates: + - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.65.6 + updated_version: v0.68.2 + - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl + updated_modules: + - repo: terraform-aws-security + module: custom-iam-entity + previous_version: v0.61.0 + updated_version: v0.62.0 + next_breaking_version: + version: v0.62.0 + release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 + manual_steps_you_must_follow: + - instructions_file_path: ~/-infrastructure-live/dev/_global/website-ci-cd-access/README-TO-COMPLETE-UPDATE.md +``` + +This is the `README-TO-COMPLETE-UPDATE.md` written into `dev/_global/website-ci-cd-access`: + +```markdown +# custom-iam-entity v0.61.0 -> v0.62.0 (2023.06.05 12:26:30) + +Updated dependency custom-iam-entity in ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl to version v0.62.0, which contains breaking changes. You MUST follow the instructions in the release notes to complete this update safely: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 + +Here are the release notes for version v0.62.0: + + +## Description +**Terraform 1.1 upgrade**: We have verified that this repo is compatible with Terraform `1.1.x`! + - From this release onward, we will only be running tests with Terraform `1.1.x` against this repo, so we recommend updating to `1.1.x` soon! + - We have also updated the minimum required version of Terraform to `1.0.0`. While our repos might continue to be compatible with pre-1.0.0 version of Terraform, we are no longer making any guarantees of that. + - Once all Gruntwork repos have been upgraded to work with `1.1.x`, we will publish a migration guide with a version compatibility table and announce it all via the Gruntwork Newsletter. +``` + + diff --git a/sidebars/patcher.js b/sidebars/patcher.js index 8b11ad203c..7c10061b65 100644 --- a/sidebars/patcher.js +++ b/sidebars/patcher.js @@ -1,16 +1,23 @@ const sidebar = [ { - label: "Patcher", - type: "category", - collapsible: false, - items: [ - { - label: "Getting Started", - type: "doc", - id: "patcher/index", - } - ] + "label": "Patcher", + "type": "category", + "link": { + "type": "doc", + "id": "patcher/index" + }, + "items": [ + { + "Running Patcher": [ + "patcher/running-patcher/report", + "patcher/running-patcher/update", + "patcher/running-patcher/upgrade" + ] + }, + "patcher/telemetry", + "patcher/update-strategies" + ] } -] - -module.exports = sidebar + ] + + module.exports = sidebar \ No newline at end of file diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-changelogs.png b/static/img/guides/stay-up-to-date/patcher/patcher-changelogs.png deleted file mode 100644 index 3b998f6ea1..0000000000 Binary files a/static/img/guides/stay-up-to-date/patcher/patcher-changelogs.png and /dev/null differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-no-changelogs.png b/static/img/guides/stay-up-to-date/patcher/patcher-no-changelogs.png deleted file mode 100644 index a2acd61e16..0000000000 Binary files a/static/img/guides/stay-up-to-date/patcher/patcher-no-changelogs.png and /dev/null differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report-changelog.png b/static/img/guides/stay-up-to-date/patcher/patcher-report-changelog.png new file mode 100644 index 0000000000..606e6d3cbb Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-report-changelog.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report-no-changelog.png b/static/img/guides/stay-up-to-date/patcher/patcher-report-no-changelog.png new file mode 100644 index 0000000000..c13f283a1b Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-report-no-changelog.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-futd.png b/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-futd.png new file mode 100644 index 0000000000..2c6810c1c1 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-futd.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-updates-available.png b/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-updates-available.png new file mode 100644 index 0000000000..14a9c1161b Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-report-overview-updates-available.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report-usages.png b/static/img/guides/stay-up-to-date/patcher/patcher-report-usages.png new file mode 100644 index 0000000000..e6cb9360f6 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-report-usages.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-report.png b/static/img/guides/stay-up-to-date/patcher/patcher-report.png deleted file mode 100644 index 0254368cff..0000000000 Binary files a/static/img/guides/stay-up-to-date/patcher/patcher-report.png and /dev/null differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-changelog.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-changelog.png new file mode 100644 index 0000000000..695127f000 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-changelog.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-no-changelog.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-no-changelog.png new file mode 100644 index 0000000000..01b874264b Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-no-changelog.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-no-plan.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-no-plan.png new file mode 100644 index 0000000000..6af93ddc9a Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-no-plan.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-update-available.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-update-available.png new file mode 100644 index 0000000000..c8bdf96edd Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-update-available.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-updated.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-updated.png new file mode 100644 index 0000000000..0ea75c020f Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-3p-updated.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-futd.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-futd.png new file mode 100644 index 0000000000..b1dd3ff72c Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-futd.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-update-available.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-update-available.png new file mode 100644 index 0000000000..a1cf48dede Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-update-available.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-updated.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-updated.png new file mode 100644 index 0000000000..25664c57c1 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-overview-updated.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-3p-update-available.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-3p-update-available.png new file mode 100644 index 0000000000..298a1d9fee Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-3p-update-available.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-update-available.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-update-available.png new file mode 100644 index 0000000000..e8a5409066 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-update-available.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-updated.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-updated.png new file mode 100644 index 0000000000..bd66060f33 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-usages-updated.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-version-bump.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-version-bump.png new file mode 100644 index 0000000000..457120fcf6 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-version-bump.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-update-yaml-output.png b/static/img/guides/stay-up-to-date/patcher/patcher-update-yaml-output.png new file mode 100644 index 0000000000..6d2b591570 Binary files /dev/null and b/static/img/guides/stay-up-to-date/patcher/patcher-update-yaml-output.png differ diff --git a/static/img/guides/stay-up-to-date/patcher/patcher-usages.png b/static/img/guides/stay-up-to-date/patcher/patcher-usages.png deleted file mode 100644 index 61e1ab7535..0000000000 Binary files a/static/img/guides/stay-up-to-date/patcher/patcher-usages.png and /dev/null differ