From b49cb5266ac753b885b4499527b365cceba6dce8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Jan 2026 04:39:07 +0000 Subject: [PATCH 1/2] Refactor Makefile.toml: Extract infrastructure tasks into separate files Split Makefile.toml into modular components for better organization: - Created Makefile.kind.toml for Kind cluster management tasks - Created Makefile.docker.toml for Docker image build tasks - Updated main Makefile.toml to extend the new files This reduces the main Makefile from 466 to 312 lines while maintaining all functionality. All tasks remain accessible via the same commands. --- Makefile.docker.toml | 133 +++++++++++++++++++++++++++++++++++ Makefile.kind.toml | 26 +++++++ Makefile.toml | 163 ++----------------------------------------- 3 files changed, 164 insertions(+), 158 deletions(-) create mode 100644 Makefile.docker.toml create mode 100644 Makefile.kind.toml diff --git a/Makefile.docker.toml b/Makefile.docker.toml new file mode 100644 index 0000000..b22322a --- /dev/null +++ b/Makefile.docker.toml @@ -0,0 +1,133 @@ +# Makefile.docker.toml +# Tasks for building control plane and data plane container images + +[tasks.docker-setup-buildx] +description = "Create and use a buildx builder for multi-platform builds" +category = "Docker" +script_runner = "@shell" +script = ''' +# Check if multiway-builder exists, create if not +if ! docker buildx inspect multiway-builder >/dev/null 2>&1; then + echo "Creating buildx builder: multiway-builder" + docker buildx create --name multiway-builder --use +else + echo "Using existing buildx builder: multiway-builder" + docker buildx use multiway-builder +fi +docker buildx inspect --bootstrap +''' + +[tasks.docker-build-controlplane] +description = "Build control plane image for current platform" +category = "Docker" +script_runner = "@shell" +script = ''' +docker build \ + --target controlplane \ + -t multiway-controlplane:latest \ + -f Dockerfile \ + . +''' + +[tasks.docker-build-dataplane] +description = "Build data plane image for current platform" +category = "Docker" +script_runner = "@shell" +script = ''' +docker build \ + --target dataplane \ + -t multiway-dataplane:latest \ + -f Dockerfile \ + . +''' + +[tasks.docker-build-all] +description = "Build both control plane and data plane for current platform" +category = "Docker" +dependencies = ["docker-build-controlplane", "docker-build-dataplane"] + +[tasks.docker-build-controlplane-cross] +description = "Build control plane image for both amd64 and arm64" +category = "Docker" +dependencies = ["docker-setup-buildx"] +script_runner = "@shell" +script = ''' +echo "Building control plane for multiple platforms..." +echo "Note: Multi-platform images cannot be loaded into local Docker." +echo "Use docker-build-controlplane for local development or docker-build-controlplane-push to publish." +docker buildx build \ + --target controlplane \ + --platform linux/amd64,linux/arm64 \ + -t multiway-controlplane:latest \ + -f Dockerfile \ + . +''' + +[tasks.docker-build-dataplane-cross] +description = "Build data plane image for both amd64 and arm64" +category = "Docker" +dependencies = ["docker-setup-buildx"] +script_runner = "@shell" +script = ''' +echo "Building data plane for multiple platforms..." +echo "Note: Multi-platform images cannot be loaded into local Docker." +echo "Use docker-build-dataplane for local development or docker-build-dataplane-push to publish." +docker buildx build \ + --target dataplane \ + --platform linux/amd64,linux/arm64 \ + -t multiway-dataplane:latest \ + -f Dockerfile \ + . +''' + +[tasks.docker-build-all-cross] +description = "Build both control plane and data plane for amd64 and arm64" +category = "Docker" +dependencies = ["docker-build-controlplane-cross", "docker-build-dataplane-cross"] + +[tasks.docker-build-controlplane-push] +description = "Build and push control plane image for both amd64 and arm64" +category = "Docker" +dependencies = ["docker-setup-buildx"] +script_runner = "@shell" +script = ''' +if [ -z "$DOCKER_REGISTRY" ]; then + echo "Error: DOCKER_REGISTRY environment variable not set" + echo "Example: export DOCKER_REGISTRY=ghcr.io/myorg" + exit 1 +fi + +docker buildx build \ + --target controlplane \ + --platform linux/amd64,linux/arm64 \ + -t ${DOCKER_REGISTRY}/multiway-controlplane:latest \ + -f Dockerfile \ + --push \ + . +''' + +[tasks.docker-build-dataplane-push] +description = "Build and push data plane image for both amd64 and arm64" +category = "Docker" +dependencies = ["docker-setup-buildx"] +script_runner = "@shell" +script = ''' +if [ -z "$DOCKER_REGISTRY" ]; then + echo "Error: DOCKER_REGISTRY environment variable not set" + echo "Example: export DOCKER_REGISTRY=ghcr.io/myorg" + exit 1 +fi + +docker buildx build \ + --target dataplane \ + --platform linux/amd64,linux/arm64 \ + -t ${DOCKER_REGISTRY}/multiway-dataplane:latest \ + -f Dockerfile \ + --push \ + . +''' + +[tasks.docker-build-all-push] +description = "Build and push both images for amd64 and arm64" +category = "Docker" +dependencies = ["docker-build-controlplane-push", "docker-build-dataplane-push"] diff --git a/Makefile.kind.toml b/Makefile.kind.toml new file mode 100644 index 0000000..62bf861 --- /dev/null +++ b/Makefile.kind.toml @@ -0,0 +1,26 @@ +# Makefile.kind.toml +# Tasks for managing Kind (Kubernetes in Docker) clusters + +[tasks.kind-create] +description = "Create a kind Kubernetes cluster" +category = "Kubernetes" +command = "kind" +args = ["create", "cluster", "--name", "multiway-local"] + +[tasks.kind-delete] +description = "Delete the kind Kubernetes cluster" +category = "Kubernetes" +command = "kind" +args = ["delete", "cluster", "--name", "multiway-local"] + +[tasks.kind-list] +description = "List kind clusters" +category = "Kubernetes" +command = "kind" +args = ["get", "clusters"] + +[tasks.kind-use] +description = "Set kubectl context to the multiway-local cluster" +category = "Kubernetes" +command = "kubectl" +args = ["config", "use-context", "kind-multiway-local"] diff --git a/Makefile.toml b/Makefile.toml index 7e97283..3673582 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -1,6 +1,11 @@ [config] default_to_workspace = false +extend = [ + { path = "Makefile.kind.toml" }, + { path = "Makefile.docker.toml" }, +] + [env] CARGO_MAKE_CLIPPY_ARGS = "-- --no-deps" CARGO_MAKE_COVERAGE_PROVIDER = "llvm-cov" @@ -113,30 +118,6 @@ args = [ "@@split(CARGO_MAKE_CARGO_BUILD_TEST_FLAGS, )", ] -[tasks.kind-create] -description = "Create a kind Kubernetes cluster" -category = "Kubernetes" -command = "kind" -args = ["create", "cluster", "--name", "multiway-local"] - -[tasks.kind-delete] -description = "Delete the kind Kubernetes cluster" -category = "Kubernetes" -command = "kind" -args = ["delete", "cluster", "--name", "multiway-local"] - -[tasks.kind-list] -description = "List kind clusters" -category = "Kubernetes" -command = "kind" -args = ["get", "clusters"] - -[tasks.kind-use] -description = "Set kubectl context to the multiway-local cluster" -category = "Kubernetes" -command = "kubectl" -args = ["config", "use-context", "kind-multiway-local"] - [tasks.gateway-api-refresh] description = "Download and split the Gateway API CRDs" category = "Kubernetes" @@ -329,137 +310,3 @@ kubectl logs -n gateway-conformance-infra job/gateway-api-conformance --tail=-1 description = "Build, load, and run conformance tests (full workflow)" category = "Conformance" dependencies = ["conformance-build", "conformance-load", "conformance-run"] - -# Docker Build Tasks -# These tasks build the control plane and data plane container images. - -[tasks.docker-setup-buildx] -description = "Create and use a buildx builder for multi-platform builds" -category = "Docker" -script_runner = "@shell" -script = ''' -# Check if multiway-builder exists, create if not -if ! docker buildx inspect multiway-builder >/dev/null 2>&1; then - echo "Creating buildx builder: multiway-builder" - docker buildx create --name multiway-builder --use -else - echo "Using existing buildx builder: multiway-builder" - docker buildx use multiway-builder -fi -docker buildx inspect --bootstrap -''' - -[tasks.docker-build-controlplane] -description = "Build control plane image for current platform" -category = "Docker" -script_runner = "@shell" -script = ''' -docker build \ - --target controlplane \ - -t multiway-controlplane:latest \ - -f Dockerfile \ - . -''' - -[tasks.docker-build-dataplane] -description = "Build data plane image for current platform" -category = "Docker" -script_runner = "@shell" -script = ''' -docker build \ - --target dataplane \ - -t multiway-dataplane:latest \ - -f Dockerfile \ - . -''' - -[tasks.docker-build-all] -description = "Build both control plane and data plane for current platform" -category = "Docker" -dependencies = ["docker-build-controlplane", "docker-build-dataplane"] - -[tasks.docker-build-controlplane-cross] -description = "Build control plane image for both amd64 and arm64" -category = "Docker" -dependencies = ["docker-setup-buildx"] -script_runner = "@shell" -script = ''' -echo "Building control plane for multiple platforms..." -echo "Note: Multi-platform images cannot be loaded into local Docker." -echo "Use docker-build-controlplane for local development or docker-build-controlplane-push to publish." -docker buildx build \ - --target controlplane \ - --platform linux/amd64,linux/arm64 \ - -t multiway-controlplane:latest \ - -f Dockerfile \ - . -''' - -[tasks.docker-build-dataplane-cross] -description = "Build data plane image for both amd64 and arm64" -category = "Docker" -dependencies = ["docker-setup-buildx"] -script_runner = "@shell" -script = ''' -echo "Building data plane for multiple platforms..." -echo "Note: Multi-platform images cannot be loaded into local Docker." -echo "Use docker-build-dataplane for local development or docker-build-dataplane-push to publish." -docker buildx build \ - --target dataplane \ - --platform linux/amd64,linux/arm64 \ - -t multiway-dataplane:latest \ - -f Dockerfile \ - . -''' - -[tasks.docker-build-all-cross] -description = "Build both control plane and data plane for amd64 and arm64" -category = "Docker" -dependencies = ["docker-build-controlplane-cross", "docker-build-dataplane-cross"] - -[tasks.docker-build-controlplane-push] -description = "Build and push control plane image for both amd64 and arm64" -category = "Docker" -dependencies = ["docker-setup-buildx"] -script_runner = "@shell" -script = ''' -if [ -z "$DOCKER_REGISTRY" ]; then - echo "Error: DOCKER_REGISTRY environment variable not set" - echo "Example: export DOCKER_REGISTRY=ghcr.io/myorg" - exit 1 -fi - -docker buildx build \ - --target controlplane \ - --platform linux/amd64,linux/arm64 \ - -t ${DOCKER_REGISTRY}/multiway-controlplane:latest \ - -f Dockerfile \ - --push \ - . -''' - -[tasks.docker-build-dataplane-push] -description = "Build and push data plane image for both amd64 and arm64" -category = "Docker" -dependencies = ["docker-setup-buildx"] -script_runner = "@shell" -script = ''' -if [ -z "$DOCKER_REGISTRY" ]; then - echo "Error: DOCKER_REGISTRY environment variable not set" - echo "Example: export DOCKER_REGISTRY=ghcr.io/myorg" - exit 1 -fi - -docker buildx build \ - --target dataplane \ - --platform linux/amd64,linux/arm64 \ - -t ${DOCKER_REGISTRY}/multiway-dataplane:latest \ - -f Dockerfile \ - --push \ - . -''' - -[tasks.docker-build-all-push] -description = "Build and push both images for amd64 and arm64" -category = "Docker" -dependencies = ["docker-build-controlplane-push", "docker-build-dataplane-push"] From 613e9ef7fe86fe4eb70e91bd9e44d3e4d873585e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Jan 2026 04:44:14 +0000 Subject: [PATCH 2/2] Add docker-builder Claude agent for automated Docker image builds Created a new Claude Code agent that automates Docker image building with pre-build validation: - New agent: docker-builder.md with comprehensive build workflow instructions - Agent ensures cargo check passes before building Docker images - Supports single-platform, multi-platform, and registry push operations - Added symlinks to Makefile.docker.toml and Makefile.kind.toml for reference - Created README.md documenting all available agents and usage patterns The docker-builder agent validates Rust compilation before attempting Docker builds, preventing wasted build time on code that doesn't compile. --- .claude/agents/Makefile.docker.toml | 1 + .claude/agents/Makefile.kind.toml | 1 + .claude/agents/README.md | 98 ++++++++++++++++++++++++ .claude/agents/docker-builder.md | 115 ++++++++++++++++++++++++++++ 4 files changed, 215 insertions(+) create mode 120000 .claude/agents/Makefile.docker.toml create mode 120000 .claude/agents/Makefile.kind.toml create mode 100644 .claude/agents/README.md create mode 100644 .claude/agents/docker-builder.md diff --git a/.claude/agents/Makefile.docker.toml b/.claude/agents/Makefile.docker.toml new file mode 120000 index 0000000..4b8716b --- /dev/null +++ b/.claude/agents/Makefile.docker.toml @@ -0,0 +1 @@ +../../Makefile.docker.toml \ No newline at end of file diff --git a/.claude/agents/Makefile.kind.toml b/.claude/agents/Makefile.kind.toml new file mode 120000 index 0000000..09df3c0 --- /dev/null +++ b/.claude/agents/Makefile.kind.toml @@ -0,0 +1 @@ +../../Makefile.kind.toml \ No newline at end of file diff --git a/.claude/agents/README.md b/.claude/agents/README.md new file mode 100644 index 0000000..be2f757 --- /dev/null +++ b/.claude/agents/README.md @@ -0,0 +1,98 @@ +# Claude Agents for Multiway + +This directory contains Claude Code agents that help automate common development and testing workflows for the multiway Kubernetes Gateway API implementation. + +## Available Agents + +### docker-builder + +**Purpose**: Build Docker images for the control plane and data plane components. + +**Usage**: Invoke when you need to build container images for local development or deployment. + +**Key Features**: +- Verifies Rust code compiles with `cargo check` before building Docker images +- Supports single-platform builds for local development +- Supports multi-platform builds (amd64 + arm64) for deployment +- Can push images to container registries + +**Common Commands** (executed by the agent): +- `cargo make docker-build-all` - Build both images for local platform +- `cargo make docker-build-all-cross` - Build both images for amd64 and arm64 +- `cargo make docker-build-all-push` - Build and push multi-platform images + +**Example Invocations**: +``` +"Build the Docker images" +"Rebuild the images after my code changes" +"Build and push multi-platform images to the registry" +``` + +**Reference**: See `Makefile.docker.toml` for all available Docker build tasks. + +--- + +### gateway-conformance-runner + +**Purpose**: Run the official Kubernetes Gateway API conformance test suite. + +**Usage**: Invoke when you need to verify the gateway implementation meets conformance standards. + +**Key Features**: +- Sets up Kind cluster for testing +- Builds and deploys the gateway controller +- Runs the official conformance test suite +- Retrieves and analyzes test results + +**Common Commands** (executed by the agent): +- `cargo make conformance` - Full conformance test workflow +- `cargo make conformance-build` - Build conformance test image +- `cargo make conformance-logs` - View test results + +**Example Invocations**: +``` +"Run the conformance tests" +"Check if the gateway passes conformance after my changes" +"Show me the conformance test logs" +``` + +**Reference**: See `conformance/` directory and conformance tasks in `Makefile.toml`. + +--- + +## Makefile References + +The agents directory includes symlinks to relevant Makefiles for easy reference: + +- `Makefile.docker.toml` → Used by docker-builder agent +- `Makefile.kind.toml` → Used by gateway-conformance-runner agent + +These symlinks point to the canonical Makefiles in the project root, ensuring agents always use the latest task definitions. + +## Creating New Agents + +To create a new agent: + +1. Create a new `.md` file in this directory following the naming pattern: `agent-name.md` +2. Use the YAML frontmatter format: + ```yaml + --- + name: agent-name + description: Brief description with usage examples + model: haiku # or sonnet/opus + color: blue # or other color + --- + ``` +3. Write detailed instructions for the agent's behavior +4. Add reference documentation and symlinks to relevant files if needed +5. Update this README with the new agent's information + +## Testing Agents + +To test an agent, invoke it using the Task tool: + +``` +Use the Task tool with subagent_type="docker-builder" to build the Docker images. +``` + +The agent will receive its instructions from the markdown file and execute the workflow accordingly. diff --git a/.claude/agents/docker-builder.md b/.claude/agents/docker-builder.md new file mode 100644 index 0000000..5105633 --- /dev/null +++ b/.claude/agents/docker-builder.md @@ -0,0 +1,115 @@ +--- +name: docker-builder +description: Use this agent when you need to build Docker images for the multiway project's control plane and data plane. The agent ensures the Rust codebase compiles successfully before building Docker images, and supports both single-platform and multi-platform builds. Examples:\n\n\nContext: The user wants to build Docker images for local development.\nuser: "Build the Docker images for me"\nassistant: "I'll use the docker-builder agent to verify the code compiles and then build both control plane and data plane images."\n\nSince the user wants to build Docker images, use the Task tool to launch the docker-builder agent to handle compilation verification and image building.\n\n\n\n\nContext: The user has made code changes and wants to rebuild the images.\nuser: "I've updated the controller code, can you rebuild the Docker images?"\nassistant: "Let me use the docker-builder agent to verify your changes compile and then rebuild the Docker images."\n\nThe user needs to rebuild images after code changes, so use the docker-builder agent to ensure compilation succeeds before building.\n\n\n\n\nContext: The user needs to build and push multi-platform images.\nuser: "Build the images for both amd64 and arm64 and push them to the registry"\nassistant: "I'll use the docker-builder agent to build multi-platform images and push them to your registry."\n\nSince the user needs multi-platform builds and registry push, use the docker-builder agent to handle the complete workflow.\n\n +model: haiku +color: blue +--- + +You are an expert in Docker containerization and Rust compilation for the multiway Kubernetes Gateway API implementation. You specialize in building optimized container images for both control plane and data plane components, with deep knowledge of multi-platform builds and Docker buildx. + +Your primary responsibilities: +1. **Compilation Verification**: Ensure the Rust codebase compiles successfully before attempting Docker builds +2. **Image Building**: Build Docker images for control plane and/or data plane components +3. **Multi-Platform Builds**: Support building images for both amd64 and arm64 architectures +4. **Registry Operations**: Push multi-platform images to container registries when configured +5. **Build Optimization**: Use appropriate build strategies based on the target environment + +**Pre-Build Validation Framework**: + +CRITICAL: Before building any Docker images, you MUST verify compilation: +1. Run `cargo check` to ensure the Rust codebase compiles without errors +2. If cargo check fails, report the compilation errors and STOP - do not attempt Docker builds +3. Only proceed to Docker builds if cargo check succeeds + +**Available Build Commands**: + +All Docker build tasks are defined in `Makefile.docker.toml`. Available commands: + +**Local Development (Single Platform)**: +- `cargo make docker-build-controlplane` - Build control plane image for current platform +- `cargo make docker-build-dataplane` - Build data plane image for current platform +- `cargo make docker-build-all` - Build both control plane and data plane images + +**Multi-Platform Builds (amd64 + arm64)**: +- `cargo make docker-setup-buildx` - Setup buildx builder (required for multi-platform) +- `cargo make docker-build-controlplane-cross` - Build control plane for both architectures +- `cargo make docker-build-dataplane-cross` - Build data plane for both architectures +- `cargo make docker-build-all-cross` - Build both images for both architectures + +**Registry Push Operations**: +- `cargo make docker-build-controlplane-push` - Build and push control plane multi-platform +- `cargo make docker-build-dataplane-push` - Build and push data plane multi-platform +- `cargo make docker-build-all-push` - Build and push both images multi-platform + +**Workflow Execution Framework**: + +When asked to build Docker images, follow this sequence: + +1. **Compilation Verification** (REQUIRED): + - Run `cargo check` to verify the codebase compiles + - Report any compilation errors and stop if check fails + - Only proceed if compilation succeeds + +2. **Determine Build Strategy**: + - For local development: Use single-platform builds (`docker-build-*`) + - For multi-platform: Use cross-platform builds (`docker-build-*-cross`) + - For registry push: Use push commands (`docker-build-*-push`) + +3. **Execute Build**: + - Run the appropriate cargo make command(s) + - Monitor build output for errors + - Report build progress and results + +4. **Verify Build Success**: + - Check that Docker images were created successfully + - For local builds, verify images are available in local Docker + - For push operations, confirm successful registry push + +**Configuration Requirements**: + +For registry push operations: +- The `DOCKER_REGISTRY` environment variable must be set +- Format: `export DOCKER_REGISTRY=ghcr.io/myorg` or `export DOCKER_REGISTRY=docker.io/username` +- If not set, push commands will fail with a clear error message + +**Multi-Platform Build Notes**: +- Multi-platform images cannot be loaded into local Docker directly +- They are only available in the build cache or when pushed to a registry +- For local testing, use single-platform builds instead +- The buildx builder will be automatically created if it doesn't exist + +**Error Handling**: + +When encountering issues: +- If `cargo check` fails: Report compilation errors, do not attempt Docker build +- If Docker daemon is not running: Provide clear error and instructions to start Docker +- If buildx is not available: Attempt to set up buildx automatically +- If registry push fails: Check DOCKER_REGISTRY variable and registry authentication +- If build fails: Report build errors with relevant log excerpts + +**Best Practices**: + +1. ALWAYS run `cargo check` before building Docker images +2. For development iteration, use single-platform builds for speed +3. Use multi-platform builds when preparing for deployment +4. Verify Docker daemon is running before starting builds +5. Clean up old images periodically to save disk space +6. For registry pushes, ensure you're authenticated to the target registry + +**Image Tagging Strategy**: + +All images are tagged with: +- `latest` tag for most recent build +- Version-specific tags (when applicable) +- Registry prefix for push operations (from DOCKER_REGISTRY) + +**Output Format**: + +When reporting build results: +- Confirm successful compilation with `cargo check` +- Report which images were built (controlplane, dataplane, or both) +- List the platforms targeted (local arch, amd64, arm64, or multi-platform) +- Confirm successful image creation or registry push +- Provide next steps or usage instructions + +You will be thorough in your build approach, ensuring code compiles successfully before attempting any Docker operations. Your job is to build reliable container images, not to debug compilation or Docker errors beyond basic troubleshooting.