Skip to main content

Deleting an Application

How to permanently remove an application from the platform.

This guide covers decommissioning an application — removing its deployments, ArgoCD application, and Kubernetes namespace. Use this when the application is no longer needed and you want to clean up platform resources.

This is destructive

Deleting an application removes all in-cluster resources (pods, services, configmaps, secrets, PVCs) in its namespace. This cannot be undone. If you're unsure, consider archiving the repo instead — that preserves the deployment while stopping active development.

Permissions required

Most developers do not have the permissions needed to delete platform resources directly. If you do not have the required access, contact one of your organization's platform admins to perform the deletion on your behalf.

Before You Start​

  • Confirm the application is no longer needed — check with dependent teams
  • Identify the application's namespace (usually matches the repo name — see How the Namespace Is Set)
  • Find the ArgoCD application and verify which environments it's deployed to (dev, stg, prd)
  • Identify downstream dependencies — other services that call this application
  • Check for in-cluster state (PVCs, in-cluster databases) that would be lost
  • Back up anything you need from the namespace (secrets, configmaps, data)
  • Notify dependent teams and agree on a timeline

What Gets Removed​

The following resources are deleted when you remove an application:

  • Kubernetes namespace and everything in it (deployments, services, configmaps, secrets, ingress, PVCs, network policies)
  • ArgoCD application
  • .platform/kubernetes/<name> folder in the .platform repo

What's Retained​

  • Container images in JFrog (removed separately if desired)
  • Historical logs, metrics, and traces in observability tools
  • External databases and data stores
  • DNS entries (may need manual cleanup)
  • The source repository (archive or delete separately)

Delete Steps​

The cleanest approach is to temporarily enable meta.p6m.dev/vacuum-argo before removing the manifests. This tells ArgoCD to cascade-delete all managed Kubernetes resources automatically when the application is removed.

1. Enable vacuum-argo

Set the annotation in your .platform/organization/organization.yaml (org-wide) or on a specific environment in environments.yaml:

# .platform/organization/organization.yaml
metadata:
  annotations:
    meta.p6m.dev/vacuum-argo: "true"
Propagation delay

Changes to the organization spec take approximately 15 minutes to propagate. Wait for the setting to take effect before proceeding.

2. Remove the platform manifests

Delete the .platform/kubernetes/<app-name> folder from your .platform repo for each environment where the application is deployed. Merge to main.

The ApplicationSet controller will cascade-delete the ArgoCD application and all its managed Kubernetes resources.

3. Verify deletion

# Confirm the ArgoCD application is gone
# (check the ArgoCD UI, or use the CLI)
argocd app list | grep <app-name>

# Confirm the namespace has been removed
kubectl get namespace <app-name>

4. Disable vacuum-argo

Set the annotation back to "false" (or remove it) and wait for propagation (~15 min).

# .platform/organization/organization.yaml
metadata:
  annotations:
    meta.p6m.dev/vacuum-argo: "false"
caution

Vacuum-argo causes ArgoCD to cascade-delete resources for all applications in scope, not just the one you're removing. Leaving it on risks unintended data loss if an application is accidentally removed in the future.

Validation​

  • ArgoCD application is gone in all environments
  • Kubernetes namespace is deleted (or empty and removed)
  • No orphaned resources remain
  • Dependent services have been updated to remove references
  • DNS entries cleaned up (if applicable)
  • Monitoring dashboards and alerts removed or updated

Troubleshooting​

Stuck Namespace​

A namespace stuck in Terminating state usually means a finalizer is blocking deletion. Check for stuck finalizers:

kubectl get namespace <app-name> -o json | jq '.spec.finalizers'

If finalizers are present and the namespace is otherwise empty, you can remove them to unblock deletion. Investigate what created the finalizer first — it may indicate a resource that hasn't been cleaned up.

Lingering PVCs​

PersistentVolumeClaims with Retain reclaim policy won't be automatically deleted. Check for them:

kubectl get pvc -n <app-name>

Delete them manually after confirming the data is no longer needed.

RBAC / Permission Errors​

If you don't have permission to delete the namespace or ArgoCD application, you may need elevated access. Check with the platform team.

Rollback​

If you deleted an application and need it back:

  1. Restore the .platform/kubernetes/<app-name> folder in the .platform repo (revert the commit)
  2. Re-run the CI/CD pipeline to rebuild and deploy
warning

In-cluster state (PVC data, secrets not backed by external stores) is gone once the namespace is deleted. Only the deployment itself can be recreated — not the data.