Configure Multiple Package Repositories#

Overview#

The OS Image Composer supports adding multiple custom package repositories to your image builds through the packageRepositories section in image template files. This feature allows you to include packages from additional repositories beyond the default OS repositories, enabling you to integrate specialized software, proprietary packages, or packages from specific vendors into your custom images.

How It Works#

Package repositories are configured during the image build process and are added to the package manager configuration before any packages are installed. This ensures that packages from custom repositories are available during the package installation phase, allowing you to install packages from multiple sources in a single build.

Configuration Structure#

The packageRepositories section should be placed at the root level of your image template YAML file, alongside other top-level configuration sections:

image:
  name: your-image-name
  version: "1.0"

target:
  os: ubuntu
  dist: ubuntu24
  arch: x86_64
  imageType: raw

# Package repositories are configured before any other operations
packageRepositories:
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

disk:
  name: ....
  # .... other disk configuration

systemConfig:
  name: ....
  packages:
    - ubuntu-minimal
    - edge-ai-package    # This package comes from the EdgeAI repository
    # .... other packages

Repository Configuration Properties#

Each repository entry supports the following properties:

  • codename (required): A unique identifier for the repository

  • url (required): The base URL of the package repository

  • pkey (strongly recommended): URL to the GPG public key for repository authentication. Technically this field is optional, but omitting it (or using [trusted=yes] to bypass GPG verification) should be limited to explicitly trusted internal repositories, as it disables signature verification and reduces security.

Complete Template Structure#

Here’s how the packageRepositories section fits within a complete image template:

image:
  name: multi-repo-image
  version: "1.0"

target:
  os: ubuntu
  dist: ubuntu24
  arch: x86_64
  imageType: raw

# Multiple package repositories configuration
packageRepositories:
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

  - codename: "edge-base"
    url: "https://files-rs.edgeorchestration.intel.com/files-edge-orch/microvisor/rpms/3.0/base"
    pkey: "https://raw.githubusercontent.com/open-edge-platform/edge-microvisor-toolkit/refs/heads/3.0/SPECS/edge-repos/INTEL-RPM-GPG-KEY"

disk:
  name: ....
  # .... disk configuration

systemConfig:
  name: ....
  description: ....

  packages:
    - ubuntu-minimal
    - openvino-toolkit     # From OpenVINO repository
    - edge-ai-runtime      # From EdgeAI repository
    - microvisor-base      # From edge-base repository
    # .... other packages from various repositories

  kernel:
    version: ....
    # .... kernel configuration

  configurations:
    # .... custom configurations

Real-World Example#

A comprehensive multi-repository configuration for edge computing and AI workloads:

packageRepositories:
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

  - codename: "edge-base"
    url: "https://files-rs.edgeorchestration.intel.com/files-edge-orch/microvisor/rpms/3.0/base"
    pkey: "https://raw.githubusercontent.com/open-edge-platform/edge-microvisor-toolkit/refs/heads/3.0/SPECS/edge-repos/INTEL-RPM-GPG-KEY"

  - codename: "OpenVINO"
    url: "https://yum.repos.intel.com/openvino/"
    pkey: "https://yum.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB"

  - codename: "mariner"
    url: "https://packages.microsoft.com/yumrepos/cbl-mariner-2.0-prod-extended-x86_64/"
    pkey: "https://packages.microsoft.com/azurelinux/3.0/prod/base/x86_64/repodata/repomd.xml.key"

Repository Configuration Examples#

Intel Edge AI Stack#

packageRepositories:
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

  - codename: "OpenVINO"
    url: "https://yum.repos.intel.com/openvino/"
    pkey: "https://yum.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB"

systemConfig:
  packages:
    - openvino-toolkit
    - edge-ai-runtime
    - intel-media-driver
    # ....

Microsoft and Intel Integration#

packageRepositories:
  - codename: "mariner"
    url: "https://packages.microsoft.com/yumrepos/cbl-mariner-2.0-prod-extended-x86_64/"
    pkey: "https://packages.microsoft.com/azurelinux/3.0/prod/base/x86_64/repodata/repomd.xml.key"

  - codename: "edge-base"
    url: "https://files-rs.edgeorchestration.intel.com/files-edge-orch/microvisor/rpms/3.0/base"
    pkey: "https://raw.githubusercontent.com/open-edge-platform/edge-microvisor-toolkit/refs/heads/3.0/SPECS/edge-repos/INTEL-RPM-GPG-KEY"

