Azure Native: Installation & Configuration
To provision resources with the Pulumi Azure Native 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 Native provider is available as a package in all Pulumi languages:
- JavaScript/TypeScript:
@pulumi/azure-native
- Python:
pulumi-azure-native
- Go:
github.com/pulumi/pulumi-azure-native/sdk/go/azure
- .NET:
Pulumi.AzureNative
- Java:
com.pulumi.azurenative
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.
az login --service-principal
). For such cases, authenticate using the Service Principal method instead.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.
az cloud set --name <Cloud>
, where <Cloud>
is one of AzureUSGovernment
or AzureChinaCloud
.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 or Azure DevOps. Once established, your program can exchange an ID token issued by the identity provider for an Azure token. Your Pulumi program running in the identity provider’s service, for instance, GitHub Actions CI or Azure DevOps Pipelines, 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.
OIDC Pulumi Provider Configuration
To use OIDC, either set the Pulumi configuration useOidc
via pulumi config set azure-native:useOidc true
or set the
environment variable ARM_USE_OIDC
to “true”.
Next, supply the Pulumi provider with the ID token to exchange for an Azure token. This step depends on the service (identity provider) your program will run on.
- On GitHub, you don’t need to configure anything since GitHub sets the relevant environment variables by default and the Pulumi provider reads them automatically.
- Other identity providers offer a way to access the ID token. For instance, in GitLab CI/CD jobs, the ID token is available
via the environment variable
GITLAB_OIDC_TOKEN
. Configure the Pulumi provider to use the ID token by assigning it to the Pulumi configurationazure-native:oidcToken
or the environment variableARM_OIDC_TOKEN
. - Some identity providers, such as Azure Workload Identity, supply the ID token in a file. In this case, set the
Pulumi configuration
azure-native:oidcTokenFilePath
or the environment variableARM_OIDC_TOKEN_FILE_PATH
to the path of the file.
If your identity provider does not offer an ID token directly but it does offer a way to exchange a local bearer token for an ID token, you can configure this exchange as well. This is a rare case that you won’t need unless the identity provider’s documentation explicitly requests it. In that case, set one of the following pairs:
- both the
azure-native:oidcRequestToken
andazure-native:oidcRequestUrl
Pulumi configuration values, or - both the
ARM_OIDC_REQUEST_TOKEN
andARM_OIDC_REQUEST_URL
environment variables.
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-native:clientId
and azure-native: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 Native 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_TOKEN: ${azure.login.oidc.token}
ARM_SUBSCRIPTION_ID: ${azure.login.subscriptionId}
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-native:useOidc: 'true'
azure:useOidc: 'true'
azure-native:environment: <your-environment>
azure-native:clientId: ${azure.login.clientId}
azure-native:tenantId: ${azure.login.tenantId}
azure-native:subscriptionId: ${azure.login.subscriptionId}
azure-native:oidcToken: ${azure.login.oidc.token}
This will ensure that those values are scoped only to your pulumi
run.
pulumiConfig
can also be referenced directly from within your Pulumi program code. This is done using the same method to reference values from your project’s stack settings file. You can see examples of how to do this in the Accessing Configuration from Code section of the Pulumi documentation.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.
az logout
command.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 IDtenant
is the tenant IDpassword
is the client secret
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-native:clientId <clientID>
$ pulumi config set azure-native:clientSecret <clientSecret> --secret
$ pulumi config set azure-native:tenantId <tenantID>
$ pulumi config set azure-native:subscriptionId <subscriptionId>
# optional default location, otherwise set in code
$ pulumi config set azure-native:location <locationName>
```
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_LOCATION_NAME=<YOUR_ARM_LOCATION_NAME>
$ 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_LOCATION_NAME=<YOUR_ARM_LOCATION_NAME>
> $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>"
> $env:ARM_LOCATION_NAME = "<YOUR_ARM_LOCATION_NAME>"
Alternatively, you can use a certificate instead of a password as client secret. In this case, configure the provider
as shown above except use clientCertPath
/ARM_CLIENT_CERTIFICATE_PATH
instead of clientSecret
/ARM_CLIENT_SECRET
.
Authenticate using Managed Service Identity (MSI)
When MSI is used for authentication, all
configuration is done in Azure
and we only need to tell the provider to use MSI. You can set the Pulumi configuration useMsi
or the environment
variable ARM_USE_MSI
to “true”.
You can also configure a custom MSI endpoint, although this is not generally required. Do so via the msiEndpoint
configuration or the ARM_MSI_ENDPOINT
environment variable.
Configuration options
Use pulumi config set azure-native:<option>
or pass options to the constructor of new azure-native.Provider
.
All configuration parameters are optional.
Option | Description |
---|---|
auxiliaryTenantIds | Any additional Tenant IDs which should be used for authentication. It can also be sourced from the ARM_AUXILIARY_TENANT_IDS environment variable. |
clientCertificatePassword | The password associated with the Client Certificate. For use when authenticating as a Service Principal using a Client Certificate. It can also be sourced from the ARM_CLIENT_CERTIFICATE_PASSWORD environment variable. |
clientCertificatePath | The path to a certificate to use as client secret for Service Principal authentication. It can also be sourced from the ARM_CLIENT_CERTIFICATE_PATH environment variable. |
clientId | The client ID to use for OIDC or Service Principal authentication. It can also be sourced from the ARM_CLIENT_ID environment variable. |
clientSecret | The client secret to use for Service Principal authentication. It can also be sourced from the ARM_CLIENT_SECRET environment variable. |
disablePulumiPartnerId | This will disable the Pulumi Partner ID which is used if a custom partnerId isn’t specified. It can also be sourced from the ARM_DISABLE_PULUMI_PARTNER_ID environment variable. |
environment | The cloud environment to use. It can also be sourced from the ARM_ENVIRONMENT environment variable. Supported values are: public (default), usgovernment , china . |
location | The location to use. ResourceGroups will consult this property for a default location, if one was not supplied explicitly when defining the resource. |
metadataHost | The REST endpoint for the Azure Instance Metadata Service. Pulumi will attempt to discover this automatically but it can be specified manually here. It can also be sourced from the ARM_METADATA_HOSTNAME environment variable. |
msiEndpoint | The REST endpoint to retrieve an MSI token from. Pulumi will attempt to discover this automatically but it can be specified manually here. It can also be sourced from the ARM_MSI_ENDPOINT environment variable. |
oidcRequestToken | Your cloud service or provider’s bearer token to exchange for an OIDC ID token. It can also be sourced from the ARM_OIDC_REQUEST_TOKEN environment variable. |
oidcRequestUrl | The token exchange URL for OIDC authentication. It can also be sourced from the ARM_OIDC_REQUEST_URL environment variable. |
oidcToken | The token to exchange for OIDC authentication. It can also be sourced from the ARM_OIDC_TOKEN environment variable. |
oidcTokenFilePath | The path to a file containing a token to exchange for OIDC authentication. It can also be sourced from the ARM_OIDC_TOKEN_FILE_PATH environment variable. |
partnerId | A GUID/UUID that is registered with Microsoft to facilitate partner resource usage attribution. It can also be sourced from the ARM_PARTNER_ID environment variable. |
subscriptionId | The subscription ID to use. It can also be sourced from the ARM_SUBSCRIPTION_ID environment variable. |
tenantId | The tenant ID to use for OIDC or Service Principal authentication. It can also be sourced from the ARM_TENANT_ID environment variable. |
useMsi | Set to true to authenticate using managed service identity. It can also be sourced from the ARM_USE_MSI environment variable. |
useOidc | Set to true to authenticate using OIDC. It can also be sourced from the ARM_USE_OIDC environment variable. |