Skip to content

Latest commit

 

History

History
369 lines (292 loc) · 15.4 KB

azure-cli-v2.md

File metadata and controls

369 lines (292 loc) · 15.4 KB
title description ms.date monikerRange
AzureCLI@2 - Azure CLI v2 task
Run Azure CLI commands against an Azure subscription in a PowerShell Core/Shell script when running on Linux agent or PowerShell/PowerShell Core/Batch script when running on Windows agent.
05/14/2024
>=azure-pipelines-2020

AzureCLI@2 - Azure CLI v2 task

:::moniker range=">=azure-pipelines-2020.1"

Run Azure CLI commands against an Azure subscription in a PowerShell Core/shell script when running on Linux agent. Or, run Azure CLI commands against an Azure subscription in a PowerShell/PowerShell Core/batch script when running on Windows agent.

:::moniker-end

:::moniker range="=azure-pipelines-2020"

Run Azure CLI commands against an Azure subscription in a PowerShell Core/shell script when running on Linux agent. Or, run Azure CLI commands against an Azure subscription in a PowerShell/Powershell Core/batch script when running on Windows agent.

:::moniker-end

Syntax

:::moniker range=">=azure-pipelines-2020.1"

# Azure CLI v2
# Run Azure CLI commands against an Azure subscription in a PowerShell Core/Shell script when running on Linux agent or PowerShell/PowerShell Core/Batch script when running on Windows agent.
- task: AzureCLI@2
  inputs:
    azureSubscription: # string. Alias: connectedServiceNameARM. Required. Azure Resource Manager connection. 
    scriptType: # 'ps' | 'pscore' | 'batch' | 'bash'. Required. Script Type. 
    scriptLocation: 'scriptPath' # 'inlineScript' | 'scriptPath'. Required. Script Location. Default: scriptPath.
    scriptPath: # string. Required when scriptLocation = scriptPath. Script Path. 
    #inlineScript: # string. Required when scriptLocation = inlineScript. Inline Script. 
    #arguments: # string. Alias: scriptArguments. Script Arguments. 
    #powerShellErrorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. Optional. Use when scriptType = ps || scriptType = pscore. ErrorActionPreference. Default: stop.
  # Advanced
    #addSpnToEnvironment: false # boolean. Access service principal details in script. Default: false.
    #useGlobalConfig: false # boolean. Use global Azure CLI configuration. Default: false.
    #workingDirectory: # string. Alias: cwd. Working Directory. 
    #failOnStandardError: false # boolean. Fail on Standard Error. Default: false.
    #powerShellIgnoreLASTEXITCODE: false # boolean. Optional. Use when scriptType = ps || scriptType = pscore. Ignore $LASTEXITCODE. Default: false.

:::moniker-end

:::moniker range="=azure-pipelines-2020"

# Azure CLI v2
# Run Azure CLI commands against an Azure subscription in a PowerShell Core/Shell script when running on Linux agent or PowerShell/Powershell Core/Batch script when running on Windows agent.
- task: AzureCLI@2
  inputs:
    azureSubscription: # string. Alias: connectedServiceNameARM. Required. Azure Resource Manager connection. 
    scriptType: # 'ps' | 'pscore' | 'batch' | 'bash'. Required. Script Type. 
    scriptLocation: 'scriptPath' # 'inlineScript' | 'scriptPath'. Required. Script Location. Default: scriptPath.
    scriptPath: # string. Required when scriptLocation = scriptPath. Script Path. 
    #inlineScript: # string. Required when scriptLocation = inlineScript. Inline Script. 
    #arguments: # string. Alias: scriptArguments. Script Arguments. 
    #powerShellErrorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. Optional. Use when scriptType = ps || scriptType = pscore. ErrorActionPreference. Default: stop.
  # Advanced
    #addSpnToEnvironment: false # boolean. Access service principal details in script. Default: false.
    #useGlobalConfig: false # boolean. Use global Azure CLI configuration. Default: false.
    #workingDirectory: # string. Alias: cwd. Working Directory. 
    #failOnStandardError: false # boolean. Fail on Standard Error. Default: false.
    #powerShellIgnoreLASTEXITCODE: false # boolean. Optional. Use when scriptType = ps || scriptType = pscore. Ignore $LASTEXITCODE. Default: false.

:::moniker-end

Inputs

:::moniker range=">=azure-pipelines-2020"

azureSubscription - Azure Resource Manager connection
Input alias: connectedServiceNameARM. string. Required.

Select an Azure Resource Manager service connection for the deployment.


:::moniker-end

:::moniker range=">=azure-pipelines-2020.1"

scriptType - Script Type
string. Required. Allowed values: ps (PowerShell), pscore (PowerShell Core), batch, bash (Shell).

Type of script. Select a bash or pscore script when running on Linux agent. Or, select a batch, ps, or pscore script when running on Windows agent. A pscore script can run on cross-platform agents (Linux, macOS, or Windows).


:::moniker-end

:::moniker range="=azure-pipelines-2020"

scriptType - Script Type
string. Required. Allowed values: ps (Powershell), pscore (Powershell Core), batch, bash (Shell).

Type of script. Select a bash or pscore script when running on Linux agent. Or, select a batch, ps, or pscore script when running on Windows agent. A pscore script can run on cross-platform agents (Linux, macOS, or Windows).


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

