sub.yml

### YamlMime:AzureCLIGroup
uid: az_deployment_sub
name: az deployment sub
summary: |-
  Manage Azure Resource Manager template deployment at subscription scope.
status: GA
sourceType: Core
directCommands:
- uid: az_deployment_sub_cancel
  name: az deployment sub cancel
  summary: |-
    Cancel a deployment at subscription scope.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: az deployment sub cancel --name
  examples:
  - summary: |-
      Cancel a deployment at subscription scope.
    syntax: az deployment sub cancel -n deployment01
  requiredParameters:
  - isRequired: true
    name: --name -n
    summary: |-
      The deployment name.
- uid: az_deployment_sub_create
  name: az deployment sub create
  summary: |-
    Start a deployment at subscription scope.
  description: |-
    Please specify only one of --template-file FILE | --template-uri URI | --template-spec to input the ARM template.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: >-
    az deployment sub create --location
                             [--confirm-with-what-if]
                             [--handle-extended-json-format]
                             [--name]
                             [--no-prompt {false, true}]
                             [--no-wait]
                             [--parameters]
                             [--proceed-if-no-change]
                             [--query-string]
                             [--template-file]
                             [--template-spec]
                             [--template-uri]
                             [--what-if]
                             [--what-if-exclude-change-types {Create, Delete, Deploy, Ignore, Modify, NoChange, Unsupported}]
                             [--what-if-result-format {FullResourcePayloads, ResourceIdOnly}]
  examples:
  - summary: |-
      Create a deployment at subscription scope from a remote template file, using parameters from a local JSON file.
    syntax: az deployment sub create --location WestUS --template-uri https://myresource/azuredeploy.json --parameters @myparameters.json
  - summary: |-
      Create a deployment at subscription scope from a local template file, using parameters from a JSON string.
    syntax: >-
      az deployment sub create --location WestUS --template-file azuredeploy.json  \
          --parameters '{ \"policyName\": { \"value\": \"policy2\" } }'
  - summary: |-
      Create a deployment at subscription scope from a local template, using a parameter file, a remote parameter file, and selectively overriding key/value pairs.
    syntax: >-
      az deployment sub create --location WestUS --template-file azuredeploy.json  \
          --parameters @params.json --parameters https://mysite/params.json --parameters MyValue=This MyArray=@array.json
  requiredParameters:
  - isRequired: true
    name: --location -l
    summary: |-
      The location to store the deployment metadata.
  optionalParameters:
  - name: --confirm-with-what-if -c
    summary: |-
      Instruct the command to run deployment What-If before executing the deployment. It then prompts you to acknowledge resource changes before it continues.
  - name: --handle-extended-json-format -j
    summary: |-
      Support to handle extended template content including multiline and comments in deployment.
    isDeprecated: true
    deprecateInfo: Option '--handle-extended-json-format/-j' has been deprecated and will be removed in a future release.
  - name: --name -n
    summary: |-
      The deployment name.
  - name: --no-prompt
    defaultValue: "False"
    parameterValueGroup: "false, true"
    summary: |-
      The option to disable the prompt of missing parameters for ARM template. When the value is true, the prompt requiring users to provide missing parameter will be ignored. The default value is false.
  - name: --no-wait
    defaultValue: "False"
    summary: |-
      Do not wait for the long-running operation to finish.
  - name: --parameters -p
    summary: |-
      Supply deployment parameter values.
    description: |-
      Parameters may be supplied from a file using the `@{path}` syntax, a JSON string, or as `<KEY=VALUE>` pairs. Parameters are evaluated in order, so when a value is assigned twice, the latter value will be used. It is recommended that you supply your parameters file first, and then override selectively using KEY=VALUE syntax.
  - name: --proceed-if-no-change
    summary: |-
      Instruct the command to execute the deployment if the What-If result contains no resource changes. Applicable when --confirm-with-what-if is set.
  - name: --query-string -q
    summary: |-
      The query string (a SAS token) to be used with the template-uri in the case of linked templates.
  - name: --template-file -f
    summary: |-
      The path to the template file or Bicep file.
  - name: --template-spec -s
    summary: |-
      The template spec resource id.
  - name: --template-uri -u
    summary: |-
      The URI to the template file.
  - name: --what-if -w
    summary: |-
      Instruct the command to run deployment What-If.
  - name: --what-if-exclude-change-types -x
    parameterValueGroup: "Create, Delete, Deploy, Ignore, Modify, NoChange, Unsupported"
    summary: |-
      Space-separated list of resource change types to be excluded from What-If results. Applicable when --confirm-with-what-if is set.
  - name: --what-if-result-format -r
    defaultValue: "FullResourcePayloads"
    parameterValueGroup: "FullResourcePayloads, ResourceIdOnly"
    summary: |-
      The format of What-If results. Applicable when `--confirm-with-what-if` is set.
