Quickstart: Create a custom provider and deploy custom resources

Article
05/12/2021
6 minutes to read

In this quickstart, you create your own resource provider and deploy custom resource types for that resource provider. For more information about custom providers, see Azure Custom Providers Preview overview.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.
To complete the steps in this quickstart, you need to call REST operations. There are different ways of sending REST requests.

Azure CLI
PowerShell

Prepare your environment for the Azure CLI.

Use the Bash environment in Azure Cloud Shell.
If you prefer, install the Azure CLI to run CLI reference commands.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.
- When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with 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.

Azure CLI examples use az rest for REST requests. For more information, see az rest.

The PowerShell commands are run locally using PowerShell 7 or later and the Azure PowerShell modules. For more information, see Install Azure PowerShell.
If you don't already have a tool for REST operations, install the ARMClient. It's an open-source command-line tool that simplifies invoking the Azure Resource Manager API.
After the ARMClient is installed you can display usage information from a PowerShell command prompt by typing: armclient.exe. Or, go to the ARMClient wiki.

Deploy custom provider

To set up the custom provider, deploy an example template to your Azure subscription.

After deploying the template, your subscription has the following resources:

Function App with the operations for the resources and actions.
Storage Account for storing users that are created through the custom provider.
Custom Provider that defines the custom resource types and actions. It uses the function app endpoint for sending requests.
Custom resource from the custom provider.

To deploy the custom provider, use Azure CLI, PowerShell, or the Azure portal:

Azure CLI
PowerShell

This example prompts you to enter a resource group, location, and provider's function app name. The names are stored in variables that are used in other commands. The az group create and az deployment group create commands deploy the resources.

read -p "Enter a resource group name:" rgName &&
read -p "Enter the location (i.e. eastus):" location &&
read -p "Enter the provider's function app name:" funcName &&
templateUri="https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/custom-providers/customprovider.json" &&
az group create --name $rgName --location "$location" &&
az deployment group create --resource-group $rgName --template-uri $templateUri --parameters funcName=$funcName &&
echo "Press [ENTER] to continue ..." &&
read

This example prompts you to enter a resource group, location, and provider's function app name. The names are stored in variables that are used in other commands. The New-AzResourceGroup and New-AzResourceGroupDeployment commands deploy the resources.

$rgName = Read-Host -Prompt "Enter a resource group name"
$location = Read-Host -Prompt "Enter the location (i.e. eastus)"
$funcName = Read-Host -Prompt "Enter the provider's function app name"
$templateUri = "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/custom-providers/customprovider.json"
New-AzResourceGroup -Name $rgName -Location "$location"
New-AzResourceGroupDeployment -ResourceGroupName $rgName -TemplateUri $templateUri -funcName $funcName
Read-Host -Prompt "Press [ENTER] to continue ..."

You can also deploy the solution from the Azure portal. Select the Deploy to Azure button to open the template in the Azure portal.

View custom provider and resource

In the portal, the custom provider is a hidden resource type. To confirm that the resource provider was deployed, navigate to the resource group. Select the option to Show hidden types.

Show hidden resource types

To see the custom resource type that you deployed, use the GET operation on your resource type.

GET https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users?api-version=2018-09-01-preview

Azure CLI
PowerShell

subID=$(az account show --query id --output tsv)
requestURI="https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/users?api-version=2018-09-01-preview"
az rest --method get --uri $requestURI

You receive the response:

{
  "value": [
    {
      "id": "/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users/santa",
      "name": "santa",
      "properties": {
        "FullName": "Santa Claus",
        "Location": "NorthPole",
        "provisioningState": "Succeeded"
      },
      "resourceGroup": "<rg-name>",
      "type": "Microsoft.CustomProviders/resourceProviders/users"
    }
  ]
}

$subID = (Get-AzContext).Subscription.Id
$requestURI = "https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/users?api-version=2018-09-01-preview"

armclient GET $requestURI

You receive the response:

{
  "value": [
    {
      "properties": {
        "provisioningState": "Succeeded",
        "FullName": "Santa Claus",
        "Location": "NorthPole"
      },
      "id": "/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users/santa",
      "name": "santa",
      "type": "Microsoft.CustomProviders/resourceProviders/users"
    }
  ]
}

Call action

Your custom provider also has an action named ping. The code that processes the request is implemented in the function app. The ping action replies with a greeting.

To send a ping request, use the POST operation on your custom provider.

POST https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/ping?api-version=2018-09-01-preview

Azure CLI
PowerShell

pingURI="https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/ping?api-version=2018-09-01-preview"
az rest --method post --uri $pingURI

You receive the response:

{
  "message": "hello <function-name>.azurewebsites.net",
  "pingcontent": {
    "source": "<function-name>.azurewebsites.net"
  }
}

$pingURI = "https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/ping?api-version=2018-09-01-preview"

