From 6bc78b75c7e996f9c4e8ad95f87247cb8880b7ad Mon Sep 17 00:00:00 2001 From: Gerd Oberlechner Date: Mon, 24 Feb 2025 22:47:25 +0100 Subject: [PATCH 1/3] pipeline bicep step docs Signed-off-by: Gerd Oberlechner --- docs/bicep.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 156 insertions(+), 4 deletions(-) diff --git a/docs/bicep.md b/docs/bicep.md index 82f32bde3..105be3856 100644 --- a/docs/bicep.md +++ b/docs/bicep.md @@ -1,10 +1,162 @@ -# WIP outline - Bicep Templates for ARO HCP +# Bicep Templates for ARO HCP This chapter outlines * the role of Bicep templates in deploying the required Azure infrastructure for ARO HCP * the structure of templates, modules and configuration used in this project -* the pipeline ARM step in depth * considerations for writing Bicep code that can act in cross-subscription scenarios -* output chaining -* dry-runs + +## Overview & Purpose + +The Bicep templates are responsible for provisioning the infrastructure required for ARO HCP, ensuring that resources across different architectural scopes — such as the Service Cluster Scope and the Management Cluster Scope — are deployed and interconnected correctly. Each scope has its own dedicated infrastructure components, including compute resources, networking configurations, storage solutions, and security mechanisms, all of which must be properly integrated to support the overall system. + +Beyond provisioning infrastructure, the Bicep templates also manage access control by configuring managed identities and assigning Azure RBAC roles as needed. This ensures that each deployed component has the correct permissions and authentication mechanisms in place to operate securely within its designated scope. The templates ensure that all required dependencies, identities, and permissions are correctly configured to support reliable system operation. + +## Bicep Structure + +### Templates + +Top-level Bicep templates that correlate to an architectural scope reside in the `templates` directory. These templates are prefixed according to their respective [scope](high-level-architecture.md). + +* `global*.bicep` templates for the global scope +* `region*.bicep` templates for the overall region scope +* `svc*.bicep` templates for the service cluster scope +* `mgmt*.bicep` templates for the region cluster scope + +There are two additional prefixes for special purposes + +* `dev*.bicep` templates that are exclusively required for matters of the DEV environment +* `output*.bicep` templates that allow carrying information between architectural scopes + +### Modules + +Single bicep templates can become too complex and hard to maintain big at times. To mitigate this, we group resouces by purpose and move them as dedicated bicep files into the `modules` directory. + +Modules provide a structured way to organize and reuse infrastructure definitions. While modules enhance maintainability by breaking down complex deployments into manageable components, they also serve a critical function in switching execution context during a Bicep template deployment. See the section about [Cross-Subscription deployments](#cross-subscription-deployments) for more details. + +### Parameters + +The configuration directory contains Bicep parameter files (.bicepparam). Each top-level Bicep template has a corresponding Bicep parameter file to define its configuration. These parameter files are Go templates, which are processed dynamically to generate final configuration files based on the targeted cloud, deployment environment, and region. The configuration references used in these Bicep parameter Go templates adhere to the configuration management concept described in configuration.md. This... + +## Deploying Bicep templates + +In ARO HCP, we deploy Bicep templates via [pipeline](pipeline.md) files by supporting a dedicated step type for ARM/Bicep deployments. + +> [!IMPORTANT] +> Read the documentation about [pipeline] files and their general format and functionality. The following documentation covers only the Bicep specific information + +```yaml +$schema: "pipeline.schema.v1" + +serviceGroup: Microsoft.Azure.ARO.HCP.Region +rolloutName: Region Rollout +resourceGroups: +- name: {{ .regionRG }} (1) + subscription: {{ .svc.subscription }} (2) + steps: + - name: region (3) + action: ARM (4) + template: templates/my-template.bicep (5) + parameters: configurations/my-template.tmpl.bicepparam (6) + deploymentLevel: ResourceGroup/Subscription (7) + variables: (8) + ... + [outputOnly: true/false] (9) +``` + +1. The name of Azure resourcegroup targeted by this deployment +2. The name of the Azue Subscription targeted by this deployment. When deploying via EV2, this needs to reference an [EV2 subscription key](https://ev2docs.azure.net/features/service-artifacts/actions/subscriptionProvisioningParameters.html#subscription-key) +3. The name of the Azure deployment +4. The action type `ARM` marks this step as ARM/Bicep deployment action +5. File reference to the Bicep template, relative to the location of the pipeline file +6. File reference to the Bicep parameter file, relative to the location of the pipeline file. +7. The deployment level for the Bicep template. +8. covered in detail in the [Output templates and output chaining](#output-templates-and-output-chaining) section +9. If true, a Bicep step is not allowed to declare any resources and can only provide output by inspecting `existing` resources. See details in the [output templates and output chaining](#output-templates-and-output-chaining) and [dry runs](#dry-runs) sections. + +## Cross-Subscription deployments + +By default, a Bicep template deployment runs within a specified subscription and resource group. However, when a deployment needs to reach out to another resource group or subscription, modules are the mechanism to switch the deployment scope. Declaring a module and specifying its scope results in the creation of a separate Azure deployment within the targeted subscription and resource group. This approach is essential in various scenarios because the infrastructure for ARO HCP spreads accross various subscriptions and resourcegroups. You can find details about this in [SD-DDR-0051: ARO HCP Azure Deployment Layout](https://docs.google.com/document/d/1a5d-LPbgYMozLyRle7sJRI1h10zDurqFT_jnMGWwRwY/edit?tab=t.0#heading=h.hzsa87ps5uhr). + +For example, during the regional DNS zone setup, the deployment also needs to interact with the parent DNS zone located in another resource group—and depending on the environment, even in a different subscription—to set up the zone delegation properly. + +Here is the essence of the implementation the the DNS scenario. region.bicep template accepts the Azure resource ID of the parent zones as input parameter, uses the helper functions in resource.bicep to extract the subscription and resourcegroup bits from the ID and builds the proper scope from them. + +```bicep +// region.bicep +param svcParentZoneResourceId string +import * as res from 'resource.bicep' +var svcParentZoneRef = res.dnsZoneRefFromId(svcParentZoneResourceId) +module regionalSvcZoneDelegation '../modules/dns/zone-delegation.bicep' = { + name: '${regionalDNSSubdomain}-svc-zone-deleg' + scope: resourceGroup(svcParentZoneRef.resourceGroup.subscriptionId, svcParentZoneRef.resourceGroup.name) + params: ... +} +``` + +## Output templates and output chaining + +Not all configuration provided via `bicepparam` files can be statically defined in the [configuration management](configuration.md), e.g. Azure resource IDs containing dynamic subscription IDs that are only known at the time of deployment, as we saw in the example in the [Cross-Subscription deployments](#cross-subscription-deployments) section. + +We can pass such dynamic parameter values by chaining multiple bicep modules, one providing the required dynamic values as output and the other one consuming them. This chaining approach is not a Bicep feature but something offered by our pipelines. + +In the following example the `region.bicep` template wants to setup DNS zone delegation from the parent zone to the regional zone. For that it requires the Azure resource ID of the parent zone. The `output-global.bicep` provides the `svcParentZoneResourceId` as an output parameter, while `region.tmpl.bicepparam` asks for it as input parameter. The pipeline hooks up both steps to pass the value from one to the other. + +```bicep +// output-global.bicep +... +output svcParentZoneResourceId = svcParentZone.id (1) + +// region.tmpl.bicepparam +param svcParentZoneResourceId = '__svcParentZoneResourceId__' (2) +``` + +With this in place we can hook up both bicep templates in a pipeline file. + +```yaml +... +resourceGroups: +- name: {{ .global.rg }} (3) + subscription: {{ .global.subscription }} + steps: + - name: global-output + action: ARM + template: templates/output-global.bicep + parameters: configurations/output-global.tmpl.bicepparam + outputOnly: true (4) +- name: {{ .regionRG }} (5) + subscription: {{ .svc.subscription }} + steps: + - name: region + action: ARM + template: templates/region.bicep + parameters: configurations/region.tmpl.bicepparam + variables: + ... + - name: svcParentZoneResourceId (6) + input: (7) + step: global-output + name: svcParentZoneResourceId +``` + +1. declare the output +2. declare the input - the value `__svcParentZoneResourceId__` needs to match the name of the parameter +3. run the `output-global.bicep` template towards the global scope where the parent DNS zone are managed +4. since this is an output only bicep template, we mark it as such. this makes it safe to run during dry-runs +5. run the `region.bicep` template towards the regional scope where the DNS subzones are managed +6. declare the input for the `svcParentZoneResourceId` in the `region.tmpl.bicepparam` parameterfile +7. specify where the input value is coming from + +> [!NOTE] +> Why can't we pass in subscription and resourcegroup information to bicepparam files similar to how we do it in steps (3) and (4) as they are apparently part of our [configuration](configuration.md)? +> +> This might work in simple environments, where all subscriptions are known upfront, e.g. in [config.yaml](../config/config.yaml) `global.subscription` is a concrete value pointing to our RH DEV subscription. For more complex scenarios in MSFTs environments (see [config.msft.yaml](../config/config.msft.yaml)), such subscription configuration does not hold actual subscription names or IDs, but symbolic subscription references that make sense for MSFTs deployment orchestration solution EV2. The real subscription IDs are only known during deployment time, when a Bicep template runs within an actual subscription. + +## Dry-runs + +We leverage ARMs [what-if](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-what-if?tabs=azure-powershell) functionlity to conduct some basic testing on Bicep templates changes before running them towards any environment. + +Bicep deployments will not provide any `output` values required for [output chaining](#output-templates-and-output-chaining) when running in `what-if` mode. To mitigate this, depend only on `outputOnly` steps backed by an `output-*.bicep` template. Our pipeline PR checks will execute proper deployments for `outputOnly: true` steps even during pipeline dry-runs, to ensure expected output chaining variables can be passed between steps. There are safeguards in place to ensure an `outputOnly: true` step does not declare and potentially modify any Azure resources. + +> [!WARNING] +> `what-if` runs do not replace proper testing as the functionality is limited and heavily depends on the preflight checks of the involved Azure Resource Providers. Don't assume a template will deploy successfuly when it passes a dry-run. But rest assured the deployment will fail with certainty if the dry-run fails. From 3760a20f4f9b1b5e6262dfcd3aebe48b70c7c853 Mon Sep 17 00:00:00 2001 From: Gerd Oberlechner Date: Tue, 25 Feb 2025 11:27:48 +0100 Subject: [PATCH 2/3] pipeline doc Signed-off-by: Gerd Oberlechner --- docs/README.md | 14 ++- docs/pipeline-concept.md | 182 +++++++++++++++++++++++++++++++++++++++ docs/pipeline.md | 9 -- docs/terminology.md | 17 ++++ 4 files changed, 211 insertions(+), 11 deletions(-) create mode 100644 docs/pipeline-concept.md delete mode 100644 docs/pipeline.md diff --git a/docs/README.md b/docs/README.md index b70f6995a..007a8cfd9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,11 +18,21 @@ Welcome to the **ARO HCP** documentation. This guide provides an overview of the - Guidelines and limitations 1. **Deployment Concept** - - [Pipelines concept](pipeline.md) + - [Pipelines concept](pipeline-concept.md) - Deployment artifacts - [Azure infrastructure Bicep templates](bicep.md) - [Helm Charts](helm.md) - [Container images](images.md) - - [Deploying to environments](deployment.md) + +1. **Deploying ARO HCP** + - [Pipelines](pipelines.md) + - documents existing pipelines + - Red Hat development tenant deployments + - [Personal ARO HCP instance](personal-dev.md) + - [Integrated DEV instance](integrated-dev.md) + - [CS PR instance](cspr.md) + - [Personal perfscale instance](perscale-deployment.md) + - MSFT deployments + - [MSIT INT](msit-int.md) 1. **[Terminology](terminology.md)** diff --git a/docs/pipeline-concept.md b/docs/pipeline-concept.md new file mode 100644 index 000000000..36ba40857 --- /dev/null +++ b/docs/pipeline-concept.md @@ -0,0 +1,182 @@ +# ARO HCP Deployment Pipelines + +ARO HCP deployment pipelines define the rollout process for infrastructure and services across different [Azure environments](environments.md). These pipelines follow a custom YAML format that allows defining deployment steps targeting specific Azure subscriptions, resource groups, and AKS clusters. + +This document is intended for ARO HCP developers and SREs. It provides guidance on writing pipeline files that cover the deployment of different aspects of ARO HCP. Readers will learn how to structure pipeline files, define steps, and combine them effectively to deploy infrastructure and services. + +## Pipeline File Structure + +ARO HCP pipelines are defined in a custom YAML format that describes the deployment context, specifying which Azure subscriptions and resource groups are targeted. The pipeline file consists of high-level attributes that set the scope for deployments. + +The following example illustrates the top-level structure of a pipeline file: + +```yaml +serviceGroup: Microsoft.Azure.ARO.HCP.Region (1) +rolloutName: Region Rollout (2) +resourceGroups: (3) +- name: {{ .global.rg }} (4) + subscription: {{ .global.subscription }} (5) + aksCluster: {{ .global.aksCluster }} (6) + steps: [] (7) +``` + +1. Defines the logical grouping of services being deployed. This value can be freely chosen as long as it is unique and prefixed with `Microsoft.Azure.ARO.HCP`. +2. `rolloutName`: Specifies a human-readable name for the rollout process. +3. `resourceGroups`: A list of deployment contexts targeted by the pipeline. +4. `resourceGroups.name`: The name of the resource group. Can be configured statically or dynamically using configuration lookups via Go template syntax. +5. `resourceGroups.subscription`: The Azure subscription ID associated with the resource group. Can be configured statically or dynamically using configuration lookups via Go template syntax. +6. `resourceGroups.aksCluster`: Optional. Specifies the name of the AKS cluster that deployment steps should target. Can be configured statically or dynamically using configuration lookups via Go template syntax. + +## Pipeline Steps + +A subscription/resourcegroup/AKS execution context needs to define a sequence of deployment steps. These steps define what needs to be deployed, how, and in what order. + +### Step Structure + +A step is defined using a set of properties that determine its function and execution behavior. + +```yaml +... +resourceGroups: +- ... + steps: + - name: step-name (1) + action: step-type (2) + dependsOn: (3) + - other-step-name + (4) +``` + +1. `name`: An identifier for the step that is unique within the entire pipeline file. +2. `action`: The type of step being executed. This can be an ARM step, a shell step, or any other supported step type (see [Step Types](#step-types)). +3. `dependsOn`: An optional list of other step names that must complete successfully before this step is executed. Dependencies must be cycle-free to ensure a valid execution order. +4. Step type specific properties that define the behavior of the step. + +### Step Types + +ARO HCP pipelines support multiple step types, each designed for a specific deployment scenario. The two most commonly used types are: + +#### ARM / Bicep Step + +Used for deploying Azure infrastructure using Bicep templates. These steps allow defining and updating Azure resources declaratively. + +```yaml + ... + steps: + - name: region-infra + action: ARM (1) + template: templates/region.bicep (2) + parameters: configurations/region.tmpl.bicepparam (3) + deploymentLevel: ResourceGroup (4) +``` + +1. `action: ARM` marks the step as an ARM step. +2. `template`: The path to the Bicep template file that defines the infrastructure to be deployed. +3. `parameters`: The path to the Bicep parameters file that provides input values for the template. +4. `deploymentLevel`: The scope at which the deployment should occur. Valid values are `ResourceGroup` and `Subscription`. + +Detailed information about Bicep templates in general and how to use the ARM step type, can be found in the [Bicep documentation](bicep.md#deploying-bicep-templates). + +#### Shell Step + +Execute shell commands or scripts within the pipeline environment. Shell steps are commonly used for deploying services via Helm charts, or performing other automation tasks. + +```yaml + ... + steps: + - name: upgrade-istio + action: Shell (1) + script: make deploy (2) + variables: (3) + - name: TARGET_VERSION (4) + configRef: svc.istio.targetVersion (5) + - name: RETRIES + value: 5 (6) +``` + +1. `action: Shell` marks the step as a shell step. +2. `script`: The shell command to be executed. This can be a single command or a script file. +3. `variables`: A list of environment variables that are set before executing the script. +4. `variables.name`: The name of the environment variable. +5. `variables.configRef`: The [configuration reference](configuration.md) to look up the value for the environment variable. +6. `variables.value`: Alternatively static values can be provided for the environment variable. + +Currently, the following list of tools can be used within shell scripts: + +- az +- helm +- kubectl +- jq + +>[!WARNING] +> TODO: we need to alignt the tool versions between the EV2 execution context and the Red Hat pipeline runner. + +Shell steps are mostly used for service deployments leveraging [Helm charts](helm.md). + +### Step execution context + +All steps share a common execution context: + +#### Azure session + +When executing step, an Azure session is provided for the defined subscription (`resourceGroups.subscription`) and resourcegroup (`resourceGroups.name`), allowing authenticated Azure operations. The identity used for this session is provided in the [configuration](configuration.md) as `aroDevopsMsiId`. + +Please note that this identity does not have access to all Azure resources in our subscriptions and resourcegroups by default. The necessary permissions need to be granted explicitly. You can observe this in various Bicep templates, where this identity is granted specific permissions, e.g. on Key Vaults or storage accounts. + +#### Azure resource groups + +The resourcegroup (`resourceGroups.name`) is pre-created before step execution starts. + +#### AKS cluster + +If an `resourceGroups.aksCluster` is specified, the `KUBECONFIG` environment variable is set and allows cluster admin interaction withe the AKS cluster. This is mostly relevant for `Shell` steps. + +## Pipeline Deployment Scope + +A pipeline is the smallest unit of deployment in ARO HCP. This means that all steps within a pipeline are executed from start to finish—there is no concept of executing a single step in only. + +A pipeline typically corresponds to one architectural scope, such as global, regional, service or management. More details about these scopes can be found in the [architecture documentation](high-level-architecture.md). However, pipelines are not strictly limited to a single architectural scope. In some cases, cross-scope deployments are necessary, e.g. the regional DNS zone needs delegation from its parent, which resides in the global scope. You can find elaborate details about this in the [Bicep documentation](bicep.md#cross-subscription-deployments). + +In most cases, each service has its own dedicated pipeline. This allows services to be rolled out individually. + +By structuring pipelines appropriately, deployments can be managed efficiently while ensuring the right level of isolation and access across scopes. + +## Pipeline Execution in Different Environments + +The various target environments for ARO HCP infrastructure and service deployment have very unique requirements on the rollout process, involving different tools and policies. Microsoft environments require deployments to be driven by ADO and their [EV2](https://ev2docs.azure.net) deployment service, which cannot be used for non-Microsoft environments. The Red Hat developemnt environment on the other hand does not have such strictly regulated rollout processes and we chose to use GitHub actions as the overall driver for rollouts. + +The custom pipeline format supports multiple deployment environments and tools to accommodate these different execution requirements and tooling. + +> [!TIP] +> You can find out more about the different environments and ARO HCP instances in the [environments documentation](environments.md). + +### Microsoft ADO and EV2 + +For Microsoft tenant deployments, we run ADO pipelines that use a dedicated EV2 generator. This generator translates pipeline files into EV2 manifests, uploads them to EV2, and performs an SDP rollout. + +The pipeline format, with its resource group and subscription references and the list of steps, translates very well to the EV2 format. For example, the ARM and Shell step types are built-in step types in EV2. More details about the generation process will be provided in a dedicated document (tbd). + +### Red Hat Pipeline Runner + +Within the Red Hat development tenant for ARO HCP, we have two primary use cases for deployments. + +Developers and SREs deploy their personal development ARO HCP instances using Makefile targets, such as `make infra.all`. Behind the scene, this executes a series of pipelines using a custom pipeline runner that interprets the pipeline files and takes actions accordingly, adhering to the defined expectations described in the [Step execution context](#step-execution-context) section. + +In addition, some shared ARO HCP instances are continuously reconciled on each change in the ARO-HCP repository using GitHub Actions. These actions leverage the same Makefile targets and the same pipeline executor as developers and SREs. + +The custom pipeline runner can be found in [tooling/templatize](tooling/templatize). + +To manually run a pipeline you can use the `templatize.sh` script, e.g. to deploy `my-pipeline.yaml` with the `personal-dev` environment architetype in the `public` cloud, run + +```sh +./templatize.sh personal-dev my-pipeline.yaml -P run -c public +``` + +The pipeline runner supports a dry-run mode that allows you to simulate the execution of a pipeline without actually deploying any resources. This is useful for verifying the correctness of the pipeline file and the expected behavior of the steps. Add the `-d` option to the `templatize.sh` command to enable dry-run mode: + +```sh +./templatize.sh personal-dev my-pipeline.yaml -P run -c public -d +``` + +> [!IMPORTANT] +Please consult the step specific documentation for more details on the behavior of each step type during dry-run. diff --git a/docs/pipeline.md b/docs/pipeline.md deleted file mode 100644 index 5b9a17038..000000000 --- a/docs/pipeline.md +++ /dev/null @@ -1,9 +0,0 @@ -# WIP outline - Pipeline concept - -- pipeline file format - - service group requirements - - targeting regions, subscriptions and AKS clusters - - available az context - - available kubeconfig file - - permissions - - general step functionality (variables, dependsOn) diff --git a/docs/terminology.md b/docs/terminology.md index e5331cdf1..9eafef6b5 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -79,3 +79,20 @@ - **Abbreviation**: ACM - **References**: - [Documentation](https://www.redhat.com/en/technologies/management/advanced-cluster-management) + +## Microsoft Terminology + +### Azure DevOps + +- **Definition**: Microsoft's cloud-based service for collaborating on code development. Includes source code hosting, CI/CD, and more. +- **Abbreviation**: ADO +- **References**: + - [Docs](https://learn.microsoft.com/en-us/azure/devops/) + - [ARO HCP ADO Pipelines](https://msazure.visualstudio.com/AzureRedHatOpenShift/_build?definitionScope=%5COneBranch%5Chcp) + +### EV2 + +- **Definition**: Microsoft automated platform for deploying Azure resources accross clouds. +- **References**: + - [Docs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview) + - [ARO HCP EV2](https://ev2docs.azure.net/getting-started/overview.html) From 01c94cf6bc86110c370a0fc4b7a59eb5611ea45a Mon Sep 17 00:00:00 2001 From: Gerd Oberlechner Date: Mon, 3 Mar 2025 15:14:00 +0100 Subject: [PATCH 3/3] service deploy doc Signed-off-by: Gerd Oberlechner --- docs/README.md | 3 ++- docs/helm.md | 7 ------- docs/pipeline-concept.md | 35 ++++++++++++++++++++++++++++++----- 3 files changed, 32 insertions(+), 13 deletions(-) delete mode 100644 docs/helm.md diff --git a/docs/README.md b/docs/README.md index 007a8cfd9..a704a87a6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,9 +19,10 @@ Welcome to the **ARO HCP** documentation. This guide provides an overview of the 1. **Deployment Concept** - [Pipelines concept](pipeline-concept.md) + - [Service deployment concept](service-deployment-concept.md) - Deployment artifacts - [Azure infrastructure Bicep templates](bicep.md) - - [Helm Charts](helm.md) + - [Helm Charts](service-deployment-concept.md#helm-chart) - [Container images](images.md) 1. **Deploying ARO HCP** diff --git a/docs/helm.md b/docs/helm.md deleted file mode 100644 index 7111c93b6..000000000 --- a/docs/helm.md +++ /dev/null @@ -1,7 +0,0 @@ -# WIP outline - Helm Charts - -- why helm -- helm chart structure -- makefiles and pipelines -- configuration and lookups -- dry-runs diff --git a/docs/pipeline-concept.md b/docs/pipeline-concept.md index 36ba40857..83db1394c 100644 --- a/docs/pipeline-concept.md +++ b/docs/pipeline-concept.md @@ -75,6 +75,8 @@ Used for deploying Azure infrastructure using Bicep templates. These steps allow 3. `parameters`: The path to the Bicep parameters file that provides input values for the template. 4. `deploymentLevel`: The scope at which the deployment should occur. Valid values are `ResourceGroup` and `Subscription`. +This step type supports dry-run testing via [what-if](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-what-if?tabs=azure-powershell). + Detailed information about Bicep templates in general and how to use the ARM step type, can be found in the [Bicep documentation](bicep.md#deploying-bicep-templates). #### Shell Step @@ -103,13 +105,36 @@ Execute shell commands or scripts within the pipeline environment. Shell steps a Currently, the following list of tools can be used within shell scripts: -- az -- helm -- kubectl -- jq +- `az` +- `helm` +- `kubectl` +- `jq` +- `make` +- ... + +See the [Shell extension](https://ev2docs.azure.net/features/service-artifacts/actions/shell-extensions/overview.html) documentation for more details. + +Shell steps also support dry-run testing, but such scripts need to explicitely implement it and mark support for it with the `dryRun` property. + +```yaml + ... + steps: + - ... + action: Shell + ... + dryRun: (1) + variables: + - name: DRY_RUN (2) + value: "true" +``` + +1. `dryRun`: Marks the step as supporting dry-run testing. +2. `variables`: A list of environment variables that are set before executing the script. + +It is the scripts responsibility to react to the `DRY_RUN` environment variable correctly and not perform any real update actions on the target subscription/resourcegroup/AKS cluster. >[!WARNING] -> TODO: we need to alignt the tool versions between the EV2 execution context and the Red Hat pipeline runner. +> TODO: we need to align the tool versions between the EV2 execution context and the Red Hat pipeline runner. Shell steps are mostly used for service deployments leveraging [Helm charts](helm.md).