Skip to content

docs: for pull #553, fixed 2 outdated doc(s) #556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joggrbot wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: for pull #553, fixed 2 outdated doc(s) #556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 29 additions & 6 deletions docs/api/resourcemanager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -876,7 +876,6 @@ with respect to the current state of the instance.<br/>




Project is the Schema for the projects API.

<table>
Expand Down Expand Up @@ -1009,9 +1008,9 @@ ProjectStatus defines the observed state of Project.
<td>[]object</td>
<td>
Represents the observations of a project's current state.
Known condition types are: "Ready"<br/>
<br/>
<i>Default</i>: [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for control plane to reconcile reason:Unknown status:Unknown type:Ready]]<br/>
Known condition types are: "Ready" and "ResourceCleanup".
<br/>
<i>Default</i>: [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for control plane to reconcile reason:Unknown status:Unknown type:Ready]]<br/>
</td>
<td>false</td>
</tr></tbody>
Expand All @@ -1025,6 +1024,29 @@ Known condition types are: "Ready"<br/>

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
```

<table>
<thead>
<tr>
Expand All @@ -1039,7 +1061,7 @@ Condition contains details for one aspect of the current state of this API Resou
<td>string</td>
<td>
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.<br/>
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.<br/>
<br/>
<i>Format</i>: date-time<br/>
</td>
Expand Down Expand Up @@ -1093,3 +1115,4 @@ with respect to the current state of the instance.<br/>
<td>false</td>
</tr></tbody>
</table>

50 changes: 31 additions & 19 deletions docs/architecture/controllers/project-controller/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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.