armclient POST $pingURI

You receive the response:

{
  "pingcontent": {
    "source": "<function-name>.azurewebsites.net"
  },
  "message": "hello <function-name>.azurewebsites.net"
}

Create a resource type

To create the custom resource type, you can deploy the resource in a template. This approach is shown in the template you deployed in this quickstart. You can also send a PUT request for the resource type.

PUT https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users/<resource-name>?api-version=2018-09-01-preview

{"properties":{"FullName": "Test User", "Location": "Earth"}}

Azure CLI
PowerShell

addURI="https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/users/testuser?api-version=2018-09-01-preview"
az rest --method put --uri $addURI --body "{'properties':{'FullName': 'Test User', 'Location': 'Earth'}}"

You receive the response:

{
  "id": "/subscriptions/<sub-ID>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users/testuser",
  "name": "testuser",
  "properties": {
    "FullName": "Test User",
    "Location": "Earth",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "<rg-name>",
  "type": "Microsoft.CustomProviders/resourceProviders/users"
}

$addURI = "https://management.azure.com/subscriptions/$subID/resourceGroups/$rgName/providers/Microsoft.CustomProviders/resourceProviders/$funcName/users/testuser?api-version=2018-09-01-preview"
$requestBody = "{'properties':{'FullName': 'Test User', 'Location': 'Earth'}}"

armclient PUT $addURI $requestBody

You receive the response:

{
  "properties": {
    "provisioningState": "Succeeded",
    "FullName": "Test User",
    "Location": "Earth"
  },
  "id": "/subscriptions/<sub-ID>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceProviders/<provider-name>/users/testuser",
  "name": "testuser",
  "type": "Microsoft.CustomProviders/resourceProviders/users"
}

Custom resource provider commands

Use the custom-providers commands to work with your custom resource provider.

List custom resource providers

Use the list command to display all the custom resource providers in a subscription. The default lists the current subscription's custom resource providers, or you can specify the --subscription parameter. To list for a resource group, use the --resource-group parameter.

az custom-providers resource-provider list --subscription $subID

[
  {
    "actions": [
      {
        "endpoint": "https://<provider-name>.azurewebsites.net/api/{requestPath}",
        "name": "ping",
        "routingType": "Proxy"
      }
    ],
    "id": "/subscriptions/<sub-id>/resourceGroups/<rg-name>/providers/Microsoft.CustomProviders/resourceproviders/<provider-name>",
    "location": "eastus",
    "name": "<provider-name>",
    "provisioningState": "Succeeded",
    "resourceGroup": "<rg-name>",
    "resourceTypes": [
      {
        "endpoint": "https://<provider-name>.azurewebsites.net/api/{requestPath}",
        "name": "users",
        "routingType": "Proxy, Cache"
      }
    ],
    "tags": {},
    "type": "Microsoft.CustomProviders/resourceproviders",
    "validations": null
  }
]

Show the properties

Use the show command to display the custom resource provider's properties. The output format resembles the list output.

az custom-providers resource-provider show --resource-group $rgName --name $funcName

Create a new resource

Use the create command to create or update a custom resource provider. This example updates the actions and resourceTypes.

az custom-providers resource-provider create --resource-group $rgName --name $funcName \
--action name=ping endpoint=https://myTestSite.azurewebsites.net/api/{requestPath} routing_type=Proxy \
--resource-type name=users endpoint=https://myTestSite.azurewebsites.net/api/{requestPath} routing_type="Proxy, Cache"

"actions": [
  {
    "endpoint": "https://myTestSite.azurewebsites.net/api/{requestPath}",
    "name": "ping",
    "routingType": "Proxy"
  }
],

"resourceTypes": [
  {
    "endpoint": "https://myTestSite.azurewebsites.net/api/{requestPath}",
    "name": "users",
    "routingType": "Proxy, Cache"
  }
],

Update the provider's tags

The update command only updates tags for a custom resource provider. In the Azure portal, the custom resource provider's app service shows the tag.

az custom-providers resource-provider update --resource-group $rgName --name $funcName --tags new=tag

"tags": {
  "new": "tag"
},

Delete a custom resource provider

The delete command prompts you and deletes only the custom resource provider. The storage account, app service, and app service plan aren't deleted. After the provider is deleted, you're returned to a command prompt.

az custom-providers resource-provider delete --resource-group $rgName --name $funcName

Next steps

For an introduction to custom providers, see the following article:

Azure Custom Providers Preview overview

Quickstart: Create a custom provider and deploy custom resources

Please rate your experience

Prerequisites

Deploy custom provider

View custom provider and resource

Call action

Create a resource type

Custom resource provider commands

List custom resource providers

Show the properties

Create a new resource

Update the provider's tags

Delete a custom resource provider

Next steps

Feedback