Mirage 4.5.0 released

Community
,
1

On behalf of the Mirage team, I’m happy to announce the release of MirageOS 4.5.0. This was merged in opam-repository last week, so it should be available just in time for the upcoming 14th MirageOS hack retreat!

This release introduces a significant change in the Mirage tool by splitting the definition of command-line arguments used at configure-time and runtime. Command-line arguments used in the configure script (also called ‘configuration keys’ and defined in the Key module) are essential during the setup of module dependencies for the unikernel, allowing for specialized production of a unikernel for a given target runtime environment. On the other hand, command-line arguments that the unikernel can use a runtime (defined in the Runtime_arg module) are helpful for customizing deployments without altering the dependencies of the unikernels.

  • API changes:

    • There is no more ~stage parameter for Key.Arg.info.
    • Key now define command-line arguments for the configuration tool.
    • There is a new module Runtime_arg to define command-line arguments for the unikernel.
    • As there are no more keys type 'Both, users are now expected to create two separated keys in that case (one for configure-time, one for runtime) or decide if the key is useful at runtime of configure-time.

  • Intended use of configuration keys (values of type 'a key):

    • Used to set up module dependencies of the unikernel, such as the target (hvt, xen, etc.) and whether to use DHCP or a fixed IP address.
    • Enable the production of specialized unikernels suitable for specific target runtime environments and dedicated network and storage stacks.
    • Similar keys will produce reproducible binaries to be uploaded to artifact repositories like Docker Hub or https://builds.robur.coop/.

  • Intended use of command-line runtime arguments (values of type a runtime_arg):

    • Allow users to customize deployments by changing device configuration, like IP addresses, secrets, block device names, etc., post downloading of binaries.
    • These keys don’t alter the dependencies of the unikernels.
    • A runtime keys is just a reference to a normal Cmdliner term.

  • key_gen.ml is not generated anymore, so users cannot refer to Key_gen.<key_name> directly.

    • Any runtime argument has to be declared (using runtime_arg and registered on the device (using ~runtime_args). The value of that argument will then be passed as an extra parameter of the connect function of that device.
    • Configuration keys are not available at runtime anymore. For instance, Key_gen.target has been removed.

  • Code migration:

    (* in config.ml *)
let key =
  let doc = Key.Arg.info ~doc:"A Key." ~stage:`Run [ "key" ] in
  Key.(create "key" Arg.(opt_all ~stage:`Run string doc))
let main = main ~keys:[abstract hello] ..

    (* in unikernel.ml *)
let start _ =
  let key = Key_gen.hello () in
  ...

    becomes:

    (* in config.ml *)
let hello = runtime_arg ~pos:__POS__ "Unikernel.hello"
let main = main ~runtime_args:[hello] ...

    (* in unikernel.ml *)
open Cmdliner

let hello =
  let doc = Arg.info ~doc:"How to say hello." [ "hello" ] in
  Arg.(value & opt string "Hello World!" doc)

let start _ hello =
  ...

The mirage-skeleton repository and a few tutorials on https://mirage.io have been updated and now compile with mdx to check for future API breakage. Documentation PRs are very welcome if you find some missing updates. We also welcome more general feedback regarding this API change.

I also would like to use this announcement as a reminder that we have restarted the mirage bi-weekly calls. Check the MirageOS mailing list or the MirageOS Matrix channel for more info. The next one is planned for the 29th of April. If you are using or planning to use MirageOS (or are just curious about the project), feel free to join, it’s open to everyone!

Happy hacking!

11 Likes