external-secrets/docs/contributing/devguide.md

Getting Started

You must have a working Go environment and then clone the repo:

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

Note: many of the make commands use 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

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

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:

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

Run tests and lint the code: (golangci-lint@1.49.0 is needed.)

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:

make docs

Installing

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

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:

make crds.install
make run

To remove the CRDs run:

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:

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

Documentation

We use mkdocs material and 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:

make docs.serve

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

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