Edit

Tutorial: Use persisted parameters to simplify sequential Azure CLI commands

  • Article

Azure CLI offers persisted parameters that enable you to store parameter values for continued use. In this tutorial, you learn how to work with persisted values, and use these local values to efficiently execute sequential commands.

In this tutorial, you learn to:

  • Use az config param-persist reference commands
  • Execute sequential commands using persisted parameters

This tutorial uses the following Azure CLI commands

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

  1. Install the Azure CLI

    If you prefer, you can also use Azure Cloud Shell to complete the steps in this tutorial. Azure Cloud Shell is an interactive shell environment that you use through your browser. Start Cloud Shell by using one of these methods:

  2. If you're using a local install of the Azure CLI, complete these steps:

    • Sign in using the az login command, then follow the steps displayed in your terminal to complete the authentication process.

      az login

    • This tutorial requires version 2.12.0 or later of the Azure CLI. Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

1. Determine your local directory

Persisted parameter values are stored in the working directory of the Azure storage account used by Azure Cloud Shell. If you're using a local install of the Azure CLI, values are stored in the working directory on your machine.

To find, create or change the working directory being used by the Azure CLI, use these familiar CLI commands.

# List directories
dir

# Make directory
mkdir azCLI

# Change directory
cd azCLI

2. Turn on Persisted parameters

Persisted parameters must be turned on before parameter values can be stored. You receive a warning until az config param-persist moves out of the experimental stage. See Overview: Azure CLI reference types and status to learn about the Azure CLI reference types, status, and support levels.

az config param-persist on

3. Create persisted parameters

To store values for persisted parameters, execute an Azure CLI command of your choice that contains the parameters you want to store. For example, create a resource group and the --location and --name parameters are stored for future use.

  1. Store the location and resource group name.

    # With persisted parameters turned on, create a resource group
az group create --name RG1forTutorial --location eastus2

# See new persisted parameters
az config param-persist show

    {
  "all": {
    "location": "eastus2",
    "resource_group_name": "RG1forTutorial"
  }
}

  2. Using the new persisted parameters, create a storage account.

    # Create a storage account
az storage account create --name sa1fortutorial

# See that storage_account_name has been added to persisted parameters
az config param-persist show

    {
  "all": {
    "location": "eastus2",
    "resource_group_name": "RG1forTutorial",
    "storage_account_name": "sa1fortutorial"
  }
}

  3. Create a persisted parameter without creating a new resource.

    If you don't want to create a new Azure resource, resource_group_name and location parameters can be stored by using noncreate commands like show or list. See Azure CLI persisted parameters for a full list of supported parameters, and the action needed to retain values. This example also removes all parameter values by using the az config param-persist delete command.

    # Clear all persisted parameters for demonstration.
az config param-persist delete --all

# List all storage accounts which will create the `resource_group_name` stored parameter value.
az storage account show --resource-group RG1forTutorial --name sa1fortutorial

# See the new stored value created for resource group.  The storage account name is only stored with a 'create' command.
az config param-persist show

    {
  "all": {
    "resource_group_name": "RG1forTutorial"
  }
}

4. Replace persisted parameters

Replacing a stored parameter value is as simple as executing a command containing a different value.

  1. Create new persisted parameters.

    # Clear all persisted parameters for demonstration
az config param-persist delete --all

# Create a storage account placing "location", "resource_group_name", and "storage_account_name" into persisted parameters
az storage account create --name sa1fortutorial --resource-group RG1forTutorial --location eastus2

# See persisted parameters entries
az config param-persist show

    {
  "all": {
    "location": "eastus2",
    "resource_group_name": "RG1forTutorial",
    "storage_account_name": "sa1fortutorial"
  }
}

  2. Replace the newly stored values.

    # Create a second storage account while changing both the "storage_account_name" and "location" persisted parameters
az storage account create --name sa2fortutorial --location westeurope

# See new persisted parameters
az config param-persist show

    {
  "all": {
    "location": "westeurope",
    "resource_group_name": "RG1forTutorial",
    "storage_account_name": "sa2fortutorial"
  }
}

    Note

    Even if persisted parameters are turned on, you don't have to use them. You can still execute commands with all parameter values specified. However, be aware that with persisted parameters turned on, you will be creating new persisted parameters, or overwriting existing ones.

5. Execute sequential commands

These scripts create an Azure Function app using the Consumption plan.

# Reminder: function app and storage account names must be unique.

# Turn persisted parameters on.
az config param-persist on

# Create a resource group.
az group create --name RG2forTutorial --location westeurope

# Create an Azure storage account in the resource group omitting "--location" and "--resource-group" parameters.
az storage account create \
  --name sa3fortutorial \
  --sku Standard_LRS

# Create a serverless function app in the resource group omitting "--storage-account" and "--resource-group" parameters.
az functionapp create \
  --name FAforTutorial \
  --consumption-plan-location westeurope \
  --functions-version 2

# See the stored parameter values.
az config param-persist show

6. Delete persisted parameters

Use the az config param-persist delete command to remove entries.

# Remove a single persisted parameters entry by specifying the name, not the value
az config param-persist delete resource_group_name

# Remove all persisted parameters entries and do not prompt for confirmation
az config param-persist delete --all --yes

Important

Persisted parameters do not get updated when an Azure resource is deleted.

# delete a resource group
az group delete --name RG1forTutorial

# verify that the resource group no longer exists
az group list --output table

# See that the resource group name remains in persisted parameters
az config param-persist show

7. Turn off persisted parameters

You can turn off persisted parameters by using the az config param-persist off command, but your saved persisted parameters data aren't be deleted.

# Turn persisted parameters off
az config param-persist off

# See that your persisted parameters still exist
az config param-persist show

# Try to create a new resource relying on persisted parameters and receive error "...the following arguments are required:..."
az storage account create --name SA4inAzCLI --sku Standard_LRS

8. Clean up resources

When no longer needed, use the az group delete command to remove the resource group, and all related resources.

az group delete --name RG1forTutorial

See also