Microservices
A microservice is one container, or one WASM module, on one Edgelet node. It has an image, ports, environment, and optional fleet model and knowledge mounts. It belongs to one application.
The YAML field spec.agent.name is the Edgelet node name. The node kind in YAML is Agent.
Field tables, including volume mappings, environment, and extraHosts, are on Microservice fields. potctl unmarshals this kind strictly. Unknown keys fail at deploy.
Where it runs
The container shape follows the target node's containerEngine. See Container engines.
containerEngine | What runs |
|---|---|
edgelet | One container on Edgelet's built-in engine. |
docker or podman | The same microservice as one container on that engine. |
The Controller schedules pull, create, and health checks on that node.
When to use it
Deploy kind: Microservice when the application already exists, or when you want a separate document from kind: Application. Put the service inline under spec.microservices when one application file should carry the whole group. See Applications.
Use spec.template when the container shape comes from a microservice template.
User deploy cannot create system microservices. Updates to those use the system microservice API. See Logs and exec.
Name
| Source | Result |
|---|---|
metadata.name: api and spec.application: myapp | myapp/api |
metadata.name: myapp/api | Application myapp, microservice api |
describe, logs, exec, and delete use application/microservice.
What deploy -f does
potctl deploy -f microservice.yaml -n my-ecn
deploy without patch flags calls the full microservice deploy. The Controller creates the service or updates it when that name already exists in the application. It decides whether the container is rebuilt. Set spec.rebuild: true when you need a rebuild on that deploy.
| Mode | CLI | Requirement |
|---|---|---|
| Full deploy | deploy -f | Normal create or update. |
| Models only | --patch-model | Microservice-only file, and spec.models is required. |
| Knowledge only | --patch-knowledge | Microservice-only file, and spec.knowledge is required. |
| Both flags | both on one command | Models are patched first, then knowledge. |
Patch flags fail when the file contains any kind other than Microservice.
Before the first deploy:
- The application exists, or it is earlier in the same file.
- The Edgelet node exists, and its architecture matches the images.
- Registry, catalog item, model, and knowledge objects already exist when the microservice names them.
Update, move, and rename
Re-deploy the same file to change the image, container, node, or template. Export first when you are editing a live service:
potctl describe microservice myapp/api -o msvc.yaml -n my-ecn
Describe output includes read-only status. Remove status, uuid, and created before you deploy that file again.
potctl rebuild microservice myapp/api -n my-ecn
potctl start microservice myapp/api -n my-ecn
potctl stop microservice myapp/api -n my-ecn
potctl delete microservice myapp/api -n my-ecn
Move a microservice to another Edgelet node in the same namespace:
potctl move microservice api edge-02 -n my-ecn
The rename subcommand is gone. To change the application/microservice name, export the YAML, deploy it under the new name, then delete the old microservice.
A model-only patch file:
apiVersion: datasance.com/v3
kind: Microservice
metadata:
name: inference
namespace: my-ecn
spec:
application: myapp
agent:
name: edge-01
models:
bindPath: /models
permissions: ro
items:
- name: smollm2-135m
- name: org-llm
potctl deploy -f patch-models.yaml --patch-model -n my-ecn
Catalog item changes may or may not rebuild the container. The Controller decides.
Node limits, the engine URL, and NATS leaf settings belong on Agent or AgentConfig. On a microservice, agent is the name only.
Bridge DNS
Two microservices on the same Edgelet node can reach each other by name when they use the bridge (container.hostNetworkMode: false). Host-network containers do not get these names.
The default zone is svc.bridge.local.
For application myapp and microservice worker:
| Form | Name |
|---|---|
| Short name on the bridge | myapp.worker |
| FQDN | myapp.worker.svc.bridge.local |
Reserved names on that same bridge are router.default.svc.bridge.local, nats.default.svc.bridge.local, and edgelet.default.svc.bridge.local.
The engine, the resolver, Docker and Podman aliases, and extraHosts are documented on DNS.
Models, knowledge, and runtime classes
spec.models and spec.knowledge bind fleet catalog rows into the container. container.runtime selects a runtime handler. The field shapes are on Microservice fields. Catalog rows are AI Model Catalog, AI Knowledge Catalog, and Runtime classes.
spec.models and spec.knowledge
Each item names a catalog row. bindPath is the mount inside the container. permissions is ro or rw.
Container models and knowledge
container.runtime is the handler name from a runtime class attached to the Edgelet node. container.platform is the OCI platform, such as wasi/wasm.
Attach the blobs to the Edgelet node before the microservice expects them:
potctl attach model MODEL_NAME AGENT_NAME -n my-ecn
potctl attach knowledge KNOWLEDGE_NAME AGENT_NAME -n my-ecn
potctl attach runtimeclass RUNTIME_CLASS AGENT_NAME -n my-ecn
Confirm modelStatus, activeModels, knowledgeStatus, activeKnowledge, and runtime class status with describe agent.
Examples
Minimal service
Application myapp must already exist, or sit above this document in the same file. Edgelet node edge-01 must already be registered.
apiVersion: datasance.com/v3
kind: Microservice
metadata:
name: api
namespace: my-ecn
spec:
application: myapp
agent:
name: edge-01
images:
registry: remote
amd64: ghcr.io/datasance/example/api:1.0.0
arm64: ghcr.io/datasance/example/api:1.0.0
container:
ports:
- internal: 8080
external: 8080
protocol: tcp
config: {}
natsConfig:
natsAccess: false
Template, model, and runtime
The template inference-ms is on Microservice templates. The model smollm2-135m is a fleet catalog row attached to edge-01. container.runtime: spin needs that handler on the node.
apiVersion: datasance.com/v3
kind: Microservice
metadata:
name: inference
namespace: my-ecn
spec:
application: myapp
template:
name: inference-ms
variables:
- key: agent-name
value: edge-01
- key: model1
value: smollm2-135m
agent:
name: edge-01
models:
bindPath: /models
permissions: ro
items:
- name: smollm2-135m
images:
registry: remote
amd64: ghcr.io/datasance/inference:1.0.0
container:
runtime: spin
platform: wasi/wasm
ports:
- internal: 8080
external: 8080
protocol: tcp
Console
Running microservices are in EdgeOps Console → Workloads. Logs and shells are on Logs and exec. Node daemon logs stay on Node logs and exec.