From 66fcfd468a186824d751389dffc9c4c49088a13a Mon Sep 17 00:00:00 2001 From: "joggrbot[bot]" <107281636+joggrbot[bot]@users.noreply.github.com> Date: Wed, 1 Apr 2026 17:22:20 +0000 Subject: [PATCH] [skip ci] docs: fix outdated docs --- docs/api/resourcemanager.md | 35 ++++++++++--- .../controllers/project-controller/README.md | 50 ++++++++++++------- 2 files changed, 60 insertions(+), 25 deletions(-) diff --git a/docs/api/resourcemanager.md b/docs/api/resourcemanager.md index c8b75e94..165a82ee 100644 --- a/docs/api/resourcemanager.md +++ b/docs/api/resourcemanager.md @@ -25,6 +25,7 @@ Resource Types: + OrganizationMembership establishes a user's membership in an organization and optionally assigns roles to grant permissions. The controller automatically manages PolicyBinding resources for each assigned role, simplifying access @@ -676,7 +677,6 @@ This information is populated by the controller from the referenced user. - Use lowercase for path, which influences plural name. Ensure kind is Organization. Organization is the Schema for the Organizations API @@ -876,7 +876,6 @@ with respect to the current state of the instance.
- Project is the Schema for the projects API. @@ -1009,9 +1008,9 @@ ProjectStatus defines the observed state of Project. @@ -1025,6 +1024,29 @@ Known condition types are: "Ready"
Condition contains details for one aspect of the current state of this API Resource. +For Project resources, known condition types include: +- **Ready**: Indicates project and infrastructure are ready for use. See the Reason for additional details. +- **ResourceCleanup**: Indicates progress and completion of project resource deletion when the project is being deleted. This condition is managed by the controller to track cleanup status. + +For the **ResourceCleanup** condition, the following values are used: +- **status**: + - `True` when cleanup is ongoing, + - `False` when cleanup is complete. +- **reason**: + - `CleanupStarted`: Resource cleanup (deletion) has started; delete commands are being issued. + - `CleanupAwaitingCompletion`: Cleanup commands have been issued and the controller is waiting for resources to be removed. + - `CleanupComplete`: All resources have been deleted and finalizer will be removed, completing project deletion. + +Example: +``` +status: + conditions: + - type: ResourceCleanup + status: "False" + reason: CleanupComplete + message: Project resources have been deleted +``` +
[]object Represents the observations of a project's current state. -Known condition types are: "Ready"
-
- Default: [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for control plane to reconcile reason:Unknown status:Unknown type:Ready]]
+Known condition types are: "Ready" and "ResourceCleanup". +
+Default: [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for control plane to reconcile reason:Unknown status:Unknown type:Ready]]
 false
@@ -1039,7 +1061,7 @@ Condition contains details for one aspect of the current state of this API Resou @@ -1093,3 +1115,4 @@ with respect to the current state of the instance.
string lastTransitionTime is the last time the condition transitioned from one status to another. -This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
+This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

Format: date-time
 false
