From 7a037ccf4a993c6333e14a26c09d6cc2814ed715 Mon Sep 17 00:00:00 2001 From: Gilad K Date: Fri, 23 Jan 2026 12:33:16 -0500 Subject: [PATCH 1/2] init --- mint.json | 3 - provision/overview.mdx | 490 ++++++++++++++++++++++++++-- provision/provisioning-on-aws.mdx | 120 ------- provision/provisioning-on-azure.mdx | 231 ------------- provision/provisioning-on-gcp.mdx | 87 ----- 5 files changed, 469 insertions(+), 462 deletions(-) delete mode 100644 provision/provisioning-on-aws.mdx delete mode 100644 provision/provisioning-on-azure.mdx delete mode 100644 provision/provisioning-on-gcp.mdx diff --git a/mint.json b/mint.json index ca64350..31c9a9c 100644 --- a/mint.json +++ b/mint.json @@ -43,9 +43,6 @@ "group": "Provision", "pages": [ "provision/overview", - "provision/provisioning-on-aws", - "provision/provisioning-on-azure", - "provision/provisioning-on-gcp", "provision/changing-instance-types", "provision/cluster-upgrades", "provision/cost-optimization" diff --git a/provision/overview.mdx b/provision/overview.mdx index 2614d22..5a65878 100644 --- a/provision/overview.mdx +++ b/provision/overview.mdx @@ -5,27 +5,475 @@ sidebarTitle: "Overview" Porter provisions and manages the underlying infrastructure in your own cloud. During project creation, Porter will prompt you to provision resources in a cloud provider of your choice. -For step by step instructions on how to provision infrastructure in each cloud provider, see the link below. - - - - - -## FAQ[](#faq "Direct link to heading") - -### How much does the underlying infrastructure cost?[](#how-much-does-the-underlying-infrastructure-cost "Direct link to heading") +Select your cloud provider below for step-by-step provisioning instructions. + + + + ## Quick Installation + + Porter provisions infrastructure in your own AWS account through the `AssumeRole` [operation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). + Simply put, Porter can _assume_ the role that you create in your own AWS account as long as you declare that you trust Porter to do so. + This eliminates the need to rely on static AWS credentials and makes it easier to revoke access for security purposes. Porter creates a CloudFormation to manage this role in your account using 3 simple steps. + + + The IAM role Porter creates must be kept in your AWS account for Porter to + keep managing your infrastructure. Deleting this role will cause Porter to + fail and stop managing your infrastructure. + + + + + After selecting AWS as your cloud provider you will be prompted to login to your AWS account. Upon successful login you will be prompted to provide the AWS Account ID of the account in which you wish to provision your cluster in. + You can find your Account ID at the top right corner of your [AWS console](https://console.aws.amazon.com). + Input your Account ID and click on **Grant Permissions**. + + + + You will be directed to your AWS console to create a CloudFormation stack. If this window did not appear, please ensure that your browser has not blocked the pop-up window. This stack will create the role Porter will assume to manage your infrastructure. + Scroll to the bottom of the screen. Check the "I acknowledge..." box and click on **Create Stack**. It may take a few minutes for the role to be fully created. After creation you can proceed to selecting provisioning settings. + + + If you want to use Porter with less expansive permissions than what is + provisioned by the CloudFormation stack, please contact us through the support widget to inquire about Porter + Enterprise. Porter Enterprise requires minimum IAM permissions that are + smaller in scope. + + + + + On the next page, you will be prompted to select the AWS region that you want to provision your infrastructure in. + Porter supports all AWS regions. + + + 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. + + + + + If there are any quota limits on your account imposed by AWS, Porter will request them on your behalf by default. Alternatively, if you wish to manually request quota increases, + follow the links prompting you to the AWS dashboard. If you go the manual route, you will not be able to provision your cluster until these quota increase requests have been approved. + + + + Once you click **Provision**, Porter will start spinning up the requisite infrastructure in your account. This may take up to 30 minutes. + + + + ### Troubleshooting + + + + If your cluster has been provisioning for more than 45 minutes, there may be an issue. Check the following: + + - Verify that the IAM role still exists in your AWS account and hasn't been deleted + - Check your AWS Service Quotas to ensure they were approved + - Verify that the selected region supports the requested instance types + + If issues persist, contact us through the dashboard chat bot with your project ID. + + + + If you encounter permission errors: + + - Verify the CloudFormation stack created successfully and the role exists + - Ensure the role has not been modified after creation + - Check that your AWS account has not applied SCPs (Service Control Policies) that restrict Porter's actions + + + + AWS typically approves quota increases automatically, but some may require manual review: + + - Check the status of quota requests in the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/) + - Requests under manual review typically take 24-48 hours + - If urgent, you can contact AWS support to expedite the review + + + + If the CloudFormation stack fails to create: + + - Ensure you have sufficient permissions in your AWS account to create IAM roles + - Check that you're logged into the correct AWS account (the account ID should match) + - Verify your account is in good standing and billing is enabled + + + + ### Deleting Provisioned Resources + + + For Porter to delete your resources, it needs the IAM role that was initially + created during provisioning. Please make sure to delete the resources first, + and then delete the IAM role after. If you've already deleted the IAM role, + you will have to delete the resources [directly from the AWS + console.](/other/deleting-dangling-resources) + + + To delete resources that have been provisioned by Porter, click on the Infrastructure tab on the sidebar of the dashboard. There you can find the **Delete Cluster** button. + + Once the cluster has been deleted, navigate to **CloudFormation Stacks** in your AWS console to delete the role that was created during initial provisioning. This will revoke Porter's access to your account. + Select the stack named `PorterRole` and click **Delete**. + + + Deleting resources on AWS via Porter may result in dangling resources. After + clicking delete, please make sure to check your AWS console to see if all + resources have properly been removed. You can remove any dangling resources + via either the AWS console or the CLI. + + + For a guide on how to delete the dangling resources, see [Deleting Dangling Resources](/other/deleting-dangling-resources). + + + + ## Setup Options + + You can set up Azure for Porter in two ways: + + - **[Option 1: Automated Setup Script (Recommended)](#option-1-automated-setup-script-recommended)** - One-click setup using our script + - **[Option 2: Manual Setup](#option-2-manual-setup)** - Step-by-step manual configuration + + ### Option 1: Automated Setup Script (Recommended) + + **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: + + ```bash + # 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](#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**. + + + --- + + ### Option 2: Manual Setup + + + + 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](https://github.com/porter-dev/api-contracts/assets/66391417/b163d9fa-a1fb-47e3-b642-6bf42f0da0cf) + + 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. + + + + + 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`. + + + Set the `PORTER_AZURE_SUBSCRIPTION_ID` environment variable to your subscription id: + + ```bash + PORTER_AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + ``` + + Run the following command to create the role: + + ```bash + 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 + ``` + + + + Create a new service principal through the Azure CLI that uses the role you just created: + + ```bash + 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: + + ```json + { + "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" + } + ``` + + + + 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. + + | Resource Family | Recommended Quota | + | --------------------------- | ----------------- | + | Total Regional vCPUs | 40 | + | Standard Basv2 Family vCPUs | 40 | + + After selecting each resource family, click **Request quota increase** and input your desired quota limit. Requests should be approved automatically within a few minutes. + + ### Provisioning Your Porter Cluster + + + + 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. + + + + 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. + + + + 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. + + + 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. + + + + + 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 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](https://aka.ms/NewClientSecret) and select the app ID for the service principal that was used to create your cluster + 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 `-` 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. + + + + Porter runs on a Kubernetes cluster in your own Google Cloud account. You can provision a cluster through Porter by providing the credentials of a GCP service account. + + + Quick Installation uses **Owner** permissions to set up Porter. You can + optionally specify the minimum IAM policies for provisioning both a cluster + and registry. + + + ## Prerequisites + + ### Enabling GCP APIs + + To use Porter on GCP, you must first enable some APIs on your project. + + + + Navigate to the **APIs & Services** tab of your project. + + ![APIs and services](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/75c924c8-88d4-40a7-5a35-5e29261f4d00/large "Screen Shot 2021-05-06 at 6.23.07 PM.png") + + + + Click on the **Enable APIs and Services** button at the top. This will bring up a catalog of APIs that you can enable on GCP. Enable the following five APIs: + + - Compute Engine API + - Kubernetes Engine API + - Cloud Resource Manager API + - Container Registry API + - Artifact Registry API + + It might take a few minutes for each of these APIs to be enabled. + + + + ### Creating a Service Account + + + + Go to your [Google Cloud console](https://console.cloud.google.com/) and navigate to **IAM & Admin** → **Service Accounts**. + + ![Service accounts](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/c7dbb5ea-64ff-4ac5-4b97-6b4ff403cb00/large "Screen Shot 2021-04-15 at 6.41.26 PM.png") + + + + Select **Create Service Account**. + + ![Create service account](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/a625aa4d-08d9-4a47-885a-d470fd1a3100/large "Screen Shot 2021-04-15 at 6.45.42 PM.png") + + + + After naming your service account, grant the service account these five permissions: + + - **Cloud Storage > Storage Admin** + - **Compute Engine > Compute Admin** + - **Kubernetes Engine > Kubernetes Engine Admin** + - **Service Accounts > Service Account User** + - **Artifact Registry > Artifact Registry Administrator** + + Select **Done** to create the service account. + + ![Create service account confirmation](/images/provisioning-infrastructure/gcp-service-account-permissions.png) + + + + Once the service account has been created, under **Actions** select **Manage keys**. + + ![Manage keys](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/7ed41d02-b6dd-40cf-b2aa-bdbb23155900/large "Screen Shot 2021-04-15 at 6.51.25 PM.png") + + Select **ADD KEY** → **Create new key** and then choose **JSON** as your key type. After creation, your JSON key will automatically be downloaded as a file. You will need this key later. + + ![Download JSON](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/9e17f17a-9d9e-4bdc-5978-55275f3d9a00/large "Screen Shot 2021-04-15 at 6.56.30 PM.png") + + + + ## Provisioning a Cluster + + + + Select "GCP" from the cloud providers. + + + + Click "Drop a GCP Service Account JSON here, or click to browse." and upload the JSON key file from the Prerequisites step, then click "Continue". + + + + Select the region that you would like to provision in, then click "Provision". + + + + Before you are able to provision a cluster you must pass all provision checks. Troubleshooting steps will be shown on the dashboard if you encounter these errors. + + + + Once you click **Provision**, Porter will start spinning up the requisite infrastructure in your account. This may take up to 30 minutes. + + + + ### Deleting Provisioned Resources + + + Deleting resources on GCP via Porter may result in dangling resources. After + clicking delete, please make sure to check your GCP console to see if all + resources have properly been removed. You can remove any dangling resources + via either the GCP console or the gcloud CLI. + + + We recommend that you delete all provisioned resources through Porter as well as confirm resources have been deleted from the GCP console. This will ensure that you do not get charged on GCP 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 GCP console. It may take up to 30 minutes for these resources to be deleted from your GCP console. + + + +## FAQ + +### How much does the underlying infrastructure cost? The cost of your infrastructure varies entirely on the amount of resources you use. By default, clusters provisioned by Porter cost around $200 per month. **All of the underlying infrastructure cost can be covered with your cloud credits from AWS, Google Cloud, and Azure.** diff --git a/provision/provisioning-on-aws.mdx b/provision/provisioning-on-aws.mdx deleted file mode 100644 index a9c9795..0000000 --- a/provision/provisioning-on-aws.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Provisioning on AWS" ---- - -## Quick Installation[](#quick-installation "Direct link to heading") - -Porter provisions infrastructure in your own AWS account through the `AssumeRole` [operation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). -Simply put, Porter can _assume_ the role that you create in your own AWS account as long as you declare that you trust Porter to do so. -This eliminates the need to rely on static AWS credentials and makes it easier to revoke access for security purposes. Porter creates a CloudFormation to manage this role in your account using 3 simple steps. - - - The IAM role Porter creates must be kept in your AWS account for Porter to - keep managing your infrastructure. Deleting this role will cause Porter to - fail and stop managing your infrastructure.{" "} - - -1. After selecting AWS as your cloud provider you will be prompted to login to your AWS account. Upon successful login you will be prompted to provide the AWS Account ID of the account in which you wish to provision your cluster in. - You can find your Account ID at the top right corner of your [AWS console](https://console.aws.amazon.com). - Input your Account ID and click on **Grant Permissions**. - -2. You will be directed to your AWS console to create a CloudFormation stack. If this window did not appear, please ensure that your browser has not blocked the pop-up window. This stack will create the role Porter will assume to manage your infrastructure. - Scroll to the bottom of the screen. Check the "I acknowledge..." box and click on **Create Stack**. It may take a few minutes for the role to be fully created. After creation you can proceed to selecting provisioning settings. - - {" "} - - If you want to use Porter with less expansive permissions than what is - provisioned by the CloudFormation stack, please contact us through the support widget to inquire about Porter - Enterprise. Porter Enterprise requires minimum IAM permissions that are - smaller in scope.{" "} - - -4. On the next page, you will be prompted to select the AWS region that you want to provision your infrastructure in. - Porter supports all AWS regions. - - - 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. - - -5. If there are any quota limits on your account imposed by AWS, Porter will request them on your behalf by default. Alternatively, if you wish to manually request quota increases, -follow the links prompting you to the AWS dashboard. If you go the manual route, you will not be able to provision your cluster until these quota increase requests have been approved - -6. Once you click **Provision**, Porter will start spinning up the requisite infrastructure in your account. This may take up to 30 minutes. - -## Troubleshooting Initial Provisioning[](#troubleshooting-initial-provisioning "Direct link to heading") - -### Provisioning takes longer than 30 minutes - -If your cluster has been provisioning for more than 45 minutes, there may be an issue. Check the following: - -- Verify that the IAM role still exists in your AWS account and hasn't been deleted -- Check your AWS Service Quotas to ensure they were approved -- Verify that the selected region supports the requested instance types - -If issues persist, contact us through the dashboard chat bot with your project ID. - -### Permission errors during provisioning - -If you encounter permission errors: - -## Troubleshooting Initial Provisioning[](#troubleshooting-initial-provisioning "Direct link to heading") - -### Provisioning takes longer than 30 minutes - -If your cluster has been provisioning for more than 30 minutes, there may be an issue. Check the following: - -- Verify that the IAM role still exists in your AWS account and hasn't been deleted -- Check your AWS Service Quotas to ensure they were approved -- Verify that the selected region supports the requested instance types - -If issues persist, contact us through the dashboard chat bot with your project ID. - -### Permission errors during provisioning - -If you encounter permission errors: - -- Verify the CloudFormation stack created successfully and the role exists -- Ensure the role has not been modified after creation -- Check that your AWS account has not applied SCPs (Service Control Policies) that restrict Porter's actions - -### Quota increase requests not approved - -AWS typically approves quota increases automatically, but some may require manual review: - -- Check the status of quota requests in the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/) -- Requests under manual review typically take 24-48 hours -- If urgent, you can contact AWS support to expedite the review - -### CloudFormation stack creation fails - -If the CloudFormation stack fails to create: - -- Ensure you have sufficient permissions in your AWS account to create IAM roles -- Check that you're logged into the correct AWS account (the account ID should match) -- Verify your account is in good standing and billing is enabled - -## Deleting Provisioned Resources[](#deleting-provisioned-resources "Direct link to heading") - - - For Porter to delete your resources, it needs the IAM role that was initially - created during provisioning. Please make sure to delete the resources first, - and then delete the IAM role after. If you've already deleted the IAM role, - you will have to delete the resources [directly from the AWS - console.](/other/deleting-dangling-resources) - - -To delete resources that have been provisioned by Porter, click on the Infrastructure tab on the sidebar of the dashboard. There you can find the **Delete Cluster** button. - -Once the cluster has been deleted, navigate to **CloudFormation Stacks** in your AWS console to delete the role that was created during initial provisioning. This will revoke Porter's access to your account. -Select the stack named `PorterRole` and click **Delete**. - - - Deleting resources on AWS via Porter may result in dangling resources. After - clicking delete, please make sure to check your AWS console to see if all - resources have properly been removed. You can remove any dangling resources - via either the AWS console or the CLI. - - -For a guide on how to delete the dangling resources, see [Deleting Dangling Resources](/other/deleting-dangling-resources). diff --git a/provision/provisioning-on-azure.mdx b/provision/provisioning-on-azure.mdx deleted file mode 100644 index bb1cabf..0000000 --- a/provision/provisioning-on-azure.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Provisioning on Azure" ---- - -## Setup Options - -You can set up Azure for Porter in two ways: - -- **[Option 1: Automated Setup Script (Recommended)](#option-1-automated-setup-script-recommended)** - One-click setup using our script -- **[Option 2: Manual Setup](#option-2-manual-setup)** - Step-by-step manual configuration - -### Option 1: Automated Setup Script (Recommended) - -**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: - -```bash -# 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](#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[](#prerequisites "Direct link to heading") - -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](https://github.com/porter-dev/api-contracts/assets/66391417/b163d9fa-a1fb-47e3-b642-6bf42f0da0cf) - -2. 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[](#creating-service-principal "Direct link to heading") - -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 -``` - -2. 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" -} -``` - -3. 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 [](#quotas "Direct link to heading") - -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 Family | Recommended Quota | -| --------------------------- | ----------------- | -| Total Regional vCPUs | 40 | -| Standard Basv2 Family vCPUs | 40 | - -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[](#provisioning-porter-cluster "Direct link to heading") - -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[](#-rotating-service-principal-credentials "Direct link to heading") - -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](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-provisioned-resources "Direct link to heading") - - - 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 `-` 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**. diff --git a/provision/provisioning-on-gcp.mdx b/provision/provisioning-on-gcp.mdx deleted file mode 100644 index d93c411..0000000 --- a/provision/provisioning-on-gcp.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Provisioning on Google Cloud" ---- - -Porter runs on a Kubernetes cluster in your own Google Cloud account. You can provision a cluster through Porter by providing the credentials of a GCP service account. - - - Quick Installation uses **Owner** permissions to set up Porter. You can - optionally specify the minimum IAM policies for provisioning both a cluster - and registry. - - -## Prerequisites[](#prerequisites "Direct link to heading") - -### Enabling GCP APIs[](#enabling-apis "Direct link to heading") - -To use Porter on GCP, you must first enable some APIs on your project. - -1. Navigate to the **APIs & Services** tab of your project. - -![APIs and services](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/75c924c8-88d4-40a7-5a35-5e29261f4d00/large "Screen Shot 2021-05-06 at 6.23.07 PM.png") - -2. Click on the **Enable APIs and Services** button at the top. This will bring up a catalog of APIs that you can enable on GCP. Enable the following five APIs: - -- Compute Engine API -- Kubernetes Engine API -- Cloud Resource Manager API -- Container Registry API -- Artifact Registry API - -It might take a few minutes for each of these APIs to be enabled. Once you can confirm that all five APIs are enabled from the **APIs & Services** tab, proceed to the next section. - -### Creating a Service Account[](#creating-service-account "Direct link to heading") - -1. First, go to your [Google Cloud console](https://console.cloud.google.com/) and navigate to **IAM & Admin** \-> **Service Accounts**: - -![Service accounts](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/c7dbb5ea-64ff-4ac5-4b97-6b4ff403cb00/large "Screen Shot 2021-04-15 at 6.41.26 PM.png") - -2. Select **Create Service Account**: - -![Create service account](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/a625aa4d-08d9-4a47-885a-d470fd1a3100/large "Screen Shot 2021-04-15 at 6.45.42 PM.png") - -3. After naming your service account, grant the service account these five permissions: - -- **Cloud Storage > Storage Admin** -- **Compute Engine > Compute Admin** -- **Kubernetes Engine > Kubernetes Engine Admin** -- **Service Accounts > Service Account User** -- **Artifact Registry > Artifact Registry Administrator** - -Select **Done** to create the service account. - -![Create service account confirmation](/images/provisioning-infrastructure/gcp-service-account-permissions.png) - -4. Once the service account has been created, under **Actions** select **Manage keys**. - -![Manage keys](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/7ed41d02-b6dd-40cf-b2aa-bdbb23155900/large "Screen Shot 2021-04-15 at 6.51.25 PM.png") - -5. Select **ADD KEY** \-> **Create new key** and then choose **JSON** as your key type. After creation, your JSON key will automatically be downloaded as a file. You will need this key later. - -![Download JSON](https://imagedelivery.net/l4LYM_vOYKe7O1NCT_Nc_g/9e17f17a-9d9e-4bdc-5978-55275f3d9a00/large "Screen Shot 2021-04-15 at 6.56.30 PM.png") - -## Provisioning a cluster[](#provisioning-cluster "Direct link to heading") - -1. Select "GCP" from the cloud providers: - -2. Click "Drop a GCP Service Account JSON here, or click to browse." and upload the JSON key file from the Prerequisites step, then click "Continue" - -3. Select the region that you would like to provision in, then click "Provision" - -4. Before you are able to provision a cluster you must pass all provision checks. Troubleshooting steps will be shown on the dashboard if you encounter these errors. -5. Once you click **Provision**, Porter will start spinning up the requisite infrastructure in your account. This may take up to 30 minutes. - -## Deleting Provisioned Resources[](#deleting-provisioned-resources "Direct link to heading") - - - Deleting resources on GCP via Porter may result in dangling resources. After - clicking delete, please make sure to check your GCP console to see if all - resources have properly been removed. You can remove any dangling resources - via either the GCP console or the gcloud CLI. - - -We recommend that you delete all provisioned resources through Porter as well as confirm resources have been deleted from the GCP console. This will ensure that you do not get charged on GCP 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 GCP console. It may take up to 30 minutes for these resources to be deleted from your GCP console. From 54484e8066c080178d3e978e9b33d854ac066a58 Mon Sep 17 00:00:00 2001 From: Gilad K Date: Fri, 23 Jan 2026 12:35:32 -0500 Subject: [PATCH 2/2] fix --- mint.json | 2 +- provision/{overview.mdx => cloud-provider.mdx} | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename provision/{overview.mdx => cloud-provider.mdx} (99%) diff --git a/mint.json b/mint.json index 31c9a9c..c8dfc71 100644 --- a/mint.json +++ b/mint.json @@ -42,7 +42,7 @@ { "group": "Provision", "pages": [ - "provision/overview", + "provision/cloud-provider", "provision/changing-instance-types", "provision/cluster-upgrades", "provision/cost-optimization" diff --git a/provision/overview.mdx b/provision/cloud-provider.mdx similarity index 99% rename from provision/overview.mdx rename to provision/cloud-provider.mdx index 5a65878..0b6f194 100644 --- a/provision/overview.mdx +++ b/provision/cloud-provider.mdx @@ -1,6 +1,6 @@ --- -title: "Provisioning Infrastructure" -sidebarTitle: "Overview" +title: "Provisioning Cloud Provider" +sidebarTitle: "Cloud Provider" --- Porter provisions and manages the underlying infrastructure in your own cloud. During project creation, Porter will prompt you to provision resources in a cloud provider of your choice.