Skip to content

📖 [Docs] Reorganize developer documentation #1279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 19, 2024
Merged

📖 [Docs] Reorganize developer documentation #1279

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d02ed3c
Reorganize developer documentation
bentito Sep 18, 2024
e379eca
Incorporate trgeiger comments
bentito Sep 18, 2024
7f54af6
Remove How-to; clarify Kind use; grammar
bentito Sep 19, 2024
2aa40b4
Fix missing backticks
bentito Sep 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 43 additions & 58 deletions docs/drafts/developer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -69,33 +63,20 @@ 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:

```sh
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.

Expand All @@ -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.

Expand All @@ -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

Expand Down Expand Up @@ -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 name>_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.
Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.