OfflineImage YAML Specification
potctl deploys container images to Edgelet nodes that cannot pull from a registry. Pull images on your workstation, transfer them over SSH, load them on each node, and register a catalog item bound to registry ID 2 (from_cache).
Legacy x86 and arm fields are removed. Use amd64, arm64, riscv64, and arm under spec. potctl registers a catalog item whose Controller images[] entries use matching archId values.
Single-architecture example
---
apiVersion: datasance.com/v3
kind: OfflineImage
metadata:
name: alpine-offline-amd64
spec:
amd64: alpine:3.20
agent:
- edge-1
- edge-2
Multi-architecture example
List every architecture your target Edgelet nodes need. potctl pulls only the platforms required by the agents in spec.agent.
---
apiVersion: datasance.com/v3
kind: OfflineImage
metadata:
name: alpine-offline
spec:
amd64: alpine:3.20
arm64: alpine:3.20
riscv64: alpine:3.20
arm: alpine:3.20
auth:
username: foo
password: bar
agent:
- edge-1
- edge-2
- edge-3
Private registry credentials are optional. When auth is set, both username and password are required.
Architecture IDs
YAML key (spec) | archId | Architecture |
|---|---|---|
amd64 | 1 | 64-bit x86 (linux/amd64) |
arm64 | 2 | 64-bit ARM (linux/arm64) |
riscv64 | 3 | 64-bit RISC-V (linux/riscv64) |
arm | 4 | 32-bit ARM (linux/arm) |
potctl resolves each agent's arch from AgentConfig and transfers the matching spec image. If an agent needs an architecture you did not list, deploy fails with a validation error.
Field reference
| Field | Description |
|---|---|
metadata.name | Unique name for the offline image resource and the catalog item created from it. |
spec.amd64 | Image reference to pull for amd64 agents (for example alpine:3.20 or ghcr.io/datasance/my-app:1.0). |
spec.arm64 | Image reference for arm64 agents. |
spec.riscv64 | Image reference for riscv64 agents. |
spec.arm | Image reference for 32-bit ARM agents. |
spec.auth | Optional registry credentials for private images. |
spec.auth.username | Registry username. |
spec.auth.password | Registry password or token. |
spec.agent | List of remote Agent names (Edgelet nodes) that receive the images. |
At least one architecture image and at least one agent are required. OfflineImage supports remote Agent kinds only (not LocalAgent).
Deployment
potctl deploy -f offline-image.yaml
Command flags
| Flag | Description |
|---|---|
--no-cache | Do not cache pulled images locally after download. |
--transfer-pool int | Maximum concurrent SSH transfers (default: 2). |
# Default: 2 concurrent transfers, caching enabled
potctl deploy -f offline-image.yaml
# Skip local cache after pull
potctl deploy -f offline-image.yaml --no-cache
# Raise concurrent transfer limit
potctl deploy -f offline-image.yaml --transfer-pool 4
How it works
- Pull: potctl pulls the listed images on your machine from the configured registry.
- Transfer: Images are copied to each target Edgelet node over SSH.
- Load: Images are loaded into the node's container engine (Edgelet, Docker, or Podman).
- Catalog: potctl creates or updates a catalog item with registry ID 2 so microservices can reference it by name or ID.
For the full airgap workflow (Control Plane, Edgelet nodes, and microservice images), see Airgap Deployment.
Use cases
- Air-gapped Edgelet nodes: Pre-load images where outbound registry access is blocked.
- Network-restricted sites: Transfer once through a bastion or jump host.
- Offline preparation: Stage images before field deployment.
- Bandwidth limits: Pull once locally, distribute to many nodes.