Update AppWrapper architecture for Kueue 0.11

Author: dgrove-oss

site/_pages/arch-controller.md

@@ -4,55 +4,24 @@ title: "AppWrapper Controllers"
 classes: wide
 ---
 
-Kueue has a well-developed pattern for Kueue-enabling a Custom
-Resource Definition and its associated operator. Following this pattern
-allows the resulting operator to smoothly run alongside the core Kueue
-operator. The pattern consists of three main elements: an Admission
-Controller, a Workload Controller, and a Framework Controller.
+Kueue has a [well-developed pattern](https://kueue.sigs.k8s.io/docs/tasks/dev/integrate_a_custom_job/)
+for Kueue-enabling a Custom Resource Definition and its associated operator.
 
-#### Admission Controller
+AppWrapper version 1.0.6 and earlier was an *external Kueue integration*
+and therefore versions of the AppWrapper controller were closely tied to a matching
+Kueue version (Kueue 0.7 through Kueue 0.10).
 
-Kueue requires the definition of an Admission Controller that ensures
-that the `.spec.suspend` field of newly created AppWrapper instances is
-set to true. We also leverage the Admission Controller to ensure that
-the user creating the AppWrapper is entitled to create all wrapped resources
-and to validate AppWrapper-specific invariants.
+Starting with Kueue 0.11 and AppWrapper version 1.1, AppWrapper becamse a first class
+*built-in Kueue integration*.  This allows a looser coupling between the
+two controllers and a significant simplification in their joint deployment and configuration.
 
-See [appwrapper_webhook.go]({{ site.gh_main_url }}/internal/webhook/appwrapper_webhook.go)
-for the implementation.
-
-#### Workload Controller
-
-The Workload Controller is an instantiation of Kueue’s JobReconciller
-along with an implementation of Kueue’s GenericJob interface for
-AppWrappers.  As is standard practice in Kueue, this controller will
-watch AppWrapper instances and their owned Workload instances to
-reconcile the two. This controller makes it possible for Kueue to
-suspend and resume the AppWrapper and constrain the placement of pods
-created by the wrapped resources of the AppWrapper. It also translates
-the status of the AppWrapper to the format expected by Kueue.
-
-See [workload_controller.go]({{ site.gh_main_url }}/internal/controller/workload/workload_controller.go)
-for the implementation.
-
-To ensure smooth interoperation with all possible configurations of Kueue,
-it is recommended to register AppWrappers as an
-[externalFramework](https://kueue.sigs.k8s.io/docs/tasks/dev/integrate_a_custom_job/#building-an-external-integration)
-with Kueue. Our script [deploy-kueue.sh]({{ site.gh_main_url }}/hack/deploy-kueue.sh) automates
-this. The script accomplishes the following tasks:
-
-1. Adds the ability to get, list, and watch AppWrappers to the RBACs for Kueue's manager role.
-2. Adds `"AppWrapper.v1beta2.workload.codeflare.dev"` to the list of `externalFrameworks` in
-   Kueue's manager configuration.
-
-
-#### Framework Controller
+#### AppWrapper Controller
 
-The Framework Controller is a standard reconciliation loop that watches AppWrapper instances and
+The AppWrapper Controller is a standard reconciliation loop that watches AppWrapper instances and
 is responsible for all AppWrapper-specific operations including
 creating, monitoring, and deleting the wrapped resources in response
 to the modifications of the AppWrapper instance’s specification and
-status made by the Workload Controller described above.
+status.
 
 ```mermaid!
 ---
@@ -103,7 +72,7 @@ stateDiagram-v2
 The state diagram above depicts the transitions between the Phases of
 an AppWrapper.  A label on an edge indicates the state change that will
 trigger that transition.  For example, if an AppWrapper is in the
-Suspended Phase and `spec.suspend` becomes False then the Framework Controller
+Suspended Phase and Kueue sets `spec.suspend` to `false` then the AppWrapper Controller
 will transition the AppWrapper to the Resuming Phase.
 
 These states are augmented by two orthogonal Conditions:
@@ -113,16 +82,16 @@ These states are augmented by two orthogonal Conditions:
 QuotaReserved and ResourcesDeployed are both true in states colored blue below.
 
 QuotaReserved and ResourcesDeployed will initially be true in the Failed state (pink),
-but will become false when the Framework Controller succeeds at deleting all resources created
+but will become false when the AppWrapper Controller succeeds at deleting all resources created
 in the Resuming phase.
 
 ResourcesDeployed will be true in the Succeeded state (green), but QuotaReserved will be false.
-After a configurable delay, the Framework controller will eventually delete the resources of
+After a configurable delay, the AppWrapper controller will eventually delete the resources of
 Succeeded AppWrappers and ResourcesDeployed will become false.
 
 Any phase may transition to the Terminating phase (not shown) when the AppWrapper is deleted.
 During the Terminating phase, QuotaReserved and ResourcesDeployed may initially be true
-but will become false once the Framework Controller succeeds at deleting all associated resources.
+but will become false once the AppWrapper Controller succeeds at deleting all associated resources.
 
 See [appwrapper_controller.go]({{ site.gh_main_url }}/internal/controller/appwrapper/appwrapper_controller.go)
 for the implementation.