From bac6a715b5c2f362aa32ee366ff4b38b5301424c Mon Sep 17 00:00:00 2001 From: David Grove Date: Sat, 24 Feb 2024 16:17:09 -0500 Subject: [PATCH] expand description section of readme; document release process --- README.md | 45 +++++++++++++++++++++++++++++++++--- docs/distribution.md | 24 ------------------- docs/release_instructions.md | 20 ++++++++++++++++ 3 files changed, 62 insertions(+), 27 deletions(-) delete mode 100644 docs/distribution.md create mode 100644 docs/release_instructions.md diff --git a/README.md b/README.md index 2af4933..68aaffe 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,51 @@ [![Continuous Integration](https://github.com/project-codeflare/appwrapper/actions/workflows/CI.yaml/badge.svg)](https://github.com/project-codeflare/appwrapper/actions/workflows/CI.yaml) An AppWrapper is a collection of Kubernetes resources than can be jointly queued -and dispatched using [Kueue](https://kueue.sigs.k8s.io). +and admitted using [Kueue](https://kueue.sigs.k8s.io). ## Description -// TODO(user): An in-depth paragraph about your project and overview of use -The lifecycle of an AppWrapper instance is depicted in a [state transition diagram](docs/state-diagram.md). +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. + +#### Admission Controller + +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 also entitled to create the contained resources +and to validate AppWrapper-specific invariants. + +See [appwrapper_webhook.go](./internal/controller/appwrapper_webhook.go) +for the implementation. + +#### Workload Controller + +An instantiation of Kueue’s GenericReconciller along with an +implementation of Kueue’s GenericJob interface for the AppWrapper +CRD. As is standard practice in Kueue, this controller will watch +AppWrapper instances and their owned Workload instances to reconcile +the two. This controller will make it possible for Kueue to suspend, +resume, and constrain the placement of the AppWrapper. It will report +the status of the AppWrapper to Kueue. + +See [workload_controller.go](./internal/controller/workload_controller.go) +for the implementation. + +#### Framework Controller + +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. + +This [state transition diagram](docs/state-diagram.md) depicts the +lifecycle of an AppWrapper; the implementation is found in +[appwrapper_controller.go](./internal/controller/appwrapper_controller.go). ## Getting Started diff --git a/docs/distribution.md b/docs/distribution.md deleted file mode 100644 index 0a7e4b6..0000000 --- a/docs/distribution.md +++ /dev/null @@ -1,24 +0,0 @@ -## Project Distribution - -***TODO: This is kubebuilder-generated boilerplate. Adapt to our usage patterns.*** - -Following are the steps to build the installer and distribute this project to users. - -1. Build the installer for the image built and published in the registry: - -```sh -make build-installer IMG=/appwrapper:tag -``` - -NOTE: The makefile target mentioned above generates an 'install.yaml' -file in the dist directory. This file contains all the resources built -with Kustomize, which are necessary to install this project without -its dependencies. - -2. Using the installer - -Users can just run kubectl apply -f to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//appwrapper//dist/install.yaml -``` diff --git a/docs/release_instructions.md b/docs/release_instructions.md new file mode 100644 index 0000000..00d2681 --- /dev/null +++ b/docs/release_instructions.md @@ -0,0 +1,20 @@ +## Release Instructions + +The entire AppWrapper release process is automated via GitHub actions. + +To make a release, simply create a new release tag (vX.Y.Z) and push the +tag to the main branch. This will trigger the `release` workflow which +will: + + build, tag, and push images to [quay.io/ibm/appwrapper](https://quay.io/repository/ibm/appwrapper) + + generate the install.yaml for the release + + create a [GitHub release](https://github.com/project-codeflare/appwrapper/releases) that contains the install.yaml + + +## Installing from a Release + +If you have a Kubernetes cluster with Kueue installed, you can install +a release of the AppWrapper CRD and operator simply by doing: +```sh +kubectl apply --server-side -f https://github.com/project-codeflare/appwrapper/releases/download/RELEASE_VERSION/install.yaml +``` +Replace `RELEASE_VERSION` in the above URL with an actual version, for example `v0.3.2`.