Merge pull request #287 from spinkube/move-contrib-to-readme

move "running locally" into the README

README.md

@@ -1,38 +1,168 @@
 # Spin Operator
 
-The Spin Operator enables deploying Spin applications to Kubernetes. It watches [SpinApp Custom Resources](https://www.spinkube.dev/docs/glossary/#spinapp-crd) and realizes the desired state in the Kubernetes cluster. This project was built using the Kubebuilder framework and contains a Spin App CRD and controller.
+Spin Operator enables deploying Spin applications to Kubernetes. It watches [SpinApp Custom
+Resources](https://www.spinkube.dev/docs/glossary/#spinapp-crd) and realizes the desired state in
+the Kubernetes cluster.
 
-## Documentation
+This project was built using the Kubebuilder framework and contains a Spin App CRD and controller.
 
-To learn more about the Spin Operator and the SpinKube organization, please visit [the official SpinKube documentation](https://www.spinkube.dev/docs/).
+All documentation is available online at https://www.spinkube.dev/docs/. If you're just getting
+started, the [quickstart guide](https://www.spinkube.dev/docs/install/quickstart/) will guide you to
+a minimal installation that'll work while you walk through the introduction.
 
-At this point in the preview, we recommend testing Spin Operator on a local k3d cluster via `make install`. The [quickstart guide](https://www.spinkube.dev/docs/spin-operator/quickstart/) will walk you through prequisites and the installation workflow.
+To get more help:
 
-> > Spin Operator installation via Helm chart for remote clusters while in private preview is WIP and can tracked [here](https://github.com/spinkube/spin-operator/issues/54). In the meantime, please use the guidance from our quickstart guide.
+- Join the #spinkube channel on Slack at https://cncf.slack.com.
 
-## Tutorials
+To contribute to SpinKube, check out the [contributing
+guide](https://www.spinkube.dev/docs/contrib/) for information about getting involved.
 
-There are a host of tutorials in the [SpinKube documentation](https://www.spinkube.dev/docs/install/). For example:
+## Running the test suite
 
-- [Quickstart](https://www.spinkube.dev/docs/install/quickstart/)
-- [Deploying on Azure k8s service](https://www.spinkube.dev/docs/install/azure-kubernetes-service/)
-- [Scaling Spin Apps with Horizontal Pod Autoscaler (HPA)](https://www.spinkube.dev/docs/topics/autoscaling/scaling-with-hpa/)
-- [Scaling Spin Apps with Kubernetes Event Driver Autoscaler (KEDA)](https://www.spinkube.dev/docs/topics/autoscaling/scaling-with-keda/)
-- [Running spin-operator locally](https://www.spinkube.dev/docs/contrib/running-locally/)
-- [Running on a remote (non-local) K8s cluster](https://www.spinkube.dev/docs/contrib/running-on-a-cluster/)
+To run the test suite, execute the following command:
 
-## Feedback
+```shell
+make test
+```
 
-The remaining articles are under construction. You're welcome to view and open both [Spin Operator](https://github.com/spinkube/spin-operator/issues) and [documentation](https://github.com/spinkube/documentation/issues) issues and feature requests. As this work is under development, please note that current features, functionality and supporting documentation are likely to change as the projects evolve and improvements are made.
+## Building
 
-For questions or support, please visit our [Discord channel](https://discord.com/channels/926888690310053918/1200012610196738208).
+To build the Spin Operator binary, execute the following command:
 
-## Contributing (Spin Operator)
+```shell
+make
+```
 
-If you would like to contribute, please visit this [contributing](https://www.spinkube.dev/docs/contrib/) page.
+## Running a local development environment
 
-## Contributing (Documentation)
+There are two options to run spin-operator:
 
-If you would like to contribute to SpinKube and Spin Operator, please visit this [contributing](https://www.spinkube.dev/docs/contrib/) page.
+1. Run spin-operator on your computer
+1. Deploy spin-operator to a remote Kubernetes cluster
 
-The documentation is written using Hugo (as the static site generator), Docsy (as the technical documentation template) and GitHub pages (for hosting). However, during construction (prior to the website being rendered and publicly available) you are welcome to run a local copy of the documentation using the `hugo server` command. You can do so by following [these instructions](https://www.spinkube.dev/docs/contrib/#previewing-your-changes-locally).
+### Option 1: Run spin-operator on your computer
+
+k3d is a lightweight Kubernetes distribution that runs on Docker. This is the standard development
+workflow most spin-operator developers use to test their changes.
+
+Ensure that your system has all the prerequisites installed before continuing:
+
+- [Go](https://go.dev/)
+- [Docker](https://docs.docker.com/engine/install/)
+- [k3d](https://k3d.io/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+
+Create a k3d cluster:
+
+```shell
+k3d cluster create wasm-cluster \
+    --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.15.1 \
+    -p "8081:80@loadbalancer" \
+    --agents 2
+```
+
+Install the `SpinApp` and `SpinAppExecutor` Custom Resource Definitions into the cluster:
+
+```shell
+make install
+```
+
+Create a `RuntimeClass` and `SpinAppExecutor`:
+
+```shell
+kubectl apply -f config/samples/spin-runtime-class.yaml
+kubectl apply -f config/samples/spin-shim-executor.yaml
+```
+
+Run spin-operator:
+
+```shell
+make run
+```
+
+Run the sample application:
+
+```shell
+kubectl apply -f ./config/samples/simple.yaml
+```
+
+Forward a local port to the application so that it can be reached:
+
+```shell
+kubectl port-forward svc/simple-spinapp 8083:80
+```
+
+In a different terminal window, make a request to the application:
+
+```shell
+curl localhost:8083/hello
+```
+
+You should see "Hello world from Spin!".
+
+### Option 2: Deploy spin-operator to a remote Kubernetes cluster
+
+This is harder than running Spin Operator on your computer, but deploying Spin Operator into a
+remote cluster lets you test things like webhook support.
+
+Ensure that your system has all the prerequisites installed before continuing:
+
+- [Go](https://go.dev/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [Docker](https://docs.docker.com/engine/install/) (optional: for building and pushing your own
+  Docker image)
+
+Install cert-manager into your cluster for webhook support:
+
+```shell
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
+kubectl wait --for=condition=available --timeout=300s deployment/cert-manager-webhook -n cert-manager
+```
+
+Install the `SpinApp` and `SpinAppExecutor` Custom Resource Definitions into the cluster:
+
+```shell
+make install
+```
+
+Create a `RuntimeClass` and `SpinAppExecutor`:
+
+```shell
+kubectl apply -f config/samples/spin-runtime-class.yaml
+kubectl apply -f config/samples/spin-shim-executor.yaml
+```
+
+> OPTIONAL: You can build and push the Spin Operator image using `make docker-build` and
+> `make docker-push`.
+>
+>     export IMG_REPO=<some-registry>/spin-operator
+>     make docker-build docker-push
+
+Deploy Spin Operator to the cluster:
+
+```shell
+make deploy
+```
+
+Run the sample application:
+
+```shell
+kubectl apply -f ./config/samples/simple.yaml
+```
+
+Forward a local port to the application so that it can be reached:
+
+```shell
+kubectl port-forward svc/simple-spinapp 8083:80
+```
+
+In a different terminal window, make a request to the application:
+
+```shell
+curl localhost:8083/hello
+```
+
+You should see "Hello world from Spin!".
+
+> NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be
+> logged in as admin.