Skip to content

Commit 15fe1a1

Browse files
hiddecohiddeco
authored
docs: add v1.3.0 release notes (#3565)
Signed-off-by: Hidde Beydals <[email protected]>
1 parent 9ea87a2 commit 15fe1a1

File tree

2 files changed

+140
-2
lines changed

2 files changed

+140
-2
lines changed

Diff for: ‎docs/docs/80-release-notes/100-deprecations.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,9 @@ The table below summarizes features that have been deprecated and either removed
1515

1616
| Feature | Deprecated In | Removed In | Replacement/Notes |
1717
|---------|---------------|------------|-------------------|
18-
| Promotion Steps Fields | [v1.1.0](./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](./98-v1.1.0.md#new-and-updated-promotion-steps) |
19-
| `helm-update-image` step | [v1.1.0](./98-v1.1.0.md#new-and-updated-promotion-steps) | Scheduled for v1.3.0 | Use the more flexible `yaml-update` step. [more info](./98-v1.1.0.md#new-and-updated-promotion-steps) |
18+
| `messageFromSteps` of `git-commit` Promotion Step | [v1.3.0](./96-v1.3.0.md#new-deprecations) | Scheduled for v1.5.0 | Use the `message` field in combination with expressions. Refer to the [documentation](https://main.docs.kargo.io/user-guide/reference-docs/promotion-steps/git-commit/#composed-commit-message) for more information. |
19+
| Promotion Steps Fields | [v1.1.0](./98-v1.1.0.md#new-and-updated-promotion-steps) | [v1.3.0](./96-v1.3.0.md#breaking-changes) | 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](./98-v1.1.0.md#new-and-updated-promotion-steps) |
20+
| `helm-update-image` step | [v1.1.0](./98-v1.1.0.md#new-and-updated-promotion-steps) | [v1.3.0](./96-v1.3.0.md#breaking-changes) | Use the more flexible `yaml-update` step. [more info](./98-v1.1.0.md#new-and-updated-promotion-steps) |
2021
| Legacy Promotion Mechanisms | v0.9.0 | [v1.0.0](./99-v1.0.0.md#breaking-changes) | Migrate to promotion steps. [more info](./99-v1.0.0.md#breaking-changes) |
2122

2223
## Breaking Changes

Diff for: ‎docs/docs/80-release-notes/96-v1.3.0.md

+137
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
## ⚠️ Breaking Changes {#breaking-changes}
2+
3+
As announced in our [`v1.1.0` release notes](https://github.com/akuity/kargo/releases/tag/v1.1.0), several deprecated features from _before_ we introduced support for Expression Language have been removed in this release.
4+
5+
- The `fromOrigin` and `fromFreight` fields in the [`argocd-update`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/argocd-update), [`git-clone`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-clone/), [`helm-update-chart`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/helm-update-chart/), and [`kustomize-set-image`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/kustomize-set-image/) steps have been removed in favor of the [expression functions](https://docs.kargo.io/user-guide/reference-docs/expressions#functions).
6+
- The `<thing>FromStep` fields in the [`argocd-update`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/argocd-update), [`git-open-pr`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-open-pr/), and [`git-wait-for-pr`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-wait-for-pr/) steps have been removed in favor of using [step outputs](https://docs.kargo.io/user-guide/reference-docs/expressions#pre-defined-variables).
7+
- The `helm-update-image` step has been removed in favor of the more generic [`yaml-update` step](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/yaml-update) which supports the same functionalities.
8+
9+
To discover the new way of providing the configuration for these steps, please refer to the updated documentation examples for each step linked above.
10+
11+
## ⚠️ New Deprecations {#new-deprecations}
12+
13+
Consistent with the changes noted above, the `messageFromSteps` field of the [`git-commit`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-commit#configuration) promotion step is newly deprecated in favor of using the `message` field with expressions instead.
14+
15+
`messageFromSteps` is scheduled for removal in the v1.5.0 release.
16+
17+
## ✨ New Features {#new-features}
18+
19+
### 🔀 Conditional Step Execution {#conditional-step-execution}
20+
21+
Promotion steps now allow the definition of an [`if` expression](https://docs.kargo.io/user-guide/reference-docs/promotion-templates#conditional-steps) that evaluates to a boolean value. When this [expression](https://docs.kargo.io/user-guide/reference-docs/expressions) evaluates to `false`, the step is skipped and the next step in the sequence is executed.
22+
23+
```yaml
24+
apiVersion: kargo.akuity.io/v1alpha1
25+
kind: Stage
26+
metadata:
27+
name: test
28+
namespace: kargo-demo
29+
spec:
30+
# ...
31+
promotionTemplate:
32+
spec:
33+
steps:
34+
- uses: fake-step
35+
if: ${{ outputs.step1.someOutput == 'value' }}
36+
```
37+
38+
While the current use cases for this within `Promotion` templates may seem limited, it does allow you to conditionally execute a task step based on provided [task variables](https://docs.kargo.io/user-guide/reference-docs/promotion-tasks#task-variables) in `PromotionTask`s.
39+
40+
In a future release, Kargo will be adding support for improved failure and error handling, which will supercharge this feature based on the outcome of previous steps. Follow [this issue](https://github.com/akuity/kargo/issues/3228) for more information and updates.
41+
42+
### 🎛️ Control of Semantics for Freight Requests {#control-of-semantics-for-freight-requests}
43+
44+
Previously, any requested `Freight` for a `Stage` was automatically available to it as soon as one of the listed upstream `Stage`s had successfully verified it. Starting with this release, and thanks to the efforts of @aidan-canva, it is now possible to define an "availability strategy" that requires it to have been verified in _all_ upstream Stages.
45+
46+
```yaml
47+
apiVersion: kargo.akuity.io/v1alpha1
48+
kind: Stage
49+
metadata:
50+
name: uat
51+
namespace: kargo-demo
52+
spec:
53+
requestedFreight:
54+
- origin:
55+
kind: Warehouse
56+
name: my-warehouse
57+
sources:
58+
stages:
59+
- test
60+
- uat
61+
availabilityStrategy: All
62+
```
63+
64+
Refer to the [updated documentation](https://docs.kargo.io/user-guide/how-to-guides/working-with-stages#requested-freight) for more information.
65+
66+
### 🛡️ Stage Verification Improvements {#stage-verification-improvements}
67+
68+
#### Expression Language in Arguments
69+
70+
The values specified in `args` do now support [expressions](https://docs.kargo.io/user-guide/reference-docs/expressions) (including [functions](https://docs.kargo.io/user-guide/reference-docs/expressions/#functions)) to dynamically set values based on the context of the `Freight` being verified.
71+
72+
For example, the following defines an argument `commit` with a value set to the commit hash that is being verified using the [`commitFrom` expression function](https://docs.kargo.io/user-guide/reference-docs/expressions#commitfromrepourl-freightorigin):
73+
74+
```yaml
75+
apiVersion: kargo.akuity.io/v1alpha1
76+
kind: Stage
77+
metadata:
78+
name: test
79+
namespace: kargo-demo
80+
spec:
81+
# ...
82+
verification:
83+
analysisTemplates:
84+
- name: kargo-demo
85+
args:
86+
- name: commit
87+
value: ${{ commitFrom("https://github.com/example/repo.git").ID }}
88+
```
89+
90+
#### Support for `ClusterAnalysisTemplate`s
91+
92+
It is now allowed to reference a `ClusterAnalysisTemplate` within the verification configuration of a `Stage`. This enables you as a Kargo operator to define [verification checks](https://docs.kargo.io/user-guide/how-to-guides/verification#configuring-verification) once and use them across multiple `Project`s:
93+
94+
```yaml
95+
apiVersion: kargo.akuity.io/v1alpha1
96+
kind: Stage
97+
metadata:
98+
name: dev
99+
namespace: guestbook
100+
spec:
101+
# ...
102+
verification:
103+
analysisTemplates:
104+
- name: integration-test
105+
kind: ClusterAnalysisTemplate
106+
```
107+
108+
Additionally, the `ClusterAnalysisTemplate`s can now be managed through the Kargo UI. Thanks to @BenHesketh21 for this contribution!
109+
110+
### 🪜 New and Updated Promotion Steps {#new-and-updated-promotion-steps}
111+
112+
- The new [`json-parse`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/json-parse) and [`yaml-parse`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/yaml-parse) steps allow for parsing JSON and YAML files to extract values from them.
113+
- Thanks to @Tchoupinax, the [`git-open-pr`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-open-pr) and [`git-wait-for-pr`](https://docs.kargo.io/user-guide/reference-docs/promotion-steps/git-wait-for-pr) promotion steps do now support Gitea.
114+
115+
### 🖥️ UI Improvements {#ui-improvements}
116+
117+
- Scaling issues in the `Stage` pipeline view have been addressed.
118+
- As noted in another section, `ClusterAnalysisTemplate`s can now be managed through the UI.
119+
120+
### 🛠️ Other Notable Changes {#other-notable-changes}
121+
122+
- You can now opt-in to allow credential lookups for HTTP URLs, refer to `controller.allowCredentialsOverHTTP` in the [chart documentation](https://github.com/akuity/kargo/tree/v1.3.0-rc.1/charts/kargo#controller) for more information.
123+
- "Superstar" (i.e. `**`) glob patterns are now allowed in the [include and exclude paths of a `Warehouse`'s Git subscription](https://docs.kargo.io/user-guide/how-to-guides/working-with-warehouses#git-subscription-path-filtering), making it easier to include or exclude all files and/or directories in nested paths.
124+
- The `Healthy` Condition of a `Stage` will now be `Unknown` instead of `False` when the last `Promotion` failed.
125+
- Long `Stage` names will no longer result in `AnalysisRun` creation failures. (Thanks again @aidan-canva!)
126+
127+
## 🙏 New Contributors {#new-contributors}
128+
129+
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:
130+
131+
* @aarontams
132+
* @nixphix
133+
* @mimartin12
134+
* @joelddiaz
135+
* @abelhoula
136+
137+
**Full Changelog**: https://github.com/akuity/kargo/compare/v1.2.3...v1.3.0

0 commit comments

Comments
 (0)