diff --git a/README.md b/README.md index bc750a94..8973a45e 100644 --- a/README.md +++ b/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=/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=/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=/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 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//appwrapper//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 diff --git a/docs/distribution.md b/docs/distribution.md new file mode 100644 index 00000000..0a7e4b66 --- /dev/null +++ b/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=/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 +```