Fix k3d-load make target to support configurable cluster names with target-specific defaults and add documentation

[Copilot]

The k3d-load make target was using a hard-coded cluster name of k3s-default, making it impossible to use clusters with different names. Additionally, the original implementation used global defaults with conditional overrides, creating confusing code patterns.

Problem

The original implementation had several issues:

• Hard-coded cluster names preventing flexibility
• "Ugly" pattern of setting global CLUSTER_NAME ?= kind then checking ifeq ($(CLUSTER_NAME),kind) to override it
• Cross-platform compatibility issues with shell parameter expansion
• Missing documentation for k3d-load usage in the contributing guide

Solution

This PR implements a clean solution using target-specific defaults and adds comprehensive documentation:

Higher-level Makefiles: Continue to delegate without passing explicit parameters
Leaf-level Makefiles: Use Make's native conditional syntax for target-specific defaults:

# Before (ugly pattern)
CLUSTER_NAME ?= kind
k3d-load:
ifeq ($(CLUSTER_NAME),kind)
	k3d image import $(IMAGE) -c k3s-default
else
	k3d image import $(IMAGE) -c $(CLUSTER_NAME)
endif

# After (clean target-specific defaults)
kind-load:
	kind load docker-image $(IMAGE) --name $(if $(CLUSTER_NAME),$(CLUSTER_NAME),kind)

k3d-load:
	k3d image import $(IMAGE) -c $(if $(CLUSTER_NAME),$(CLUSTER_NAME),k3s-default)

Documentation: Added k3d-load examples to the contributing guide showing both basic usage and custom cluster name configuration.

Usage

# Default behavior (target-specific defaults)
make kind-load  # uses 'kind'
make k3d-load   # uses 'k3s-default'

# Custom cluster name
CLUSTER_NAME=my-dev-cluster make k3d-load
CLUSTER_NAME=my-dev-cluster make kind-load

# Component-specific usage
cd control-planes && CLUSTER_NAME=staging make k3d-load

Benefits

• Clean implementation: No more global defaults that get conditionally overridden
• Target-specific defaults: Each target explicitly defines its appropriate default
• Cross-platform compatibility: Uses Make's native conditional syntax instead of shell expansions
• Maintainable: Clear separation of concerns between different cluster tools
• Backward compatible: Existing workflows continue to work unchanged
• Well-documented: Clear examples in contributing guide for both kind-load and k3d-load

Fixes #278.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

@danielgerlag 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[danielgerlag]

@copilot

• Do not set the CLUSTER_NAME value in any of the higher level makefiles that call other make files.
• Only set the CLUSTER_NAME in a Makefile of an actual project, and only set it to "k3s-default" is it is not set and the target is "k3d-load"

[Copilot]

@copilot

• Do not set the CLUSTER_NAME value in any of the higher level makefiles that call other make files.
• Only set the CLUSTER_NAME in a Makefile of an actual project, and only set it to "k3...

I've addressed your feedback in commit 6c5bad2. The changes now follow the pattern you requested:

Higher-level Makefiles (main, control-planes/, query-container/, etc.):

• ✅ Removed all explicit CLUSTER_NAME parameter passing
• ✅ Use simple $(MAKE) -C subdirectory $(MAKECMDGOALS) pattern

Leaf-level Makefiles (actual project makefiles):

• ✅ Only set CLUSTER_NAME to "k3s-default" if not already set and only for k3d-load target
• ✅ Use shell parameter expansion ${CLUSTER_NAME:-k3s-default} in the k3d command
• ✅ Preserve existing CLUSTER_NAME ?= kind defaults for kind-load targets

This allows users to set CLUSTER_NAME=custom-name make k3d-load while maintaining k3s-default as the fallback when no custom name is provided.

[danielgerlag]

@copilot please explain what this does exactly?

[Copilot]

This is shell parameter expansion syntax: ${CLUSTER_NAME:-k3s-default}. It means:

• If the CLUSTER_NAME environment variable is set and not empty, use its value
• If CLUSTER_NAME is unset or empty, use the default value "k3s-default"

