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.

  1. Create App: An ECO is configured on a valid controller, e.g. zedcloud
  2. Receive Device Config (zedagent): EVE device receives and processes an updated device config message which contains the new ECO app
  3. Create Local App Config (zedagent): parse the app config in the device config message to create and publish an AppInstanceConfig for the ECO
  4. Consolidate ECO management (zedmanager): Retrieve and parse the AppInstanceConfig, and launch the ECO using the following steps.
  5. Retrieve and verify image
  6. Prepare ECO networking
  7. 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.

  1. Download the image
  2. zedmanager: for each image in the AppInstanceConfig, create and publish a DownloaderConfig
  3. downloader: see the DownloaderConfig
  4. downloader: create and publish a DownloaderStatus marked PendingAdd
  5. downloader: create space and download the image. This contains the logic to handle different download types in handleSyncOp()
  6. downloader: update and publish the DownloaderStatus as complete
  7. zedmanager: retrieve the DownloaderStatus, download is complete
  8. Verify the image
  9. zedmanager: for each image successfully downloaded, create and publish a VerifyImageConfig
  10. verifier: see the VerifyImageConfig
  11. verifier: create and publish a VerifyImageStatus marked PendingAdd
  12. verifier: verify the image referenced in the verifier config
  13. verifier: update and publish the VerifyImageStatus as complete
  14. 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.

  1. Set up LISP
  2. zedmanager: create and publish an EIDConfig
  3. identitymanager: see the EIDConfig
  4. identitymanager: if needed, create the LISP EIDs and register them
  5. identitymanager: create and publish an EIDStatus marking as complete
  6. zedmanager: retrieve the EIDStatus, LISP EID stage complete
  7. Set up networking
  8. zedmanager: create and publish an AppNetworkConfig
  9. zedrouter: see the AppNetworkConfig
  10. zedrouter: set up network connectivity
  11. zedrouter: create and publish an AppNetworkStatus marking as complete
  12. zedmanager: retrieve AppNetworkStatus, ECO networking preparation is complete

Activate ECO

zedmanager#doActivate() coordinates activating the ECO.

  1. Activate ECO
  2. zedmanager: create and publish a DomainConfig
  3. domainmanager: see the DomainConfig
  4. domainmanager: start the domain
  5. domainmanager: create and publish a DomainStatus
  6. 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:

  1. Reserve space on the device's disk for artifacts
  2. Retrieve artifacts from remote locations
  3. 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:

  1. 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 an error.
  2. 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.
  3. Add a case statement for your new download protocol to the switch dsCtx.TransportMethod.