- uid: az_deployment_sub_delete
  name: az deployment sub delete
  summary: |-
    Delete a deployment at subscription scope.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: >-
    az deployment sub delete --name
                             [--no-wait]
  examples:
  - summary: |-
      Delete a deployment at subscription scope.
    syntax: az deployment sub delete -n deployment01
  requiredParameters:
  - isRequired: true
    name: --name -n
    summary: |-
      The deployment name.
  optionalParameters:
  - name: --no-wait
    defaultValue: "False"
    summary: |-
      Do not wait for the long-running operation to finish.
- uid: az_deployment_sub_export
  name: az deployment sub export
  summary: |-
    Export the template used for a deployment.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: az deployment sub export --name
  examples:
  - summary: |-
      Export the template used for a deployment at subscription scope.
    syntax: az deployment sub export --name MyDeployment
  requiredParameters:
  - isRequired: true
    name: --name -n
    summary: |-
      The deployment name.
- uid: az_deployment_sub_list
  name: az deployment sub list
  summary: |-
    List deployments at subscription scope.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: az deployment sub list [--filter]
  examples:
  - summary: |-
      List deployments at subscription scope.
    syntax: az deployment sub list
  optionalParameters:
  - name: --filter
    summary: |-
      Filter expression using OData notation. You can use --filter "provisioningState eq '{state}'" to filter provisioningState. To get more information, please visit https://learn.microsoft.com/rest/api/resources/deployments/listatsubscriptionscope#uri-parameters.
    isPreview: true
- uid: az_deployment_sub_show
  name: az deployment sub show
  summary: |-
    Show a deployment at subscription scope.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: az deployment sub show --name
  examples:
  - summary: |-
      Show a deployment at subscription scope.
    syntax: az deployment sub show -n deployment01
  requiredParameters:
  - isRequired: true
    name: --name -n
    summary: |-
      The deployment name.
- uid: az_deployment_sub_validate
  name: az deployment sub validate
  summary: |-
    Validate whether a template is valid at subscription scope.
  description: |-
    Please specify only one of --template-file FILE | --template-uri URI | --template-spec to input the ARM template.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: >-
    az deployment sub validate --location
                               [--handle-extended-json-format]
                               [--name]
                               [--no-prompt {false, true}]
                               [--parameters]
                               [--query-string]
                               [--template-file]
                               [--template-spec]
                               [--template-uri]
  examples:
  - summary: |-
      Validate whether a template is valid at subscription scope.
    syntax: az deployment sub validate --location westus2 --template-file {template-file}
  - summary: |-
      Validate whether a template is valid at subscription scope. (autogenerated)
    syntax: az deployment sub validate --location westus2 --parameters MyValue=This MyArray=@array.json --template-file azuredeploy.json
  requiredParameters:
  - isRequired: true
    name: --location -l
    summary: |-
      The location to store the deployment metadata.
  optionalParameters:
  - name: --handle-extended-json-format -j
    summary: |-
      Support to handle extended template content including multiline and comments in deployment.
    isDeprecated: true
    deprecateInfo: Option '--handle-extended-json-format/-j' has been deprecated and will be removed in a future release.
  - name: --name -n
    summary: |-
      The deployment name.
  - name: --no-prompt
    defaultValue: "False"
    parameterValueGroup: "false, true"
    summary: |-
      The option to disable the prompt of missing parameters for ARM template. When the value is true, the prompt requiring users to provide missing parameter will be ignored. The default value is false.
  - name: --parameters -p
    summary: |-
      Supply deployment parameter values.
    description: |-
      Parameters may be supplied from a file using the `@{path}` syntax, a JSON string, or as `<KEY=VALUE>` pairs. Parameters are evaluated in order, so when a value is assigned twice, the latter value will be used. It is recommended that you supply your parameters file first, and then override selectively using KEY=VALUE syntax.
  - name: --query-string -q
    summary: |-
      The query string (a SAS token) to be used with the template-uri in the case of linked templates.
  - name: --template-file -f
    summary: |-
      The path to the template file or Bicep file.
  - name: --template-spec -s
    summary: |-
      The template spec resource id.
  - name: --template-uri -u
    summary: |-
      The URI to the template file.
- uid: az_deployment_sub_wait
  name: az deployment sub wait
  summary: |-
    Place the CLI in a waiting state until a deployment condition is met.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: >-
    az deployment sub wait --name
                           [--created]
                           [--custom]
                           [--deleted]
                           [--exists]
                           [--interval]
                           [--timeout]
                           [--updated]
  examples:
  - summary: |-
      Place the CLI in a waiting state until a deployment condition is met. (autogenerated)
    syntax: az deployment sub wait --created --name MyDeployment
  requiredParameters:
  - isRequired: true
    name: --name -n
    summary: |-
      The deployment name.
  optionalParameters:
  - name: --created
    defaultValue: "False"
    summary: |-
      Wait until created with 'provisioningState' at 'Succeeded'.
  - name: --custom
    summary: |-
      Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].
  - name: --deleted
    defaultValue: "False"
    summary: |-
      Wait until deleted.
  - name: --exists
    defaultValue: "False"
    summary: |-
      Wait until the resource exists.
  - name: --interval
    defaultValue: "30"
    summary: |-
      Polling interval in seconds.
  - name: --timeout
    defaultValue: "3600"
    summary: |-
      Maximum wait in seconds.
  - name: --updated
    defaultValue: "False"
    summary: |-
      Wait until updated with provisioningState at 'Succeeded'.
