Getting started with Fundament development

Prerequisites

Mise: installs the pinned just, k3d, kubectl, helm, skaffold, mkcert, go and bun from mise.toml
Docker with at least 16 GiB of memory; 24 GiB recommended when you also run the plugin sandbox
certutil (NSS tools), which mkcert needs to install the local CA:

OS	Install
macOS	`brew install nss`
Debian/Ubuntu	`apt install libnss3-tools`
Fedora/RHEL	`dnf install nss-tools`
Arch	`pacman -S nss`

macOS

The default shared memory limits are too low for PostgreSQL. For embedded-postgres, create/edit /etc/sysctl.conf:

kern.sysv.shmall=65536
kern.sysv.shmmax=16777216

Windows

Use PowerShell 7 (winget install Microsoft.PowerShell); mise activate depends on a hook it does not have on Windows PowerShell 5.1, where it silently fails to populate PATH. Check your powershell version with $PSVersionTable.PSVersion. If the profile refuses to load, run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned.

Add to $PROFILE:

$env:PATH = "C:\Program Files\Git\bin;C:\Program Files\Git\usr\bin;$env:PATH"
mise activate pwsh | Out-String | Invoke-Expression

Those PATH entries supply the bash and cygpath that just recipes need; the postinstall hook just e2e::install fails until they are present, so rerun it afterwards.

Use Edge or Chrome for the console: mkcert cannot install its CA into Firefox on Windows (no NSS certutil), so calls to authn.fundament.localhost fail.

Install the tools

mise trust
mise install

Run mise install without arguments; naming a tool, as in mise install go, rewrites that tool’s pinned version in mise.toml to latest.

Run the platform

just cluster-start
just dev-hotreload

cluster-start creates the k3d-fundament cluster on first run, installs the local CA and the Envoy Gateway that serves every *.fundament.localhost host on port 8443, and switches the kubectl context to it.
dev-hotreload builds and deploys every service, then stays attached.
- Edits to existing files are synced into the running containers.
- Adding, moving or deleting a file rebuilds the image and redeploys.
Every deploy resets the databases to the test data.
Ctrl-C stops watching; the deployment keeps running.
It runs in mock mode: clusters exist only in the database. For real clusters, see Test environment.

A cluster created before the local edge moved to Envoy Gateway cannot run the chart. cluster-start detects it and stops; recreate it with just cluster-delete && just cluster-create.

To check the production images (the Dockerfiles CI builds), run just dev once and stop it with Ctrl-C: it rebuilds and redeploys on every file change.

Open the console

https://console.fundament.localhost:8443

User	Password	Organization
`alice@acme-corp.com`	`password`	`acme-corp`, with cluster `acme-cluster`
`platform-admin@fundament.io`	`password`	`system`, which owns the first-party plugins

If a host does not answer, check that the gateway is PROGRAMMED and every route is Accepted:

kubectl -n gateway get gateway,certificate
kubectl -n fundament get httproute

See console-frontend/README.md for the frontend commands.

Bruno

The collection in bruno/ calls the stack on https://…:8443. Bruno does not read the system trust store, so point it at the mkcert CA that cluster-start installed (mkcert -CAROOT prints its folder):

In the app: Preferences → General → Use custom CA certificate, select rootCA.pem and keep Keep default CA certificates on.
With the CLI: bru run --env local --cacert "$(mkcert -CAROOT)/rootCA.pem".

Edit the docs

Under just dev-hotreload, https://docs.fundament.localhost:8443 shows edits to existing pages in docs/ within seconds. Without the cluster:

just docs-dev     # dev server on http://localhost:4321
just docs-build   # production build, fails on broken links

Remove

just cluster-delete

Test environment: a real Gardener in a local VM, for e2e scenarios and real clusters
Plugins: write a plugin, run it locally
Block devices for k3d: storage plugin work