Skip to content

development-environment.md

Latest commit

 

History

History
234 lines (175 loc) · 9.27 KB

development-environment.md

File metadata and controls

234 lines (175 loc) · 9.27 KB

DocumentDB Kubernetes Operator – Development Environment

This guide walks you through two supported workflows for contributing to the DocumentDB Kubernetes Operator:

  1. VS Code devcontainer (recommended) – consistent, pre-baked toolchain that mirrors CI and includes Docker-in-Docker, kind, kubectl/helm, Azure CLI, mongosh, golangci-lint, and other utilities.
  2. Native host setup – install the required toolchain directly on your Linux, macOS, or WSL2 environment.

Whichever path you choose, the repository Makefile and helper scripts provide a consistent developer experience. Start by cloning or forking the repository as usual, then proceed with the sections below.

# From a shell on your workstation
git clone https://github.com/documentdb/documentdb-kubernetes-operator.git
cd documentdb-kubernetes-operator

1. Developing with the VS Code devcontainer

Prerequisites

Launching the container

  1. Open the repository folder in VS Code.

  2. Follow the prompt “Reopen in Container”, or run the “Dev Containers: Reopen in Container” command from the command palette.

  3. VS Code builds the container defined in .devcontainer/devcontainer.json using the mcr.microsoft.com/devcontainers/go:2-1.25-bookworm base image. The build installs the following features:

    • Docker-in-Docker runtime for building and running images
    • kind + kubectl/helm/kubectx/kubens/stern for Kubernetes workflows
    • Azure CLI and kubelogin for interacting with AKS and Fleet
    • golangci-lint for static analysis

  4. After the container starts, the postCreateCommand configures helpful shell aliases (for example, k → kubectl, with tab completion) and downloads Go module dependencies.

Daily workflow inside the devcontainer

All commands run inside the container root (/workspaces/documentdb-kubernetes-operator). Common tasks:

Task Command
List available targets make help
Regenerate CRDs and deepcopy code make manifests generate
Lint and test make lint && make test
Build the operator binary make build
Build & push local Docker images (operator + sidecar) DEPLOY=true ./scripts/development/deploy.sh --build-only
Spin up a kind cluster, push images, deploy operator & sample DEPLOY=true DEPLOY_CLUSTER=true ./scripts/development/deploy.sh
View operator logs stern documentdb-operator -n documentdb-operator

Tip: The devcontainer uses Debian bookworm as its base image. Kind falls back to iptables mode for kube-proxy, which is sufficient for local development.

Useful scripts

2. Developing on your local machine (Linux, macOS, WSL2)

If you prefer not to use containers, install the same toolchain locally. The commands below assume a Unix-like shell (bash/zsh). Windows users should follow the Linux instructions inside WSL2.

Required tools

Component Minimum version Notes
Go 1.25.0 Matches go.mod. Install via package manager or go.dev
Docker Engine 24.x Needed for image builds and kind
kind 0.31+ kind.sigs.k8s.io
kubectl 1.30+ Align with the Kubernetes version you test against
Helm 3.15+ Required by deployment scripts
golangci-lint 1.55+ curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b /usr/local/bin
jq, make, git, tar, gzip, sed, awk latest Usually part of the OS base image
Optional: Azure CLI, kubelogin, mongosh latest Needed for Azure Fleet testing and DocumentDB samples

Linux (Debian/Ubuntu example)

sudo apt-get update
sudo apt-get install -y build-essential curl git jq make tar gzip
sudo snap install go --channel=1.25/stable
curl -Lo kind https://kind.sigs.k8s.io/dl/v0.31.0/kind-linux-amd64 && chmod +x kind && sudo mv kind /usr/local/bin/
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b /usr/local/bin

macOS (Homebrew)

brew update
brew install go@1.25 docker kind kubectl helm jq make coreutils findutils
brew install golangci-lint

If you use Docker Desktop, enable the Kubernetes networking settings recommended by the kind quick-start guide. On macOS, disable AirPlay (port 5000) if you run local registries on that port.

Optional tools

  • Azure CLI + kubelogin (brew install azure-cli kubelogin or apt-get install azure-cli)
  • mongosh for interacting with the sample DocumentDB cluster (brew install mongosh or apt-get install mongodb-mongosh)
  • stern for multi-pod log streaming (brew install stern)

Validating your setup

# Confirm Go toolchain
make help

# Run lint and unit tests
make lint
make test

# Spin up or refresh the kind environment (includes local registry)
DEPLOY=true DEPLOY_CLUSTER=true ./scripts/development/deploy.sh

# When finished
./scripts/development/kind_with_registry.sh delete

The deploy.sh script builds operator and sidecar images tagged with the current Git SHA (configurable via TAG). It then pushes them into the local registry (localhost:5001 by default), primes the kind cluster, and deploys the operator through Helm.

3. Repository layout & common workflows

Directory / Script Purpose
cmd/ Operator entry point (main.go)
internal/ Controller logic, utilities, replication code
api/ CRD types and generated DeepCopy files
documentdb-helm-chart/ Helm chart for operator deployment
scripts/development/ Local dev tooling (kind setup, deployment helpers)
scripts/operator/ Helm install/uninstall automation
scripts/deployment-examples/ Sample manifests (including mongosh client)

Make targets you’ll use often

  • make manifests generate – update CRDs and DeepCopy sources after editing API types
  • make fmt – gofmt all Go sources
  • make lint / make lint-fix – run golangci-lint (and autofix where possible)
  • make test – execute unit tests via controller-runtime envtest
  • make build – compile the manager binary (bin/manager)
  • make docker-build – build operator container image (controller)
  • make docker-buildx – multi-architecture build (requires Docker Buildx)
  • make build-installer – produce install.yaml bundle used for alternative installs

Cleaning up

  • make clean – remove compiled binaries
  • ./scripts/development/kind_with_registry.sh delete – delete the dev kind cluster and local registry container
  • docker image prune – remove dangling image layers after repeated builds

4. Testing public documentation locally

To build the documentation and run a development server for live previewing:

  1. Create a Python virtual environment:

    python3 -m venv documentdb-k8s-docs-venv

  2. Activate the virtual environment:

    source documentdb-k8s-docs-venv/bin/activate

  3. Install MkDocs:

    pip install mkdocs mkdocs-material

  4. Run the local MkDocs server for testing:

    mkdocs serve

    This starts a local server (typically at http://127.0.0.1:8000) where you can preview documentation changes in real time.

5. Contributing guidelines

Before opening a pull request, review the repository-wide CONTRIBUTING.md for the CLA process, style guidance, branching expectations, and code of conduct. Helpful reminders:

  • Always run make lint and make test locally (or inside the devcontainer) before pushing.
  • Include unit tests, e2e tests, or integration checks when modifying controller logic.
  • Keep Helm chart changes in sync with generated manifests and sample values.
  • Update documentation (including this guide) if you add new dependencies or workflows.

For questions or proposals, open an issue or start a discussion in the GitHub repository. Happy hacking!