first editing pass on README (#5)

README.md

@@ -1,5 +1,8 @@
 # AppWrapper
 
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
+[![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).
 
@@ -9,94 +12,131 @@ and dispatched using [Kueue](https://kueue.sigs.k8s.io).
 ## Getting Started
 
 ### Prerequisites
-- go version v1.21.0+
-- docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
 
-### To Deploy on the cluster
-**Build and push your image to the location specified by `IMG`:**
+You'll need `go` v1.21.0+ installed on your development machine.
 
-```sh
-make docker-build docker-push IMG=<some-registry>/appwrapper:tag
-```
+You'll need a container runtime and cli (eg `docker` or `rancher-desktop`).
 
-**NOTE:** This image ought to be published in the personal registry you specified.
-And it is required to have access to pull the image from the working environment.
-Make sure you have the proper permission to the registry if the above commands don’t work.
+You’ll need a Kubernetes cluster to run against.
 
-**Install the CRDs into the cluster:**
+You can use [kind](https://sigs.k8s.io/kind) to get a local cluster
+for testing, or run against a remote cluster. All commands shown in
+this readme will automatically use the current context in your
+kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
 
-```sh
-make install
-```
+For the purposes of simplifying the getting started documentation, we
+proceed assuming you will create a local `kind` cluster.
 
-**Deploy the Manager to the cluster with the image specified by `IMG`:**
+### Create your cluster and deploy Kueue
 
+Create the cluster with:
 ```sh
-make deploy IMG=<some-registry>/appwrapper:tag
+./hack/create-test-cluster.sh
 ```
 
-> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
-privileges or be logged in as admin.
+Deploy Kueue on the cluster with:
+```sh
+./hack/deploy-kueue.sh
+```
 
-**Create instances of your solution**
-You can apply the samples (examples) from the config/sample:
+### Deploy on the cluster
 
+Build your image and push it to the cluster with:
 ```sh
-kubectl apply -k config/samples/
+make docker-build kind-push
 ```
 
->**NOTE**: Ensure that the samples has default values to test it out.
-
-### To Uninstall
-**Delete the instances (CRs) from the cluster:**
+Deploy the CRDs and controller to the cluster:
+```sh
+make deploy
+```
 
+Within a few seconds, the controller pod in the `appwrapper-system`
+namespace should be Ready.  Verify this with:
 ```sh
-kubectl delete -k config/samples/
+kubectl get pods -n appwrapper-system
 ```
 
-**Delete the APIs(CRDs) from the cluster:**
+You can now try deploying a sample `AppWrapper`:
+```sh
+kubectl apply -f samples/appwrapper.yaml
+```
 
+You should shortly see a Pod called `sample` running.
+After running for 5 seconds, the Pod will complete and the
+AppWrapper's status will be Completed.
 ```sh
-make uninstall
+% kubectl get appwrappers
+NAME     STATUS
+sample   Running
+% kubectl get pods
+NAME     READY   STATUS    RESTARTS   AGE
+sample   1/1     Running   0          2s
+% kubectl get pods
+NAME     READY   STATUS      RESTARTS   AGE
+sample   0/1     Completed   0          9s
+% kubectl get appwrappers
+NAME     STATUS
+sample   Completed
 ```
 
-**UnDeploy the controller from the cluster:**
+You can now delete the sample AppWrapper.
+```sh
+kubectl delete -f samples/appwrapper.yaml
+```
 
+To undeploy the CRDs and controller from the cluster:
 ```sh
 make undeploy
 ```
 
-## Project Distribution
+### Run the controller as a local process against the cluster
 
-Following are the steps to build the installer and distribute this project to users.
+For faster development and debugging, you can run the controller
+directly on your development machine as local process that will
+automatically be connected to the cluster.  Note that in this
+configuration, the webhooks that implement the Admission Controllers
+are not operational.  Therefore your CRDs will not be validated and
+you must explictly set the `suspended` field to `true` in your
+AppWrapper YAML files.
 
-1. Build the installer for the image built and published in the registry:
+Install the CRDs into the cluster:
 
 ```sh
-make build-installer IMG=<some-registry>/appwrapper:tag
+make install
 ```
 
-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.
+Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
+```sh
+make run
+```
 
-2. Using the installer
+**NOTE:** You can also run this in one step by running: `make install run`
 
-Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
+You can now deploy a sample with `kubectl apply -f
+samples/appwrapper.yaml` and observe its execution as described
+above.
 
+After deleting all AppWrapper CR instances, you can uninstall the CRDs
+with:
 ```sh
-kubectl apply -f https://raw.githubusercontent.com/<org>/appwrapper/<tag or branch>/dist/install.yaml
+make uninstall
 ```
 
 ## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
 
-**NOTE:** Run `make help` for more information on all potential `make` targets
+### Pre-commit hooks
+
+This repository includes pre-configured pre-commit hooks. Make sure to install
+the hooks immediately after cloning the repository:
+```sh
+pre-commit install
+```
+See [https://pre-commit.com](https://pre-commit.com) for prerequisites.
+
+### Running tests locally
 
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
+TODO: Document this once we finish porting the scripts from MCADv2.
 
 ## License
 

docs/distribution.md

@@ -0,0 +1,24 @@
+## 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=<some-registry>/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 <URL for YAML BUNDLE> to install the project, i.e.:
+
+```sh
+kubectl apply -f https://raw.githubusercontent.com/<org>/appwrapper/<tag or branch>/dist/install.yaml
+```