Azure Classic: Installation & Configuration

To provision resources with the Pulumi Azure provider, you need to have Azure credentials. Your Azure credentials are never sent to Pulumi.com. Pulumi uses the Azure SDK and the credentials in your environment to authenticate requests from your computer to Azure.

Installation

The Azure Classic provider is available as a package in all Pulumi languages:

• JavaScript/TypeScript: @pulumi/azure
• Python: pulumi-azure
• Go: github.com/pulumi/pulumi-azure/sdk/v4/go/azure
• .NET: Pulumi.Azure
• Java: com.pulumi.azure

Authentication Methods

Pulumi can authenticate to Azure via several methods:

• Azure CLI
• OpenID Connect (OIDC)
• Service Principal with a client secret or certificate
• Managed Service Identity (MSI)

If you’re running the Pulumi CLI locally, in a developer scenario, we recommend using the Azure CLI. For team environments, particularly in Continuous Integration, one of the other options is strongly recommended.

Authenticate using the CLI

The CLI instructions assume you’re using the Azure CLI (az).

Log in to the Azure CLI and Pulumi will automatically use your credentials:

$ az login
A web browser has been opened at https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize. Please continue the login in the web browser. If no web browser is available or if the web browser fails to open, use device code flow with `az login --use-device-code`.

Do as instructed to log in. After completed, az login will return and you are ready to go.

The Azure CLI, and thus Pulumi, will use the Default Subscription by default. You can override the subscription by setting your subscription ID to the id output from az account list’s output:

$ az account list

Pick out the <id> from the list and run:

$ az account set --subscription=<id>

Authenticate with OpenID Connect (OIDC)

OIDC allows you to establish a trust relationship between Azure and another identity provider such as GitHub. Once established, your program can exchange a token issued by the identity provider (in this case, GitHub) for an Azure token. Your Pulumi program running in, for instance, GitHub Actions CI, can then access Azure, without storing any secrets in GitHub.

OIDC Azure Configuration

To configure the trust relationship in Azure, please refer to this guide. This needs to be set up only once.

Additionally, you may find the GitHub OIDC documentation helpful.

OIDC Pulumi Provider Configuration

To use OIDC, either set the Pulumi configuration useOidc via pulumi config set azure:useOidc true or set the environment variable ARM_USE_OIDC to “true”.

Next, supply the provider with an ID token and a URL to use for exchange. In GitHub, we don’t need to configure this since GitHub sets the relevant environment variables ACTIONS_ID_TOKEN_REQUEST_TOKEN and ACTIONS_ID_TOKEN_REQUEST_URL by default and the provider reads them. In other scenarios, set the Pulumi configuration azure:oidcRequestToken or environment variable ARM_OIDC_REQUEST_TOKEN for the token, and configuration azure:oidcRequestUrl or environment variable ARM_OIDC_REQUEST_URL for the URL.

Finally, configure the client and tenant IDs of your Azure Active Directory application. Refer to the above Azure documentation on how to retrieve the IDs, and set them via Pulumi config as azure:clientId and azure:tenantId or via environment variables as ARM_CLIENT_ID and ARM_TENANT_ID.

OIDC Dynamic Credentials with Pulumi ESC

In addition to configuring the Azure provider locally, you also have the option to centralize your configurations using Pulumi ESC (Environments, Secrets, and Configuration). Using this service will enable you to run Pulumi CLI commands with dynamically generated credentials, removing the need to configure and manage your credentials locally.

To do this, you will need to complete the following steps:

Configure OIDC between Pulumi and Azure

Refer to the Configuring OpenID Connect for Azure Guide for the step-by-step process on how to do this.

[Optional] Move Pulumi config to your ESC environment

With Pulumi ESC, you can define and expose environment variables as shown below:

values:
  azure:
    login:
      fn::open::azure-login:
        clientId: <your-client-id>
        tenantId: <your-tenant-id>
        subscriptionId: <your-subscription-id>
        oidc: true
  environmentVariables:
    ARM_USE_OIDC: 'true'
    ARM_CLIENT_ID: ${azure.login.clientId}
    ARM_TENANT_ID: ${azure.login.tenantId}
    ARM_OIDC_REQUEST_TOKEN: ${azure.login.oidc.token}
    ARM_OIDC_TOKEN: ${azure.login.oidc.token}
    ARM_SUBSCRIPTION_ID: ${azure.login.subscriptionId}
    ARM_OIDC_REQUEST_URL: https://api.pulumi.com/oidc

