diff --git a/docs/drafts/developer.md b/docs/drafts/developer.md index dbaf3999b..4ce60ac2c 100644 --- a/docs/drafts/developer.md +++ b/docs/drafts/developer.md @@ -1,10 +1,24 @@ + ## Getting Started -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. + +The following `make run` starts a [KIND](https://sigs.k8s.io/kind) cluster for you to get a local cluster for testing, see the manual install steps below for how to run against a remote cluster. > [!NOTE] > Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). +> +> If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos). + +### Quickstart Installation + +First, you need to install the CRDs and the operator-controller into a new [KIND cluster](https://kind.sigs.k8s.io/). You can do this by running: + +```sh +make run +``` + +This will build a local container image of the operator-controller, create a new KIND cluster and then deploy onto that cluster. This will also deploy the catalogd and cert-manager dependencies. -### Installation +### To Install Any Given Release > [!CAUTION] > Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command @@ -16,27 +30,7 @@ The latest version of Operator Controller can be installed with the following co curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s ``` -### Additional setup on Macintosh computers -On Macintosh computers some additional setup is necessary to install and configure compatible tooling. - -#### Install Homebrew and tools -Follow the instructions to [installing Homebrew](https://docs.brew.sh/Installation) and then execute the following to install tools: - -```sh -brew install bash gnu-tar gsed -``` - -#### Configure your shell -Modify your login shell's `PATH` to prefer the new tools over those in the existing environment. This example should work either with `zsh` (in $HOME/.zshrc) or `bash` (in $HOME/.bashrc): - -```sh -for bindir in `find $(brew --prefix)/opt -type d -follow -name gnubin -print` -do - export PATH=$bindir:$PATH -done -``` - -### Running on the cluster +### Manual Step-by-Step Installation 1. Install Instances of Custom Resources: ```sh @@ -69,21 +63,6 @@ To undeploy the controller from the cluster: make undeploy ``` -### How it works -This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). - -It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) -which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster. - -### Test It Out - -Install the CRDs and the operator-controller into a new [KIND cluster](https://kind.sigs.k8s.io/): -```sh -make run -``` -This will build a local container image of the operator-controller, create a new KIND cluster and then deploy onto that cluster. -This will also deploy the catalogd and cert-manager dependencies. - ### Modifying the API definitions If you are editing the API definitions, generate the manifests such as CRs or CRDs using: @@ -91,11 +70,13 @@ If you are editing the API definitions, generate the manifests such as CRs or CR make manifests ``` +--- + **NOTE:** Run `make help` for more information on all potential `make` targets. -### Rapid iterative development with Tilt +### Rapid Iterative Development with Tilt -If you are developing against the combined ecosystem of catalogd + operator-controller you will want to take advantage of `tilt`: +If you are developing against the combined ecosystem of catalogd + operator-controller, you will want to take advantage of `tilt`: [Tilt](https://tilt.dev) is a tool that enables rapid iterative development of containerized workloads. @@ -105,8 +86,6 @@ Here is an example workflow without Tilt for modifying some source code and test 2. Build the container image. 3. Either push the image to a registry or load it into your kind cluster. 4. Deploy all the appropriate Kubernetes manifests for your application. - 1. Or, if this is an update, you'd instead scale the Deployment to 0 replicas, scale back to 1, and wait for the - new pod to be running. This process can take minutes, depending on how long each step takes. @@ -125,9 +104,7 @@ Follow Tilt's [instructions](https://docs.tilt.dev/install.html) for installatio ### Installing catalogd operator-controller requires -[catalogd](https://github.com/operator-framework/catalogd). Please make sure it's installed, either normally or via -their own Tiltfiles, before proceeding. If you want to use Tilt, make sure you specify a unique `--port` flag to each -`tilt up` invocation. +[catalogd](https://github.com/operator-framework/catalogd). Please make sure it's installed, either normally or via its own Tiltfile., before proceeding. If you want to use Tilt, make sure you specify a unique `--port` flag to each `tilt up` invocation. ### Install tilt-support Repo @@ -171,25 +148,33 @@ v0.33.1, built 2023-06-28 (ctrl-c) to exit ``` -Typically, you'll want to press the space bar to have it open the UI in your web browser. +At the end of the installation process, the command output will prompt you to press the space bar to open the web UI, which provides a useful overview of all the installed components. + +--- + +## Special Setup for MacOS + +Some additional setup is necessary on Macintosh computers to install and configure compatible tooling. -Shortly after starting, Tilt processes the `Tiltfile`, resulting in: +### Install Homebrew and tools +Follow the instructions to [install Homebrew](https://docs.brew.sh/Installation), and then execute the following command to install the required tools: -- Building the go binaries -- Building the images -- Loading the images into kind -- Running kustomize and applying everything except the Deployments that reference the images above -- Modifying the Deployments to use the just-built images -- Creating the Deployments +```sh +brew install bash gnu-tar gsed +``` -### Making code changes +### Configure your shell +To configure your shell, either add this to your bash or zsh profile (e.g., in $HOME/.bashrc or $HOME/.zshrc), or run the following command in the terminal: -Any time you change any of the files listed in the `deps` section in the `_binary` `local_resource`, -Tilt automatically rebuilds the go binary. As soon as the binary is rebuilt, Tilt pushes it (and only it) into the -appropriate running container, and then restarts the process. +```sh +for bindir in `find $(brew --prefix)/opt -type d -follow -name gnubin -print` +do + export PATH=$bindir:$PATH +done +``` --- ## Contributing -Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information. \ No newline at end of file +Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.