Document structured APT content (#3464)

guides/common/assembly_importing-content.adoc

@@ -99,6 +99,10 @@ endif::[]
 ifndef::satellite[]
 include::modules/proc_extracting-gpg-public-key-fingerprints-from-release-files.adoc[leveloffset=+1]
 
+include::modules/con_structured-apt-content.adoc[leveloffset=+1]
+
+include::modules/proc_enabling-structured-apt-content.adoc[leveloffset=+1]
+
 include::modules/proc_adding-custom-deb-repositories.adoc[leveloffset=+1]
 
 :parent-DL: {DL}

guides/common/modules/con_structured-apt-content.adoc

@@ -0,0 +1,40 @@
+[id="Structured-apt-content"]
+= Structured APT content
+
+With structured APT content, Deb repositories on {Project} use the same structure as the upstream Deb repository.
+This allows features that attach to the repository structure to work the same way as they would with the upstream repository, for example:
+
+* `apt list --upgradable` will no longer list `unknown,unknown` as the release and distribution for packages.
+Instead, `apt` will list the proper release and distribution from the upstream repository.
+* You can use client-side APT pinning in the same way as when using the upstream repository directly.
+
+.Comprehensibility
+With structured APT content, repositories in {Project} use the same structure as the upstream repository.
+They do not use the special `default/all` publication concept which does not exist outside of {Project}.
+
+.Performance
+With structured APT content, publishing repository metadata will take roughly half the time, compared to publishing without structured APT content.
+
+.Limitations
+* Once you have enabled structured APT on {Project}, do not disable it.
+Using structured APT content will be mandatory with a future {Project} version.
+* Any Deb packages that were uploaded to
+ifdef::katello[]
+{Project} 3.2
+endif::[]
+ifdef::orcharhino[]
+{Project} 6.4
+endif::[]
+and older are not automatically migrated to structured APT content.
+You can work around this issue by deleting and re-uploading affected Deb packages.
+
+.Prerequisites for hosts
+* The host is registered to {ProjectName}.
+include::snip_prerequisite-project-client-repository-enabled.adoc[]
+ifdef::orcharhino[]
+* Your {DL} host uses the latest {project-client-name}.
+For more information, see https://atixservice.zendesk.com/hc/de/articles/16326419356572[Deb content: Using structured APT] in _ATIX Service Portal_.
+endif::[]
+ifndef::orcharhino[]
+* Your {DL} host runs `subscription-manager` version 1.29.35-3 or higher.
+endif::[]

guides/common/modules/proc_enabling-structured-apt-content.adoc

@@ -0,0 +1,41 @@
+[id="enabling-structured-apt-content"]
+= Enabling structured APT content
+
+You can enable structured APT content on your {Project} to use the same Deb repository structure as the remote repositories they are synchronized from.
+
+.Procedure
+. Backup your {ProjectServer}.
++
+For more information, see {AdministeringDocURL}backing-up-{project-context}-server-and-{smart-proxy-context}_admin[Backing Up {ProjectServer} and {SmartProxyServer}] in _{AdministeringDocTitle}_.
+. Ensure that there are no running tasks:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} health check --label foreman-tasks-not-running
+----
+. In the {ProjectWebUI}, navigate to *Administer* > *Settings*.
+. On the *Content* tab, set the *Enable structured APT for deb content* setting to `Yes`.
+. On your {ProjectServer}, start {Project} maintenance mode:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} maintenance-mode start
+----
+. Migrate your Deb content:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# foreman-rake katello:migrate_structure_content_for_deb
+----
++
+On {Project} with 40 Deb repositories published to many content view versions and promoted to multiple lifecycle environments each, this step took 15 minutes.
+The amount of time depends on the number of packages, repositories, content view versions, and other tasks running on your {ProjectServer}.
+. Stop {Project} maintenance mode:
++
+[options="nowrap" subs="+quotes,verbatim,attributes"]
+----
+# {foreman-maintain} maintenance-mode stop
+----
+. Perform a complete sync of your {SmartProxyServers} that provide Deb content to hosts.
++
+For more information, see {AdministeringDocURL}Synchronizing_Content_from_{project-context}_Server_to_{smart-proxy-context-titlecase}_Servers_admin[Synchronizing content from {ProjectServer} to {SmartProxyServers}] in _{AdministeringDocTitle}_.