ECO Initialization
This document describes the ECO initialization process, specifically how an ECO goes from "configured in the controller" to "launched and running". This includes:
- configuration creation
- image download and verification
- network creation and initialization
- ECO launch
For a deeper understanding off ECOs, please read ECOS.md.
Process
The high-level process for preparing an ECO follows this flow. In each section, the responsible component is placed in brackets. All communication between components, i.e. configs and statuses, are performed using publish-subscribe via pubsub.
- Create App: An ECO is configured on a valid controller, e.g. zedcloud
- Receive Device Config (zedagent): EVE device receives and processes an updated device config message which contains the new ECO app
- Create Local App Config (zedagent): parse the app config in the device config message to create and publish an AppInstanceConfig for the ECO
- Consolidate ECO management (zedmanager): Retrieve and parse the AppInstanceConfig, and launch the ECO using the following steps.
- Retrieve and verify image
- Prepare ECO networking
- Launch ECO
zedmanager
itself does not do any of the downloading, preparation or launching. It only orchestrates
tasks between other microservices that do the actual work. Orchestration is via messages on the pubsub
.
zedmanager
's main function for launching or updating ECOs is
doUpdate().
This calls one separate function for each of the three major steps in launching an ECO.
It is important to recall that all inter-process communication, including between zedmanager
and the microservices responsible for downloading and verifying images, preparing networking,
and activating an ECO, are performed asynchronously via pubsub. Thus, the
actual progression from "request action X" to "action X complete" is not synchronous.
Rather, one function will publish the request for action X, while a separate handler
will react to the status update that action X is complete and start the next stage.
Image Download
zedmanager#doInstall() coordinates the downloading and verifying of the image. It first downloads, then verifies the image.
- Download the image
- zedmanager: for each image in the AppInstanceConfig, create and publish a DownloaderConfig
- downloader: see the DownloaderConfig
- downloader: create and publish a DownloaderStatus marked
PendingAdd
- downloader: create space and download the image. This contains the logic to handle different download types in handleSyncOp()
- downloader: update and publish the DownloaderStatus as complete
- zedmanager: retrieve the DownloaderStatus, download is complete
- Verify the image
- zedmanager: for each image successfully downloaded, create and publish a VerifyImageConfig
- verifier: see the VerifyImageConfig
- verifier: create and publish a VerifyImageStatus marked
PendingAdd
- verifier: verify the image referenced in the verifier config
- verifier: update and publish the VerifyImageStatus as complete
- zedmanager: retrieve the VerifyImageStatus, verification is complete
Image verification is validation of each component's actual sha256 hash matches that which was provided by the controller.
Prepare Networking
zedmanager#doPrepare() coordinates the preparation of networking. It first sets up LISP EIDs, if needed, then creates any networking.
- Set up LISP
- zedmanager: create and publish an EIDConfig
- identitymanager: see the EIDConfig
- identitymanager: if needed, create the LISP EIDs and register them
- identitymanager: create and publish an EIDStatus marking as complete
- zedmanager: retrieve the EIDStatus, LISP EID stage complete
- Set up networking
- zedmanager: create and publish an AppNetworkConfig
- zedrouter: see the AppNetworkConfig
- zedrouter: set up network connectivity
- zedrouter: create and publish an AppNetworkStatus marking as complete
- zedmanager: retrieve AppNetworkStatus, ECO networking preparation is complete
Activate ECO
zedmanager#doActivate() coordinates activating the ECO.
- Activate ECO
- zedmanager: create and publish a DomainConfig
- domainmanager: see the DomainConfig
- domainmanager: start the domain
- domainmanager: create and publish a DomainStatus
- zedmanager: see the DomainStatus, ECO launch is complete
A diagram describing this flow is below:
[TO BE FILLED IN]
The list of subscriptions relevant to ECO initialization is as follows.
Publisher | Topic | Subscribers |
---|---|---|
zedagent |
AppInstanceConfig |
zedmanager |
zedmanager |
DownloaderConfig |
downloader |
VerifyImageConfig |
verifier |
|
EIDConfig |
identitymanager |
|
AppNetworkConfig |
zedrouter |
|
DomainConfig |
domainmgr |
|
AppInstanceStatus |
multiple | |
downloader |
DownloaderStatus |
zedmanager |
verifier |
VerifyImageStatus |
zedmanager |
identitymanager |
EIDStatus |
zedmanager |
zedrouter |
AppNetworkStatus |
zedmanager |
domainmgr |
DomainStatus |
zedmanager |
Image Download Architecture and Protocols
"Downloading images" means the following:
- Reserve space on the device's disk for artifacts
- Retrieve artifacts from remote locations
- Place the artifacts in the reserved space
Artifacts may be one or more of:
- Disk images
- Kernel
- initrd
- OCI (container) images
- Configuration information (metadata / manifests)
zedmanager
, when requesting download of artifacts, is mostly ignorant of the artifact types,
or even if they are images for VMs or OCI containers. It simply passes the download information
to downloader
, which, in turn, retrieves the bits and places them on disk.
downloader
itself supports multiple protocols, aware of the source only in one loop, which
is responsible for parsing the image source and retrieving it using the appropriate protocol.
This loop is in handleSyncOp()),
specifically the switch TransportMethod
statement here.
Once the transport-specific logic is complete, the artifact is in the target location, and common processes continue.
Adding New Download Protocols
To add a new download protocol:
- Create a
func
in downloader that knows how to download, given the credentials and information necessary. This method should accept, as a parameter, the local path where it should deposit the artifact, and return anerror
. - Add an entry for the type to the various
DsType*
constants and variables in the api protobufs under storage.proto and regenerate all of the API language imports. - Add a
case
statement for your new download protocol to the switch dsCtx.TransportMethod.