systemConfig:
  packages:
    - mariner-base-packages
    - microvisor-runtime
    - edge-orchestration-tools
    # ....

Development Environment#

packageRepositories:
  - codename: "docker-ce"
    url: "https://download.docker.com/linux/ubuntu"
    pkey: "https://download.docker.com/linux/ubuntu/gpg"

  - codename: "nodejs"
    url: "https://deb.nodesource.com/node_18.x"
    pkey: "https://deb.nodesource.com/gpgkey/nodesource.gpg.key"

systemConfig:
  packages:
    - docker-ce
    - docker-ce-cli
    - nodejs
    - npm
    # ....

Trusted Repository (No GPG Verification)#

# WARNING: "[trusted=yes]" disables signature verification.
# Only use this for repositories fully controlled by your organization,
# typically in development or testing, and never for public or third-party repos.
packageRepositories:
  - codename: "internal-repo"
    url: "https://internal.company.com/packages"
    pkey: "[trusted=yes]"  # Bypasses GPG verification; ONLY for internal, organization-controlled repos.

  - codename: "test-repo"
    url: "https://test.example.com/packages"
    pkey: "[trusted=yes]"  # No signature verification; for internal dev/test only, not public/third-party repos.

systemConfig:
  packages:
    - internal-package
    - test-package
    # ....

Execution Process#

Repository Setup Phase#

The build process follows this sequence when multiple repositories are configured:

  1. Repository Configuration: All repositories in packageRepositories are added to the package manager

  2. GPG Key Import: Public keys are downloaded and imported for repository authentication (skipped for [trusted=yes] repositories)

  3. Repository Refresh: Package lists are updated from all configured repositories

  4. Package Installation: Packages from all repositories become available for installation

Package Resolution#

When packages are installed:

  • The package manager searches all configured repositories

  • Dependencies can be resolved across multiple repositories

  • Repository priority may affect package selection when conflicts exist

Best Practices#

1. Always Include GPG Keys#

Include GPG keys for repository authentication and security:

packageRepositories:
  # Good - includes GPG key for security
  - codename: "secure-repo"
    url: "https://example.com/packages"
    pkey: "https://example.com/gpg-key.pub"

  # Use trusted=yes only for internal/trusted repositories
  - codename: "internal-repo"
    url: "https://internal.company.com/packages"
    pkey: "[trusted=yes]"

  # Avoid - missing pkey entirely reduces security
  - codename: "insecure-repo"
    url: "https://example.com/packages"

2. Use Descriptive Codenames#

Choose clear, descriptive codenames that indicate the repository purpose:

packageRepositories:
  # Good - descriptive codenames
  - codename: "EdgeAI"
  - codename: "OpenVINO"
  - codename: "docker-ce"

  # Avoid - unclear codenames
  - codename: "repo1"
  - codename: "custom"

3. Verify Repository URLs#

Ensure repository URLs are correct and accessible:

packageRepositories:
  # Verify these URLs are accessible during build
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

4. Document Repository Sources#

Add comments to document repository purposes:

packageRepositories:
  # Intel Edge AI packages for computer vision and inference
  - codename: "EdgeAI"
    url: "https://yum.repos.intel.com/edgeai/"
    pkey: "https://yum.repos.intel.com/edgeai/GPG-PUB-KEY-INTEL-DLS.gpg"

  # Microsoft CBL-Mariner extended packages
  - codename: "mariner"
    url: "https://packages.microsoft.com/yumrepos/cbl-mariner-2.0-prod-extended-x86_64/"
    pkey: "https://packages.microsoft.com/azurelinux/3.0/prod/base/x86_64/repodata/repomd.xml.key"

Security Considerations#

Repository Trust#

  • Only add repositories from trusted sources

  • Always include GPG keys for repository authentication when available

  • Use pkey: "[trusted=yes]" only when GPG keys are unavailable and the repository is under your organization’s direct control

  • Regularly review and update repository configurations

  • Be cautious with repositories that don’t provide GPG keys

Network Security#

  • Use HTTPS URLs when available

  • Consider using local repository mirrors for improved security and performance

  • Validate GPG key fingerprints when possible