Document deleting orphaned Kubernetes objects

src/pages/docs/argo-cd/live-object-status/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-03-28
-modDate: 2026-03-19
+modDate: 2026-08-24
 navSection: Live Object Status
 title: Overview
 navTitle: Overview
@@ -90,6 +90,10 @@ Sync Status tracks whether the changes Octopus pushed to git still match what Ar
 | Git Drift   |  <i class="fa-solid fa-not-equal orange"></i> | Octopus has detected that the changes it applied to git have been modified since the last deployment (e.g. by a manual edit) |
 | Unknown     |   <i class="fa-solid fa-question grey"></i>   | We don't have information about the live status of this object                                                               |
 
+:::div{.info}
+Objects observed through Argo CD are never marked as **Orphaned**. Argo CD has its own [pruning](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/#no-prune-resources) behavior for objects removed from git.
+:::
+
 ### Detailed object information
 
 Selecting an object or application name in the table will open a drawer containing detailed information.

src/pages/docs/kubernetes/live-object-status/deleting-orphaned-objects.md

@@ -0,0 +1,88 @@
+---
+layout: src/layouts/Default.astro
+pubDate: 2026-08-19
+modDate: 2026-08-24
+navSection: Deleting orphaned objects
+title: Deleting orphaned objects
+navTitle: Deleting orphaned objects
+description: How to review and delete Kubernetes objects that Octopus no longer deploys but that are still running in your cluster.
+navOrder: 60
+---
+
+When a deployment stops including an object that a previous release deployed, Octopus marks that object as **Orphaned** in Kubernetes Live Object Status, and it keeps running in your cluster until someone removes it. Octopus can delete orphaned objects for you, one at a time or in bulk, from the project's Live Status page.
+
+## Requirements
+
+To delete orphaned objects you need:
+
+- The `DeployedResourceAdminister` permission for the project, environment, and tenant you are deleting in
+- A Kubernetes agent whose service account is allowed to delete the objects in question
+- Objects reported by the [Kubernetes monitor](/docs/kubernetes/targets/kubernetes-agent/kubernetes-monitor). Objects observed through Argo CD are never orphaned and cannot be deleted this way
+
+## Delete orphaned objects
+
+Open your project and select **Live Status** for the environment (and tenant) you want. The table offers a delete action on every orphaned row, and when an application has orphaned objects the page also shows a card counting them. To list only orphaned objects, use the **Sync status** filter and select **Orphaned**.
+
+:::figure
+![Live Status table showing orphaned objects](/docs/img/kubernetes/live-object-status/live-status-orphaned-objects.png)
+:::
+
+### A single object
+
+1. Open the row's **Resource actions** menu and choose **Review & delete**.
+2. Confirm in the **Delete orphaned resource** dialog by choosing **Delete**.
+
+You can also select the object to open its detail drawer and use the **Delete** button there.
+
+### Several objects at once
+
+1. Choose **Review & delete** on the orphaned-objects card to open the **Delete orphaned resources** drawer.
+2. Select the objects to delete. Objects are grouped by deployment target, so you can select a whole target or everything at once.
+3. Choose **Next**.
+4. Review the **Confirm deletion** step, which lists every selected object grouped by deployment target.
+5. Choose **Delete**.
+
+## The deletion task
+
+Each request queues one **Delete Kubernetes resources** task, which is linked from the Kubernetes resource being deleted. Deletion tasks can run at the same time as deployments.
+
+The deletion task runs a script on the Kubernetes Agent that calls `kubectl delete` with a 5 minute timeout for each resource. If some objects delete and others don't, the task deletes everything it can, records every outcome, and then fails.
+
+Octopus validates your selection when you confirm, and silently skips an object when:
+
+- The object is no longer orphaned, most likely because a deployment re-added it.
+- A deletion task for the object is already queued or running.
+- The monitor no longer reports the object in the cluster, so there is nothing to delete.
+- Status information for the object is stale, so Octopus cannot safely delete it.
+
+## Permissions
+
+Deleting an orphaned object needs permission in two places: in Octopus, to request the deletion, and in your cluster, for the agent that carries it out.
+
+### Octopus permissions
+
+Requesting a deletion requires the `DeployedResourceAdminister` permission ("Administer deployed resources managed by Octopus"), scoped to the project, environment, and tenant. It is included by default in the **Project Contributor**, **Project Deployer**, **Project Lead**, and **Space Manager** built-in roles.
+
+### Cluster permissions
+
+Octopus deletes objects by running `kubectl delete` on the Kubernetes agent, so the deletion uses the **agent's** service account. Make sure that account is allowed to delete the kinds and namespaces you expect to clean up. When you use the [permissions controller](/docs/kubernetes/targets/kubernetes-agent/granular-permissions) to scope permissions per step, deletions run under the reserved step slug `octopus-kubernetes-resource-deletion`.
+
+## Auditing
+
+Every deletion task writes one audit event to the **Audit** screen in **Configuration**, succeeded or failed, recorded against the user who requested it. Its details list every object with its outcome, grouped by deployment target, with failures first.
+
+## Known limitations
+
+- Only top-level orphaned objects can be deleted. Child objects, such as Pods belonging to a Deployment can't be deleted from Octopus to restart a service.
+- You cannot stop tracking an orphaned object without deleting it. If the object is still needed by something else, delete it and recreate it from a different project.
+
+## Version notes
+
+- Deleting orphaned Kubernetes objects requires Octopus Server 2026.3.13597 and Kubernetes agent version 2.38.3 or later (v2) / 3.0.1 or later (v3).
+
+## Learn more
+
+- [Kubernetes Live Object Status](/docs/kubernetes/live-object-status)
+- [Orphaned objects](/docs/kubernetes/live-object-status#orphaned-objects)
+- [Troubleshooting Live Object Status](/docs/kubernetes/live-object-status/troubleshooting)
+- [Kubernetes agent permissions controller](/docs/kubernetes/targets/kubernetes-agent/granular-permissions)

src/pages/docs/kubernetes/live-object-status/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-03-28
-modDate: 2026-05-24
+modDate: 2026-08-24
 navSection: Live Object Status
 title: Kubernetes Live Object Status
 navTitle: Overview
@@ -79,31 +79,30 @@ Sync Status tracks whether the changes Octopus deployed still matches the resour
 
 ### Object Sync Status
 
-| Label       |                  Status Icon                  | Description                                                                                      |
-| :---------- | :-------------------------------------------: | :----------------------------------------------------------------------------------------------- |
-| In Sync     |    <i class="fa-solid fa-check green"></i>    | Object manifest matches what was applied                                                         |
-| Out of Sync |  <i class="fa-solid fa-arrow-up orange"></i>  | Object manifest is not the same as what was applied                                              |
-| Unknown     |   <i class="fa-solid fa-question grey"></i>   | We don't have information about the live status of this object                                   |
-| Orphaned    | <i class="fa-solid fa-link-slash orange"></i> | Object was deployed in a previous release but is no longer part of the latest deployment process |
+| Label       |                                   Status Icon                                  | Description                                                                                      |
+| :---------- | :----------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------- |
+| In Sync     |                     <i class="fa-solid fa-check green"></i>                    | Object manifest matches what was applied                                                         |
+| Out of Sync |                   <i class="fa-solid fa-arrow-up orange"></i>                  | Object manifest is not the same as what was applied                                              |
+| Unknown     |                    <i class="fa-solid fa-question grey"></i>                   | We don't have information about the live status of this object                                   |
+| Orphaned    | <i class="fa-solid fa-link-slash" style="color: var(--colorIconWarning);"></i> | Object was deployed in a previous release but is no longer part of the latest deployment process |
+| Deleting    |                   <i class="fa-solid fa-hourglass blue"></i>                   | Octopus is deleting this orphaned object. Select the status to open the task doing the work      |
 
 Take a look at our [troubleshooting guide](/docs/kubernetes/live-object-status/troubleshooting) for details on why you may see some object statuses
 
 ### Orphaned objects
 
-When you deploy a project that no longer includes a resource that was deployed in a previous release (for example, you remove a resource from a YAML manifest or remove a step from the deployment process), Octopus marks the dropped resource as **Orphaned** in the Live Status table.
+When a deployment succeeds and no longer includes an object that was deployed in a previous release (for example, you remove an object from a YAML manifest or remove a step from the deployment process), Octopus marks the dropped object as **Orphaned** in the Live Status table.
 
 Orphaned objects:
 
 - keep their existing Health Status, so Octopus continues tracking them while they remain in your cluster
-- have **Orphaned** as their Sync Status (shown with the link-slash icon in the table above)
-- are summarized by a total-orphans count shown on the project's Live Status page
-- can be narrowed to by using the Live Status table's filter and selecting **Orphaned**
+- have **Orphaned** as their Sync Status
+- are excluded from the rolled-up Application Health Status and Application Sync Status
+- can be deleted directly from Octopus, see [deleting orphaned objects](/docs/kubernetes/live-object-status/deleting-orphaned-objects)
 
-The orphan state clears automatically on the next deployment that re-adds the resource. If you remove an orphaned object from your cluster directly (for example with `kubectl delete`), the Kubernetes monitor detects the removal and Octopus stops tracking the resource, so the orphan entry disappears from the Live Status table without any manual intervention.
+Orphans are detected only after a **successful** deployment, so a failed deployment never marks anything as orphaned.
 
-:::div{.info}
-Orphaned-resource tracking requires every Kubernetes monitor in the application instance to be on agent version 2.38.3 or later (v2) / 3.0.1 or later (v3). On clusters with any older agent, the resource is silently removed from the Live Status table when it is dropped from a deployment, matching the previous behavior.
-:::
+Skipping a step, or disabling it, does not orphan the objects that step deploys. Octopus only orphans an object when the step that deployed it ran and no longer produces it, or when that step has been removed from the deployment process altogether.
 
 ### Detailed object information
 
@@ -154,6 +153,8 @@ The Kubernetes Agent has a new component called the Kubernetes monitor which als
 
 During a deployment, Octopus will capture any applied Kubernetes manifests and send them to the monitor. The monitor uses these manifests to track the deployed objects in the cluster, keeping track of their synchronization and health.
 
+Objects applied by a step that is skipped or disabled in a later deployment keep their live status. Octopus continues to track them from the deployment that applied them.
+
 ### Script steps
 
 The built in Kubernetes steps will automatically report the applied manifests for deployments, however Octopus needs a bit of help when you're making changes using kubectl script steps.
@@ -215,6 +216,8 @@ Viewing the data returned from the Kubernetes monitor from within Octopus requir
 
 This data includes the resource and application status, as well as pod logs and events for objects being monitored. This may be a change in security posture that your team should carefully consider.
 
+Deleting an orphaned object additionally requires the `DeployedResourceAdminister` permission, and the Kubernetes agent's own service account must be allowed to delete the object. See [deleting orphaned objects](/docs/kubernetes/live-object-status/deleting-orphaned-objects#permissions).
+
 ## Secrets
 
 ### Octopus sensitive variables
@@ -256,12 +259,11 @@ This setting defaults to on for all projects, but may change in the future.
 
 ## Known issues and limitations
 
-### Excluded steps
-
-The desired object list is compiled from objects that were applied during the last deployment. If steps are excluded during a deployment, then live status will not be shown for objects that were applied in those steps.
-
-Please avoid skipping steps that deploy Kubernetes objects.
-
 ### Runbooks are not supported
 
 Objects modified by Runbooks are not monitored. Please deploy the objects via a Deployment if you want them to be monitored.
+
+## Version notes
+
+- [Deleting orphaned objects](/docs/kubernetes/live-object-status/deleting-orphaned-objects) is available from Octopus Server 2026.3.13597.
+- Orphan detection requires Octopus Server 2026.3, as well as every Kubernetes monitor in the project/environment/tenant combination to be on agent version 2.38.3 or later (v2) / 3.0.1 or later (v3). If you are on an older version, an object dropped from a deployment is removed from Live Status instead of being marked **Orphaned**.

src/pages/docs/kubernetes/live-object-status/troubleshooting/index.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-03-28
-modDate: 2026-01-21
+modDate: 2026-08-24
 navTitle: Troubleshooting
 title: Troubleshooting
 navSection: Troubleshooting
@@ -86,3 +86,33 @@ If possible, we recommend ensuring that
 
 - Octopus is the only entity to modify your deployments
 - You craft your Kubernetes manifests to ensure that there are no invalid fields
+
+### Why is an object not orphaned after a deployment? \{#object-not-orphaned}
+
+An object is marked [Orphaned](/docs/kubernetes/live-object-status#orphaned-objects) when a deployment succeeds and no longer deploys an object that a previous release deployed. Common causes are renaming an object, removing the object from a manifest, or removing the step that deployed it from the deployment process.
+
+Skipping or disabling a step does not orphan its objects.
+
+If you expected an object to be orphaned and it isn't, check that every Kubernetes monitor referenced by the project is on an agent version that supports orphan tracking, listed in the [version notes](/docs/kubernetes/live-object-status#version-notes). Orphan tracking is all-or-nothing for a given project/environment/tenant combination.
+
+### An object stays orphaned after I re-added the step \{#orphan-persists-after-re-adding-a-step}
+
+Octopus clears the orphan state when a deployment deploys the object again. You must deploy the release after re-adding a step that was removed.
+
+## Deleting orphaned objects \{#deleting-orphaned-objects}
+
+### Octopus says an object was deleted but it's still in my cluster \{#deleted-object-still-present}
+
+Deleting an object deletes its dependents in the background, so a successful deletion returns as soon as the object itself is gone. Kubernetes garbage collects what it owned afterwards, which means deleting a Deployment reports success while its ReplicaSets and Pods are still being removed.
+
+### A deletion failed \{#deletion-failed}
+
+Open the deletion task from the warning icon beside the object. The task log contains detailed error messages to help troubleshooting.
+
+The most common cause is cluster permissions. Deletions run on the Kubernetes agent using the agent's service account, so the agent needs `delete` on that kind and namespace. See [cluster permissions](/docs/kubernetes/live-object-status/deleting-orphaned-objects#cluster-permissions).
+
+### I can't delete an object because its status is stale \{#cannot-delete-stale-object}
+
+Octopus refuses to delete an object whose status information is stale, because it can't confirm what is actually in the cluster. Status goes stale after 10 minutes without an update from the Kubernetes monitor.
+
+Follow [failed to establish connection with Kubernetes monitor](/docs/kubernetes/live-object-status/troubleshooting#failed-to-establish-connection-with-kubernetes-monitor) to get the monitor reporting again, then retry the deletion.

src/pages/docs/kubernetes/targets/kubernetes-agent/granular-permissions.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-9-24
-modDate: 2025-9-24
+modDate: 2026-08-24
 title: Granular Permissions
 description: Define Kubernetes RBAC for your Kubernetes agent deployment based on Octopus context
 navOrder: 22
@@ -119,6 +119,10 @@ Each field adheres to the following rules to match:
 
 Each `WorkloadServiceAccount` must have at least one non-empty field. You cannot have a `WorkloadServiceAccount` that matches every scope.
 
+:::div{.info}
+[Deleting an orphaned Kubernetes object](/docs/kubernetes/live-object-status/deleting-orphaned-objects) is not run by a deployment step, so it uses the reserved step slug `octopus-kubernetes-resource-deletion`. Use that slug in the `steps` scope to grant the `delete` permissions those cleanups need without widening what your deployments can do.
+:::
+
 ##### Permissions
 
 The permissions applied for each scope can be configured a couple of ways:
@@ -246,3 +250,7 @@ If you do not have access to query the Kubernetes cluster, we recommend you make
 :::div{.hint}
 To list all the permissions you have within a particular namespace, add `kubectl auth can-i --list -n <your-namespace>` to your script.
 :::
+
+## Version notes
+
+- The reserved step slug `octopus-kubernetes-resource-deletion`, used when [deleting orphaned Kubernetes objects](/docs/kubernetes/live-object-status/deleting-orphaned-objects), is available from Octopus Server 2026.3.13597.