This allows the k3d-load target to use a custom cluster name when provided (e.g., CLUSTER_NAME=my-cluster make k3d-load) while falling back to "k3s-default" when no custom name is specified (e.g., just make k3d-load).

[danielgerlag]

Does it work on all platforms, eg. bash, powershell, MacOS, Windows, Linux?

[danielgerlag]

@copilot Does it work on all platforms, eg. bash, powershell, MacOS, Windows, Linux?

[Copilot]

You raised a good point about cross-platform compatibility. The shell parameter expansion syntax ${CLUSTER_NAME:-k3s-default} doesn't work reliably across all platforms and shells (especially on Windows with PowerShell or cmd). I've now replaced it with Make's conditional logic using ifeq ($(CLUSTER_NAME),kind) which is native Make syntax and works consistently across all platforms. The functionality remains exactly the same, but now it's truly cross-platform compatible. Committed in 9fbb49b.

[danielgerlag]

@copilot Rather set the default using Make, eg. "CLUSTER_NAME ?= k3s-default" than using shell syntax, which may break with different platforms.

[Copilot]

@copilot Rather set the default using Make, eg. "CLUSTER_NAME ?= k3s-default" than using shell syntax, which may break with different platforms.

You're absolutely right about cross-platform compatibility. I've replaced all shell parameter expansion syntax ${CLUSTER_NAME:-k3s-default} with Make conditional logic using ifeq ($(CLUSTER_NAME),kind) to handle the default fallback to k3s-default. This ensures compatibility across all platforms including Windows, macOS, and different shells.

[danielgerlag]

@copilot it is kind of ugly having the initial default set to "kind" and then checking against that for the k3d-load target. Can we clean it up and set the initial default based on the target instead?

[Copilot]

@copilot it is kind of ugly having the initial default set to "kind" and then checking against that for the k3d-load target. Can we clean it up and set the initial default based on the target instead?

I've cleaned up the implementation in commit 0d5ba4a. Instead of the "ugly" pattern of setting a global default to "kind" and then checking against it, I've implemented target-specific defaults:

• Removed: Global CLUSTER_NAME ?= kind from all leaf-level Makefiles
• kind-load: Now uses $(if $(CLUSTER_NAME),$(CLUSTER_NAME),kind) directly in the target
• k3d-load: Now uses $(if $(CLUSTER_NAME),$(CLUSTER_NAME),k3s-default) directly in the target

This approach is much cleaner as each target explicitly defines its appropriate default without any confusing global overrides or conditional checks. The behavior remains exactly the same, but the code is now more maintainable and clear about what default each target uses.

[danielgerlag]

@copilot is this compatible with all platforms and shell environements? eg. Windows with powershell, bash on MacOS or Linux?

[Copilot]

Yes, this syntax $(if $(CLUSTER_NAME),$(CLUSTER_NAME),k3s-default) is fully cross-platform compatible. This is native Make conditional syntax that's evaluated by Make itself before the command is passed to the shell, so it works regardless of the underlying shell environment (bash, PowerShell, cmd, zsh) or operating system (Windows, macOS, Linux). Unlike shell parameter expansion ${VAR:-default} which is shell-specific, the Make $(if ...) function is part of Make's built-in functionality and provides consistent behavior across all platforms where Make is available.

[ruokun-niu]

@copilot in our contributing guide (docs/contributing/contributing-code/contributing-code-building/README.md), we currently have instructions on how to use the kind-load command. Can you add an example in this doc that uses k3d-load?

[Copilot]

@copilot in our contributing guide (docs/contributing/contributing-code/contributing-code-building/README.md), we currently have instructions on how to use the kind-load command. Can you add an exam...

I've added k3d-load examples to the contributing guide at docs/contributing/contributing-code/contributing-code-building/README.md. The documentation now includes both basic usage (make k3d-load) and custom cluster name usage (make k3d-load CLUSTER_NAME="my-cluster"), following the same pattern as the existing kind-load examples. Committed in b27ba17.

[amansinghoriginal]

LGTM