feat: export distribution container build artifacts

Add a new --export-dir flag to the `llama stack build` command that
allows users to export container build artifacts to a specified
directory instead of building the container directly. This feature is
useful for:

- Building containers in different environments
- Sharing build configurations
- Customizing the build process

The exported tarball includes:
- Containerfile (Dockerfile)
- Run configuration file (if building from config)
- External provider files (if specified)
- Build script for assistance

The tarball is named with a timestamp for uniqueness: <distro-name>_<timestamp>.tar.gz

Documentation has been updated in building_distro.md to reflect this new
functionality as well as integration tests.

Signed-off-by: Sébastien Han <[email protected]>

Author: leseb

.github/workflows/providers-build.yml

@@ -198,3 +198,60 @@ jobs:
               'source /etc/os-release && echo "$ID"' \
               | grep -qE '^(rhel|ubi)$' \
               || { echo "Base image is not UBI 9!"; exit 1; }
+
+  export-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.10'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+        with:
+          python-version: "3.10"
+
+      - name: Install LlamaStack
+        run: |
+          uv venv
+          source .venv/bin/activate
+          uv pip install -e .
+
+      - name: Pin template to UBI9 base
+        run: |
+          yq -i '
+            .image_type    = "container" |
+            .image_name    = "ubi9-test" |
+            .distribution_spec.container_image = "registry.access.redhat.com/ubi9:latest"
+          ' llama_stack/templates/starter/build.yaml
+
+      - name: Test the export
+        run: |
+          USE_COPY_NOT_MOUNT=true LLAMA_STACK_DIR=. uv run llama stack build --config llama_stack/templates/starter/build.yaml --export-dir export
+          for file in export/*; do
+            echo "File: $file"
+            if [[ "$file" == *.tar.gz ]]; then
+              echo "Tarball found"
+              tarball_found=1
+              tar -xzvf "$file"
+              if [ -f "Containerfile" ]; then
+                echo "Containerfile found"
+              else
+                echo "Containerfile not found"
+                exit 1
+              fi
+            else
+              continue
+            fi
+            break
+          done
+          if [ -z "$tarball_found" ]; then
+            echo "Tarball not found"
+            exit 1
+          fi
+          cd export
+          docker build -t test .

docs/source/distributions/building_distro.md

@@ -53,7 +53,7 @@ The main points to consider are:
 
 ```
 llama stack build -h
-usage: llama stack build [-h] [--config CONFIG] [--template TEMPLATE] [--list-templates] [--image-type {conda,container,venv}] [--image-name IMAGE_NAME] [--print-deps-only] [--run]
+usage: llama stack build [-h] [--config CONFIG] [--template TEMPLATE] [--list-templates] [--image-type {conda,container,venv}] [--image-name IMAGE_NAME] [--print-deps-only] [--run] [--export-dir EXPORT_DIR]
 
 Build a Llama stack container
 
@@ -71,6 +71,8 @@ options:
                         found. (default: None)
   --print-deps-only     Print the dependencies for the stack only, without building the stack (default: False)
   --run                 Run the stack after building using the same image type, name, and other applicable arguments (default: False)
+  --export-dir EXPORT_DIR
+                        Export the build artifacts to a specified directory instead of building the container. This will create a tarball containing the Dockerfile and all necessary files to build the container. (default: None)
 
 ```
 
@@ -260,6 +262,24 @@ Containerfile created successfully in /tmp/tmp.viA3a3Rdsg/ContainerfileFROM pyth
 You can now edit ~/meta-llama/llama-stack/tmp/configs/ollama-run.yaml and run `llama stack run ~/meta-llama/llama-stack/tmp/configs/ollama-run.yaml`
 ```
 
+You can also export the build artifacts to a specified directory instead of building the container directly. This is useful when you want to:
+- Build the container in a different environment
+- Share the build configuration with others
+- Customize the build process
+
+To export the build artifacts, use the `--export-dir` flag:
+
+```
+llama stack build --config my-build.yaml --image-type container --export-dir ./my-build
+```
+
+This will create a tarball in the specified directory containing:
+- The Dockerfile (named Containerfile)
+- The run configuration file (if building from a config)
+- Any external provider files (if specified in the config)
+
+The tarball will be named with a timestamp to ensure uniqueness, for example: `<distro-name>_<timestamp>.tar.gz`
+
 After this step is successful, you should be able to find the built container image and test it with `llama stack run <path/to/run.yaml>`.
 :::
 

llama_stack/cli/stack/_build.py

@@ -228,6 +228,7 @@ def run_stack_build_command(args: argparse.Namespace) -> None:
             image_name=image_name,
             config_path=args.config,
             template_name=args.template,
+            export_dir=args.export_dir,
         )
 
     except (Exception, RuntimeError) as exc:
@@ -341,6 +342,7 @@ def _run_stack_build_command_from_build_config(
     image_name: str | None = None,
     template_name: str | None = None,
     config_path: str | None = None,
+    export_dir: str | None = None,
 ) -> str:
     image_name = image_name or build_config.image_name
     if build_config.image_type == LlamaStackImageType.CONTAINER.value:
@@ -383,6 +385,7 @@ def _run_stack_build_command_from_build_config(
         image_name,
         template_or_config=template_name or config_path or str(build_file_path),
         run_config=run_config_file,
+        export_dir=export_dir,
     )
     if return_code != 0:
         raise RuntimeError(f"Failed to build image {image_name}")

llama_stack/cli/stack/build.py

@@ -5,6 +5,7 @@
 # the root directory of this source tree.
 import argparse
 import textwrap
+from pathlib import Path
 
 from llama_stack.cli.stack.utils import ImageType
 from llama_stack.cli.subcommand import Subcommand
@@ -82,6 +83,13 @@ def _add_arguments(self):
             help="Build a config for a list of providers and only those providers. This list is formatted like: api1=provider1,api2=provider2. Where there can be multiple providers per API.",
         )
 
+        self.parser.add_argument(
+            "--export-dir",
+            type=Path,
+            default=None,
+            help="Export the build artifacts to a specified directory instead of building the container. This will create a directory containing the Dockerfile and all necessary files to build the container.",
+        )
+
     def _run_stack_build_command(self, args: argparse.Namespace) -> None:
         # always keep implementation completely silo-ed away from CLI so CLI
         # can be fast to load and reduces dependencies

llama_stack/distribution/build.py

@@ -93,6 +93,7 @@ def build_image(
     image_name: str,
     template_or_config: str,
     run_config: str | None = None,
+    export_dir: str | None = None,
 ):
     container_base = build_config.distribution_spec.container_image or "python:3.10-slim"
 
@@ -108,6 +109,8 @@ def build_image(
             container_base,
             " ".join(normal_deps),
         ]
+        if export_dir is not None:
+            args.append(export_dir)
 
         # When building from a config file (not a template), include the run config path in the
         # build arguments

llama_stack/distribution/build_container.sh

@@ -26,7 +26,7 @@ BUILD_CONTEXT_DIR=$(pwd)
 
 if [ "$#" -lt 4 ]; then
   # This only works for templates
-  echo "Usage: $0 <template_or_config> <image_name> <container_base> <pip_dependencies> [<run_config>] [<special_pip_deps>]" >&2
+  echo "Usage: $0 <template_or_config> <image_name> <container_base> <pip_dependencies> [<run_config>] [<special_pip_deps>] [<export_dir>]" >&2
   exit 1
 fi
 set -euo pipefail
@@ -43,23 +43,26 @@ shift
 # Handle optional arguments
 run_config=""
 special_pip_deps=""
-
-# Check if there are more arguments
-# The logics is becoming cumbersom, we should refactor it if we can do better
-if [ $# -gt 0 ]; then
-  # Check if the argument ends with .yaml
-  if [[ "$1" == *.yaml ]]; then
-    run_config="$1"
-    shift
-    # If there's another argument after .yaml, it must be special_pip_deps
-    if [ $# -gt 0 ]; then
-      special_pip_deps="$1"
-    fi
-  else
-    # If it's not .yaml, it must be special_pip_deps
-    special_pip_deps="$1"
-  fi
-fi
+export_dir=""
+
+# Process remaining arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    *.yaml)
+      run_config="$1"
+      shift
+      ;;
+    *)
+      # Check if argument is a valid directory path (export_dir) or special_pip_deps
+      if [[ "$1" == *" "* ]] || ! mkdir -p "$1" 2>/dev/null; then
+        special_pip_deps="$1"
+      else
+        export_dir="$1"
+      fi
+      shift
+      ;;
+  esac
+done
 
 # Define color codes
 RED='\033[0;31m'
@@ -83,8 +86,8 @@ add_to_container() {
   fi
 }
 
-# Check if container command is available
-if ! is_command_available $CONTAINER_BINARY; then
+# Check if container command is available only if not running in export mode
+if ! is_command_available $CONTAINER_BINARY && [ -z "$export_dir" ]; then
   printf "${RED}Error: ${CONTAINER_BINARY} command not found. Is ${CONTAINER_BINARY} installed and in your PATH?${NC}" >&2
   exit 1
 fi
@@ -96,7 +99,7 @@ FROM $container_base
 WORKDIR /app
 
 # We install the Python 3.11 dev headers and build tools so that any
-# C‑extension wheels (e.g. polyleven, faiss‑cpu) can compile successfully.
+# C-extension wheels (e.g. polyleven, faiss-cpu) can compile successfully.
 
 RUN dnf -y update && dnf install -y iputils git net-tools wget \
     vim-minimal python3.11 python3.11-pip python3.11-wheel \
@@ -270,6 +273,43 @@ printf "Containerfile created successfully in %s/Containerfile\n\n" "$TEMP_DIR"
 cat "$TEMP_DIR"/Containerfile
 printf "\n"
 
+# If export_dir is specified, copy all necessary files and exit
+if [ -n "$export_dir" ]; then
+  mkdir -p "$export_dir"
+  timestamp=$(date '+%Y-%m-%d_%H-%M-%S')
+  tar_name="${image_name//[^a-zA-Z0-9]/_}_${timestamp}.tar.gz"
+
+  # If a run config is provided, copy it to the export directory otherwise it's a template build and
+  # we don't need to copy anything
+  if [ -n "$run_config" ]; then
+    mv "$run_config" "$TEMP_DIR"/run.yaml
+  fi
+
+  # Create the archive with all files
+  echo "Creating tarball with the following files:"
+  echo "- Containerfile"
+  [ -n "$run_config" ] && echo "- run.yaml"
+  [ -n "$external_providers_dir" ] && echo "- providers.d directory"
+
+  # Capture both stdout and stderr from tar command
+  tar_output=$(tar -czf "$export_dir/$tar_name" \
+    -C "$TEMP_DIR" Containerfile \
+    ${run_config:+-C "$BUILD_CONTEXT_DIR" "$(basename run.yaml)"} \
+    ${external_providers_dir:+-C "$BUILD_CONTEXT_DIR" providers.d} 2>&1)
+  tar_status=$?
+
+  if [ $tar_status -ne 0 ]; then
+    echo "ERROR: Failed to create tarball" >&2
+    echo "Tar command output:" >&2
+    echo "$tar_output" >&2
+    exit 1
+  fi
+  rm -rf providers.d run.yaml
+
+  echo "Build artifacts tarball created: $export_dir/$tar_name"
+  exit 0
+fi
+
 # Start building the CLI arguments
 CLI_ARGS=()
 

tests/unit/distribution/test_build_path.py

@@ -16,9 +16,10 @@
 def test_container_build_passes_path(monkeypatch, tmp_path):
     called_with = {}
 
-    def spy_build_image(cfg, build_file_path, image_name, template_or_config, run_config=None):
+    def spy_build_image(cfg, build_file_path, image_name, template_or_config, run_config=None, export_dir=None):
         called_with["path"] = template_or_config
         called_with["run_config"] = run_config
+        called_with["export_dir"] = export_dir
         return 0
 
     monkeypatch.setattr(