Skip to content

Latest commit

 

History

History
269 lines (186 loc) · 8.52 KB

dev-guide.md

File metadata and controls

269 lines (186 loc) · 8.52 KB

Developer Reference

The external-dns is the work of thousands of contributors, and is maintained by a small team within kubernetes-sigs. This document covers basic needs to work with external-dns codebase. It contains instructions to build, run, and test external-dns.

Tools

Building and/or testing external-dns requires additional tooling.

First Steps

*Configure Development Environment

You must have a working Go environment, compile the build, and set up testing.

git clone https://github.com/kubernetes-sigs/external-dns.git && cd external-dns

Building & Testing

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

Build, run tests and lint the code:

make go-lint
make test
make cover-html

If added any flags, re-generate flags documentation

make generate-flags-documentation

We require all changes to be covered by acceptance tests and/or unit tests, depending on the situation. In the context of the external-dns, acceptance tests are tests of interactions with providers, such as creating, reading information about, and destroying DNS resources. In contrast, unit tests test functionality wholly within the codebase itself, such as function tests.

Continuous Integration

When submitting a pull request, you'll notice that we run several automated processes on your proposed change. Some of these processes are tests to ensure your contribution aligns with our standards. While we strive for accuracy, some users may find these tests confusing.

Execute code without building binary

The external-dns does not require make build. You could compile and run Go program with the command

go run main.go \
    --provider=aws \
    --registry=txt \
    --source=fake \
    --log-level=info

For this command to run successfully, it will require AWS credentials and access to local or remote access.

To run local cluster please refer to running local cluster

Deploying a local build

After building local images, it is often useful to deploy those images in a local cluster

We use Minikube but it could be Kind or any other solution.

Create a local cluster

For simplicity, minikube can be used to create a single node cluster.

You can set a specific Kubernetes version by setting the node's container image. See basic controls within the documentation about configuration for more details on this.

Once you have a configuration in place, create the cluster with that configuration:

minikube start \
  --profile=external-dns \
  --memory=2000 \
  --cpus=2 \
  --disk-size=5g \
  --kubernetes-version=v1.31 \
  --driver=docker

minikube profile external-dns

After the new Kubernetes cluster is ready, identify the cluster is running as the single node cluster:

❯❯ kubectl get nodes
NAME           STATUS   ROLES           AGE   VERSION
external-dns   Ready    control-plane   16s   v1.31.4

Building local images

When building local images with ko you can't specify the registry used to create the image names. It will always be ko.local.

Note: You could skip this step if you build and push image to your private registry or using an official external-dns image

❯❯ export KO_DOCKER_REPO=ko.local
❯❯ export VERSION=v1
❯❯ docker context use rancher-desktop ## (optional) this command is only required when using rancher-desktop
❯❯ ls -al /var/run/docker.sock ## (optional) validate tha docker runtime is configured correctly and symlink exist

❯❯ ko build --tags ${VERSION}
❯❯ docker images
$$ ko.local/external-dns-9036f6870f30cbdefa42a10f30bada63   local-v1

Push image to minikube

Refer to load image

❯❯ minikube image load ko.local/external-dns-9036f6870f30cbdefa42a10f30bada63:local-v1
❯❯ minikube image ls
$$ registry.k8s.io/pause:3.10
$$ ...
$$ ko.local/external-dns-9036f6870f30cbdefa42a10f30bada63:local-v1
$$ ...
❯❯ kubectl run external-dns --image=ko.local/external-dns-9036f6870f30cbdefa42a10f30bada63:local-v1 --image-pull-policy=Never

Build and push directly in minikube

Any docker command you run in this current terminal will run against the docker inside minikube cluster.

Refer to push directly

❯❯ eval $(minikube -p external-dns docker-env)
❯❯ echo $MINIKUBE_ACTIVE_DOCKERD
$$ external-dns
❯❯ export VERSION=v1
❯❯ ko build --local --tags ${VERSION}
❯❯ docker images
$$ REPOSITORY                                               TAG
$$ registry.k8s.io/kube-apiserver                           v1.31.4
$$ ....
$$ ko.local/external-dns-9036f6870f30cbdefa42a10f30bada63   minikube-v1
$$ ...
❯❯ eval $(minikube docker-env -u) ## unset minikube

Pushing to an in-cluster using Registry addon

Refer to pushing images for a full configuration

❯❯ export KO_DOCKER_REPO=$(minikube ip):5000
❯❯ export VERSION=registry-v1
❯❯ minikube addons enable registry
❯❯ ko build --tags ${VERSION}

Building image and push to a registry

Build container image and push to a specific registry

make build.push IMAGE=your-registry/external-dns

Deploy with Helm

Build local images if required, load them on a local cluster, and deploy helm charts, run:

Render chart templates locally and display the output

❯❯ helm lint --debug charts/external-dns
❯❯ helm template external-dns charts/external-dns --output-dir _scratch

Deploy manifests to a cluster with required values

❯❯ kubectl apply -f _scratch --recursive=true

Modify chart or values and validate the diff

❯❯ helm template external-dns charts/external-dns --output-dir _scratch
❯❯ kubectl diff -f _scratch/external-dns --recursive=true --show-managed-fields=false

Helm Values

This helm chart comes with a JSON schema generated from values with helm schema plugin.

  1. Install required plugin(s)
❯❯ scripts/helm-tools.sh --install
  1. Ensure that the schema is always up-to-date
❯❯ scripts/helm-tools.sh --diff
  1. When not up-to-date, update JSON schema
❯❯ scripts/helm-tools.sh --schema
  1. Runs a series of tests to verify that the chart is well-formed, linted and JSON schema is valid
❯❯ scripts/helm-tools.sh --lint
  1. Auto-generate documentation for helm charts into markdown files.
❯❯ scripts/helm-tools.sh --docs
  1. Add an entry to the chart CHANGELOG.md under ## UNRELEASED section and open pull request

Deploy with kubernetes manifests

Note; kubernetes manifest are not up to date. Consider to create an examples folder

kubectl apply -f kustomize --recursive=true --dry-run=client

Contribute to documentation

All documentation is in docs folder. If new page is added or removed, make sure mkdocs.yml is also updated.

Install required dependencies. In order to not to break system packages, we are going to use virtual environments with pipenv.

❯❯ pipenv shell
❯❯ pip install -r docs/scripts/requirements.txt
❯❯ mkdocs serve
$$ ...
$$ Serving on http://127.0.0.1:8000/