Deploy manifest reference

Edgelet accepts edgelet.iofog.org/v1 YAML manifests via:

edgelet deploy -f manifest.yaml
edgelet deploy -f manifest.yaml --timeout=20m   # ControlPlane async apply

Validation runs in the daemon before apply. Shapes are defined in the Edgelet source models and surfaced through EdgeletAPI /v1/deploy/*.

Example files: download from /edgelet/examples/ (also under docs/edgelet/examples/ in the docs repo).

Kind	Example	Guide section
Microservice	microservice.yaml	Microservice
Registry	registry.yaml	Registry
RuntimeClass	runtimeclass.yaml, runtimeclass-edgelet-wasmtime.yaml	RuntimeClass
ControlPlane	controlplane.yaml	ControlPlane

---

Common fields

Field	Value
apiVersion	edgelet.iofog.org/v1 (required)
kind	Microservice, Registry, RuntimeClass, or ControlPlane

Legacy apiVersion: v3 and Java-era kinds are rejected.

---

Microservice

Local or operator-managed workload deployed through Edgelet (not Controller snapshot sync).

Annotated reference: microservice.yaml lists every YAML key with inline comments.

Schema vs implemented

Field	Status
metadata.namespace	Parsed; not used — runtime application is always edgelet
spec.config	Parsed; not applied
spec.container.annotations	Parsed; not applied
spec.container.healthCheck	Parsed; not wired in local deploy
All other fields in the example	Applied via local manifest build

Top-level shape

apiVersion: edgelet.iofog.org/v1
kind: Microservice
metadata:
  name: <dns-label>           # required
  namespace: edgelet          # optional; use edgelet for local deploy scope
  labels: {}                  # optional user labels (protected keys stripped)
spec:
  image: <image-ref>          # required
  registry: <id>                # optional registry row ID
  container: { ... }          # see below
  schedule: <int>             # optional ordering hint
  config: {}                    # optional opaque config map

spec.container (common fields)

Field	Type	Notes
hostNetworkMode	bool	Host network — disables bridge DNS
isPrivileged	bool	Privileged container
runAsUser	string	User ID or name
runtime	string	OCI runtime name (embed engine + RuntimeClass)
platform	string	Platform selector when pulling
ipcMode, pidMode	string	Passed to engine
capAdd, capDrop	[]string	Linux capabilities
env	{key,value}[]	User env (EDGELET_* reserved)
extraHosts	{name,address}[] or legacy strings	/etc/hosts + docker ExtraHosts
ports	{internal,external,protocol}[]	Port mappings
volumes	{hostDestination,containerDestination,accessMode,type}[]	BIND, VOLUME, or controller VOLUME_MOUNT. Delete does not remove VOLUME data on the embedded engine — see Volumes.
commands	[]string	Container command override
cpuSetCpus	string	cpuset
memoryLimit	int64	Memory limit bytes
healthCheck	object	Healthcheck spec

Apply

edgelet deploy -f examples/microservice.yaml
edgelet ms ls --source local

See DNS & discovery and Container engines.

---

Registry

Credentials for image pulls stored in local SQLite.

apiVersion: edgelet.iofog.org/v1
kind: Registry
spec:
  url: <registry-host>        # required
  private: true|false         # required
  username: <string>          # required when private=true
  password: <string>          # required when private=true
  email: <string>             # optional

Apply

edgelet deploy -f examples/registry.yaml
edgelet registry ls

Registry apply is synchronous. Secrets are stored locally. Treat YAML as sensitive.

---

RuntimeClass

Maps a handler name to OCI runtime configuration on containerEngine: edgelet (linux embed only).

Naming

containerEngine: edgelet is the embedded engine product. Wasm workload runtimes use distinct handler keys. For example edgelet-wasmtime (Datasance shim) vs upstream wasmtime. See runtimeclass-edgelet-wasmtime.yaml and Wasm runtime.

apiVersion: edgelet.iofog.org/v1
kind: RuntimeClass
metadata:
  name: <dns-label>           # required; lowercase DNS label (e.g. edgelet-wasmtime)
handler: <handler>              # required; catalog handler (e.g. edgelet-wasmtime, spin)

Reserved name: crun (built-in default).

Apply

edgelet deploy -f examples/runtimeclass.yaml
edgelet runtimeclass ls

Reference microservice spec.container.runtime to the RuntimeClass name. See Container engines.

---

ControlPlane

Deploys one Controller container per Edgelet node (optional — remote controllerUrl is valid without local ControlPlane).

Annotated reference: controlplane.yaml lists every YAML key (active + commented optional blocks).

Required fields

Field	Notes
spec.controller.image	Controller container image
spec.auth.mode	embedded or external
spec.auth.bootstrap	Required when mode: embedded (username, password with complexity rules)
spec.auth.issuerUrl + spec.auth.client	Required when mode: external

Forbidden fields

Field	Reason
metadata.labels	Rejected at validate
spec.siteCA, spec.localCA	Import via Controller REST after deploy

apiVersion: edgelet.iofog.org/v1
kind: ControlPlane
metadata:
  name: <ms-name>             # required; DNS-1123 label
  namespace: <namespace>      # optional; default applied if empty
spec:
  controller:
    image: <image>            # required
    registry: <id>              # optional
    port: 51121               # optional API port
    publicUrl: <url>          # recommended — CONTROLLER_PUBLIC_URL
    trustProxy: true|false    # optional
  console:
    port: 8008                # optional — host port 80 maps here
    url: <url>                # optional — CONSOLE_URL
  auth:                         # required
    mode: embedded|external
    insecureAllowHttp: false
    insecureAllowBootstrapLog: false
    bootstrap:                  # required when mode=embedded
      username: admin
      password: "<secret>"      # ≥12 chars, 1 uppercase, 1 special
    issuerUrl: <url>            # required when mode=external
    client:                     # required when mode=external
      id: <id>
      secret: <secret>
    consoleClient: ecn-viewer
    consoleClientEnabled: false
    rateLimit: { enabled, maxRequestsPerWindow, windowMs }
    sessionStore: { type, ttlMs, secret }
    tokenTtl: { accessTokenTtlSeconds, refreshTokenTtlSeconds }
    oidcTtl: { interactionTtlSeconds, grantTtlSeconds, sessionTtlSeconds, idTokenTtlSeconds }
  systemMicroservices:        # optional router/nats image maps per arch
    router: { amd64: "...", arm64: "..." }
    nats: { ... }
  nats:
    enabled: true|false
  # events, database, tls, vault, logLevel — see Control Plane guide

Rules

• metadata.labels forbidden on ControlPlane manifests.
• spec.siteCA / spec.localCA forbidden — import CAs via Controller REST after deploy.
• At most one ControlPlane row per node; delete via edgelet controlplane delete.

Apply (async)

edgelet deploy -f examples/controlplane.yaml
edgelet controlplane get

Default poll budget 15 minutes. See Control plane on node.

DNS identity

FQDNs derive from metadata.namespace + metadata.name. See DNS & discovery.

---

CLI quick reference

Action	Command
Apply manifest	edgelet deploy -f <file>
List local MS	edgelet ms ls --source local
List registries	edgelet registry ls
List runtime classes	edgelet runtimeclass ls
Control plane status	edgelet controlplane get
Validate only	EdgeletAPI POST /v1/deploy/microservices:validate

---

See also

• Installation — install and provisioning
• Deployment — production topology
• Control plane on node — operator guide
• EdgeletAPI v1 — HTTP contract

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!