Skip to content

Developer guide

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.

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 IMAGE_NAME=external-secrets IMAGE_TAG=latest

Run tests and lint the code: 

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 --name 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
# export TAG=v0.8.2

# 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

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