scriptLocation - Script Location
string. Required. Allowed values: inlineScript (Inline script), scriptPath (Script path). Default value: scriptPath.

Path to the script.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

scriptPath - Script Path
string. Required when scriptLocation = scriptPath.

Fully qualified path of the script. Use .ps1, .bat, or .cmd when using Windows-based agent. Use .ps1 or .sh when using Linux-based agent or a path relative to the the default working directory.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

inlineScript - Inline Script
string. Required when scriptLocation = inlineScript.

You can write your scripts inline here. When using Windows agent, use PowerShell, PowerShell Core, or batch scripting. Use PowerShell Core or shell scripting when using Linux-based agents. For batch files, use the prefix call before every Azure command. You can also pass predefined and custom variables to this script by using arguments.

The following is an example for PowerShell/PowerShellCore/shell.

az --version 
az account show

The following is an example for batch.

call  az --version 
call az account show

:::moniker-end

:::moniker range=">=azure-pipelines-2020"

arguments - Script Arguments
Input alias: scriptArguments. string.

Arguments passed to the script.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

powerShellErrorActionPreference - ErrorActionPreference
string. Optional. Use when scriptType = ps || scriptType = pscore. Allowed values: stop, continue, silentlyContinue. Default value: stop.

Prepends the line $ErrorActionPreference = 'VALUE' at the top of your PowerShell/PowerShell Core script.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

addSpnToEnvironment - Access service principal details in script
boolean. Default value: false.

Adds the service principal ID, service principal key or workload identity federation token, and tenant ID of the Azure endpoint you chose to the script's execution environment. You can use the servicePrincipalId, servicePrincipalKey or idToken, and tenantId variables in your script.

This is honored only when the Azure endpoint has service principal authentication scheme or workload identity federation authentication scheme.

The following list shows the syntax to access environment variables based on the script type.

  • PowerShell script syntax: $env:servicePrincipalId

  • Batch script syntax: %servicePrincipalId%

  • Shell script syntax: $servicePrincipalId


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

useGlobalConfig - Use global Azure CLI configuration
boolean. Default value: false.

If this input is false, this task will use its own Azure CLI configuration directory. Use this task to run Azure CLI tasks in parallel releases.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

workingDirectory - Working Directory
Input alias: cwd. string.

Current working directory where the script is run. If left blank, this input is the root of the repo (build) or artifacts (release), which is $(System.DefaultWorkingDirectory).


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

failOnStandardError - Fail on Standard Error
boolean. Default value: false.

If this input is true, this task will fail when any errors are written to the StandardError stream. Clear the checkbox to ignore standard errors and instead rely on exit codes to determine the status.


:::moniker-end

:::moniker range=">=azure-pipelines-2020"

powerShellIgnoreLASTEXITCODE - Ignore $LASTEXITCODE
boolean. Optional. Use when scriptType = ps || scriptType = pscore. Default value: false.

If this input is false, the line if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } is appended to the end of your script. This will propagate the last exit code from an external command as the exit code of PowerShell. Otherwise, the line is not appended to the end of your script.


:::moniker-end

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

:::moniker range=">=azure-pipelines-2020"

None.

:::moniker-end

Remarks

What's new in Version task version 2.0

  • Support for PowerShell and PowerShell Core script.
  • PowerShell Core works with cross-platform agents (Linux, macOS, or Windows), make sure the agent has PowerShell version 6 or more.
  • Powershell script works with only Windows agent, make sure the agent has PowerShell version 5 or below.

Prerequisites

  • A Microsoft Azure subscription.
  • Azure Resource Manager service connection to your Azure account.
  • Microsoft hosted agents have Azure CLI pre-installed. However if you are using private agents, install Azure CLI on the computer(s) that run the build and release agent. If an agent is already running on the machine on which the Azure CLI is installed, restart the agent to ensure all the relevant stage variables are updated.

Examples

The following example lists the version of Azure CLI and gets the details of the subscription.

- task: AzureCLI@2
  displayName: Azure CLI
  inputs:
    azureSubscription: <Name of the Azure Resource Manager service connection>
    scriptType: ps
    scriptLocation: inlineScript
    inlineScript: |
      az --version
      az account show

The following example illustrates how to pass arguments to your script.

  • Passing arguments to inline scripts:

    - task: AzureCLI@2
  inputs:
    azureSubscription: <Azure_Resource_Manager_Service_Connection>
    scriptType: 'ps'
    scriptLocation: 'inlineScript'
    arguments: '$(AZURE_STORAGE_ACCOUNT) $(AZURE_STORAGE_KEY)'
    inlineScript: './scripts/publish.ps1 $1 $2'

  • Passing arguments with script path:

    - task: AzureCLI@2
  inputs:
    azureSubscription: <Azure_Resource_Manager_Service_Connection>
    scriptType: 'ps'
    scriptLocation: 'scriptPath'
    arguments: '$(AZURE_STORAGE_ACCOUNT) $(AZURE_STORAGE_KEY)'
    scriptPath: './scripts/publish.ps1'

Requirements

:::moniker range=">=azure-pipelines-2020"

Requirement Description
Pipeline types YAML, Classic build, Classic release
Runs on Agent, DeploymentGroup
Demands None
Capabilities This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions Any
Settable variables Any
Agent version 2.0.0 or greater
Task category Deploy

:::moniker-end

See also