> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuring an Azure key vault for Maia runners
export const m_runner = "Maia runner";
export const maia = "Maia";
export const RunnerMetadata = ({runnerType, platforms = []}) => {
return
Runner type
{runnerType}
Runner platform
{platforms.map((platform, i) =>
{platform} ✅
)}
;
};
The [Azure {m_runner}](/docs/guides/azure-arm-runner-install) requires access to an [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/basic-concepts) vault. The deployment template will automatically create a key vault in the same resource group as the {m_runner}, but if you prefer, the {m_runner} can reference a different key vault you have previously created. This other key vault may be in the same or a different resource group. You might want to reference a key vault in a different resource group so that you can have multiple {m_runner}s referencing the same secrets, for example.
This topic describes the configuration steps you will need to perform in order to use an existing key vault. You don't need to follow these steps if you are allowing the ARM template install to create a new key vault.
You can use multiple key vaults to store secrets for {maia}. When you [add a new secret definition](/docs/guides/secrets-and-secret-definitions), you can choose which of your key vaults the secret is stored in.
***
## Prerequisites
To reference a different key vault, ensure the key vault already exists in the desired resource group. Before initiating the deployment process, you will need the following details:
* Name of the key vault that you want to use.
* Name of the resource group where the key vault resides.
* An Azure subscription with appropriate permissions to manage access control.
* Access to both the resource group containing the key vault and the resource group where the identity resides.
We assume an understanding of basic Azure Identity and Access Management (IAM) concepts if you intend to follow this process.
***
## Grant Azure Key Vault access
To use an existing key vault located in a different resource group, you first need to ensure appropriate role permissions have been granted to the identity requiring access. This requires the **Key Vault Secrets User** role to be granted to the relevant identity via the Azure portal, as follows.
Determine the **identity** that requires access to the key vault. If you aren't familiar with the concept of identities, read [What are managed identities for Azure resources?](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) or [Assign a managed identity access to a resource by using the Azure portal](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/howto-assign-access-portal) in the Microsoft documentation.
You have two options:
* Create a managed identity in the [Azure portal](https://portal.azure.com/#create/Microsoft.ManagedIdentity) that you then assign to the resource group where the {m_runner} will be deployed, and then deploy the {m_runner} as described in [{m_runner} installation using an ARM template](/docs/guides/azure-arm-runner-install).
* Deploy the {m_runner} as described in [{m_runner} installation using an ARM template](/docs/guides/azure-arm-runner-install) without first granting the access. This will automatically create a managed identity with `${resourcePrefix}-identity` as a default name. Note that the deployment will initially fail due to missing permissions. You will then have to perform the following steps, and then redeploy the {m_runner} in the **Deployments** section of the resource group where you initially attempt to deploy.
You can pre-create the access policies and assign them to the managed identity, then use that managed identity with the template. This allows for greater control over permissions.
### Assign the key vault secrets officer role
To add secrets in the Azure {m_runner}'s key vault, the managed identity needs to have the **Key Vault Secrets Officer** role granted to it. This is granted automatically by the deployment template. If you need to assign the role manually, do the following:
1. Log in to the [Azure portal](https://portal.azure.com/#home).
2. Click **Key vaults** and click the name of the key vault you want to use.
3. Click **Access control (IAM)**.
4. In the **Access Control (IAM)** panel, click **+ Add**, then click **Add role assignment** to create a new role assignment.
5. Search for the role **Key Vault Secrets Officer**, click it to select it, then click **Next**.
6. Click **+ Select members**, search for the identity requiring access to the key vault, click it to select it, then click **Select**.
7. Click **Review + assign**.
If you have the Azure Key Vault firewall enabled, you also need to allow the local IP address that you will use to add secrets to the key vault. To do this:
1. Log in to the [Azure portal](https://portal.azure.com/#home).
2. Click **Key vaults** and click the name of the key vault you want to use.
3. Click **Networking**.
4. Click the **Firewalls and virtual networks** tab.
5. Under **Allow access from**, click **Selected networks**.
6. Click **+ Add existing virtual networks**.
7. Select the subscription, virtual networks, and subnets that you want to allow access to this key vault.
8. Click **Save**.
***
## Verify access
To verify that access has been successfully granted, you can:
* Use the identity that was granted access to retrieve secrets from the key vault.
* Attempt to retrieve secrets programmatically or via the Azure portal using the granted identity's credentials.
* Review access logs or audit logs to confirm successful access attempts.
You can test that {maia} has access to a particular key vault by ensuring that it's visible in the **Vault name** drop-down in any of the various places where you can choose a key vault (for example, when [adding a new project](/docs/guides/projects#add-a-new-project)).