Skip to main content

​
Setup Options

You can set up Azure for Porter in two ways: Prerequisites for the script:
  • Azure CLI installed and authenticated (az login)
  • jq command-line JSON processor installed
  • Admin permissions on your Azure subscription (for granting API permissions)
Download and run our automated setup script that handles all the configuration steps for you: 
# Download the setup script
curl -O https://raw.githubusercontent.com/porter-dev/docs/main/scripts/setup-azure-porter.sh

# Make it executable
chmod +x setup-azure-porter.sh

# Run the script (optionally provide subscription ID)
./setup-azure-porter.sh [your-subscription-id]
The script will:
  • ✅ Enable all required Azure resource providers
  • ✅ Create the custom porter-aks-restricted role
  • ✅ Create the service principal with proper permissions
  • ✅ Add Microsoft Graph API permissions
  • ✅ Grant admin consent (if you have permissions)
  • ✅ Display the credentials needed for Porter
After running the script:
  1. Copy the displayed credentials to the Porter dashboard when creating your project
  2. Request quota increases if needed (see Compute Quotas section below)
  3. Proceed with cluster provisioning in Porter
If the script fails to grant admin consent automatically, you can grant it manually in the Azure Portal: App registrations > azure-porter-restricted-sp > API permissions > Grant admin consent for Default Directory.
If you prefer to set up manually or want to understand each step, continue with Option 2 below.

​
Option 2: Manual Setup

​
Prerequisites

To provision through Porter, you must enable certain Azure resource providers for your subscription.
  1. In the Azure portal, search for Subscriptions, select the subscription you would like to use to provision, and click the Resource providers tab in the subscription console.
Resource providers
  1. Enable the following providers by selecting the providers and clicking Register:
  • Microsoft.Capacity
  • Microsoft.Compute
  • Microsoft.ContainerRegistry
  • Microsoft.ContainerService
  • Microsoft.ManagedIdentity
  • Microsoft.Network
  • Microsoft.OperationalInsights
  • Microsoft.OperationsManagement
  • Microsoft.ResourceGraph
  • Microsoft.Resources
  • Microsoft.Storage
It might take a few minutes for providers to complete registration. Once you confirm that all resource providers are enabled, proceed to the next section.

​
Creating the Service Principal

  1. Create a new role with the Azure CLI
The following commands can be run in the Azure Cloud Shell (selecting the Bash option) or in your local terminal after installing the Azure CLI and authenticating with az login.
Most of the permissions required by Porter to manage your infrastructure come with Azure’s built-in Contributor role. However, this role does not allow for role assignments, which are crucial for Porter. For this reason, we need to create a new role that combines the Contributor scope along with permissions to create role assignments. We will do this through the Azure CLI. To get started, set the PORTER_AZURE_SUBSCRIPTION_ID environment variable to your subscription id: 
PORTER_AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Run the following command to create the role: 
envsubst << EOF | az role definition create --role-definition @-
{
    "assignableScopes": ["/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}"],
    "description": "Grants Porter access to manage resources for an AKS cluster.",
    "id": "/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}/providers/Microsoft.Authorization/roleDefinitions/porter-aks-restricted",
    "isCustom": true,
    "name": "porter-aks-restricted",
    "permissions": [
        {
            "actions": ["*"],
            "dataActions": [],
            "notActions": [
                "Microsoft.Authorization/elevateAccess/Action",
                "Microsoft.Blueprint/blueprintAssignments/write",
                "Microsoft.Blueprint/blueprintAssignments/delete",
                "Microsoft.Compute/galleries/share/action"
            ],
            "notDataActions": []
        }
    ],
    "roleName": "Contributor",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions"
}
EOF
  1. Create a new service principal through the Azure CLI that uses the role you just created:
az ad sp create-for-rbac \
--name="azure-porter-restricted-sp" \
--role="porter-aks-restricted" \
--scopes="/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}"
Running this will display the following output, which you will need when you go to provision your cluster on the Porter dashboard: 
{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "azure-porter-restricted-sp",
  "name": "azure-porter-restricted-sp",
  "password": "0000-0000-0000-0000-000000000000",
  "tenant": "00000000-0000-0000-0000-000000000000"
}
  1. Grant API permissions to your service principal
