Update docs

Author: shanejbrown

buildrunner/docker/multiplatform_image_builder.py

@@ -77,7 +77,7 @@ def __init__(
         docker_registry: Optional[str] = None,
         build_registry: Optional[str] = MP_LOCAL_REGISTRY,
         temp_dir: str = os.getcwd(),
-        platform_builders: Optional[Dict[str, str]] = None,
+        platform_builders: Optional[Union[Dict[str, List[str]], List[str]]] = None,
         cache_builders: Optional[List[str]] = None,
         cache_from: Optional[Union[dict, str]] = None,
         cache_to: Optional[Union[dict, str]] = None,

docs/global-configuration.rst

@@ -99,8 +99,16 @@ they are used when put into the global configuration file:
   # and therefore this must be configured in buildrunner itself to perform builds
   # across multiple builders for different platforms. Any platform not specified
   # here will use the default configured buildx builder.
+  # 
+  # Each platform can be configured with either a single builder (string) or
+  # a list of builders (array of strings). When using a list, buildrunner will
+  # randomly select one builder for each build.
   platform-builders:
     platform1: builder1
+    platform2:
+      - builder1
+      - builder2
+      - builder3
 
   # Configures caching *for multi-platform builds only*
   docker-build-cache:

examples/build/builders/README.rst

@@ -2,7 +2,42 @@
 Builders Example
 ==================
 
-This example demonstrates how to use Buildrunner with custom builders.
+This example demonstrates how to use Buildrunner with custom builders and random builder selection.
+
+Platform Builders Configuration
+===============================
+
+The ``platform-builders`` configuration allows you to specify which builders to use for different platforms. When multiple builders are available for a platform, Buildrunner will randomly select one to distribute the load.
+
+Configuration Options
+---------------------
+
+1. **Multiple builders per platform** (recommended for load balancing):
+
+   .. code-block:: yaml
+
+       platform-builders:
+         linux/amd64:
+           - builder1
+           - builder2
+           - builder3
+         linux/arm64:
+           - builder4
+           - builder5
+
+2. **Single builder per platform**:
+
+   .. code-block:: yaml
+
+       platform-builders:
+         linux/amd64: builder1
+         linux/arm64: builder2
+
+
+Random Selection
+----------------
+
+When multiple builders are configured for a platform, Buildrunner will randomly select one builder for each build. This helps distribute the build load across available builders and can improve build performance by utilizing multiple build resources.
 
 How to Run
 ==========
@@ -23,13 +58,12 @@ How to Run
 
        ./run-buildrunner.sh -f examples/build/builders/buildrunner.yaml -c examples/build/builders/global-config.yaml
 
-  or
+   or
 
    .. code-block:: sh
 
        ./run-buildrunner.sh -f examples/build/builders/buildrunner.yaml -c examples/build/builders/global-config-list.yaml
 
-
 3. **Remove builders**
 
    From the base directory, run:

tests/test_config_validation/test_global_config.py

@@ -134,16 +134,26 @@ def fixture_override_master_config_file(tmp_path):
         (
             """
           platform-builders:
-            linux/amd64: builder2
-            linux/arm64: builder3
+            linux/amd64: builder1
+            linux/arm64: builder2
           """,
             [],
         ),
         (
             """
           platform-builders:
+            linux/amd64: builder1
+            linux/arm64:
+              - builder1
+              - builder2
+          """,
+            [],
+        ),
+        (
+            """
+          platform-builders:
+            - builder1
             - builder2
-            - builder3
           """,
             ["platform-builders:  Input should be a valid dictionary (dict_type)"],
         ),