- uid: az_deployment_sub_what-if
  name: az deployment sub what-if
  summary: |-
    Execute a deployment What-If operation at subscription scope.
  description: |-
    Please specify only one of --template-file FILE | --template-uri URI | --template-spec to input the ARM template.
  status: GA
  sourceType: Core
  editLink: https://github.com/Azure/azure-cli/blob/dev/src/azure-cli/azure/cli/command_modules/resource/_help.py
  syntax: >-
    az deployment sub what-if --location
                              [--exclude-change-types {Create, Delete, Deploy, Ignore, Modify, NoChange, Unsupported}]
                              [--name]
                              [--no-pretty-print]
                              [--no-prompt {false, true}]
                              [--parameters]
                              [--query-string]
                              [--result-format {FullResourcePayloads, ResourceIdOnly}]
                              [--template-file]
                              [--template-spec]
                              [--template-uri]
  examples:
  - summary: |-
      Execute a deployment What-If operation at a subscription.
    syntax: az deployment sub what-if --location WestUS --template-uri https://myresource/azuredeploy.json --parameters @myparameters.json
  - summary: |-
      Execute a deployment What-If operation at a subscription with ResourceIdOnly format.
    syntax: az deployment sub what-if --location WestUS --template-uri https://myresource/azuredeploy.json --parameters @myparameters.json --result-format ResourceIdOnly
  - summary: |-
      Execute a deployment What-If operation at a subscription without pretty-printing the result.
    syntax: az deployment sub what-if --location WestUS --template-uri https://myresource/azuredeploy.json --parameters @myparameters.json --no-pretty-print
  requiredParameters:
  - isRequired: true
    name: --location -l
    summary: |-
      The location to store the deployment What-If operation metadata.
  optionalParameters:
  - name: --exclude-change-types -x
    parameterValueGroup: "Create, Delete, Deploy, Ignore, Modify, NoChange, Unsupported"
    summary: |-
      Space-separated list of resource change types to be excluded from What-If results.
  - name: --name -n
    summary: |-
      The deployment name.
  - name: --no-pretty-print
    summary: |-
      Disable pretty-print for What-If results. When set, the output format type will be used.
  - name: --no-prompt
    defaultValue: "False"
    parameterValueGroup: "false, true"
    summary: |-
      The option to disable the prompt of missing parameters for ARM template. When the value is true, the prompt requiring users to provide missing parameter will be ignored. The default value is false.
  - name: --parameters -p
    summary: |-
      Supply deployment parameter values.
    description: |-
      Parameters may be supplied from a file using the `@{path}` syntax, a JSON string, or as `<KEY=VALUE>` pairs. Parameters are evaluated in order, so when a value is assigned twice, the latter value will be used. It is recommended that you supply your parameters file first, and then override selectively using KEY=VALUE syntax.
  - name: --query-string -q
    summary: |-
      The query string (a SAS token) to be used with the template-uri in the case of linked templates.
  - name: --result-format -r
    defaultValue: "FullResourcePayloads"
    parameterValueGroup: "FullResourcePayloads, ResourceIdOnly"
    summary: |-
      The format of What-If results.
  - name: --template-file -f
    summary: |-
      The path to the template file or Bicep file.
  - name: --template-spec -s
    summary: |-
      The template spec resource id.
  - name: --template-uri -u
    summary: |-
      The URI to the template file.
commands:
- az_deployment_sub_cancel
- az_deployment_sub_create
- az_deployment_sub_delete
- az_deployment_sub_export
- az_deployment_sub_list
- az_deployment_sub_show
- az_deployment_sub_validate
- az_deployment_sub_wait
- az_deployment_sub_what-if
globalParameters:
- name: --debug
  summary: |-
    Increase logging verbosity to show all debug logs.
- name: --help -h
  summary: |-
    Show this help message and exit.
- name: --only-show-errors
  summary: |-
    Only show errors, suppressing warnings.
- name: --output -o
  defaultValue: "json"
  parameterValueGroup: "json, jsonc, none, table, tsv, yaml, yamlc"
  summary: |-
    Output format.
- name: --query
  summary: |-
    JMESPath query string. See <a href="http://jmespath.org/">http://jmespath.org/</a> for more information and examples.
- name: --subscription
  summary: |-
    Name or ID of subscription. You can configure the default subscription using `az account set -s NAME_OR_ID`.
- name: --verbose
  summary: |-
    Increase logging verbosity. Use --debug for full debug logs.
metadata:
  ms.date: 01/06/2025
  description: Manage Azure Resource Manager template deployment at subscription scope.