-
Notifications
You must be signed in to change notification settings - Fork 460
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Filter Condition Doc * Feedback Incorporated + Better Examples * Feedback Incorporated
- Loading branch information
1 parent
606a16c
commit e0d95a1
Showing
1 changed file
with
132 additions
and
0 deletions.
There are no files selected for viewing
132 changes: 132 additions & 0 deletions
132
docs/user-guide/global-configurations/filter-condition.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| # Filter Condition | ||
|
|
||
| [](https://devtron.ai/pricing) | ||
|
|
||
| ## Introduction | ||
|
|
||
| The [workflows](../creating-application/workflow/) you create in Devtron for managing the CI-CD of your application can be made flexible, for e.g., not all events (such as image builds) generated during the CI stage require progression to the CD stage. Therefore, instead of creating multiple pipelines that cater to complex requirements, Devtron provides you the option of creating filters to make your workflow efficient. | ||
|
|
||
| Using filter conditions, you can control the progression of events. Here are a few general examples: | ||
| * Images containing the label "test" should not be eligible for deployment in production environment | ||
| * Only images having tag versions greater than v0.7.4 should be eligible for deployment | ||
| * Images hosted on Docker Hub should be eligible but not the rest | ||
|
|
||
| --- | ||
|
|
||
| ## Steps to Create a Filter | ||
|
|
||
| {% hint style="info" %} | ||
| **Pre-requisite**: You must have application(s) with CI-CD workflow(s) configured | ||
| {% endhint %} | ||
|
|
||
| 1. From the left sidebar, go to **Global Configurations** → **Filter Condition**. | ||
|
|
||
| 2. Add a filter condition. | ||
|
|
||
|  | ||
|
|
||
| 3. In the **Define Filter condition** section, you get the following fields: | ||
| * **Filter For**: Choose the pipeline upon which the filter should apply. Currently, you can use filter conditions for CD pipelines only. Support for CI pipelines is underway. | ||
|
|
||
|  | ||
|
|
||
| * **Filter Name**: Give a name to the filter. | ||
| * **Description**: (Optional) Add a description to the filter, preferably explaining what it does. | ||
| * **Filter Condition**: You can specify either a pass condition, fail condition, or both the conditions: | ||
| * **Pass Condition**: Only those events that satisfy the condition will be directed through your pipeline. | ||
| * **Fail Condition**: Events that fail the condition will not be directed through your pipeline.. | ||
| * **Use CEL Expression**: You can use `Common Expression Language` (CEL) to define the conditions. Currently, you can create conditions with the help of following variables: | ||
| * **containerImage**: Package that contains all the necessary files and instructions to run an application in a container, e.g., gcr.io/k8s-minikube/kicbase:v0.0.39. It returns a string value in the following format: `<registry>/<repository>:<tag>` | ||
| * **containerRepository**: Storage location for container images, e.g., kicbase | ||
| * **containerImageTag**: Versioning of image to indicate its release, e.g., v0.0.39 | ||
| * **imageLabels**: The label(s) you assign to an image in the CD pipeline, e.g., ["PROD","Stage"]. It returns an array of strings. | ||
|
|
||
| Click **View filter criteria** to check the supported criteria. You get a copy button and a description of each criterion upon hovering. Moreover, you can go to **CEL expression** to learn more about the rules and supported syntax. Check [Examples](#examples) to know more. | ||
|
|
||
|  | ||
|
|
||
| 4. Click **Next**. | ||
|
|
||
| 5. In the **Apply to** section, you get the following fields: | ||
| * **Application**: Choose one or more applications to which your filter condition must apply. | ||
|
|
||
|  | ||
|
|
||
| * **Environment**: Choose one or more environments to which your filter condition must apply. | ||
|
|
||
|  | ||
|
|
||
| {% hint style="info" %} | ||
| Since an application can have more than one environment, the filter conditions apply only to the environment you chose in the **Apply to** section. If you create a filter condition without choosing an application or environment, it will not apply to any of your pipelines. | ||
| {% endhint %} | ||
|
|
||
| 6. Click **Save**. You have successfully created a filter. | ||
|
|
||
|  | ||
|
|
||
| {% hint style="warning" %} | ||
| If you create filters using CEL expressions that result in a conflict (i.e., passing and failing of the same image), fail will have higher precedence | ||
| {% endhint %} | ||
|
|
||
| --- | ||
|
|
||
| ## Examples | ||
|
|
||
| Here's a sample pipeline we will be using for our explanation of [pass condition](#pass-condition) and [fail condition](#fail-condition). | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ### Pass Condition | ||
|
|
||
| Consider a scenario where you wish to make an image eligible for deployment only if its tag version is greater than `v0.0.7` | ||
|
|
||
| The CEL Expression should be `containerImageTag > "v0.0.7"` | ||
|
|
||
|  | ||
|
|
||
| Go to the **Build & Deploy** tab. The filter condition was created specifically for `test` environment, therefore the filter condition would be evaluated only at the relevant CD pipeline, i.e., `test` | ||
|
|
||
|  | ||
|
|
||
| Click **Select Image** for the `test` CD pipeline. The first tab **Eligible images** shows the list and count of images that have satisfied the pass condition since their tag versions were greater than `v0.0.7`. Hence, they are marked eligible for deployment. | ||
|
|
||
|  | ||
|
|
||
| The second tab **Latest images** shows the latest builds (up to 10 images) irrespective of whether they have satisfied the filter condition(s) or not. The ones that have not satisfied the filter conditions get marked as `Excluded`. In other words, they are not eligible for deployment. | ||
|
|
||
|  | ||
|
|
||
| Clicking the filter icon at the top-left shows the filter condition(s) applied to the `test` CD pipeline. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ### Fail Condition | ||
|
|
||
| Consider a scenario where you wish to exclude an image from deployment if its tag starts with the word `trial` or ends with the word `testing` | ||
|
|
||
| The CEL Expression should be `containerImageTag.startsWith("trial") || containerImageTag.endsWith("testing")` | ||
|
|
||
|  | ||
|
|
||
| Go to the **Build & Deploy** tab. The filter condition was created specifically for `devtron-demo` environment, therefore the filter condition would be evaluated only at the relevant CD pipeline, i.e., `devtron-demo` | ||
|
|
||
|  | ||
|
|
||
| Click **Select Image** for the `devtron-demo` CD pipeline. The first tab **Eligible images** shows the list and count of images that have not met the fail condition. Hence, they are marked eligible for deployment. | ||
|
|
||
|  | ||
|
|
||
| The second tab **Latest images** shows the latest builds (up to 10 images) irrespective of whether they have satisfied the filter condition(s) or not. The ones that have satisfied the filter conditions get marked as `Excluded`. In other words, they are not eligible for deployment. | ||
|
|
||
|  | ||
|
|
||
| Clicking the filter icon at the top-left shows the filter condition(s) applied to the `devtron-demo` CD pipeline. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|