curtin-dev team mailing list archive

[Tiago Pasqualini da Silva <mp+475552@xxxxxxxxxxxxxxxxxx>]

Tiago Pasqualini da Silva has proposed merging ~tiago.pasqualini/curtin:fix_doc into curtin:master.

Commit message:
Add documentation section about APT templates

Curtin supports the usage of templates for APT configuration, but
currently there is no mention of it in the documentation. This
patch adds a section explaining how to use it.

Requested reviews:
  Server Team CI bot (server-team-bot): continuous-integration
  curtin developers (curtin-dev)

For more details, see:
https://code.launchpad.net/~tiago.pasqualini/curtin/+git/curtin/+merge/475552
-- 
Your team curtin developers is requested to review the proposed merge of ~tiago.pasqualini/curtin:fix_doc into curtin:master.

diff --git a/doc/topics/apt_source.rst b/doc/topics/apt_source.rst
index 2a4616e..52e1996 100644
--- a/doc/topics/apt_source.rst
+++ b/doc/topics/apt_source.rst
@@ -130,7 +130,7 @@ That would be specified as ::
           =PBAe
           -----END PGP PUBLIC KEY BLOCK-----
 
-The file `examples/apt-source.yaml <https://git.launchpad.net/curtin/tree/examples/apt-source.yaml>`_ holds various further examples that can be configured with this feature.
+The file `examples/apt-source.yaml <https://github.com/canonical/curtin/blob/master/examples/apt-source.yaml>`_ holds various further examples that can be configured with this feature.
 
 deb822 sources on Ubuntu >= 24.04
 ---------------------------------
@@ -205,6 +205,55 @@ This is a collection of additional ideas people can use the feature for customiz
          Suites: $RELEASE $RELEASE-updates $RELEASE-security $RELEASE-proposed
          Components: main restricted universe multiverse
 
+Using templates
+~~~~~~~~~~~~~~~
+
+Curtin supports the usage of custom templates for rendering ``sources.list`` or ``ubuntu.sources``.
+If a template is not provided, curtin will try to modify the ``sources.list`` (or ``ubuntu.sources`` in the case of deb822) in the target at
+``/etc/apt/sources.list`` (or ``/etc/apt/sources.list.d/ubuntu.sources`` in the case of deb822). Within these templates you can use the following
+replacement variables: ``$RELEASE, $MIRROR, $PRIMARY, $SECURITY``.
+
+The following example configures ``ubuntu.sources`` in deb822 format, supplies a custom GPG key, and uses the template feature to genericise the configuration across releases.
+
+::
+
+ apt:
+   primary:
+     - arches: [amd64, i386, default]
+       uri: http://mymirror.local/ubuntu
+   sources_list: |
+     Types: deb
+     URIs: $PRIMARY
+     Suites: $RELEASE $RELEASE-updates $RELEASE-security $RELEASE-proposed
+     Components: main
+     key: | # full key as block
+       -----BEGIN PGP PUBLIC KEY BLOCK-----
+       Version: GnuPG v1
+       mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3O
+       RwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1
+       Twx6DKLF+3rF5nf1F3Q=
+       =PBAe
+       -----END PGP PUBLIC KEY BLOCK-----
+
+The template above will result in the following ``ubuntu.sources`` file:
+
+::
+
+ Types: deb
+ URIs: http://mymirror.local/ubuntu
+ Suites: noble noble-updates noble-security noble-backports
+ Components: main
+ Signed-By: | # full key as block
+   -----BEGIN PGP PUBLIC KEY BLOCK-----
+   Version: GnuPG v1
+   mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3O
+   RwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1
+   Twx6DKLF+3rF5nf1F3Q=
+   =PBAe
+   -----END PGP PUBLIC KEY BLOCK-----
+
+The file `examples/apt-source.yaml <https://github.com/canonical/curtin/blob/master/examples/apt-source.yaml>`_ holds more examples on how to use templates.
+
 Timing
 ~~~~~~
 The feature is implemented at the stage of curthooks_commands, which runs just after curtin has extracted the image to the target.