From patchwork Fri Jul 19 16:38:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Kiszka X-Patchwork-Id: 3710 Return-Path: Received: from shymkent.ilbers.de ([unix socket]) by shymkent (Cyrus 2.5.10-Debian-2.5.10-3+deb9u2) with LMTPA; Fri, 19 Jul 2024 18:38:57 +0200 X-Sieve: CMU Sieve 2.4 Received: from mail-wm1-f56.google.com (mail-wm1-f56.google.com [209.85.128.56]) by shymkent.ilbers.de (8.15.2/8.15.2/Debian-8+deb9u1) with ESMTPS id 46JGcsb3002664 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Fri, 19 Jul 2024 18:38:54 +0200 Received: by mail-wm1-f56.google.com with SMTP id 5b1f17b1804b1-42674318a4esf17640785e9.1 for ; Fri, 19 Jul 2024 09:38:54 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1721407128; cv=pass; d=google.com; s=arc-20160816; b=ysx2nNgLQGn3BaPTba+soI7309nBAM+r2fEfvCH4GDFKxeG8SqUvy8vrKWJl8FQ4Mq JZ956yGu6WWQ9+uzlWncyWTXza94EpvD951syzOJKRur5E2VYmgmvvwuXbi1caZsd7Fm xl+x/o1Loe/vWZE/92AvBpcW9JRlpuEyW5LkBBqwbsmVEtqon4NIOL1idthifCScxFba 49X1VgM8LdCYXd0sk39+847WlBvndlskZW3gysTP1sE7WsM6m+/q5v1LoycsdggqIXPK RT9kQAnMnFapB8xoO7NS/vfdfBkZmfsMA2GCy7S50ZGIVqvrIPWqImKf3lpYs38Sbwsi c78A== 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=kIOJcMC6x4IWUMbuxMej4F19IxCf1XU//W3pVYaFPZY=; fh=I8niZciwQIgaBobYet8LxBT82Tv3W3lk+dSa0wPGKDI=; b=oCt24BkHf0nv6Zi6B7EOCLr1onR+wL1E7A8sGx8VH1forp7AOx+cbsvU1GMszlG86Y F3eJsIGY55YSVH4bMi9Y+bewJ3jRq8UpBgcXvPTSmuY/kZg75Alq+cRTq5ncme54c4fm MPWpPbhFUDRYiZzUsMQpJVWRcdE7jRlo07MiYCK2ORdxDW3KFq2ZZu6FWGBJQimguF2/ GIzMqomtHcssyMYqX8WZ4YNys2kJKU+cAdqTV1gKaMOU2Q6wfvH+zG2BxYgpklLoQrJM FG/cDuQ3VlmVNnuBJ9fdSzATvdwzpSY8uRiUgltmwSxFN0ZPnW0rIgnfHa6uONHF60Jz ha+Q==; darn=isar-build.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=D84FDjb5; spf=pass (google.com: domain of fm-294854-2024071916384593b534507bf250d812-2vt89o@rts-flowmailer.siemens.com designates 185.136.65.227 as permitted sender) smtp.mailfrom=fm-294854-2024071916384593b534507bf250d812-2Vt89O@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=1721407128; x=1722011928; 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=kIOJcMC6x4IWUMbuxMej4F19IxCf1XU//W3pVYaFPZY=; b=g8reSTe4SLH1ZrBrBHFK2pOKJFzPPnGdqAzPXrT74jdsRbB8ZEd0kZGM8+uEDWEY9w clQWiXl4Y2v6OsAVZXgs2ZfU7zpqLPoGIrkdOwQm9iGpmXKugSds9WlXtZnPLpqvMc6j ux1yLFP+YY8bOpCfbF9EfT6JiZXKx359h2dfaKdKXh6gRB19bPYrnjGIF2U/XTYtnAcI u2BRnVlrpX1/oaVmk9TJ+hd/4XBWdpAapvddvpCqYZhgeqAjTTDoxlQGQHRrzR4Lh0E+ JDk71D75XLX2U9w69+lEkXUnSPMJByfGNpYoIHaIOmOFq6mkgZYEhoQWzFHETywlOYNe zzSA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721407128; x=1722011928; 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=kIOJcMC6x4IWUMbuxMej4F19IxCf1XU//W3pVYaFPZY=; b=kfjHPcvlA7CbQVD+3Nio9PIWTgUCkx7WMfnuY8RDFGPDGwGIxRMU5UzlMr5WSscmoA luaL2TNEMWxoUof2obQDouv7lo2UKxE4zqN9FViWyxiQeWodGdB8DyBIi09oy+unZ+so q0E4NJTGlkoiHDS301FiOCc3OvLTdzEMO9AOI0o2goaX2rzug/8Tdtpx7PxBoALXyLGC Kh2J54OJJPv9znxnD24aYbl3hK9+n0X6Yp6prdLH0PAaptH5M1tcmenuXN3ylgN7RuFn wyT7zslyq6wc+gHnuzIIIpSZyw2eMkIorsTsZ3yfzk6rJ3vPgEHGpx/YMkK3l1eGbBpP 5SJg== X-Forwarded-Encrypted: i=2; AJvYcCXoIbWsUkEoE/9QyktBFnHydg0SVkroCnAnQ7usqKrwkoKF6BdQeTX/1GqY4rl6+4vqG/7B/onc3QmK9teYb5sO+2KDwY0= X-Gm-Message-State: AOJu0Yya7qyGRWgCcXdvloaVIFffGGdfa+dJ8d4rdZm+MEeAaN5voOqO BcPp6U4T/z8HtBY959bsoa0EyfPw0R1kjQiDwgzo1dJ+EXgkygDk X-Google-Smtp-Source: AGHT+IHuJmqaS5TiErZmy7geCYluS2gxM6X9T5FXRyMqtbjfVE0ZaGzTvScMYkdQB+zryVyYEwYxDw== X-Received: by 2002:a05:600c:4fc6:b0:426:5e1c:1ac2 with SMTP id 5b1f17b1804b1-427c2cacf29mr76892525e9.8.1721407127609; Fri, 19 Jul 2024 09:38:47 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a05:600c:510a:b0:426:7318:c5a0 with SMTP id 5b1f17b1804b1-427c83a94e1ls15034325e9.2.-pod-prod-05-eu; Fri, 19 Jul 2024 09:38:45 -0700 (PDT) X-Received: by 2002:a05:600c:1f07:b0:426:5b44:2be7 with SMTP id 5b1f17b1804b1-427c2cb865emr76412785e9.10.1721407125406; Fri, 19 Jul 2024 09:38:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1721407125; cv=none; d=google.com; s=arc-20160816; b=KpsfubUp8pB3qiO4V2s+yjwTd4gqhSMEdMkf+9mIVrpjJ4yALyoFz7KIbvl6Hc6uZb j5zHd9s635uVipFsV0mCyhNj6GWwODcf/A24QpMXaB1fOzF3BrLxFK29eIcopt5U4/XW hOgNtg7F80ehxuwdSKxYUduEe6Yj4NGUYAijJMBUjKOfzwM7v+tHjY5/g7u1eQj8g1zW 5zBbbTh4ccKQRG/sltCI7RheJ8b0+CCUX6nOAdZbg/jvI/PueZvzoK5749Y/1RDj5Tw1 GEFxLKbC9rLkT8YLz3KMA7Wstiwvn/zNav53mMISbzVn+qbzEj7JFqVxgxCxAwglTV7J 3I2Q== 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=BVG8ZbQIbKYYng1kSStiENS2JGVTDaSoFvKjxSoBf+Q=; fh=sG8mVX6bNXJXg1RhSNhryk9YKHryCWWF37H72hfFhEU=; b=R5kIF5Y24g57iZiWqIqiQhYs7GKaIQYrDUn20oHhfeE60+aBNdZKvG1Uu9K9dzJbBv FDxdlWqNZd1N4vQw/edHqtoMjXubHZQtEcPTtosVAB0e/I3nN15rcSrxyS2nlP8KOQhb kdlyDtEVGuk8patVfSnZadQBqAg/hYdwuvNKytFuI3gkGOeh2AnLF9vWdpquYLynfQqY fRbNv4QVEyGhCq41aWV4A9V8vh16wAognjPGJ1BJ5KUwjelAXiCDVmMxyIhNL3NH591/ 4EiLw7vxuYIyCl5IQwi2Rm0kF6vjlmXnKG3rs7EpUgLGvcoIHBZC29MKfg5qS5wFtiZe d3UA==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=D84FDjb5; spf=pass (google.com: domain of fm-294854-2024071916384593b534507bf250d812-2vt89o@rts-flowmailer.siemens.com designates 185.136.65.227 as permitted sender) smtp.mailfrom=fm-294854-2024071916384593b534507bf250d812-2Vt89O@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from mta-65-227.siemens.flowmailer.net (mta-65-227.siemens.flowmailer.net. [185.136.65.227]) by gmr-mx.google.com with ESMTPS id 5b1f17b1804b1-427d2911f57si1635545e9.0.2024.07.19.09.38.45 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 19 Jul 2024 09:38:45 -0700 (PDT) Received-SPF: pass (google.com: domain of fm-294854-2024071916384593b534507bf250d812-2vt89o@rts-flowmailer.siemens.com designates 185.136.65.227 as permitted sender) client-ip=185.136.65.227; Received: by mta-65-227.siemens.flowmailer.net with ESMTPSA id 2024071916384593b534507bf250d812 for ; Fri, 19 Jul 2024 18:38:45 +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 v4 5/5] doc: Describe how to use the container fetcher and loader Date: Fri, 19 Jul 2024 18:38:43 +0200 Message-ID: <049353103858d43105d45603619a7548f2a29579.1721407122.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=D84FDjb5; spf=pass (google.com: domain of fm-294854-2024071916384593b534507bf250d812-2vt89o@rts-flowmailer.siemens.com designates 185.136.65.227 as permitted sender) smtp.mailfrom=fm-294854-2024071916384593b534507bf250d812-2Vt89O@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 | 58 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/doc/user_manual.md b/doc/user_manual.md index 776ae52c..2bdacbec 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -1519,3 +1519,61 @@ 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. + +In case a multi-arch image is specified, the fetcher will only pull for the +package architecture of the requesting recipe (`PACKAGE_ARCH`). The fetched +images are stored as zstd-compressed in docker-archive format in the +`WORKDIR` of the recipe. The name of the image is derived from the container +image name, replacing all `/` with `.` and appending `:.zst`. Example: +`docker://debian;tag=bookworm` will be saved as `debian:bookworm.zst`. + +### 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" +```