In your Azure portal, search for App registrations. Under the All applications tab, you should see the newly-created service principal. Select the principal and navigate to the API Permissions tab: Select Add a permission > Microsoft Graph > Application permissions and select the following seven permissions:
  • Application.ReadWrite.All
  • Directory.ReadWrite.All
  • Domain.Read.All
  • Group.Create
  • Group.ReadWrite.All
  • RoleManagement.ReadWrite.Directory
  • User.ReadWrite.All
Click Add permissions to save these permissions, and then click Grant admin consent for Default Directory to grant these permissions to your service principal.

​
Compute Quotas

By default, Azure limits the types of resources you can provision in your subscription. To provision a Porter cluster, you will need to request a quota increase for the compute resources you plan to use. In your Azure portal, navigate to your subscription and select Usage + quotas. Set the resource filter to Compute and region to your desired region. While the exact virtual machines provisioned by Porter will depend on your selected region’s availability, the following table lists the default virtual machine types that Porter will provision along with recommended initial quota limits:
Resource FamilyRecommended Quota
Total Regional vCPUs40
Standard Basv2 Family vCPUs40
After selecting each resource family, click Request quota increase and input your desired quota limit. Requests should be approved automatically within a few minutes. If your request is not approved automatically, fill out the support ticket as prompted. Approval is typically granted in a few hours.

​
Provisioning Your Porter Cluster

  1. Once you create your project and select Azure as your cloud provider, you will be prompted to provide the credentials for the service principal you created earlier.
  2. After providing your credentials, hit “Continue”. In the case that you do not have cloud credits, we have provided a breakdown of the monthly costs on Azure.
  3. On the next page, you will be able to configure your Azure cluster. For choosing an Azure tier, we recommend choosing a Free tier for non-production workloads, and the Standard tier for production workloads. This is something you are able to change after creating your cluster, should your needs change. You will also be prompted to select a region, and have the option to cutomize your machine type. In the case you don’t have specific preferences, the default is a safe start. This is also something you will be able to update once your cluster has been provisioned.
    For guidance on choosing a region, if you have an external database to Porter, we recommend choosing a region close to your database. Otherwise, consider choosing a region near your primary customer base.
  4. Once you click Provision, Porter will start spinning up the requisite infrastructure in your account. This may take up to 30 minutes.

​
Rotating Service Principal Credentials

Azure mandates that client secrets for Service Principals(the password field displayed when you create a Service Principal) expire every 365 days. When a client secret expires, Porter loses the ability to manage your infrastructure or push new deployments. Note that in the event of a client secret’s expiration, your cluster continues to function normally, and existing workloads are not affected. To refresh your client secret:
  1. Visit https://aka.ms/NewClientSecret and select the app ID for the service principal that was used to create your cluster(to check what your app ID is, you can navigate to Integrations on the Porter dashboard and select Azure).
  2. Generate a fresh client secret, and copy new value.
  3. Navigate to Integrations on the Porter dashboard and select Azure.
  4. Update the value of the Password field with the new value you generated on Azure, and hit Update.

​
Deleting Provisioned Resources

Deleting resources on Azure via Porter may result in dangling resources. After clicking delete, please make sure to check your Azure portal to see if all resources have properly been removed. You can remove any dangling resources via either the Azure console or the Azure CLI.
We recommend that you delete all provisioned resources through Porter as well as confirm resources have been deleted from the Azure portal. This will ensure that you do not get charged on Azure for lingering resources. To delete resources, click on Additional settings from the Infrastructure tab. Click Delete Cluster to remove the cluster from Porter and delete resources in your Azure console. It may take up to 30 minutes for these resources to be deleted from your Azure subscription. To confirm that resources have been deleted, navigate to your Azure portal and search for Resource groups. You should expect to see a resource group named <PROJECT_ID>-<AZURE_REGION> containing an Azure container registry with your application build images. By default, Porter will not delete your build images, so you will need to delete this resource group manually. No other resource groups should be present. If any are, you should delete them manually by clicking on the resource group and selecting Delete resource group.