chore: improved orphan deletion description (#1024)

Author: vmyroslav

controllers/basic_controller.go

@@ -379,23 +379,24 @@ func (i *instanceReconcilerHelper) getObjectRefs(ctx context.Context, o client.O
 // that we can retry during the next reconciliation. When applicable, it retrieves an associated object that
 // has to be deleted from Kubernetes, and it could be a secret associated with an instance.
 func (i *instanceReconcilerHelper) finalize(ctx context.Context, o v1alpha1.AivenManagedObject) (bool, error) {
-	i.rec.Event(o, corev1.EventTypeNormal, eventTryingToDeleteAtAiven, "trying to delete instance at aiven")
-
 	var err error
 	finalised := true
 	deletionPolicy := deletionPolicyDelete
 
 	// Parse the annotations for the deletion policy. For simplicity, we only allow 'Orphan'.
 	// If set will skip the deletion of the remote object. Disable by removing the annotation.
 	if p, ok := o.GetAnnotations()[deletionPolicyAnnotation]; ok {
-		deletionPolicy = deletionPolicyOrphan
-		if p != deletionPolicyOrphan {
+		if p == deletionPolicyOrphan {
+			deletionPolicy = deletionPolicyOrphan
+			i.log.Info("'Orphan' deletion policy detected - Aiven resource will be preserved on Kubernetes resource deletion")
+		} else {
 			i.log.Info(fmt.Sprintf("Invalid deletion policy! Only '%s' is allowed.", deletionPolicyOrphan))
 			finalised = false
 		}
 	}
 
 	if deletionPolicy == deletionPolicyDelete {
+		i.rec.Event(o, corev1.EventTypeNormal, eventTryingToDeleteAtAiven, "trying to delete instance at aiven")
 		finalised, err = i.h.delete(ctx, i.avnGen, o)
 		if err != nil {
 			meta.SetStatusCondition(o.Conditions(), getErrorCondition(errConditionDelete, err))
@@ -432,20 +433,24 @@ func (i *instanceReconcilerHelper) finalize(ctx context.Context, o v1alpha1.Aive
 
 	// checking if instance was finalized, if not triggering a requeue
 	if !finalised {
-		i.log.Info("instance is not yet deleted at aiven, triggering requeue")
+		i.log.Info("instance is not yet deleted at Aiven, triggering requeue")
 		return true, nil
 	}
 
-	i.log.Info("instance was successfully deleted at aiven, removing finalizer")
-	i.rec.Event(o, corev1.EventTypeNormal, eventSuccessfullyDeletedAtAiven, "instance is gone at aiven now")
+	if deletionPolicy == deletionPolicyOrphan {
+		i.log.Info("Kubernetes resource finalized with orphan policy - Aiven resource preserved")
+	} else {
+		i.log.Info("instance was successfully deleted at Aiven, removing finalizer")
+		i.rec.Event(o, corev1.EventTypeNormal, eventSuccessfullyDeletedAtAiven, "instance is gone at aiven now")
+	}
 
 	// remove finalizer, once all finalizers have been removed, the object will be deleted.
 	if err := removeFinalizer(ctx, i.k8s, o, instanceDeletionFinalizer); err != nil {
 		i.rec.Event(o, corev1.EventTypeWarning, eventUnableToDeleteFinalizer, err.Error())
 		return false, fmt.Errorf("unable to remove finalizer: %w", err)
 	}
 
-	i.log.Info("finalizer was removed, instance is deleted")
+	i.log.Info("finalizer was removed, resource is deleted")
 	return false, nil
 }
 

docs/docs/guides/deletion-policy.md

@@ -0,0 +1,35 @@
+# Deletion Policy
+
+The Aiven Operator provides a deletion policy annotation that prevents deletion of Aiven resources when Kubernetes resources are removed. This feature works with all Aiven operator resources.
+
+## Overview
+
+By default, when you delete an Aiven operator resource (like `PostgreSQL`, `KafkaTopic`, `ServiceUser`, etc.), the operator deletes both the Kubernetes resource and the corresponding Aiven service. The `controllers.aiven.io/deletion-policy: Orphan` annotation allows you to override this behavior and preserve the Aiven resource while removing only the Kubernetes resource.
+
+## Using the Deletion Policy
+
+### Step 1: Add the Annotation
+
+Add the deletion policy annotation to the resource you want to protect:
+
+```yaml
+apiVersion: aiven.io/v1alpha1
+kind: PostgreSQL  # or any other Aiven resource
+metadata:
+  name: my-database
+  namespace: my-namespace
+  annotations:
+    controllers.aiven.io/deletion-policy: Orphan
+spec:
+  # ... existing configuration
+```
+
+### Step 2: Delete the Kubernetes Resource
+
+Now you can safely delete the Kubernetes resource:
+
+```bash
+kubectl delete postgresql my-database -n my-namespace
+```
+
+The Kubernetes resource is deleted, but the Aiven service remains intact and continues running.

docs/mkdocs.yml

@@ -73,6 +73,7 @@ nav:
           - troubleshooting.md
           - installation/uninstalling.md
           - guides/token-management.md
+          - guides/deletion-policy.md
       - Resources: &crds
           - resources/alloydbomni.md
           - resources/cassandra.md