Skip to content

PR#527 and other editorial review corrections for Agama auto installation docs #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 6, 2025
Merged

PR#527 and other editorial review corrections for Agama auto installation docs #595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions articles/agama-automated-installation.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
<!-- Tasks -->
<resources>
<resource xml:id="_using-autoyast-profiles-with-agama" href="../tasks/using-autoyast-profiles-with-agama.xml">
<description>Using Auto&yast; profiles with &agama;</description>
<description>Using &ay; profiles with &agama;</description>
</resource>
<resource xml:id="_initiating-agama-automated-installation" href="../tasks/initiating-agama-automated-installation.xml">
<description>Initiating automated installation using Agama</description>
Expand All @@ -65,7 +65,7 @@
</resource>
<resource xml:id="_autoyast-agama-compatibility-reference"
href="../references/autoyast-agama-compatibility-reference.xml">
<description>Compatibility between Auto&yast; and &agama; profiles</description>
<description>Compatibility between &ay; and &agama; profiles</description>
</resource>
</resources>
<!-- Legal -->
Expand Down Expand Up @@ -116,7 +116,7 @@
<meta name="description" its:translate="yes">How to automate &productname; installations for unattended bulk deployments using &agama;, ensuring efficient and consistent server provisioning</meta>
<meta name="social-descr" its:translate="yes">Automatically install &productnameshort; using &agama;</meta>
<!-- suitable categories has to be identical with the category selected in the docserv config -->

