Skip to content

Delta Packages

Delta packages provide a bandwidth-efficient way to upgrade K2s installations by including only the files that have changed between two versions, rather than redistributing the entire package.

Overview

A delta package contains:

  • Changed files: Files that differ between the source and target versions
  • Wholesale directories: Complete directories that must be replaced entirely (e.g., bin/kube, bin/docker)
  • Delta manifest: A JSON file describing the changes and metadata
  • Debian package changes (optional): Linux package differences for the KubeMaster VM
  • Apply script: A PowerShell script to apply the delta to an existing installation

Addons are excluded

Delta packages do not include addon files. Addons are managed separately via k2s addons ... and are not modified during a delta upgrade.

Delta Package vs Full Package

Aspect Full Package Delta Package
Size 2-4 GB typically 50-1000 MB typically
Contains All K2s files Only changed files
Requires Nothing Specific source version
Use case Fresh installs, major upgrades Minor/patch upgrades

Creating a Delta Package

Prerequisites

  • Two K2s offline packages (source and target versions)
  • PowerShell 5.1 or later
  • Sufficient disk space for extraction (3x package size recommended)

Basic Usage

Bash Session
k2s system package --delta-package `
    -d C:\packages `
    -n k2s-delta-v1.4.0-to-v1.5.0.zip `
    --package-version-from C:\packages\k2s-v1.4.0.zip `
    --package-version-to C:\packages\k2s-v1.5.0.zip

Parameters

Flag Required Description
--delta-package Yes Enables delta package creation mode
-d, --target-dir Yes Target directory for the output package
-n, --name Yes Name of the output delta package ZIP file
--package-version-from Yes Path to the older (source) K2s package ZIP
--package-version-to Yes Path to the newer (target) K2s package ZIP
-c, --certificate No Path to code signing certificate (.pfx file)
-w, --password No Password for the code signing certificate
-o, --output No Show log output in terminal

Example with Code Signing

Bash Session
k2s system package --delta-package `
    -d C:\packages `
    -n k2s-delta-v1.4.0-to-v1.5.0.zip `
    --package-version-from C:\packages\k2s-v1.4.0.zip `
    --package-version-to C:\packages\k2s-v1.5.0.zip `
    -c path\to\cert.pfx `
    -w mycertpassword

Delta Package Contents

After creation, the delta package contains:

Text Only
k2s-delta-v1.4.0-to-v1.5.0.zip
├── delta-manifest.json          # Metadata and file lists
├── Apply-Delta.ps1              # Application script
├── bin/                         # Changed binaries
│   ├── kube/                   # Kubernetes binaries (wholesale)
│   ├── docker/                 # Docker binaries (wholesale)
│   ├── containerd/             # Containerd binaries (wholesale)
│   └── cni/                    # CNI plugins (wholesale)
├── lib/                         # Changed library files
├── smallsetup/                  # Changed setup scripts
├── scripts/                     # Delta application scripts
│   ├── apply-debian-delta.sh   # Linux package update script
│   └── verify-debian-delta.sh  # Linux package verification
└── debian-delta/                # (Optional) Debian package changes
    ├── added-packages.txt
    ├── removed-packages.txt
    ├── changed-packages.txt
    └── packages/                # Downloaded .deb files

Delta Manifest Structure

The delta-manifest.json file describes the changes between versions. A typical manifest includes:

JSON
{
  "sourceVersion": "1.4.0",
  "targetVersion": "1.5.0",
  "createdAt": "2025-02-03T10:30:00Z",
  "filesAdded": ["lib/new-module.psm1"],
  "filesModified": ["lib/existing-module.psm1"],
  "filesRemoved": ["lib/deprecated-module.psm1"],
  "wholesaleDirectories": ["bin/kube", "bin/docker", "bin/cni", "bin/containerd"],
  "debianDelta": {
    "added": ["new-package"],
    "removed": ["old-package"],
    "changed": ["updated-package"]
  },
  "imageDiff": {
    "added": ["new-image:tag"],
    "removed": ["old-image:tag"]
  }
}

Applying a Delta Package

Prerequisites

  • An existing K2s installation matching the delta's source version
  • Administrator privileges
  • The delta package ZIP file

Application Steps

  1. Extract the delta package to a temporary location:

    PowerShell
    Expand-Archive -Path "k2s-delta-v1.4.0-to-v1.5.0.zip" -DestinationPath "C:\temp\delta"

  2. Run the upgrade from the extracted delta folder:

    Bash Session
    cd C:\temp\delta
k2s system upgrade

  3. Verify the installation:

    Bash Session
    k2s system status

Best Practices

When to Use Delta Packages

✅ Recommended for:

  • Minor version upgrades (e.g., 1.4.0 → 1.5.0)
  • Patch releases (e.g., 1.4.0 → 1.4.1)
  • Bandwidth-constrained environments
  • Large-scale deployments with many nodes

❌ Not recommended for:

  • Major version upgrades (e.g., 1.x → 2.x)
  • Fresh installations
  • Upgrades spanning multiple minor versions

Version Compatibility

⚠️ Version Matching: Delta packages are version-specific. A delta from v1.4.0 to v1.5.0 can only be applied to installations running exactly v1.4.0.

To upgrade across multiple versions, either:

  1. Create sequential delta packages (v1.4.0 → v1.4.1 → v1.5.0)
  2. Use a full package for the final version

Troubleshooting

Common Issues

Version Mismatch Error

Text Only
Error: Source version mismatch. Expected 1.4.0, found 1.3.0

Solution: Ensure your current installation matches the delta's source version, or use -Force (with caution).

Missing Files After Apply

Check the delta manifest to verify which files were expected:

PowerShell
Get-Content delta-manifest.json | ConvertFrom-Json | Select-Object -ExpandProperty filesAdded

Debian Delta Failures

If Linux package updates fail:

  1. Check network connectivity in the VM
  2. Verify the .deb files exist in debian-delta/packages/
  3. Run verification script to identify missing packages

Logs

Delta package creation logs are written to:

  • Console output (with -o or --output flag)
  • K2s log directory: C:\var\log\k2s\

For more detailed logging, use the verbosity flag:

Bash Session
k2s system package --delta-package ... -o -v debug

Integration with CI/CD

Automated Delta Generation

YAML
# Example GitHub Actions workflow snippet
- name: Generate Delta Package
  run: |
    k2s system package --delta-package `
      -d ${{ env.OUTPUT_DIR }} `
      -n "k2s-delta-${{ env.PREV_VERSION }}-to-${{ env.NEW_VERSION }}.zip" `
      --package-version-from "${{ env.PREV_PACKAGE }}" `
      --package-version-to "${{ env.NEW_PACKAGE }}" `
      -o

Artifact Publishing

Delta packages can be published alongside full releases:

Text Only
releases/
├── k2s-v1.5.0.zip                    # Full package
├── k2s-delta-v1.4.0-to-v1.5.0.zip   # Delta from previous minor
└── k2s-delta-v1.4.1-to-v1.5.0.zip   # Delta from previous patch

See Also