RDK Resources
[*RDK Preferred*]
Code Management Facility
RDK Forums
[RDK Conferences]
RDK Support
Archives
Papers & Presentations Archive
Table of Contents |
---|
BundleGen is a command-line tool to convert OCI Images into extended OCI Bundles for use with the Dobby container manager.
In OCI, there are two distinct ways of packing applications for containers - Images and Bundles.
At a high-level an OCI implementation would download an OCI Image then convert that image into an OCI Runtime filesystem bundle. At this point the OCI Runtime Bundle would be run by an OCI Runtime.
...
Once built, an OCI Image can then be uploaded to a registry server and discovered by name, downloaded, verified by hash, trusted through a signature, and converted into the runtime bundle ready to run by the runtime.
Once the image is unpacked and converted into a bundle, this bundle can be used to launch a container using an OCI compliant runtime. The bundle consists of two parts:
...
The bundle contains an OCI configuration file (which is named config.json) which can specify host-independent details such as which executable to launch and host-specific settings such as mount locations, hook paths, Linux namespaces and cgroups. Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments.
It is possible to manually create an OCI bundle from scratch by hand-crafting the runtime configuration and copying files into the rootfs. For more information on how to create OCI bundles from scratch, see the following pages:
As part of the DAC project, Consult Red created a standalone tool to accompany Dobby called BundleGen.
...
Obtain the OCI Image using Skopeo (open-source tool by RedHat)
Unpack the OCI image with Umoci (open-source tool by OCI)
Validate App is compatible
Modify the OCI config based on the platform template. This includes but is not limited to:
Environment Variables
Mounts for sockets, libraries
Device whitelisting
User and groups
RDK plugins (networking, loopback mounts, logging)
To create a bundle that is compatible for an application, BundleGen requires a small amount of metadata about the application. This can be thought of as similar to a manifest in Android apps. The app metadata can include information about storage and memory requirements, whether the app needs graphics support and network access such as port forwarding.
The app metadata is a JSON file, an example of which is below:
Code Block | ||
---|---|---|
| ||
{
"id": "com.rdk.wayland-egl-test",
"type": "application/vnd.rdk-app.dac.native",
"version": "1.0.0",
"description": "Simple wayland egl demo, showing green rectangle",
"graphics": true,
"network": {
"type": "open"
},
"storage": {},
"resources": {
"ram": "128M"
},
"features": [],
"mounts": []
} |
The full syntax can be found here: https://github.com/rdkcentral/BundleGen/blob/master/docs/AppMetadata.md
The example images built by the SDK contain metadata files which are the embedded inside the OCI image for BundleGen to use: https://github.com/stagingrdkm/meta-dac-sdk/tree/master/recipes-example/images/metadatas
If using images from the Docker hub or other OCI registry that were not generated by the DAC SDK, then you will need to manually write a metadata file for the app and provide the file to BundleGen in the generate command via the optional --appmetadata argument.
Before you can use BundleGen, you must create an OCI image containing your application using the SDK and upload it to an OCI registry such as the Docker Hub. Once that is complete, follow the below instructions to use BundleGen.
Start To use Bundle Generator, start by launching the Fedora-based VM provided in the BundleGen repo here: https://github.com/rdkcentral/BundleGen/blob/master/Vagrantfile. If you are not sure how to work with Vagrant, see below:
Expand | ||
---|---|---|
| ||
Start by installing Vagrant on your host machine by downloading the relevant version for your OS here: https://www.vagrantup.com/downloads. You must also have VirtualBox installed on your system. Vagrant works with all versions of VirtualBox > 4.0. Download and install the relevant VirtualBox binary from here: https://www.virtualbox.org/wiki/Downloads. To get the virtual machine ready for use, run the following:
When VM is running (after "vagrant up") you can use more than one active session of "vagrant ssh" if needed. In Vagrant there is default mount directory: hosts directory where "Vagrantfile" is stored will be bind-mounted into "/vagrant" inside VM. This can be used to moving files in/out of the VM. So any new file created/moved to Vagrantfile directory should be visible in "/vagrant" and other way around. The files don't always show up instantly. You may need to use "vagrant halt" and "vagrant up" to restart the VM. The files should then be visible in "/vagrant". Known bug: For some reason sometimes in Fedora VM this default bind-mount doesn't work as it should. If that happens and you cannot move files in/out of VM you can use vagrant scp (https://github.com/invernizzi/vagrant-scp) instead. |
Once the VM is running, perform the following steps
Now you can create bundle from images by doinggenerated by the SDK by running the generate commad: bundlegen generate --platform <platform-name> --appmetadata <path-to-app-metadata> <img-url> <output-dir>. Example:
Code Block |
---|
$ bundlegen generate --platform rpi3 docker://my-app ~/outputdirectory |
Note the image URL should be in the form `docker://image-url`. If the image is on the Docker Hub, the full URL can be omitted - e.g `docker://hello-world`.
...