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 1 commit
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: 49 additions & 52 deletions docs/drafts/developer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,22 @@

## 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.

> [!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).

### 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.

### Installation

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
### Running on the cluster -- the targets `make run` combines
1. Install Instances of Custom Resources:

```sh
Expand Down Expand Up @@ -69,20 +63,11 @@ 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
## Iterative Development

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.
If you are making code changes and want to iterate on them quickly, there are specific targets for this purpose.

### Modifying the API definitions
If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
Expand All @@ -93,9 +78,9 @@ 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 +90,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 +108,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 their own Tiltfiles, 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 @@ -173,23 +154,39 @@ v0.33.1, built 2023-06-28

Typically, you'll want to press the space bar to have it open the UI in your web browser.

Shortly after starting, Tilt processes the `Tiltfile`, resulting in:
---

## Special Setup for MacOS

Some additional setup is necessary on Macintosh computers 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
```

- 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
---

### Making code changes
## How it works
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).

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

---

## Contributing

Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
Loading