To expose configuration values to Pulumi IaC, you will need to add a second-level key named pulumiConfig and define your desired values underneath it. Further, if your workflow does not require the exposure of environment variables, you can also define those variables under the pulumiConfig block as shown below:

values:
  azure:
    login:
      fn::open::azure-login:
        clientId: <your-client-id>
        tenantId: <your-tenant-id>
        subscriptionId: <your-subscription-id>
        oidc: true
  pulumiConfig:
    azure:useOidc: 'true'
    azure:location: WestUS2
    azure:environment: <your-environment>
    azure:clientId: ${azure.login.clientId}
    azure:tenantId: ${azure.login.tenantId}
    azure:subscriptionId: ${azure.login.subscriptionId}
    azure:oidcRequestToken: ${azure.login.oidc.token}
    azure:oidcToken: ${azure.login.oidc.token}
    azure:oidcRequestUrl: https://api.pulumi.com/oidc

This will ensure that those values are scoped only to your pulumi run.

Import your environment

The last step is to update your project’s stack settings file (Pulumi.<stack-name>.yaml) to import your ESC environment as shown below:

environment:
  - <your-environment-name>

Make sure to replace <your-environment-name> with the name of the ESC environment you created in the previous steps.

You can test that your configuration is working by running the pulumi preview command. This will validate that your Azure resources can be deployed using the dynamically generated credentials in your environment file.

Authenticate using a Service Principal

A Service Principal is an application in Azure Active Directory with a client ID and a tenant ID, exactly like the one used in the OIDC scenario. In this scenario, instead of a pre-configured trust relationship, a client secret is used to authenticate with Azure.

Create your Service Principal and get your tokens

To use a Service Principal, you must first create one. If you already have one, skip this section.

You can create a Service Principal using the Azure CLI, using the Azure Cloud Shell, or using the Azure Portal.

After creating a Service Principal, you will obtain three important tokens:

• appId is the client ID
• password is the client secret
• tenant is the tenant ID

For example, a common Service Principal as displayed by the Azure CLI looks something like this:

{
  "appId": "WWWWWWWW-WWWW-WWWW-WWWW-WWWWWWWWWWWW",
  "displayName": "ServicePrincipalName",
  "name": "http://ServicePrincipalName",
  "password": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "tenant": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY"
}

You also need to obtain a Subscription ID. To retrieve your current Subscription ID, you can use:

$ az account show --query id -o tsv

To list all available subscriptions, you can use:

$ az account list --query '[].{subscriptionName:name,subscriptionId:id}' -o tsv

Make tokens available to Pulumi

Once you have the Service Principal’s authorization tokens, choose one of the ways below to make them available to Pulumi:

Set configuration using pulumi config

Remember to pass --secret when setting clientSecret so that it is properly encrypted:

```bash
$ pulumi config set azure:clientId <clientID>
$ pulumi config set azure:clientSecret <clientSecret> --secret
$ pulumi config set azure:tenantId <tenantID>
$ pulumi config set azure:subscriptionId <subscriptionId>
```

Set configuration using environment variables

$ export ARM_CLIENT_ID=<YOUR_ARM_CLIENT_ID>
$ export ARM_CLIENT_SECRET=<YOUR_ARM_CLIENT_SECRET>
$ export ARM_TENANT_ID=<YOUR_ARM_TENANT_ID>
$ export ARM_SUBSCRIPTION_ID=<YOUR_ARM_SUBSCRIPTION_ID>

$ export ARM_CLIENT_ID=<YOUR_ARM_CLIENT_ID>
$ export ARM_CLIENT_SECRET=<YOUR_ARM_CLIENT_SECRET>
$ export ARM_TENANT_ID=<YOUR_ARM_TENANT_ID>
$ export ARM_SUBSCRIPTION_ID=<YOUR_ARM_SUBSCRIPTION_ID>

> $env:ARM_CLIENT_ID = "<YOUR_ARM_CLIENT_ID>"
> $env:ARM_CLIENT_SECRET = "<YOUR_ARM_CLIENT_SECRET>"
> $env:ARM_TENANT_ID = "<YOUR_ARM_TENANT_ID>"
> $env:ARM_SUBSCRIPTION_ID = "<YOUR_ARM_SUBSCRIPTION_ID>"

Configuration options

Use pulumi config set azure:<option> or pass options to the constructor of new azure.Provider.