diff --git a/cloud-accounts/connecting-a-cloud-account.mdx b/cloud-accounts/connecting-a-cloud-account.mdx index d71e982..5d35c69 100644 --- a/cloud-accounts/connecting-a-cloud-account.mdx +++ b/cloud-accounts/connecting-a-cloud-account.mdx @@ -51,13 +51,15 @@ Before Porter can create a cluster, you need to grant it access to your cloud ac ## Revoking Access - To revoke Porter's access: + The cleanest way to remove an AWS account is to [delete the cloud account from Porter](/cloud-accounts/deleting-a-cloud-account). Porter tears down the IAM roles it created and walks you through removing `porter-access-manager`. - 1. First, delete any clusters through the Porter dashboard - 2. Navigate to **CloudFormation Stacks** in your AWS console - 3. Select the stack named `PorterRole` and click **Delete** + If you only want to revoke access manually: + + 1. Delete any clusters through the Porter dashboard. + 2. Navigate to **CloudFormation Stacks** in your AWS console. + 3. Select the stack named `PorterRole` and click **Delete**. - This removes the IAM role and prevents Porter from accessing your account. + This removes the IAM role and prevents Porter from accessing your account. The cloud account will remain visible in Porter until you delete it from the dashboard. diff --git a/cloud-accounts/deleting-a-cloud-account.mdx b/cloud-accounts/deleting-a-cloud-account.mdx new file mode 100644 index 0000000..113b69e --- /dev/null +++ b/cloud-accounts/deleting-a-cloud-account.mdx @@ -0,0 +1,128 @@ +--- +title: "Deleting a cloud account" +sidebarTitle: "Deleting a Cloud Account" +description: "Permanently remove an AWS cloud account from Porter, tear down the IAM roles Porter created, and revoke Porter's access to your AWS account" +--- + +You can permanently remove an AWS cloud account from a Porter project. Porter tears down the IAM roles and policies it created in your AWS account, and you finish the deletion by removing the `porter-access-manager` role you originally provisioned with CloudFormation. + + +Cloud account deletion is currently supported for **AWS** only. To stop using a GCP or Azure account with Porter, see the revoking access sections in [Connecting a cloud account](/cloud-accounts/connecting-a-cloud-account). + + +## Before You Delete + +Porter will refuse to delete a cloud account that is still in use. Before you start, remove every Porter resource that references the account: + +- **Clusters** provisioned in the account ([Deleting a cluster](/cloud-accounts/deleting-a-cluster)) +- **Object storage** buckets Porter created in the account (such as build artifact buckets) +- **Environment groups** with secrets backed by the account + +If any of these still exist, the dashboard surfaces them as blockers and the delete button stays disabled until they are removed. + + +Deleting a cloud account cannot be undone. To reconnect the same AWS account later, you have to redeploy the CloudFormation stack and add the account to Porter again from scratch. + + +--- + +## Delete the Cloud Account + + + + In the Porter dashboard, navigate to **Integrations** → **Cloud accounts** and select the AWS account you want to remove. + + + Scroll to the **Delete cloud account** section. If any clusters, object storage buckets, or environment groups still reference the account, they are listed here and the **Delete cloud account** button is disabled. + + Delete each listed resource, then return to this page. + + + Click **Delete cloud account** and confirm in the dialog. Porter immediately: + + - Marks the account as `deletion_pending`. + - Stops accepting new clusters or workloads against it. + - Begins tearing down the IAM roles and policies it created in your AWS account (`porter-manager`, `porter-infra-manager`, `porter-control-plane-manager`, `porter-node-manager`, `porter-karpenter`, and related policies). + + The account view switches to a **Deletion in progress** screen that shows the teardown steps as they complete. + + + Porter cannot delete the `porter-access-manager` role itself — that role lives in your account and is what gives Porter permission to do the teardown. Once Porter shows **IAM roles** and **IAM policies** as deleted, finish removing the account by deleting the role yourself: + + 1. Open the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation). + 2. Find the stack you originally created when connecting Porter (typically named `PorterRole`). + 3. Click **Delete**. + + Deleting the stack removes `porter-access-manager` and the associated `porter-permissions-boundary` policy. As soon as Porter can no longer assume the role, it marks **Access revoked** as complete and removes the cloud account from your project. + + + + +You can leave the **Deletion in progress** page at any time. Porter continues to retry the teardown in the background and finalizes the deletion automatically once `porter-access-manager` is gone. + + +--- + +## Deletion States + +While deletion is in progress, the cloud account moves through three stages: + +| Stage | What Porter does | What you do | +|-------|------------------|-------------| +| **IAM roles** | Deletes each Porter-managed IAM role in your AWS account. | Nothing. | +| **IAM policies** | Deletes the standalone customer-managed policies Porter created (cluster autoscaler, EKS manager, EC2 and networking, load balancer, VPC manager, Karpenter). | Nothing. | +| **Access revoked** | Waits until it can no longer assume `porter-access-manager`. | Delete the `PorterRole` CloudFormation stack to remove `porter-access-manager`. | + +If any teardown step fails (for example, because a Porter-managed role has been modified outside of Porter), the failure message is shown on the deletion screen and Porter keeps retrying. Contact support through the dashboard chat if a failure persists. + +--- + +## Deleting via the API + +Cloud account deletion is also available through the Porter API. The endpoint returns `202 Accepted` immediately and the deletion proceeds asynchronously. + +```bash +curl -X DELETE \ + "https://api.porter.run/api/v2/projects/{project_id}/clouds/{cloud_account_id}" \ + -H "Authorization: Bearer $PORTER_TOKEN" +``` + +Common responses: + +| Status | Meaning | +|--------|---------| +| `202 Accepted` | Deletion started. The account is now `deletion_pending`. | +| `400 Bad Request` | The account is not an AWS account. Only AWS deletion is supported. | +| `404 Not Found` | The cloud account does not exist in this project. | +| `409 Conflict` | The account still has dependent clusters, object storage, or environment groups. | + +You can check for dependents before issuing the delete: + +```bash +curl \ + "https://api.porter.run/api/v2/projects/{project_id}/clouds/{cloud_account_id}/dependents" \ + -H "Authorization: Bearer $PORTER_TOKEN" +``` + +The response lists active `clusters`, `object_storage` buckets, and `environment_groups` referencing the account. Empty arrays mean the account is safe to delete. + +Poll the cloud account to watch deletion progress — the `status.state` field reports `deletion_pending` until the account is fully removed, and `status.deletion` contains the per-step teardown state shown in the dashboard. + +--- + +## Troubleshooting + + + + The dashboard lists the clusters, object storage buckets, or environment groups still tied to the account. Delete each one and refresh the page. If you see a resource you no longer recognize, check the [Deleting Dangling Resources](/other/deleting-dangling-resources) guide. + + + Porter is waiting on you. Delete the `PorterRole` CloudFormation stack in your AWS account to remove `porter-access-manager`. Once Porter can no longer assume that role, deletion finalizes within a minute. + + + Porter reports the underlying AWS error on the deletion screen. The most common cause is that someone modified or deleted a Porter-managed IAM role or policy outside of Porter. Porter keeps retrying — if the failure persists, contact support through the dashboard chat with your project ID and the failure message. + + + Porter can no longer assume into your account to clean up the roles it created. Delete the remaining Porter-managed roles and policies manually from the IAM console, then contact support to remove the cloud account record from your project. + + diff --git a/cloud-accounts/deleting-a-cluster.mdx b/cloud-accounts/deleting-a-cluster.mdx index 4ff924d..3b021e6 100644 --- a/cloud-accounts/deleting-a-cluster.mdx +++ b/cloud-accounts/deleting-a-cluster.mdx @@ -35,7 +35,9 @@ Before deleting your cluster: This process may take up to 30 minutes. - After the cluster is deleted: + After the cluster is deleted, if you also want to disconnect the AWS account from Porter, [delete the cloud account](/cloud-accounts/deleting-a-cloud-account). Porter tears down the IAM roles it created and guides you through removing the `PorterRole` CloudFormation stack. + + If you only want to revoke access manually without removing the cloud account from Porter: 1. Navigate to **CloudFormation Stacks** in your AWS console 2. Select the stack named `PorterRole` diff --git a/mint.json b/mint.json index ac0c6d9..a546c85 100644 --- a/mint.json +++ b/mint.json @@ -49,7 +49,8 @@ "cloud-accounts/cluster-upgrades", "cloud-accounts/advanced-cluster-settings", "cloud-accounts/cluster-observability", - "cloud-accounts/deleting-a-cluster" + "cloud-accounts/deleting-a-cluster", + "cloud-accounts/deleting-a-cloud-account" ] }, {