+ \ No newline at end of file diff --git a/docs/architecture/controllers/project-controller/README.md b/docs/architecture/controllers/project-controller/README.md index c0acb7f4..9283ebc7 100644 --- a/docs/architecture/controllers/project-controller/README.md +++ b/docs/architecture/controllers/project-controller/README.md @@ -66,8 +66,7 @@ the following reconciliation logic: 1. **Fetch Project**: Retrieve the `Project` resource from the control plane cluster -2. **Handle Finalizers**: Process deletion and cleanup if the project is being - deleted +2. **Handle Finalizers & Cleanup**: If the project is being deleted, transition through resource cleanup conditions (see Deletion and Cleanup section below) before removing the finalizer. 3. **Check Readiness**: Skip reconciliation if the project is already in a ready state 4. **Provision Infrastructure**: Create or update the `ProjectControlPlane` in @@ -214,30 +213,35 @@ sequenceDiagram API->>PC: Project Deletion Event PC->>PC: Check finalizers exist - PC->>InfraAPI: Get ProjectControlPlane - InfraAPI-->>PC: ProjectControlPlane found - - PC->>InfraAPI: Delete ProjectControlPlane - InfraAPI-->>PC: ProjectControlPlane deleted - - Note over PC: Wait for infrastructure cleanup - PC->>InfraAPI: Verify ProjectControlPlane deleted - InfraAPI-->>PC: Not Found (404) - - PC->>API: Remove finalizer from Project + Note over PC: Start multi-phase resource cleanup + loop Resource cleanup process + PC->>PC: Set ResourceCleanup condition to CleanupStarted + PC->>InfraAPI: Issue delete commands for project resources + PC->>PC: Set ResourceCleanup condition to CleanupAwaitingCompletion + PC->>InfraAPI: Poll resource state (IsPurgeComplete) + alt Resources remain + PC->>PC: Set ResourceCleanup condition to CleanupStarted (reissue deletes) + else All resources gone + PC->>PC: Set ResourceCleanup condition to CleanupComplete + PC->>API: Remove finalizer + end + end API->>API: Complete Project deletion API-->>User: Project deleted ``` #### Deletion Steps -The controller implements proper cleanup using Kubernetes finalizers: +The controller implements proper multi-phase cleanup using Kubernetes finalizers and status conditions: + +1. **Finalizer Registration**: Adds finalizer to `Project` during creation. +2. **Deletion Detection**: Detects when `Project` has `deletionTimestamp` set. +3. **Resource Cleanup Initiation**: Sets the `ResourceCleanup` condition with reason `CleanupStarted`, issues delete commands for project resources. +4. **Awaiting Resource Deletion**: Sets the condition to `CleanupAwaitingCompletion` while waiting for all project resources (e.g., namespaces, resources) to be removed in the target cluster. +5. **Retry if Needed**: If resources remain, sets `CleanupStarted` again to re-issue deletes. +6. **Cleanup Complete**: When resources are deleted, sets reason `CleanupComplete` and removes the finalizer from the Project to complete deletion. -1. **Finalizer Registration**: Adds finalizer to `Project` during creation -2. **Deletion Detection**: Detects when `Project` has `deletionTimestamp` set -3. **Infrastructure Cleanup**: Deletes corresponding `ProjectControlPlane` in - infrastructure cluster -4. **Finalizer Removal**: Removes finalizer from `Project` to allow deletion +During this process, the controller accurately updates status conditions so clients and users can track deletion progress. ### Status Conditions @@ -247,12 +251,19 @@ The controller implements proper cleanup using Kubernetes finalizers: - `True`: Project and infrastructure are ready - `False`: Project is provisioning or has issues - `Unknown`: Initial state or waiting for infrastructure +- **ResourceCleanup**: Indicates resource cleanup progress during project deletion + - `True`, reason: `CleanupStarted` — Resource cleanup (deletion) has started, and the controller is actively issuing delete commands for project resources. + - `True`, reason: `CleanupAwaitingCompletion` — Delete commands have been issued and the controller is waiting for all referenced resources to be removed. + - `False`, reason: `CleanupComplete` — All project resources have been deleted; project deletion may now proceed. #### Condition Reasons - `Ready`: Project is fully operational - `Provisioning`: Project is being created/updated - `ProjectNameConflict`: Name already exists +- `CleanupStarted`: Project resource deletion has started, delete commands issued +- `CleanupAwaitingCompletion`: Waiting for resources to be removed after delete +- `CleanupComplete`: All resources removed, deletion can complete - Infrastructure-specific reasons propagated from `ProjectControlPlane` ### Cross-Cluster Watching @@ -312,3 +323,4 @@ The controller exposes standard controller-runtime metrics: Structured logging is used throughout the controller for reconciliation events, status updates, and error conditions. + \ No newline at end of file