azuredns.toml raw

   1  Name = "Azure DNS"
   2  Description = ''''''
   3  URL = "https://azure.microsoft.com/services/dns/"
   4  Code = "azuredns"
   5  Since = "v4.13.0"
   6  
   7  Example = '''
   8  ### Using client secret
   9  
  10  AZURE_CLIENT_ID=<your service principal client ID> \
  11  AZURE_TENANT_ID=<your service principal tenant ID> \
  12  AZURE_CLIENT_SECRET=<your service principal client secret> \
  13  lego --dns azuredns -d '*.example.com' -d example.com run
  14  
  15  ### Using client certificate
  16  
  17  AZURE_CLIENT_ID=<your service principal client ID> \
  18  AZURE_TENANT_ID=<your service principal tenant ID> \
  19  AZURE_CLIENT_CERTIFICATE_PATH=<your service principal certificate path> \
  20  lego --dns azuredns -d '*.example.com' -d example.com run
  21  
  22  ### Using Azure CLI
  23  
  24  az login \
  25  lego --dns azuredns -d '*.example.com' -d example.com run
  26  
  27  ### Using Managed Identity (Azure VM)
  28  
  29  AZURE_TENANT_ID=<your service principal tenant ID> \
  30  AZURE_RESOURCE_GROUP=<your target zone resource group name> \
  31  lego --dns azuredns -d '*.example.com' -d example.com run
  32  
  33  ### Using Managed Identity (Azure Arc)
  34  
  35  AZURE_TENANT_ID=<your service principal tenant ID> \
  36  IMDS_ENDPOINT=http://localhost:40342 \
  37  IDENTITY_ENDPOINT=http://localhost:40342/metadata/identity/oauth2/token \
  38  lego --dns azuredns -d '*.example.com' -d example.com run
  39  
  40  '''
  41  
  42  Additional = '''
  43  ## Description
  44  
  45  Several authentication methods can be used to authenticate against Azure DNS API.
  46  
  47  ### Default Azure Credentials (default option)
  48  
  49  Default Azure Credentials automatically detects in the following locations and prioritized in the following order:
  50  
  51  1. Environment variables for client secret: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
  52  2. Environment variables for client certificate: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_CERTIFICATE_PATH`
  53  3. Workload identity for resources hosted in Azure environment (see below)
  54  4. Shared credentials (defaults to `~/.azure` folder), used by Azure CLI
  55  
  56  Link:
  57  - [Azure Authentication](https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication)
  58  
  59  ### Environment variables
  60  
  61  #### Service Discovery
  62  
  63  Lego automatically finds all visible Azure (private) DNS zones using [Azure ResourceGraph query](https://learn.microsoft.com/en-us/azure/governance/resource-graph/).
  64  This can be limited by specifying environment variable `AZURE_SUBSCRIPTION_ID` and/or `AZURE_RESOURCE_GROUP` which limits the
  65  DNS zones to only a subscription or to one resourceGroup.
  66  
  67  Additionally environment variable `AZURE_SERVICEDISCOVERY_FILTER` can be used to filter DNS zones with an addition Kusto filter eg:
  68  
  69  ```
  70  resources
  71  | where type =~ "microsoft.network/dnszones"
  72  | ${AZURE_SERVICEDISCOVERY_FILTER}
  73  | project subscriptionId, resourceGroup, name
  74  ```
  75  
  76  
  77  #### Client secret
  78  
  79  The Azure Credentials can be configured using the following environment variables:
  80  * AZURE_CLIENT_ID = "Client ID"
  81  * AZURE_CLIENT_SECRET = "Client secret"
  82  * AZURE_TENANT_ID = "Tenant ID"
  83  
  84  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `env`.
  85  
  86  #### Client certificate
  87  
  88  The Azure Credentials can be configured using the following environment variables:
  89  * AZURE_CLIENT_ID = "Client ID"
  90  * AZURE_CLIENT_CERTIFICATE_PATH = "Client certificate path"
  91  * AZURE_TENANT_ID = "Tenant ID"
  92  
  93  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `env`.
  94  
  95  ### Workload identity
  96  
  97  Workload identity allows workloads running Azure Kubernetes Services (AKS) clusters to authenticate as an Azure AD application identity using federated credentials.
  98  
  99  This must be configured in kubernetes workload deployment in one hand and on the Azure AD application registration in the other hand.
 100  
 101  Here is a summary of the steps to follow to use it :
 102  * create a `ServiceAccount` resource, add following annotations to reference the targeted Azure AD application registration : `azure.workload.identity/client-id` and `azure.workload.identity/tenant-id`.
 103  * on the `Deployment` resource you must reference the previous `ServiceAccount` and add the following label : `azure.workload.identity/use: "true"`.
 104  * create a federated credentials of type `Kubernetes accessing Azure resources`, add the cluster issuer URL  and add the namespace and name of your kubernetes service account.
 105  
 106  Link :
 107  - [Azure AD Workload identity](https://azure.github.io/azure-workload-identity/docs/topics/service-account-labels-and-annotations.html)
 108  
 109  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `wli`.
 110  
 111  ### Azure Managed Identity
 112  
 113  #### Azure Managed Identity (with Azure workload)
 114  
 115  The Azure Managed Identity service allows linking Azure AD identities to Azure resources, without needing to manually manage client IDs and secrets.
 116  
 117  Workloads with a Managed Identity can manage their own certificates, with permissions on specific domain names set using IAM assignments.
 118  For this to work, the Managed Identity requires the **Reader** role on the target DNS Zone,
 119  and the **DNS Zone Contributor** on the relevant `_acme-challenge` TXT records.
 120  
 121  For example, to allow a Managed Identity to create a certificate for "fw01.lab.example.com", using Azure CLI:
 122  
 123  ```bash
 124  export AZURE_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
 125  export AZURE_RESOURCE_GROUP="rg1"
 126  export SERVICE_PRINCIPAL_ID="00000000-0000-0000-0000-000000000000"
 127  
 128  export AZURE_DNS_ZONE="lab.example.com"
 129  export AZ_HOSTNAME="fw01"
 130  export AZ_RECORD_SET="_acme-challenge.${AZ_HOSTNAME}"
 131  
 132  az role assignment create \
 133  --assignee "${SERVICE_PRINCIPAL_ID}" \
 134  --role "Reader" \
 135  --scope "/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${AZURE_RESOURCE_GROUP}/providers/Microsoft.Network/dnszones/${AZURE_DNS_ZONE}"
 136  
 137  az role assignment create \
 138  --assignee "${SERVICE_PRINCIPAL_ID}" \
 139  --role "DNS Zone Contributor" \
 140  --scope "/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${AZURE_RESOURCE_GROUP}/providers/Microsoft.Network/dnszones/${AZURE_DNS_ZONE}/TXT/${AZ_RECORD_SET}"
 141  ```
 142  
 143  A timeout wrapper is configured for this authentication method.
 144  The duration can be configured by setting the `AZURE_AUTH_MSI_TIMEOUT`.
 145  The default timeout is 2 seconds.
 146  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `msi`.
 147  
 148  #### Azure Managed Identity (with Azure Arc)
 149  
 150  The Azure Arc agent provides the ability to use a Managed Identity on resources hosted outside of Azure
 151  (such as on-prem virtual machines, or VMs in another cloud provider).
 152  
 153  While the upstream `azidentity` SDK will try to automatically identify and use the Azure Arc metadata service,
 154  if you get `azuredns: DefaultAzureCredential: failed to acquire a token.` error messages,
 155  you may need to set the environment variables:
 156  * `IMDS_ENDPOINT=http://localhost:40342`
 157  * `IDENTITY_ENDPOINT=http://localhost:40342/metadata/identity/oauth2/token`
 158  
 159  A timeout wrapper is configured for this authentication method.
 160  The duration can be configured by setting the `AZURE_AUTH_MSI_TIMEOUT`.
 161  The default timeout is 2 seconds.
 162  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `msi`.
 163  
 164  ### Azure CLI
 165  
 166  The Azure CLI is a command-line tool provided by Microsoft to interact with Azure resources.
 167  It provides an easy way to authenticate by simply running `az login` command.
 168  The generated token will be cached by default in the `~/.azure` folder.
 169  
 170  This authentication method can be specifically used by setting the `AZURE_AUTH_METHOD` environment variable to `cli`.
 171  
 172  ### Open ID Connect
 173  
 174  Open ID Connect is a mechanism that establish a trust relationship between a running environment and the Azure AD identity provider.
 175  It can be enabled by setting the `AZURE_AUTH_METHOD` environment variable to `oidc`.
 176  
 177  ### Azure DevOps Pipelines
 178  
 179  It can be enabled by setting the `AZURE_AUTH_METHOD` environment variable to `pipeline`.
 180  
 181  '''
 182  
 183  [Configuration]
 184    [Configuration.Credentials]
 185      AZURE_CLIENT_ID = "Client ID"
 186      AZURE_CLIENT_SECRET = "Client secret"
 187      AZURE_TENANT_ID = "Tenant ID"
 188      AZURE_CLIENT_CERTIFICATE_PATH = "Client certificate path"
 189    [Configuration.Additional]
 190      AZURE_ENVIRONMENT = "Azure environment, one of: public, usgovernment, and china"
 191      AZURE_SUBSCRIPTION_ID = "DNS zone subscription ID"
 192      AZURE_RESOURCE_GROUP = "DNS zone resource group"
 193      AZURE_SERVICEDISCOVERY_FILTER = "Advanced ServiceDiscovery filter using Kusto query condition"
 194      AZURE_PRIVATE_ZONE = "Set to true to use Azure Private DNS Zones and not public"
 195      AZURE_ZONE_NAME = "Zone name to use inside Azure DNS service to add the TXT record in"
 196      AZURE_AUTH_METHOD = "Specify which authentication method to use"
 197      AZURE_AUTH_MSI_TIMEOUT = "Managed Identity timeout duration"
 198      AZURE_TTL = "The TTL of the TXT record used for the DNS challenge in seconds (Default: 60)"
 199      AZURE_POLLING_INTERVAL = "Time between DNS propagation check in seconds (Default: 2)"
 200      AZURE_PROPAGATION_TIMEOUT = "Maximum waiting time for DNS propagation in seconds (Default: 120)"
 201  
 202  [Links]
 203    API = "https://docs.microsoft.com/en-us/go/azure/"
 204    GoClient = "https://github.com/Azure/azure-sdk-for-go"
 205