Build Examples

.gitignore

@@ -20,3 +20,7 @@ buildrunner/version.py
 
 buildrunner.results
 curator.results
+
+# Ignore all .tar files
+# Manually running of some example files may create local .tar files
+*.tar

README.rst

@@ -1131,7 +1131,7 @@ See `docs/common-issues <docs/common-issues.rst>`_.
 Example Configurations
 ======================
 
-See `examples <examples/README.rst>`_.
+See `examples <examples/>`_.
 
 Contributing
 ============

examples/README.rst

@@ -14,13 +14,13 @@ To run Buildrunner using an example configuration file, follow these steps from
 2. **Execute Buildrunner with a specified configuration file:**
     .. code-block:: sh
 
-        PYTHONPATH=. ./bin/buildrunner -f examples/<path-to-config-file>
+      ./run-buildrunner.sh  -f examples/<path-to-config-file>
 
     *Example:*
 
     .. code-block:: sh
 
-      PYTHONPATH=. ./bin/buildrunner -f examples/build/basic/buildrunner.yaml
+      ./run-buildrunner.sh  examples/build/basic/buildrunner.yaml
 
 Adding a New Example Configuration File
 =======================================
@@ -39,4 +39,9 @@ To contribute a new example configuration file, adhere to the following guidelin
    - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions.
    - Any supporting files required for the configuration should be placed alongside the configuration file.
 
-Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.
+Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.
+
+Excluding Example Configuration Files from Unit Tests
+=====================================================
+
+To exclude an example configuration file from unit tests, add the file path to the ``excluded_example_files`` list in ``tests/test_buildrunner_files.py``.

examples/build/basic/buildrunner.yaml

@@ -3,5 +3,5 @@ steps:
   simple-build-step:
     build:
       dockerfile: |
-        FROM busybox:latest
+        FROM alpine:latest
         RUN echo Hello World

examples/build/buildargs/buildrunner.yaml

@@ -0,0 +1,18 @@
+# This example demonstrates how to use the buildargs field in the build step.
+# The buildargs field allows you to pass build-time variables to the Dockerfile.
+steps:
+  buildargs-step:
+    build:
+      buildargs:
+        MY_VERSION: 2.0
+      dockerfile: |
+        FROM alpine:latest
+        ARG MY_VERSION
+        LABEL version=$MY_VERSION
+
+    # To view the label in the built image do the following:
+    #  1. Uncomment the following 'push:' line
+    #  2. Run 'PYTHONPATH=. ./bin/buildrunner -f examples/build/buildargs/buildrunner.yaml'
+    #  3. Run 'docker image inspect my-images/buildargs-image:latest' to see the label.
+    #
+    # push: my-images/buildargs-image:latest

examples/build/cache/buildrunner.yaml

@@ -0,0 +1,16 @@
+# Description: This example demonstrates how to use the no-cache option in the build step.
+steps:
+  cache-build-step:
+    build:
+      no-cache: false
+      dockerfile: |
+        FROM alpine:latest
+        RUN apk update
+        RUN echo Hello World
+  no-cache-build-step:
+    build:
+      no-cache: true
+      dockerfile: |
+        FROM alpine:latest
+        RUN apk update
+        RUN echo Hello World

examples/build/import/buildrunner.yaml

@@ -0,0 +1,11 @@
+# This example demonstrates how to import a tarball image in the build step.
+# This requires the tarball image to be present in the same directory where buildrunnner is executed.
+# Before running this example, make sure to create a tarball image using the following command:
+# docker save alpine:latest -o alpine.tar
+#
+# WARNING: Do not commit the tarball image to the repository.
+#
+steps:
+  import-step:
+    build:
+      import: alpine.tar

examples/build/inject/buildrunner.yaml

@@ -0,0 +1,14 @@
+# This example demonstrates how to use the inject field to inject a file into the build context.
+# See buildrunner documentation for more information.
+steps:
+  build-step-with-inject:
+    build:
+      inject:
+        # Step 1: Inject a file into the build context
+        # The file /injectfile.txt will be injected into the build context
+        examples/build/inject/injectfile.txt: /injectfile.txt
+      dockerfile: |
+        FROM alpine
+        # Step 2: Copy the injected file into the image or use it in some other way in the build process
+        COPY /injectfile.txt /tmp/
+        RUN cat /tmp/injectfile.txt

examples/build/inject/injectfile.txt

@@ -0,0 +1 @@
+This is a sample text file that can be injected into the build context

examples/build/platform/README.rst

@@ -0,0 +1 @@
+Contains an example of building a single-platform image.

examples/build/platform/buildrunner.yaml

