Use virtual machine extensions and an Azure Resource Manager template to deploy custom scripts to Azure Arc Linux and Windows servers

This article provides guidance on how to execute custom scripts to Azure Arc-enabled servers by using virtual machine extensions. Virtual machine extensions are small applications that provide post-deployment configuration and automation tasks such as software installation, anti-virus protection, or a mechanism to run a custom script.

You can use the Azure portal, Azure CLI, an Azure Resource Manager template (ARM template), PowerShell or Linux shell script, or Azure policies to manage the extension deployment to Azure Arc-enabled servers. In the following procedures, you'll use an ARM template to deploy the custom script extension. This extension downloads and executes scripts on virtual machines. It's useful for post deployment configuration, software installation, or any other configuration or management tasks.

Important

The procedures in this article assumes you've already deployed VMs, or servers that are running on-premises or on other clouds, and you have connected them to Azure Arc. If you haven't, the following information can help you automate this.

Prerequisites

  1. Clone the Azure Arc Jumpstart repository.

    git clone https://github.com/microsoft/azure_arc.git
    
  2. As mentioned previously, this guide starts at the point where you already deployed and connected VMs or servers to Azure Arc. The following screenshots show a GCP server that's been connected with Azure Arc and is visible as a resource in Azure.

    A screenshot of a resource group from an Azure Arc-enabled server.

    A screenshot of a connected status from an Azure Arc-enabled server.

  3. Install or update Azure CLI. Azure CLI should be running version 2.7 or later. Use az --version to check your current installed version.

  4. Create an Azure service principal.

    To connect a VM or bare-metal server to Azure Arc, an Azure service principal assigned with the Contributor role is required. To create it, sign in to your Azure account and run the following command. You can also run this command in Azure Cloud Shell.

    az login
    az ad sp create-for-rbac -n "<Unique SP Name>" --role contributor
    

    For example:

    az ad sp create-for-rbac -n "http://AzureArcServers" --role contributor
    

    Output should look like this:

    {
      "appId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "displayName": "AzureArcServers",
      "name": "http://AzureArcServers",
      "password": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "tenant": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
    

Note

We highly recommend that you scope the service principal to a specific Azure subscription and resource group.

To demonstrate the custom script extension, use the following Linux and Windows scripts.

  • Linux: The script will modify the message of the day on the operating system.
  • Windows: The script will install Windows Terminal, Microsoft Edge, 7-Zip, and Visual Studio Code Chocolatey packages on the VM.

Azure Arc-enabled servers custom script extension deployment

  1. Edit the extensions parameters file for Windows or Linux

    A screenshot of an ARM template parameters file.

  2. Provide the following information to match your environment configuration:

    • The VM name as registered in Azure Arc.

    A screenshot of a machine name from an Azure Arc-enabled server.

    • The location of the resource group where you registered the Azure Arc-enabled server.

    A screenshot of an Azure region.

    • A public URI for the script that you would like to run on the servers, in this case use the URL for the script in raw format.
  3. To run either script, use the following commands:

    • Windows:

      powershell -ExecutionPolicy Unrestricted -File custom_script_windows.ps1
      
    • Linux:

      ./custom_script_linux.sh
      
  4. To deploy the ARM template for Linux or Windows, navigate to the deployment folder and run the following command with the templates that match your operating system:

    az deployment group create --resource-group <Name of the Azure resource group> \
    --template-file <The `customscript-template.json` template file location for Linux or Windows> \
    --parameters <The `customscript-template.parameters.json` template file location>
    
  5. After the template deployment has completed it's run, you should see an output as follows:

    A screenshot of an output from an ARM template.

  6. Verify a successful deployment on the Azure Arc-enabled server, in the Azure portal, by selecting Extensions settings. You should see the custom script extension installed.

    A screenshot of a custom script extension.

Another way to verify successful custom script execution is by connecting to the VMs and verifying that the operating system has been configured.

  • For the Linux VM, use SSH to connect the VM and check out the message of the day which was customized by the script:

    A screenshot of an updated daily message.

  • Connect to the Windows VM via RDP and verify that the additional software has been installed: Microsoft Edge, 7-Zip, and Visual Studio Code.

    A screenshot of additional software installed.

Clean up your environment

Complete the following steps to clean up your environment.

Remove the virtual machines from each environment by following the teardown instructions from each guide.