From patchwork Tue Jul 16 14:18:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Kiszka X-Patchwork-Id: 3702 Return-Path: Received: from shymkent.ilbers.de ([unix socket]) by shymkent (Cyrus 2.5.10-Debian-2.5.10-3+deb9u2) with LMTPA; Tue, 16 Jul 2024 16:18:23 +0200 X-Sieve: CMU Sieve 2.4 Received: from mail-lf1-f59.google.com (mail-lf1-f59.google.com [209.85.167.59]) by shymkent.ilbers.de (8.15.2/8.15.2/Debian-8+deb9u1) with ESMTPS id 46GEIMdj013365 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Tue, 16 Jul 2024 16:18:22 +0200 Received: by mail-lf1-f59.google.com with SMTP id 2adb3069b0e04-52ea883187csf5411991e87.3 for ; Tue, 16 Jul 2024 07:18:22 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1721139495; cv=pass; d=google.com; s=arc-20160816; b=YZgdaB8VDTrj+xz6XfBTJgA851ORrVcyY2IcSg1z7McIMSUC4QV3aCE4WGZuFzMXo7 wEDhgLXH6EyFaRsN3HoL0UoaJ4+XtAPKgKWfgkHeE6SyVwfF+p7LJrwA22S2koH2FZh3 uT8yD63iHFJbkl+AJ1VhGwaWTVSHhfBL/enNQyn4GiL7XKC3bi6oG5dFCPVZ5nG0Opoe OBeHC4zfgt2Jj7mlTnj8GNYd+xNubIRjCYTB6Cz12e0277+wt9F1/CraB7Tvo3b9ly0l fac2OpGoTkTA2VriGw/UVcfsTqMHQKu2L5sxAAL1USvBNCml83vbcTcdkO0AYgYNhuqu 4awA== 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:reply-to:feedback-id:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=NVtl5KSCs504vflhcJXHySR5kw0FxGPbKdCtbsRCdTk=; fh=V4zeEaFRScaizAoMW7X/RMWGyqA3qMGcelvOjSZhnC0=; b=mJpV9qPstVWESB7WxNBdflvS7UTW5Huh3i1A5x/V3sJBlrQAkXcS46qm1pIuA4jMEv h/ARiHCWGRMxoAEWjqDYbJgeZi+FNlOnuBGfDr6/ryy4/NQD5pSIjW/rFls6z5+pmBOT sfBLLz7L/TgW619CEhTqG8BKVTfdeTUkbK2e431EGMhR34R64gfOX1eTOVlngQjjxrcV TKJ2ZVFWGvKoFRhOyuJ57g/HSnWJxJLH/e4bgOR/t1aq64sGZihBan6L4oVNCPzOJmdn /g2W7E+LuNcWUK9Xr9yxprBWJx+lpil/T81XDbf2k3cAHSTWJhBkbJ2caz1o5L2Q9UZz m6Fg==; darn=isar-build.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=CnPCanMz; spf=pass (google.com: domain of fm-294854-20240716141811b22134322e75f578a7-mojsmh@rts-flowmailer.siemens.com designates 185.136.65.226 as permitted sender) smtp.mailfrom=fm-294854-20240716141811b22134322e75f578a7-Mojsmh@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20230601; t=1721139495; x=1721744295; darn=isar-build.org; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:reply-to :x-original-authentication-results:x-original-sender:feedback-id :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=NVtl5KSCs504vflhcJXHySR5kw0FxGPbKdCtbsRCdTk=; b=KruENsXhjONSTHYpOzjoe2m15DoOXXc0UiFbIc6mNu57kEQqpDBL8tK9lsoB/GrWy4 jJm0qRXFwSDQ5ysUmfSoW2qlpyXJ/VRB4aETmhZqEB9cbiZZGjt/FBOtKoTMjQqgXZvg ZDUeP+ywsmZCDvqrNSoCvpFSaAJNK11VUI/bgrYhj9XtMxyW0dDm857ELba1dkTHd4XM 5ZZvwqVkO3YMUb5rnEpI3FxWd2P6Nalkj5U/A4bc6rQxBxLXm7iva0vMdnGloP476ByH X/LQ4PeR1gzxFfHVQXRqCfdwWTkwGRX2RAxvG5E/KYiw8uV1nHjC8hN7+n7+3ePYdhv9 Czdg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721139495; x=1721744295; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :x-spam-checked-in-group:list-id:mailing-list:precedence:reply-to :x-original-authentication-results:x-original-sender:feedback-id :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:x-beenthere:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=NVtl5KSCs504vflhcJXHySR5kw0FxGPbKdCtbsRCdTk=; b=OCCe6u2TSK2HYsIdO2bywgIaz9/f9Hubzufn84EjaBUZe0tkDDS5SXTuHSxxldqNBO 66yYiHqzwKKmNd3cOrDHFuBKgOiyQWyLwAQ6Ch+XLY3710RZcLJR/3rptpiUdq9biIRd /S2Ix/o7T5MQAGRKnkBrUXodsLOPkoaGTEeJg8QGHV4/sclu7yX679yULTzSgTtwJEuL wUeHWbHptCmP4XQQFEnnF2V0WPVefL61SlCNXgM0DRCRK+Xj53B21O6mgePz4GPfLDag 9V/yF82jNwu+MGU9BTM0pvN7Hu43LOqWHvqQnUs5pez8E0EsmT6GGj21nRuHWeV6MmM+ Rvnw== X-Forwarded-Encrypted: i=2; AJvYcCV1z3+fskjYgwxZWwEvL302aa8B8KX1sRaht/OhcsoVx6hbUBm/fN3wJzYcJGGYRphkhJVynSL5K5OV+rNOwPUv5E17oI0= X-Gm-Message-State: AOJu0YzWUpjyi2WDMtxqgxHpQJhg+w+14+27TtOWH2iicLafaPFopTtU 59KG1MiTXBBtQtrfWuB6c0SIW0qP6hRUOU08Kcssw5zu9dCn+Tmp X-Google-Smtp-Source: AGHT+IEnLbRlgQx53EHx5Gnd7c9qHV+XjxouOUvh47crxi5neIu9M+ZE2yEN++I42keuJyyfRHkFTw== X-Received: by 2002:a05:6512:280c:b0:52c:a88b:9997 with SMTP id 2adb3069b0e04-52edf030adcmr1883169e87.49.1721139494503; Tue, 16 Jul 2024 07:18:14 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a19:ac02:0:b0:52e:8072:8b91 with SMTP id 2adb3069b0e04-52ec4504d4als2693328e87.1.-pod-prod-08-eu; Tue, 16 Jul 2024 07:18:12 -0700 (PDT) X-Received: by 2002:a05:6512:3f04:b0:52e:9481:eaa1 with SMTP id 2adb3069b0e04-52edef1eaedmr1775285e87.23.1721139492131; Tue, 16 Jul 2024 07:18:12 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1721139492; cv=none; d=google.com; s=arc-20160816; b=ZOBrroVR8nqooJ3wk0rjAPXfNPB91toxd5yv1r+oS3YQsTB4sEPX92aw0IeNNVbBXq 8akaYpkT6DvzdkpWeWnzYcearllkf2fZqur2hR67HJAT9qho6y2+PV9AFD9ZFBUU5Ptm Phy4wC1FR4l7F02k30vJ+1bDFIIXAcBJv3y3yRopOEMOLnt3Z3oeG54JUHDhjjPpWd3z qc5yKLyVH4PmuJW3x9faFWOupnb6ZHrPGxwdH2tsEQRwqnlWq49Zzh4aDJizvxIQ1nzk xS6qhDCAWf2pfiwrIr+CEctjMiNyhTBOnBSUIikmQA6n/hWibPW0jrOrRjS22xKQX9CF CJtw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=feedback-id:content-transfer-encoding:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:dkim-signature; bh=4AcWpN0C7NKWvt2bQCCVT9D6e+6VhTXPCLccjjb62/o=; fh=sG8mVX6bNXJXg1RhSNhryk9YKHryCWWF37H72hfFhEU=; b=o5bVb5EswtqdMV6WeY7jcDNxHSndWiSG/NlYmQqDuwupt2g/k5MwrN9ROPcIDFKNTL ujEfYi3zcR4vNsQPstw7fy7+EGRzziREAxu3rcOHGlQkBYTgTfU8/B4Uwu5PHUExw8iz gu5ZlyIuEFTfPq64rXoIErEw/4MkIDHVQfEELnsPAhA75uFCFQ5x/Kk0AZ4qLinKu3ay 0LP2Zw9imtTa+IkY6uzwVmFHlZOG2e9P6IXfjf+immUvHLzrQTnfJ2AQBmiIajWE4kiW RfC9HNtG6xmpNJy171yNALM8dpiCIeoF+VTOIFxmOyXin+mud6HaVWSXWazTWHG8M061 h2UA==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=CnPCanMz; spf=pass (google.com: domain of fm-294854-20240716141811b22134322e75f578a7-mojsmh@rts-flowmailer.siemens.com designates 185.136.65.226 as permitted sender) smtp.mailfrom=fm-294854-20240716141811b22134322e75f578a7-Mojsmh@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from mta-65-226.siemens.flowmailer.net (mta-65-226.siemens.flowmailer.net. [185.136.65.226]) by gmr-mx.google.com with ESMTPS id 2adb3069b0e04-52ed254a0f1si115976e87.7.2024.07.16.07.18.12 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 16 Jul 2024 07:18:12 -0700 (PDT) Received-SPF: pass (google.com: domain of fm-294854-20240716141811b22134322e75f578a7-mojsmh@rts-flowmailer.siemens.com designates 185.136.65.226 as permitted sender) client-ip=185.136.65.226; Received: by mta-65-226.siemens.flowmailer.net with ESMTPSA id 20240716141811b22134322e75f578a7 for ; Tue, 16 Jul 2024 16:18:12 +0200 X-Patchwork-Original-From: "'Jan Kiszka' via isar-users" From: Jan Kiszka To: isar-users Cc: Silvano Cirujano-Cuesta , Benedikt Niedermayr , Felix Moessbauer Subject: [PATCH v3 5/5] doc: Describe how to use the container fetcher and loader Date: Tue, 16 Jul 2024 16:18:09 +0200 Message-ID: <80f1c915285e61b70623f0eb2ce5f930abaa6196.1721139489.git.jan.kiszka@siemens.com> In-Reply-To: References: MIME-Version: 1.0 X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-294854:519-21489:flowmailer X-Original-Sender: jan.kiszka@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=CnPCanMz; spf=pass (google.com: domain of fm-294854-20240716141811b22134322e75f578a7-mojsmh@rts-flowmailer.siemens.com designates 185.136.65.226 as permitted sender) smtp.mailfrom=fm-294854-20240716141811b22134322e75f578a7-Mojsmh@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com X-Original-From: Jan Kiszka Reply-To: Jan Kiszka 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-Spam-Status: No, score=-4.9 required=5.0 tests=DKIMWL_WL_MED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, RCVD_IN_MSPIKE_H2,RCVD_IN_RP_CERTIFIED,RCVD_IN_RP_RNBL,RCVD_IN_RP_SAFE, SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on shymkent.ilbers.de X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= From: Jan Kiszka Signed-off-by: Jan Kiszka --- doc/user_manual.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/doc/user_manual.md b/doc/user_manual.md index 776ae52c..e97a2cd5 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -1519,3 +1519,63 @@ SBUILD_CHROOT_PREINSTALL_EXTRA += "" Then, in the dpkg recipe of your package, simply set `SBUILD_FLAVOR = ""`. To install additional packages into the sbuild chroot, add them to `SBUILD_CHROOT_PREINSTALL_EXTRA`. + +## Pre-install container images + +If an isar-generated image shall provide a container runtime, it may also be +desirable to pre-install container images to avoid having to download them on +first boot or because they may not be accessible outside of the build +environment. Isar supports this scenario via two services, a container fetcher +and a container loader. + +### Bitbake fetcher for containers + +The bitbake fetching protocol "docker://" allows to download pre-built images +from container registries. The URL consists of the image path, followed by +a recommended digest in the form `digest=sha256:` and an optional +tag in the form `tag=`. A digest is preferred over a tag to identify an +image when fetching because it also allows to validate its integrity. If a tag +is not specified, `latest` is used as tag name. + +When specifying a multi-arch image, the fetcher will download the images for +all available architectures. If this is not desired, directly specify the +digest of the desired architecture manifest instead of that the manifest list. + +The fetched container images are stored in a directory in the `WORKDIR` of the +requesting recipe. When a multi-arch image was specified, only the image +matching `PACKAGE_ARCH` will be stored. The name of the image directory is +derived from the container image name, replacing all `/` with `.`. + +### Container loader helpers + +To create a Debian package which can carry container images and load them into +local storage of docker or podman, there is a set of helpers available. To use +them in an own recipe, add +`require recipes-support/container-loader/docker-loader.inc` when using docker +and `require recipes-support/container-loader/podman-loader.inc` when using +podman. The loader will try to transfer the packaged image into the container +runtime storage on boot, but only if no container image of the same name and +tag is present already. + +Unless `CONTAINER_DELETE_AFTER_LOAD` is set to `1`, the source container images +remain by default available and may be used again for loading the storage after +it may have been emptied later on (factory reset). + +Source container images may either be fetched as binaries from a registry, see +above, or built via isar as well. + +### Example + +This creates a debian package which will download, package and then load the +`debian:bookworm-20240701-slim` container image into the docker container +storage. The package will depend on `docker.io`, insuring that that basic +runtime services are installed on the target as well. The packaged image will +be deleted from the target device's rootfs after successful import. + +``` +require recipes-support/container-loader/docker-loader.inc + +CONTAINER_DELETE_AFTER_LOAD = "1" + +SRC_URI += "docker://debian;digest=sha256:f528891ab1aa484bf7233dbcc84f3c806c3e427571d75510a9d74bb5ec535b33;tag=bookworm-20240701-slim" +```