@@ -0,0 +1,10 @@
+# Example of a buildrunner.yaml file that specifies a single platform build step.
+# The 'platform' field is optional and can be used to specify the platform for the build step.
+# If the 'platform' field is not specified, the default platform is native platform of the machine running buildrunner.
+steps:
+  single-platform-build-step:
+    build:
+      dockerfile: |
+        FROM alpine:latest
+        RUN echo Hello World
+      platform: linux/amd64

examples/build/platforms/README.rst

@@ -0,0 +1 @@
+Contains an example of building a multi-platform image.

examples/build/platforms/buildrunner.yaml

@@ -0,0 +1,12 @@
+# Example of a buildrunner.yaml file that specifies a multi-platform build step.
+# The 'platforms' field is optional and can be used to specify the platforms for the build step.
+# If the 'platforms' field is not specified, by default it will build a single platform, using the native platform of the machine running buildrunner.
+steps:
+  multi-platform-build-step:
+    build:
+      dockerfile: |
+        FROM alpine:latest
+        LABEL custom_label="Buildrunner example label"
+      platforms:
+      - linux/amd64
+      - linux/arm64

examples/run/basic/buildrunner.yaml

@@ -2,5 +2,5 @@
 steps:
   simple-run-step:
     run:
-      image: busybox:latest
+      image: alpine:latest
       cmd: echo Hello World

examples/run/services/Dockerfile

@@ -0,0 +1,5 @@
+FROM ubuntu
+
+RUN apt-get update \
+    && apt-get upgrade -y \
+    && apt-get install -y inetutils-ping bash vim

examples/run/services/buildrunner.yaml

@@ -0,0 +1,27 @@
+# This example demonstrates how to run multiple services in a single step.
+# The services are defined in the services section of the run step.
+# Note: Change cmd to tail -f /dev/null to keep the services running for debugging.
+steps:
+  my-build-step:
+    build:
+      path: examples/run/services
+    commit:
+      repository: myimages/image1
+      tags: [ 'latest' ]
+  my-services-step:
+    run:
+      image: myimages/image1:latest
+      cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+      services:
+        stats1:
+          build:
+            path: examples/run/services
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+        stats2:
+          build:
+            path: examples/run/services
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+        stats3:
+          build:
+            path: examples/run/services
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"

examples/run/services/standalone-buildrunner.yaml

@@ -0,0 +1,43 @@
+# Standalone file with buildrunner configuration using services.
+# The services are defined in the services section of the run step.
+# Note: Change cmd to tail -f /dev/null to keep the services running for debugging.
+steps:
+  my-build-step:
+    build:
+      dockerfile: |
+        FROM ubuntu
+        RUN apt-get update \
+          && apt-get upgrade -y \
+          && apt-get install -y inetutils-ping bash vim
+    commit:
+      repository: myimages/image1
+      tags: [ 'latest' ]
+  my-services-step:
+    run:
+      image: myimages/image1:latest
+      cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+      services:
+        stats1:
+          build:
+            dockerfile: |
+              FROM ubuntu
+              RUN apt-get update \
+                && apt-get upgrade -y \
+                && apt-get install -y inetutils-ping bash vim
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+        stats2:
+          build:
+            dockerfile: |
+              FROM ubuntu
+              RUN apt-get update \
+                && apt-get upgrade -y \
+                && apt-get install -y inetutils-ping bash vim
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"
+        stats3:
+          build:
+            dockerfile: |
+              FROM ubuntu
+              RUN apt-get update \
+                && apt-get upgrade -y \
+                && apt-get install -y inetutils-ping bash vim
+          cmd: echo "Hello, World!" && sleep 1 && echo "Goodbye, World!"

run-buildrunner.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# This script will run the local buildrunner code from the root of the project
+#
+# To get help, run the following command:
+#   ./run-buildrunner.sh --help
+#
+# To run the buildrunner with a specific configuration file, run the following command:
+#   ./run-buildrunner.sh -f examples/build/basic/buildrunner.yaml
+PYTHONPATH=. ./bin/buildrunner --cleanup-images "$@"

tests/test_buildrunner_files.py

@@ -119,11 +119,21 @@ def _get_test_runs(
 
 def _get_example_runs(test_dir: str) -> List[Tuple[str, str, Optional[List[str]], int]]:
     file_names = []
+
+    # Files that should be excluded from the example tests
+    excluded_example_files = [
+        "examples/build/import/buildrunner.yaml",
+    ]
+
     # Walk through the examples directory and find all files ending with buildrunner.yaml
     for root, _, files in os.walk(test_dir):
         for file in files:
             file_name = os.path.join(root, file)
-            if file_name.endswith("buildrunner.yaml"):
+            if file_name.endswith("buildrunner.yaml") and not [
+                excluded
+                for excluded in excluded_example_files
+                if file_name.endswith(excluded)
+            ]:
                 file_names.append(file_name)
 
     return [