From patchwork Mon Jul 15 10:08:32 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jan Kiszka X-Patchwork-Id: 3692 Return-Path: Received: from shymkent.ilbers.de ([unix socket]) by shymkent (Cyrus 2.5.10-Debian-2.5.10-3+deb9u2) with LMTPA; Mon, 15 Jul 2024 12:08:45 +0200 X-Sieve: CMU Sieve 2.4 Received: from mail-lf1-f55.google.com (mail-lf1-f55.google.com [209.85.167.55]) by shymkent.ilbers.de (8.15.2/8.15.2/Debian-8+deb9u1) with ESMTPS id 46FA8ie1005869 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Mon, 15 Jul 2024 12:08:44 +0200 Received: by mail-lf1-f55.google.com with SMTP id 2adb3069b0e04-52ebdbf8a7csf3099743e87.2 for ; Mon, 15 Jul 2024 03:08:44 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1721038118; cv=pass; d=google.com; s=arc-20160816; b=W44g5F+kTK2EygDGRPb60DVJb3nkcxVowZiNDasi8HDun/NtdDdEolaGg36OTPuMYi YvUKnEAbs710+A8sOY0Gbewqf/XPJaYrnqg5EWd0833Bihg3cb7xzcKwHX9q3nLWYqM/ Rto/KIcBwLp2Z27c/GxFfNrKbC0takTFkLBP6zJckLe8eYeX/OSrzTDyPH9uppzjQ2zT 90q91RO6FtlAMA8ulsOLmk/LDgJ85MgdpdvC94YO0Nq12zl/uAOt63Ovo5Bqsdx1rT93 I+7BrYyyZVpKYMgIT/RS1wBMqA9+T4VFsfbaK2lkvofnMW+8gBNrhp5CnLVSz3FizltI jc5Q== 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=IcEraZG8XQedbB0juPTShRBWi7IpMSDogj0nvMqPbow=; fh=n/a+DwmJADkrDYjJHmY97Apz5k9iSmzI8rPdg3c1V0I=; b=MJ4kepF3LFnt6lYa9oHpCQV3BDSDzrXVIbSZlEjnAwLIqmpHRugVkkx5ZAP0JAShUr CKtHPHVXtoJbIGJ/AFqr6MWtMyn/ZJoc5D3xEbq7xd3boc2+LuacwwPazsCtwbelH/rU C9daKZMnyyW8EADLkdo51wN/Qpt+82xZX1Ckhjy4fbOUjp0QVm4DI33Frmoofw9+RQ/e HkxPDCcznJEazgOc6wVweUCpINp3q/xDNvCa4tsowug4PnxaV9leb89Q4ZN99VgFqTjd LC5FTX6OHkc++Gy2mC1W9Vpl7vbiKsO1qD0D1hJNL8uHe5vM9mcrfHZebxgy5TLEiu94 8W4Q==; darn=isar-build.org ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=EqVGyv6A; spf=pass (google.com: domain of fm-294854-202407151008342a7fd46636f45a806a-ubffof@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-202407151008342a7fd46636f45a806a-UbFFOF@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=1721038118; x=1721642918; 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=IcEraZG8XQedbB0juPTShRBWi7IpMSDogj0nvMqPbow=; b=d9FWn3+Ngf1nBbWK0mN8MgGGYWB2A/Q1IV40gVjR5I4dGU3x6ebg2F8tH/NUcmGThc xPTh3sMD/zjf91IY3eqxn+D75rLGrYUKd5VXuDOfMpBq69nt/jnbD2SWhG9sb2Sxc6Pk z58J8yAGJtawaRn/n8koH88w1BSzvFX3GH8+edOwGXVGCL1DoxM6gGNcjtaKJYubNLmm XIxuPyjeSns++atY4fInF+eEXBT2cYb12M510QkjWN11ijaaFrz8LigPpnVK56Rrdff9 t2Rmu3SaaJA6AzamyDVUCueE79IgGDhnkKCBppHey1f8s4ll+cl3fUbm4AiztTedaM/8 CBsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721038118; x=1721642918; 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=IcEraZG8XQedbB0juPTShRBWi7IpMSDogj0nvMqPbow=; b=XUvAYeMZkP/TLgyWiwYzFQATEcV4BXwANbypnPSu0hhTUnplXE3Tv4GpFmFdrEXs9a NwUTPq/cR/krJB6fl+fwNEIvQPVQ0euOkjSeqyUDHegDKwKCOvxKrttbszDSX3e9qDFH uhOY3RyLVileQeBQC5eehFtjupgs3dxMMVrAsAbeEIGEMBUsN6dgbg4ntIsEV9HF1rBq SbyeT8yfO5cOJzQW7wvTt6rMMeHtFXNm4dqMREF6URErmNcsoYB2IakSnv59zuwJQq2h rckNu90toUpxuRm04SMt1oQCTUf3lkpre7E/dZ7ZpKGKZoo+eLrpf/VxNTcnmRK4s53G 4HqA== X-Forwarded-Encrypted: i=2; AJvYcCW3t1x86ofhFqYYfNEr5fsjT4TbZdyIDZNZ5NEMN8rEMw8TfK3mZnnY5Yt1wQ/wXbT3QdnjbQC4T6Qxf+PaIKsqgtSZ2Bs= X-Gm-Message-State: AOJu0YydWRa4AdvpOA0F+x2Sv4XlKIsjrBmDK0/KcnMIKthieJk3j3Ee b0Fti5n5r4+I7546QWNCGoy0bRJcHxPoePRrmAbyMgSIzLnRUbWI X-Google-Smtp-Source: AGHT+IEA/lUSUWxDA4D5Xy6dEFpb54qji4cJWNu0Wwx260eLIcuTZNML4RdSSK0ceImv3itqnxiAig== X-Received: by 2002:a05:6512:158f:b0:52e:9d60:7b4c with SMTP id 2adb3069b0e04-52eb99d4f52mr12265822e87.61.1721038117591; Mon, 15 Jul 2024 03:08:37 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 2002:ac2:5a51:0:b0:52e:9923:a1ba with SMTP id 2adb3069b0e04-52ec4521d36ls1832997e87.2.-pod-prod-06-eu; Mon, 15 Jul 2024 03:08:35 -0700 (PDT) X-Received: by 2002:a05:6512:2310:b0:52e:a7a6:ed7f with SMTP id 2adb3069b0e04-52eb99d4f79mr11963570e87.60.1721038115366; Mon, 15 Jul 2024 03:08:35 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1721038115; cv=none; d=google.com; s=arc-20160816; b=p7IuTXrMHT/hIvkJIh+kc/ZPFciRBgdJIgKCssC1zLEuh4ZrX5Q2DiWSoHLObpF8er 5yqSbC1nnljN/qIHn6MCSksUr46QXlp59oWsA3bbQxPcDioI+qS86buZ+AzIdkzEOQG6 IiTdMShqtpieeAdk+B20A/CNjBt2jVbcKBBrw30NMywMTFk6k8AgZfyto5i6snOZS3bt swPH93mDnZPMvk2f9XrwxfRykHR8CzHQli2/Yq74zauDOoRPsL6hARyx2rJtrNtv6KfW TI/tpfYMv+Z0VbEaRDQ1bBoo5GeMuyB9+I8av99Wbk/7Sr1/3cFiT3fyvWYwkFJs90g0 x5tw== 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=hcbrhizW+zLGQ2MZFaZRcEJ3AvAEjfR5l/8EpKGdW60=; fh=sG8mVX6bNXJXg1RhSNhryk9YKHryCWWF37H72hfFhEU=; b=SkH1Wy8KA4EKwPP8mtb4leTSeVT4VTTgx5hwEpJY0bZ6oJ2nNLwNflCB8z/N3zTR14 JFUquInO2qoEfeVk5gjd5FRYPm2YSzk/P8UzRSS5GqyrIJqXlRV9P9XLG33nce8iUuoS f0qpPGRc0rP4jtaKdvbw8NqE7zJIRA82Uy7481daDGgVEXobbRZK9WA93KoZ9HW3NHUf //7XOAZliRgj/xhjRUmvHQnSd5WyWFfpKNHkjr3gQmCbJx7x6jCP6nh69AO2jmCM1KBG C0jID5Z2UmCG784PBv1fmtRM2eu9nsrMGyn6UWvGwuZtEeV+2cYVTQjD0qwnE2yrKOWA +dVg==; dara=google.com ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=fm2 header.b=EqVGyv6A; spf=pass (google.com: domain of fm-294854-202407151008342a7fd46636f45a806a-ubffof@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-202407151008342a7fd46636f45a806a-UbFFOF@rts-flowmailer.siemens.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=siemens.com Received: from mta-65-225.siemens.flowmailer.net (mta-65-225.siemens.flowmailer.net. [185.136.65.225]) by gmr-mx.google.com with ESMTPS id 2adb3069b0e04-52ed257c829si77019e87.9.2024.07.15.03.08.35 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 15 Jul 2024 03:08:35 -0700 (PDT) Received-SPF: pass (google.com: domain of fm-294854-202407151008342a7fd46636f45a806a-ubffof@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) client-ip=185.136.65.225; Received: by mta-65-225.siemens.flowmailer.net with ESMTPSA id 202407151008342a7fd46636f45a806a for ; Mon, 15 Jul 2024 12:08:35 +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 v2 5/5] doc: Describe how to use the container fetcher and loader Date: Mon, 15 Jul 2024 12:08:32 +0200 Message-ID: <2e1537004e7ad48f33cd3d3daf2b8f7c3294d31a.1721038111.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=EqVGyv6A; spf=pass (google.com: domain of fm-294854-202407151008342a7fd46636f45a806a-ubffof@rts-flowmailer.siemens.com designates 185.136.65.225 as permitted sender) smtp.mailfrom=fm-294854-202407151008342a7fd46636f45a806a-UbFFOF@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..733b2b30 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 provides 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 recommened digests in the form `digest=sha256:` and an optional +tag in the form `tag=`. A digest is preferred over a tag to identify the +an when fetching as it also allows to validate its integrity. If 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 image 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 into 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 debian package with 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`, thus ensure 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" +```