akuity · krancour · Jan 16, 2025 · Jan 15, 2025 · Jan 15, 2025 · Jan 15, 2025
@@ -1,6 +1,6 @@
-## 🆕 What's New?
+## 🆕 What's New? {#whats-new}
 
-### 💪 Promotion Tasks
+### 💪 Promotion Tasks {#promotion-tasks}
 
 When support for expressions in promotion steps debuted in Kargo v1.1.0, we had a vision of eventually leveraging that capability to define reusable sequences of steps, where the particulars of each `Stage` utilizing them in their `Promotion`s could be provided, essentially, as arguments. v1.2.0 makes that vision a reality with the introduction of `PromotionTask`s (and `ClusterPromotionTask`s).
 
@@ -74,7 +74,7 @@ To use a common sequence of steps across multiple projects, use a cluster-scoped
 
 To learn more about this exciting feature, refer to our [PromotionTasks reference doc](https://docs.kargo.io/references/promotion-steps).
 
-### 🌊 Soak Time
+### 🌊 Soak Time {#soak-time}
 
 A _frequent_ request from users has been to support an option whereby a `Stage` may require any `Freight` promoted to it to have first "soaked" (remained in) an upstream `Stage` for a certain period of time, and this is now possible in v1.2.0.
 
@@ -99,7 +99,7 @@ promotionTemplate:
 
 Note that `requiredSoakTime`, if specified, is _in addition to_ the usual criteria that `Freight` must have been verified upstream before becoming available for promotion.
 
-### 🪜 New and Updated Promotion Steps
+### 🪜 New and Updated Promotion Steps {#new-and-updated-promotion-steps}
 
 * A new `json-update` allows for performing updates to JSON files in the same manner that has been possible for YAML files using the `yaml-update` step.
 
@@ -111,23 +111,23 @@ Note that `requiredSoakTime`, if specified, is _in addition to_ the usual criter
 
 Refer to the [Promotion Steps reference doc](https://docs.kargo.io/references/promotion-steps) for more details.
 
-### 🖥️ UI Improvements
+### 🖥️ UI Improvements {#ui-improvements}
 
 The two most notable UI improvements in v1.2.0 are:
 
 * When viewing a `Stage`s verification history, it is now possible to filter out "implicit" verification records that are created when a `Stage` lacking any user-defined verification process simply becomes healthy with any new `Freight` that has been promoted to it.
 
 * Project-scoped Kubernetes `Secret`s can now be managed in the UI.
 
-### ⚙️ Chart Improvements
+### ⚙️ Chart Improvements {#chart-improvements}
 
 We've, several times now, encountered users who are terminating TLS somewhere "upstream" from the Kargo API server (for instance at a reverse proxy or load balance). This has tended to impose some difficulty as the API server, itself not being configured to terminate TLS, would be unaware that any URLs it generates should begin with `https://` regardless.
 
 To address this, we've introduced a new `api.tls.terminatedUpstream` that can be set to `true` at install time.
 
 For further information, please refer directly to the [Kargo Helm chart's README](https://github.com/akuity/kargo/blob/main/charts/kargo/README.md), which describes all configuration options in detail.
 
-## 🙏 New Contributors
+## 🙏 New Contributors {#new-contributors}
 
 Kargo would be nothing without its users. An extra special thank you goes out to community members who made their first contribution to Kargo in this release:
 

@@ -1,16 +1,16 @@
 💪 The Kargo team, with support from community contributors, is proud to present v1.1.0 -- Kargo's first minor but _mighty_ release since going GA.
 
-## 🆕 What's New?
+## 🆕 What's New? {#whats-new}
 
-### `${{ Expression Language Support }}`
+### `${{ Expression Language Support }}` {#expression-language-support}
 
 The community reception to Kargo's transition away from its rigid, legacy promotion mechanisms, toward more flexible promotion steps has been overwhelmingly positive. When promotion steps first appeared in v0.9.0, we knew immediately that support for an expression language would be a powerful complement to that new feature, and this release delivers on that.
 
 For more details, consult our [expression reference documentation](https://docs.kargo.io/references/expression-language). Examples in our [promotion steps reference documentation](https://docs.kargo.io/references/promotion-steps) have also been extensively updated to reflect realistic usage of the expression language.
 
 With the advent of expression language support in promotion steps, we're noticing our own promotions processes becoming more and more similar from Stage to Stage -- often varying only in the definition of a few key variables. With this observation, it's clear that the time is right to _promote_ (pun fully intended) promotion processes to a first-class construct. So, to tease the upcoming v1.2.0 release, expect to see a new `PromotionTemplate` CRD that will enable users to DRY up their pipelines!
 
-### 🪜 New and Updated Promotion Steps
+### 🪜 New and Updated Promotion Steps {#new-and-updated-promotion-steps}
 
 ‼️ __This section contains important details about deprecations.__ ‼️
 
@@ -36,7 +36,7 @@ Last, but not least, all steps can now be configured with an optional timeout an
 
 __Please refer to the [promotion steps reference documentation](https://docs.kargo.io/references/promotion-steps) for detailed information about new and updated promotion steps as well as deprecated steps and fields.__
 
-### ⚙️ Resource and Concurrency Settings
+### ⚙️ Resource and Concurrency Settings {#resource-and-concurrency-settings}
 
 This release introduces a number of optimizations to Kargo's resource utilization.
 
@@ -48,13 +48,13 @@ This release introduces a number of optimizations to Kargo's resource utilizatio
 
 To assist in troubleshooting, effective values for all of the above are logged by each component at startup.
 
-### 🛠️ Refactored Stage Reconciliation
+### 🛠️ Refactored Stage Reconciliation {#refactored-stage-reconciliation}
 
 The controller's Stage reconciliation logic has been overhauled from top to bottom. The new implementation is more robust, more efficient, and should prove easier to maintain over time. We anticipate the refactored reconciler to also reduce the incidence of inconvenient behaviors such as pending Promotions being "stuck" for long periods of time while waiting for a Stage to reach or return to a healthy state that it may never reach.
 
 For the most part, these changes are purely internal, but users may notice that the reconciler now surfaces much more detailed information about the state of a Stage in its `status` subresource in the form of _conditions_. These should paint a clearer picture of what's happening with a Stage at any given time.
 
-### 🖥️ UI Improvements
+### 🖥️ UI Improvements {#ui-improvements}
 
 As always, the Kargo UI has received too many improvements to list in this release. Here are a few highlights:
 
@@ -66,7 +66,7 @@ As always, the Kargo UI has received too many improvements to list in this relea
 
 * A new user information page accessible from the sidebar displays the currently logged-in user's claims obtained from the identity token issued by the configured' OIDC identity provider. We anticipate this page will be useful for debugging OIDC configuration issues as well as authorization issues.
 
-## 🙏 New Contributors
+## 🙏 New Contributors {#new-contributors}
 
 Thank you to the following community members whose first contributions to Kargo were included in this release:
 
@@ -75,4 +75,4 @@ Thank you to the following community members whose first contributions to Kargo
 * @sergiofteixeira
 * @Historyman
 
-**Full Changelog**: https://github.com/akuity/kargo/compare/v1.0.4...v1.1.0
+**Full Changelog**: https://github.com/akuity/kargo/compare/v1.0.4...v1.1.0
@@ -1,40 +1,40 @@
 💥 Kargo v1.0.0 (GA) is finally here!
 
-## 🆕 What's New?
+## 🆕 What's New? {#whats-new}
 
 Not a lot. (Which is what you want in the GA release!) The main focus of v1.0.0 has been on stability and completing the pivot from rigid promotion mechanisms to flexible promotion steps that started with the v0.9.0 release.
 
 Here's a short list of noteworthy new features and fixes:
 
-### 🆕 General Improvements
+### 🆕 General Improvements {#general-improvements}
 
 - Warehouses more consistently discover new Freight at the proper interval.
 
 - Promotions no longer pre-empt running or pending verification processes.
 
-### 🪜 Promotion Step Improvements
+### 🪜 Promotion Step Improvements {#promotion-step-improvements}
 
 - Promotion steps will fail when obvious misconfigurations are detected.
 
 - Git-based promotion steps now support SSH authentication. (Warehouses already supported this.)
 
 - The `kustomize-build` promotion step now supports Helm chart inflation.
 
-### 🖥️ UI Improvements
+### 🖥️ UI Improvements {#ui-improvements}
 
 - The detailed Stage view now includes a timeline of the Stage's Freight history.
 
 - Running and pending Promotions can now be aborted directly from the UI.
 
 - Promotion workflows can be composed in the UI without writing YAML.
 
-### 🛡️ Security Improvements
+### 🛡️ Security Improvements {#security-improvements}
 
 - The official Kargo container image is now distroless. With a much smaller footprint overall, Kargo's attackable surface is reduced and maintainers will be able to more quickly respond to critical CVEs.
 
 - Kargo controllers (which may run on clusters other than the Kargo control plane) no longer require cluster-wide read access to Secrets. Instead, the management controller (a control plane component) will dynamically expand and contract the scope of all other controllers' Secret access as Projects are created and deleted. (The management controller has already done this same thing for the API server for quite some time.)
 
-## ‼️ Breaking Changes
+## ‼️ Breaking Changes {#breaking-changes}
 
 If you have designated any namespaces as "global" credential stores by providing values to `controller.globalCredentials.namespaces` at install-time, please note that you will need to either:
 
@@ -48,7 +48,7 @@ Apart from this and the final removal of the legacy promotion mechanisms, which
 
 If you still rely on the legacy promotion mechanisms, we plan to continue releasing v0.9.x patches through the end of the year to ensure users have ample time to complete the migration.
 
-## 🙏 New Contributors
+## 🙏 New Contributors {#new-contributors}
 
 Thank you to the following community members whose first contributions to Kargo were included in this release:
 

@@ -1,11 +1,30 @@
 ---
-sidebar_label: Deprecations
+sidebar_label: Deprecations and Breaking Changes
+description: A summary of deprecated features and breaking changes
 ---
 
-# Deprecation Notices
+# Deprecations and Breaking Changes
 
-:::warning
-Faeka to add notes about deprecations in every minor release >= 1.0 in this
-section. They can we extracted from the release notes and should also link
-to the relevant release notes.
-:::
+As Kargo continues to evolve, features that have outlived their usefulness,
+often having been replaced with better alternatives, are sometimes sunset. This
+page documents past and pending deprecated features and breaking changes.
+
+## Deprecations
+
+The table below summarizes features that have been deprecated and either removed or scheduled for removal.
+
+| Feature | Deprecated In | Removed In | Replacement/Notes |
+|---------|---------------|------------|-------------------|
+| Promotion Steps Fields | [v1.1.0](./80-release-notes/98-v1.1.0.md#new-and-updated-promotion-steps) | Scheduled for v1.3.0 | Several fields in promotion steps, such as `prNumberFromStep` in the `git-wait-for-pr` step, are now deprecated. These fields were  originally the only way to reference output from previous promotion steps. With the introduction of expressions, these fields have outlived their purpose, as expressions like `${{ outputs['open-pr'].prNumber }}` present a more flexible and straightforward way to reference the same output. [more info](./80-release-notes/98-v1.1.0.md#new-and-updated-promotion-steps) |
+| `helm-update-image` step | [v1.1.0](./80-release-notes/98-v1.1.0.md#new-and-updated-promotion-steps) | Scheduled for v1.3.0 | Use the more flexible `yaml-update` step. [more info](./80-release-notes/98-v1.1.0.md#new-and-updated-promotion-steps) |
+| Legacy Promotion Mechanisms | v0.9.0 | [v1.0.0](./80-release-notes/99-v1.0.0.md#breaking-changes) | Migrate to promotion steps. [more info](./80-release-notes/99-v1.0.0.md#breaking-changes) |
+
+## Breaking Changes
+
+This section summarizes significant changes that create potential for disruption
+upon upgrade. __The Kargo team strives to keep changes of this nature to an
+absolute minimum.__
+
+| Change | Version | Impact | Migration Path |
+|--------|---------|--------|----------------|
+| Global Credential Store Changes | [v1.0.0](./80-release-notes/99-v1.0.0.md#breaking-changes) | Affects installations using `controller.globalCredentials.namespaces` | Manually create a `RoleBinding`s to permit controller access to "global" credential namespaces _or_ set `controller.serviceAccount.clusterWideSecretReadingEnabled` to `true` at install time (not recommended). [more info](./80-release-notes/99-v1.0.0.md#breaking-changes) |