<!-- Determines "filter by task" filter value -->
<!-- either add link to list or list of tasks-->
<meta name="task" its:translate="no">
Expand Down Expand Up @@ -164,7 +164,7 @@
<term>EFFORT</term>
<listitem>
<para>
You may need 30 minutes to read and understand the most important sections of this
You need about 30 minutes to read and understand the most important sections of this
article. The time required for customization of Agama profiles and storage
configuration depends on deployment requirements.
</para>
Expand All @@ -185,7 +185,7 @@
<itemizedlist>
<listitem>
<para>
A bare metal server or a virtual machine. For server installations without any
A bare-metal server or a virtual machine. For server installations without any
desktop environment, &suse; recommends a minimum of 1&nbsp;CPU, 2&nbsp;GB
memory and 32&nbsp;GB storage (which includes storage for Btrfs snapshots in
the root partition, swap space, and storage for software packages).
Expand All @@ -206,7 +206,7 @@
<title>Optional registration</title>
<para>
Certain images that are signed with the developer's key may allow you to skip
registration before or while installation. Besides, certain images may
registration before or during installation. Besides, certain images may
contain all installable packages for your operating system that you can use
as an offline package repository. In such cases, you may not need an active
registration code before installation. However, if you use software packages
Expand Down
58 changes: 31 additions & 27 deletions concepts/introduction-automated-installation-using-agama.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,48 +27,52 @@
<para>
This article describes how to use &agama; for automated and unattended installation of
&productname;. You can use JSON <emphasis>profiles</emphasis> describing different aspects
of intended system, and &agama; installs accordingly. While not a fully backward compatible
replacement for Auto&yast;, it simplifies the task of automated installation and provides
of the intended system, and &agama; installs accordingly. While not a fully backward compatible
replacement for &ay;, it simplifies the task of automated installation and provides
multiple clients for interactive and automated installation.
</para>
</abstract>
</info>
<section xml:id="automated-installation-what-is-agama">
<title>What is &agama;</title>
<para>
Agama as a service-based Linux installer capable of performing both interactive and
unattended installations. You can provide &agama; a JSON profile file detailing the initial
Agama is a service-based Linux installer capable of performing both interactive and
unattended installations. You can provide &agama; with a JSON profile file detailing the initial
system state, such as user authentication, partitioning, networking and software selection.
On receiving the profile and instruction for installation from one of its supported clients,
On receiving the profile and instructions for installation from one of its supported clients,
&agama; installs your target system accordingly. Users can interact with and control the
installation process using &agama;'s web-based user interface, command-line interface and
installation process using &agama;'s Web-based user interface, command-line interface and
HTTP API, facilitating automation and integration into existing workflows.
</para>
<para>
While &agama; reuses many principles and internal components from previous SUSE installers
like &yast; and Auto&yast;, and offers a high level of backwards compatibility for unattended
installations, it is not a 100% compatible drop-in replacement for all Auto&yast; features.
like &yast; and &ay;, and offers a high level of backward compatibility for unattended
installations, it is not a 100% compatible drop-in replacement for all &ay; features.
&agama; focuses only on the installation process rather than being a general configuration
tool.
</para>
<figure xml:id="agama-server-client-architecture">
<title>&agama; server client architecture</title>
<title>&agama; client-server architecture</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="agama-server-client-architecture.png"/>
</imageobject>
<imageobject role="fo">
<imagedata fileref="agama-server-client-architecture.png" width="85%"/>
</imageobject>
<textobject role="description">
<phrase>Diagram of &agama;'s client-server architecture showing three clients&mdash;CLI,
Web UI and others&mdash;connecting to the &agama; core via an HTTP API</phrase>
</textobject>
</mediaobject>
</figure>
</section>
<section xml:id="automated-installation-why-use-agama">
<title>Why use &agama; for automated installation</title>
<title>Why use &agama; for automated installation?</title>
<para>
&agama;offers its installation service by exposing an HTTP API, which you can use
interactively from a web-based interface and a command-line interface (CLI), or provide a
JSON profile to &agama; for automated installation of a target system. Using the HTTP API you
&agama;offers its installation service through an HTTP API, which you can use
interactively from a Web-based interface and a command-line interface (CLI), or provide a
JSON profile to &agama; for automated installation of a target system. Using the HTTP API, you
can also integrate with custom scripts and deployment tools. The benefits of using Agama for
automated installation are as follows:
</para>
Expand All @@ -79,16 +83,16 @@
<para>
&agama; focuses on core installation tasks such as user authentication, network
configuration, storage setup and software installation, delegating further
configuration to other tools such as &ansible; &salt;, &cockpit; or &openscap;.
configuration to other tools such as &ansible;, &salt;, &cockpit; or &openscap;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Profile based installation</term>
<term>Profile-based installation</term>
<listitem>
<para>
You can define installation parameters for the target system in an easily readable and
editable JSON or Jsonnet profile. Existing XML based Auto&yast; are also supported with
editable JSON or Jsonnet profile. Existing XML-based &ay; profiles are also supported with
some exceptions.
</para>
</listitem>
Expand All @@ -100,8 +104,8 @@
The profile allows detailed setup including user authentication, product registration,
network connections, storage (drives, partitions, LVM, RAID, encryption, resizing,
deleting), software selection by patterns and packages, localization (language,
keyboard, timezone) and many other aspects of the target system that are not exposed in
the graphical or web-based interface. This helps in a more granular control over the
keyboard, time zone) and many other aspects of the target system that are not exposed in
the graphical or Web-based interface. This provides a more granular level of control over the
installation parameters.
</para>
</listitem>
Expand All @@ -111,20 +115,20 @@
<listitem>
<para>
&agama; supports dynamic profiles using Jsonnet, injecting hardware information that
can be processed at runtime. This avoids reliance on Auto&yast;'s rules or ERB for
can be processed at runtime. This avoids reliance on &ay;'s rules or ERB for
dynamic configurations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Auto&yast; compatibility</term>
<term>&ay; compatibility</term>
<listitem>
<para>
&agama; offers a mechanism to reuse existing AutoYaST profiles to a great extent. It
&agama; offers a mechanism to reuse existing &ay; profiles to a great extent. It
supports some dynamic features such as pre-scripts, rules/classes, and Embedded Ruby
(ERB) when using Auto&yast; profiles. A <literal>legacyAutoyastStorage</literal>
section allows direct use of the Auto&yast; profile's <literal>partitioning</literal>
section for backwards compatibility.
(ERB) when using &ay; profiles. A <literal>legacyAutoyastStorage</literal>
section allows direct use of the &ay; profile's <literal>partitioning</literal>
section for backward compatibility.
</para>
</listitem>
</varlistentry>
Expand All @@ -143,11 +147,11 @@
<listitem>
<para>
The typical way to start an unattended installation from an ISO image is using the
<literal>inst.auto</literal> kernel boot option, pointing to the profile URL or it's
<literal>inst.auto</literal> kernel boot option, pointing to the profile URL or its
location in the hard drive. You can also use the <command>agama profile
import</command> command from the &agama; CLI to load a profile, followed by the
<command>agama install</command> command. The CLI also allows inspection, modification,
validation of the profile, and subsequent monitoring of the installation process.
<command>agama install</command> command. The CLI also allows inspection, modification
and validation of the profile, and subsequent monitoring of the installation process.
</para>
</listitem>
</varlistentry>
Expand Down
38 changes: 18 additions & 20 deletions concepts/understanding-agama-installation-profiles.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,29 +29,28 @@
configuration file that specifies how the system should be set up. This profile describes
various aspects of the installation, including partitioning, networking, software
selection, and other options. The concept of using a profile for automated installation is
similar to Auto&yast;. &agama; focuses specifically on the installation process itself and
similar to &ay;. &agama; focuses specifically on the installation process itself and
delegates further system configuration to other tools. &agama; aims for a high level of
backward compatibility with Auto&yast; profiles for automated installations.
backward compatibility with &ay; profiles for automated installations.
</para>
<note>
<title>Difference between &agama; and Auto&yast; profiles</title>
<title>Difference between &agama; and &ay; profiles</title>
<para>
&agama; and Auto&yast; profiles are largely compatible for all common use cases. However,
&agama; profiles are not fully compatible with Auto&yast; profiles, and cannot be used as
&agama; and &ay; profiles are largely compatible for all common use cases. However,
&agama; profiles are not fully compatible with &ay; profiles, and cannot be used as
a drop-in replacement without checking the compatibility. There are certain aspects of
the Auto&yast; profiles that are currently supported in &agama; profiles, or may be
the &ay; profiles that are currently supported in &agama; profiles, or may be
supported in the future. However, there are certain other aspects that are neither
currently supported in &agama; profiles, nor will be supported in the future. For more
information, refer to the section
<xref linkend="autoyast-agama-compatibility-reference"></xref>.
information, refer to the section <xref linkend="autoyast-agama-compatibility-reference"></xref>.
</para>
</note>
</abstract>
</info>
<section xml:id="introduction-agama-installation-profile-structure">
<title>Introduction to the &agama; profile structure</title>
<para>
&agama; profile configuration is defined using a JSON document. It contains several sections
The &agama; profile configuration is defined using a JSON document. It contains several sections
that are necessary for describing the installation parameters for a customized system. At a
high level, the profile consists of the following sections:
</para>
Expand Down Expand Up @@ -92,7 +91,7 @@
</callout>
<callout arearefs="localization">
<para>
<literal>localization</literal>: Language, keyboard, and timezone settings.
<literal>localization</literal>: Language, keyboard, and time zone settings.
</para>
</callout>
<callout arearefs="hostname">
Expand All @@ -112,7 +111,7 @@
</callout>
<callout arearefs="bootloader">
<para>
<literal>bootloader</literal>: Bootloader config and kernel params.
<literal>bootloader</literal>: Boot loader config and kernel params.
</para>
</callout>
<callout arearefs="network">
Expand All @@ -137,7 +136,7 @@
</callout>
<callout arearefs="legacyAutoyastStorage">
<para>
<literal>legacyAutoyastStorage</literal>: Support for legacy AutoYaST JSON-style storage.
<literal>legacyAutoyastStorage</literal>: Support for legacy &ay; JSON-style storage.
</para>
</callout>
<callout arearefs="iscsi">
Expand All @@ -158,19 +157,18 @@
</para>
<para>
For more information on the JSON and Jsonnet profiles, refer to the resources mentioned in
the <xref linkend="more-info-automated-installation-agama"></xref> section. The upstream
resources usually contains most updated information and examples about the profiles.
<xref linkend="more-info-automated-installation-agama"></xref>. The upstream
resources usually contain most updated information and examples about the profiles.
</para>
</section>
<section xml:id="minimal-example-agama-installation-profile">
<title>A minimal example of an &agama; profile</title>
<para>
A minimal &agama; JSON profile must at least include sections for product identification,
product registration, and credentials for the root user. &agama; uses the defaults for the
rest of the profile. As a best practice, you should also configure the following as a best
practice:
rest of the profile. As a best practice, you should also configure the following:
</para>
<simplelist><member>A hostname</member><member>
<simplelist><member>A host name</member><member>
A non-root user
</member><member>
Minimal localization settings
Expand Down Expand Up @@ -211,7 +209,7 @@
<calloutlist>
<callout arearefs="hashed-password">
<para>
You can generated a hashed password by running the following command:
You can generate a hashed password by running the following command:
</para>
<screen>&prompt.sudo;<command>openssl passwd -6</command></screen>
</callout>
Expand All @@ -222,8 +220,8 @@
<screen>&prompt.sudo;<command>ssh-keygen -t rsa -b 4096 -C "<replaceable>[email protected]</replaceable>"
</command></screen>
<para>
Based on your requirements, choose the key type and the key size. However, it's better
to adopt a stronger security.
Based on your requirements, choose the key type and the key size. However, it is better
to adopt stronger security.
</para>
</callout>
</calloutlist>
Expand Down
12 changes: 6 additions & 6 deletions glues/more-info-automated-installation-agama.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
<para>
<link xlink:href="https://agama-project.github.io/docs/user">&agama; user
documentation</link>: Organizes information by user perspective and covers a wide range of
topics, including interactive installation, unattended installation, Auto&yast; support,
topics, including interactive installation, unattended installation, &ay; support,
boot options, URLs, command-line reference, and remote access.
</para>
<itemizedlist>
Expand All @@ -64,9 +64,9 @@
<para>
<link
xlink:href="https://agama-project.github.io/docs/user/autoyast/reference">&agama;
Auto&yast; compatibility reference</link>: Essential for users migrating from
Auto&yast; or planning to reuse Auto&yast; profiles. It details the support status of
various Auto&yast; profile sections and elements within &agama;.
&ay; compatibility reference</link>: Essential for users migrating from
&ay; or planning to reuse &ay; profiles. It details the support status of
various &ay; profile sections and elements within &agama;.
</para>
</listitem>
<listitem>
Expand All @@ -80,7 +80,7 @@
<listitem>
<para>
<link xlink:href="https://github.com/agama-project/agama">&agama; project on GitHub</link>:
Contains source code for the &agama; installer, which you can use to deep dive into the
Contains the source code for the &agama; installer, which you can use to deep dive into the
installer's internals.
</para>
<itemizedlist>
Expand All @@ -95,7 +95,7 @@
<para>
<link
xlink:href="https://github.com/agama-project/agama/blob/master/rust/agama-lib/share/examples/profile.jsonnet">&agama;
profile example in Jsonnet</link>.
profile example in Jsonnet</link>
</para>
</listitem>
<listitem>
Expand Down
6 changes: 3 additions & 3 deletions references/agama-advanced-storage-configuration.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,12 +65,12 @@
</screen>
</example>
<note>
<title>Compatibility with legacy Auto&yast; storage</title>
<title>Compatibility with legacy &ay; storage</title>
<para>
In some cases, <literal>storage</literal> can be replaced by the
<literal>legacyAutoyastStorage</literal> section. This section supports everything offered
by the <literal>partitioning</literal> section of the Auto&yast; profile. However, &agama;
does not validate this special section&mdash;be careful to provide valid Auto&yast;
by the <literal>partitioning</literal> section of the &ay; profile. However, &agama;
does not validate this special section&mdash;be careful to provide valid &ay;
options.
</para>
</note>
Expand Down
Loading