From patchwork Mon Feb 15 03:39:18 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Silvano Cirujano Cuesta X-Patchwork-Id: 331 Return-Path: Delivered-To: ilbers.mnt@gmail.com Received: by 2002:a4a:c583:0:0:0:0:0 with SMTP id x3csp5398315oop; Mon, 15 Feb 2021 05:44:32 -0800 (PST) X-Received: by 2002:adf:a298:: with SMTP id s24mr18806660wra.367.1613396672078; Mon, 15 Feb 2021 05:44:32 -0800 (PST) ARC-Seal: i=3; a=rsa-sha256; t=1613396672; cv=pass; d=google.com; s=arc-20160816; b=vpfy9me36+e5aAUPVFoeUcEPk4PetOZxxBBn73I/+3ZJpO/LiZrjsNhi8G2xS5oFGd kfEd4PmszeHqBetOoQrGLqSI0wa8fxCKeqTJurU8j+ooW89P9K2YpIbgfwM+Gf0YIz6g cYfwS+6+cCpEpdiCm+iVIUlusNjdo0AwYjtdRCJUI35ZO+j1qELp7Q2Dzk7ZstfcLz3K u8lK1fmTh/0Lru7V1VKpQs9lNB3w7bJiI061mdYpKM+6Ugpib7IciRZPTJvHSp596Fcu RJThkJo+W8x8iAZgAwJipWtIV2aAHyjCv+5g32o3umTuPMKi0bEZSsGCJIxtS4YTZTB8 k0VA== ARC-Message-Signature: i=3; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :sender:dkim-signature; bh=trK5r1fNfEJ4KhGGCnPh+iQR8gtH7fLju6sKMjMUof8=; b=wUbicihu49pqnUNkbrZc01hZtnPmpUy0HRWu4QObNSB7HJDbgxKjaPGBOgEsMZMi/7 ivPEVfzljQrrQjvN6K+Ir7LFtmRr1afIQek7I0X9ccCpTHYB6YZ+z7f5pueizN3vjGxA J2GoB270TNltIyx62P8orHayhjU8cv6wJWFOUOt+j/Z2CWroJDDpQxJdkm/j8VYbO9qT bFXI12W85OtSs7Lx2KRJHy4XAp2MqgRnNaUHNCako1Oxx6aSl5f/7TTn3h0YUCNDHnZc sQW8GrtkE+raf38xP0R978E4jrkHLUqsp2B9eClxwUaIEwSjSQc/nRqNwzwexSNa3Rll ZZSA== ARC-Authentication-Results: i=3; mx.google.com; dkim=pass header.i=@googlegroups.com header.s=20161025 header.b=k3l02cKe; arc=pass (i=2 spf=pass spfdomain=siemens.com dmarc=pass fromdomain=siemens.com); spf=pass (google.com: domain of isar-users+bncbcd6jj6cqqfrbp7vvgaqmgqelxcakva@googlegroups.com designates 209.85.220.55 as permitted sender) smtp.mailfrom=isar-users+bncBCD6JJ6CQQFRBP7VVGAQMGQELXCAKVA@googlegroups.com; dmarc=fail (p=NONE sp=NONE dis=NONE arc=pass) header.from=siemens.com Received: from mail-sor-f55.google.com (mail-sor-f55.google.com. [209.85.220.55]) by mx.google.com with SMTPS id 15sor8353735wmk.9.2021.02.15.05.44.31 (Google Transport Security); Mon, 15 Feb 2021 05:44:32 -0800 (PST) Received-SPF: pass (google.com: domain of isar-users+bncbcd6jj6cqqfrbp7vvgaqmgqelxcakva@googlegroups.com designates 209.85.220.55 as permitted sender) client-ip=209.85.220.55; Authentication-Results: mx.google.com; dkim=pass header.i=@googlegroups.com header.s=20161025 header.b=k3l02cKe; arc=pass (i=2 spf=pass spfdomain=siemens.com dmarc=pass fromdomain=siemens.com); spf=pass (google.com: domain of isar-users+bncbcd6jj6cqqfrbp7vvgaqmgqelxcakva@googlegroups.com designates 209.85.220.55 as permitted sender) smtp.mailfrom=isar-users+bncBCD6JJ6CQQFRBP7VVGAQMGQELXCAKVA@googlegroups.com; dmarc=fail (p=NONE sp=NONE dis=NONE arc=pass) header.from=siemens.com ARC-Seal: i=2; a=rsa-sha256; t=1613396671; cv=pass; d=google.com; s=arc-20160816; b=vT4smuvGRKpzwObrty/f6NRlAs7OYqFF8Z6sUKmQE5SclxRgemW5NHBhIZGgS+Sv5o /7cqguLw2Qs9X3n22K3igiUdVXoE0V4Ct4eqKzR3q3kbxaNONKe4rilYY6rzX8rI/jPx 4BYsqH4ykqyWkR5gXJfCtm/jKGceEyBei9SgJJm5mux2jXNra/cJ2kIMfy80zgpXIlAa ScGdhn2nWiDKvRkKAmYoz6cSz+6tL6LeR12mDkwbLMs49GMa7CnRkqkHZCUIx7t1woBw l36XFG+ydEMSMKvRCNpqGThoE0u0wHQbVxXDW2eHYetEtlb+0ha/kvDLK42n05ZbsrHi 8yLQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :sender:dkim-signature; bh=trK5r1fNfEJ4KhGGCnPh+iQR8gtH7fLju6sKMjMUof8=; b=UoA78HUNCGucPOoZYAWy8uI8MkxpB2V6TlBFhXY6Ad1Znqje1c4bj8t40HMVsPH+27 jKxpNC0aXPSyuWiMoq3WQrr4QpwYisOQQOhYmaWj9Au97PES1ftE2X8MZYJlSGG/pMHc QI8TH1KuiZLRRbEq4xxw9BHW3PVJlh0Ct5ltURBJZPuZLXbuh7BnCVCqok9f7DXj+iNk xERFVbquBRC+ElZ4sjRPGt71Lt9YnwkNxZpV4IFLMacG02L9QyL9SrPB0zWthiYfQTiD kUmm1QfzMYXH/G/2Z1/ekleFvVhIC3IauPsA4gsbjsIygXtZrGFfWmKegWkZkM5SViHb 5yyg== ARC-Authentication-Results: i=2; gmr-mx.google.com; spf=pass (google.com: domain of silvano.cirujano-cuesta@siemens.com designates 194.138.37.39 as permitted sender) smtp.mailfrom=silvano.cirujano-cuesta@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:from:to:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-subscribe:list-unsubscribe; bh=trK5r1fNfEJ4KhGGCnPh+iQR8gtH7fLju6sKMjMUof8=; b=k3l02cKe9Q9s//ofPp8MMlV5KItN+h0ctXwda5VT43n2njO7jjnrGXnFR5nvfJEUhm yu9vDo2qIkBmXZ9GUB3Vujm5WrgANWMy7i1kmO3dy5giQw3d8oQVWGLn4agHu6PjOUMl q7tNVvjAGI4na98onKl2vsJN0q54DQLXJfp5Ss9sBE48Y2G3Oq1HIKBwPdRAMiIGx5ng s97B9KAw707pXs246Z3S6KFLYT6XuSO2vMJ6cXeuWoT6EYb2W0ZFZVwBd7b0uZR5a/GN JHgpVAije0vig53QUD3qxci6bAV9r4JfJgBcTGILHsosRV0veicsEZEra4HMW2Q2HMai DyxQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:from:to:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding :x-original-sender:x-original-authentication-results:precedence :mailing-list:list-id:x-spam-checked-in-group:list-post:list-help :list-archive:list-subscribe:list-unsubscribe; bh=trK5r1fNfEJ4KhGGCnPh+iQR8gtH7fLju6sKMjMUof8=; b=gmfOJfg+ITP0JYAPBusNISQDRTuVydw4EOkmJW2fcBgS4eNCurf7v7SO2/oKYKSlG3 2+M8kcO3h4vvymVK0kCbjmI+k1HuSGL1fqSZ7ZDTa6L6vu8mw8cCddneQIKo1hiZg1je yQhRdXQFPyTyFbw7aOEAkIPvtJrI9N9xGSGLJr4Uvu7wbS8a51/ZxRWeXYK+HO8liBfu FKZhrlnCawblg7E23UnuS6Z2FFuFf86MD8HbfFc0HTCVSa3TJVW9rIOXqjlT64LpfHko Er3yaNWl2ZNhiYDw7fwrUl97rPUv0T/NVf2zJ+JCWq3PhvRzxnUE5V8x36eifXwodMjd bwlw== Sender: isar-users@googlegroups.com X-Gm-Message-State: AOAM532/nouX9OlQTjf79NnlGB+BJB972Bp11kUIed+iYxDVwzrtqrgj Bhs4PaRmMtIao5RD5es4S0w= X-Google-Smtp-Source: ABdhPJzZxajnD1oUOWQobBEaz2jM7if0qtERRE1YHISGP/s8ewODDjHVlgn+zRlGM9GHYT37r9m9xA== X-Received: by 2002:a7b:c411:: with SMTP id k17mr6421414wmi.185.1613396671832; Mon, 15 Feb 2021 05:44:31 -0800 (PST) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a1c:2e44:: with SMTP id u65ls512252wmu.2.canary-gmail; Mon, 15 Feb 2021 05:44:31 -0800 (PST) X-Received: by 2002:a1c:5a54:: with SMTP id o81mr14640725wmb.50.1613396665611; Mon, 15 Feb 2021 05:44:25 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1613396660; cv=none; d=google.com; s=arc-20160816; b=0q1JRXinZBL5j6MlpH3YBDNCAznwznfzvfkjlkighFdchiCvvu00rakXRarRSS5eVG X5vaSdW2nTcICRzKrIg0EPEbHaAkYqEqVB54B2QSZqHvdDnoSdCcLK9TwQxpTG65OJrR rMo1X+ixgUJIzqjbeOFjiCVZSacZ8hVJgg4zzEABsQpdUFPjJ0z8ZoOaBIGGWPUudL8k fu2CRkZaeC2o2YnKzkz24bUDEdknLSwt/uVmqUIuE1btA2b/zxVqxzJD+Cj6HaVzOwjg hvwcXsz2m4ke6iT8cr1cZS8A+taOWrWfmbITYWkNcwfA9blIVPihmD8s2wJfcWY0RVqj FeiA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from; bh=SxYQRnfWtdcCt2TK6gpVSxJ0DaKTtc6xbX4unwjm3vY=; b=xSqT+XX0iUPEfVWze81LD1gwveEvC3z9DeRp2yooInGdZGNLMhlleGX0rNUYsQ91ft /tltnjsJIrmUMBB3r8VsS9gmx93JN+oWeRaS7K4EOruj/JYu2WxxQdhUKcNgzsm1Q5Xo ZVEziFecu+66WbjcyS/UZb1MtLiZ4L7v95YOQrp5J5EAP5w8b/MSTL3mINEnHaVQ4ePm IESc8DpAEuljX4rAHzv+puZjcUwRKRYWIhPzxjha8aWFEeKEXvOEbPV3oYtNp6PUCvOt K4/3iALd/ubAf6XKPlSehZVygFshOvxImKsg2XlhE1NdhKOOJkAkPt/WQdeMPHOrgaLj dMpQ== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: domain of silvano.cirujano-cuesta@siemens.com designates 194.138.37.39 as permitted sender) smtp.mailfrom=silvano.cirujano-cuesta@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com Received: from lizzard.sbs.de (lizzard.sbs.de. [194.138.37.39]) by gmr-mx.google.com with ESMTPS id v16si1011002wmh.1.2021.02.15.05.44.20 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 15 Feb 2021 05:44:20 -0800 (PST) Received-SPF: pass (google.com: domain of silvano.cirujano-cuesta@siemens.com designates 194.138.37.39 as permitted sender) client-ip=194.138.37.39; Received: from mail2.sbs.de (mail2.sbs.de [192.129.41.66]) by lizzard.sbs.de (8.15.2/8.15.2) with ESMTPS id 11FDiJaV017927 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 15 Feb 2021 14:44:19 +0100 Received: from md1sf36c.ad001.siemens.net ([139.22.119.30]) by mail2.sbs.de (8.15.2/8.15.2) with ESMTP id 11FDdIHH008716 for ; Mon, 15 Feb 2021 14:39:19 +0100 From: Silvano Cirujano Cuesta To: isar-users@googlegroups.com Subject: [PATCH v5 4/4] docs: document creation of container images Date: Mon, 15 Feb 2021 14:39:18 +0100 Message-Id: <20210215133918.50988-5-silvano.cirujano-cuesta@siemens.com> X-Mailer: git-send-email 2.30.0 In-Reply-To: <20210215133918.50988-1-silvano.cirujano-cuesta@siemens.com> References: <20210215133918.50988-1-silvano.cirujano-cuesta@siemens.com> MIME-Version: 1.0 X-Original-Sender: silvano.cirujano-cuesta@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; spf=pass (google.com: domain of silvano.cirujano-cuesta@siemens.com designates 194.138.37.39 as permitted sender) smtp.mailfrom=silvano.cirujano-cuesta@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com Precedence: list Mailing-list: list isar-users@googlegroups.com; contact isar-users+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: isar-users@googlegroups.com X-Google-Group-Id: 914930254986 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: =?utf-8?q?1691769028928539525?= X-GMAIL-MSGID: =?utf-8?q?1691769028928539525?= Signed-off-by: Silvano Cirujano Cuesta --- doc/user_manual.md | 127 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/doc/user_manual.md b/doc/user_manual.md index a4f3d1d..f6f49bc 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -19,6 +19,7 @@ Copyright (C) 2016-2019, ilbers GmbH - [Add a Custom Application](#add-a-custom-application) - [Enabling Cross-compilation](#isar-cross-compilation) - [Create an ISAR SDK root filesystem](#create-an-isar-sdk-root-filesystem) + - [Create a containerized ISAR SDK root filesystem](#create-a-containerized-isar-sdk-root-filesystem) - [Creation of local apt repo caching upstream Debian packages](#creation-of-local-apt-repo-caching-upstream-debian-packages) @@ -84,6 +85,9 @@ If your host is >= buster, also install the following package. apt install python3-distutils ``` +If you want to generate containerized SDKs, also install the following packages: `umoci` and `skopeo`. +Umoci is provided by Debian Buster and can be installed with `apt install umoci`, Skopeo is provided by Debian Bullseye/Unstable and has to be installed either manually downloading the DEB and installing it (no other packages required) or with `apt install -t bullseye skopeo` (if unstable/bullseye included in `/etc/apt/sources.list[.d]`). + Notes: * BitBake requires Python 3.4+. @@ -223,6 +227,54 @@ qemu-system-x86_64 -m 256M -nographic -bios edk2/Build/OvmfX64/RELEASE_*/FV/OVMF qemu-system-i386 -m 256M -nographic -hda tmp/deploy/images/qemui386/isar-image-base-debian-buster-qemui386.wic.img ``` +### Generate container image with root-filesystem + +A runnable container image is generated if you set IMAGE_TYPE to 'container-img'. +Getting a container image can be the main purpose of an ISAR configuration, but not only. +A container image created from an ISAR configuration meant for bare-metal or virtual machines can be helpfull to test certain applications which requirements (e.g. libraries) can be easily resolved in a containerized environment. + +Container images can be generated in different formats, selected with the variable `CONTAINER_FORMAT`. One or more (whitespace separated) of following options can be given: + - `docker-archive`: (default) an archive containing a Docker image that can be imported with [`docker import`](https://docs.docker.com/engine/reference/commandline/import/) + - `docker-daemon`: resulting container image is made available on the local Docker Daemon + - `containers-storage`: resulting container image is made available to tools using containers/storage back-end (e.g. Podman, CRIO, buildah,...) + - `oci-archive`: an archive containing an OCI image, mostly for archiving as seed for any of the above formats + +Following formats don't work if running `bitbake ...` (to build the image) from inside of a container (e.g. using `kas-container`): `docker-daemon` and `containers-storage`. +It's technically possible, but requires making host resources (e.g. the Docker Daemon socket) accessible in the container. +What can endanger the stability and security of the host. + +The resulting container image archives (only for `docker-archive` and `oci-archive`) are made available as `tmp/deploy/images/${MACHINE}/${DISTRO}-${DISTRO_ARCH}-${container_format}.tar.xz` (being `container_format` each one of the formats specified in `CONTAINER_FORMAT`). + +### Example + + - Make the relevant environment variables available to the task + +For one-shot builds (use `local.conf` otherwise): + +``` +export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE IMAGE_TYPE CONTAINER_FORMAT" +export IMAGE_TYPE="container-img" +export CONTAINER_FORMAT="docker-archive" +``` + + - Trigger creation of container image from root filesystem + +``` +bitbake mc:qemuarm-buster:isar-image-base +``` + + - Load the container image into the Docker Daemon + +``` +xzcat build/tmp/deploy/images/qemuarm/debian-buster-armhf-docker-archive.tar.xz | docker load +``` + + - Run a container using the container image (following commands starting with `#~:` are to be run in the container) + +``` +docker run --rm -ti --volume "$(pwd):/build" isar-buster-armhf:latest +``` + --- ## Terms and Definitions @@ -834,6 +886,81 @@ ii crossbuild-essential-armhf 12.3 all Inf ~# ``` +## Create a containerized ISAR SDK root filesystem + +### Motivation + +Distributing and using the SDK root filesystem created following the instructions in "[Create an ISAR SDK root filesystem](#create-an-isar-sdk-root-filesystem)" becomes easier using container images (at least for those using containers anyway) +A "containerized" SDK adds to those advantages of a normal SDK root filesystem the comfort of container images. + +### Approach + +Create container image with SDK root filesystem with installed cross-toolchain for target architecture and ability to install already prebuilt target binary artifacts. +Developer: + - runs a container based on the resulting container image mounting the source code to be built, + - develops applications for target platform on the container and + - leaves the container getting the results on the mounted directory. + +### Solution + +User specifies the variable `SDK_FORMAT` providing a space-separated list of SDK formats to generate. + +Supported formats are: + - `tar-xz`: (default) is the non-containerized format that results from following the instructions in "[Create an ISAR SDK root filesystem](#create-an-isar-sdk-root-filesystem)" + - `docker-archive`: an archive containing a Docker image that can be imported with [`docker import`](https://docs.docker.com/engine/reference/commandline/import/) + - `docker-daemon`: resulting container image is made available on the local Docker Daemon + - `containers-storage`: resulting container image is made available to tools using containers/storage back-end (e.g. Podman, CRIO, buildah,...) + - `oci-archive`: an archive containing an OCI image, mostly for archiving as seed for any of the above formats + +User manually triggers creation of SDK formats for his target platform by launching the task `do_populate_sdk` for target image, f.e. +`bitbake -c do_populate_sdk mc:${MACHINE}-${DISTRO}:isar-image-base`. +Packages that should be additionally installed into the SDK can be appended to `SDK_PREINSTALL` (external repositories) and `SDK_INSTALL` (self-built). + +Following formats don't work if running `bitbake -c do_populate_sdk ...` (to generate the containerized SDK) from inside of a container (e.g. using `kas-container`): `docker-daemon` and `containers-storage`. +It's technically possible, but requires making host resources (e.g. the Docker Daemon socket) accessible in the container. +What can endanger the stability and security of the host. + +The resulting SDK formats are archived into `tmp/deploy/images/${MACHINE}/sdk-${DISTRO}-${DISTRO_ARCH}-${sdk_format}.tar.xz` (being `sdk_format` each one of the formats specified in `SDK_FORMATS`). +The SDK container directory `/isar-apt` contains a copy of isar-apt repo with locally prebuilt target debian packages (for ). +One may get into an SDK container and install required target packages with the help of `apt-get install :` command. +The directory with the source code to develop on should be mounted on the container (with `--volume :`) to be able to edit files in the host with an IDE and build in the container. + +### Example + + - Make the SDK formats to generate available to the task + +For one-shot builds (use `local.conf` otherwise): + +``` +export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE SDK_FORMATS" +export SDK_FORMATS="docker-archive" +``` + + - Trigger creation of SDK root filesystem + +``` +bitbake -c do_populate_sdk mc:qemuarm-buster:isar-image-base +``` + + - Load the SDK container image into the Docker Daemon + +``` +xzcat build/tmp/deploy/images/qemuarm/sdk-debian-buster-armhf-docker-archive.tar.xz | docker load +``` + + - Run a container using the SDK container image (following commands starting with `#~:` are to be run in the container) + +``` +docker run --rm -ti --volume "$(pwd):/build" isar-sdk-buster-armhf:latest +``` + + - Check that cross toolchains are installed + +``` +:~# dpkg -l | grep crossbuild-essential-armhf +ii crossbuild-essential-armhf 12.3 all Informational list of cross-build-essential packages +``` + ## Creation of local apt repo caching upstream Debian packages ### Motivation