external-secrets/docs/contributing/devguide.md

## Getting Started

You must have a working [Go environment](https://golang.org/doc/install) and
then clone the repo:

```shell
git clone https://github.com/external-secrets/external-secrets.git
cd external-secrets
```

_Note: many of the `make` commands use [yq](https://github.com/mikefarah/yq), version 4.2X.X or higher._

If you want to run controller tests you also need to install kubebuilder's `envtest`.

The recommended way to do so is to install [setup-envtest](https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest)

Here is an example on how to set it up:

```
go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest

# list available versions
setup-envtest list --os $(go env GOOS) --arch $(go env GOARCH)

# To use a specific version
setup-envtest use -p path 1.20.2

#To set environment variables
source <(setup-envtest use 1.20.2 -p env --os $(go env GOOS) --arch $(go env GOARCH))

```

for more information, please see [setup-envtest docs](https://github.com/kubernetes-sigs/controller-runtime/tree/master/tools/setup-envtest)

Our helm chart is tested using `helm-unittest`. You will need it to run tests locally if you modify the helm chart. Install it with the following command:

```
$ helm plugin install https://github.com/helm-unittest/helm-unittest
```

## Building & Testing

The project uses the `make` build system. It'll run code generators, tests and
static code analysis.

Building the operator binary and docker image:

```shell
make build
make docker.build IMG=external-secrets:latest
```

Run tests and lint the code: *(golangci-lint@1.49.0 is needed.)*
```shell
make test
make lint # OR
docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:v1.49.0 golangci-lint run
```

Build the documentation:
```shell
make docs
```

## Installing

To install the External Secret Operator into a Kubernetes Cluster run:

```shell
helm repo add external-secrets https://charts.external-secrets.io
helm repo update
helm install external-secrets external-secrets/external-secrets
```

You can alternatively run the controller on your host system for development purposes:


```shell
make crds.install
make run
```

To remove the CRDs run:

```shell
make crds.uninstall
```

If you need to test some other k8s integrations and need the operator to be deployed to the actual cluster while developing, you can use the following workflow:

```shell
# Start a local K8S cluster with KinD
kind create cluster --name external-secrets

export TAG=$(make docker.tag)
export IMAGE=$(make docker.imagename)

# Build docker image
make docker.build

# Load docker image into local kind cluster
kind load docker-image $IMAGE:$TAG -n external-secrets

# (Optional) Pull the image from GitHub Repo to copy into kind
#docker pull ghcr.io/external-secrets/external-secrets:v0.8.2
#kind load docker-image ghcr.io/external-secrets/external-secrets:v0.8.2 -n external-secrets

# Update helm charts and install to KinD cluster
make helm.generate
helm upgrade --install external-secrets ./deploy/charts/external-secrets/ \
--set image.repository=$IMAGE --set image.tag=$TAG \
--set webhook.image.repository=$IMAGE --set webhook.image.tag=$TAG \
--set certController.image.repository=$IMAGE --set certController.image.tag=$TAG


# Command to delete the cluster when done
# kind delete cluster -n external-secrets
```

!!! note "Contributing Flow"
    The HOW TO guide for contributing is at the [Contributing Process](process.md) page.


## Documentation

We use [mkdocs material](https://squidfunk.github.io/mkdocs-material/) and [mike](https://github.com/jimporter/mike) to generate this
documentation. See `/docs` for the source code and `/hack/api-docs` for the build process.

When writing documentation it is advised to run the mkdocs server with livereload:

```shell
make docs.serve
```

Run the following command to run a complete build. The rendered assets are available under `/site`.

```shell
make docs
make docs.serve
```

Open `http://localhost:8000` in your browser.

Since mike uses a branch to create/update documentation, any docs operation will create a diff on your local `gh-pages` branch.

When finished writing/reviewing the docs, clean up your local docs branch changes with `git branch -D gh-pages`