Skip to content

2.5 Update automation content signing content for Containerized installat… #2825

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
Jan 27, 2025
Merged

2.5 Update automation content signing content for Containerized installat… #2825

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
18 changes: 10 additions & 8 deletions downstream/assemblies/platform/assembly-aap-containerized-installation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,19 @@ Each virtual machine (VM) has the following system requirements:

include::platform/proc-preparing-the-rhel-host-for-containerized-installation.adoc[leveloffset=+1]
include::platform/proc-downloading-containerized-aap.adoc[leveloffset=+1]
include::platform/ref-configuring-inventory-file.adoc[leveloffset=+1]
// Commenting this out until the feature has been released
// include::platform/proc-setup-postgresql-ext-database.adoc[leveloffset=+2]
include::platform/proc-set-registry-username-password.adoc[leveloffset=+2]
include::platform/ref-using-custom-tls-certificates.adoc[leveloffset=+2]
include::platform/ref-using-custom-receptor-signing-keys.adoc[leveloffset=+2]
include::platform/ref-enabling-automation-hub-collection-and-container-signing.adoc[leveloffset=+2]
include::platform/ref-adding-execution-nodes.adoc[leveloffset=+2]
include::platform/proc-add-eda-safe-plugin-var.adoc[leveloffset=+2]

include::platform/proc-installing-containerized-aap.adoc[leveloffset=+1]
//include::platform/proc-using-postinstall.adoc[leveloffset=+1]
include::platform/ref-accessing-control-auto-hub-eda-control.adoc[leveloffset=+1]
// Commenting this out until the feature has been released
// include::platform/proc-setup-postgresql-ext-database.adoc[leveloffset=+1]
include::platform/proc-set-registry-username-password.adoc[leveloffset=+1]
include::platform/ref-using-custom-tls-certificates.adoc[leveloffset=+1]
include::platform/ref-using-custom-receptor-signing-keys.adoc[leveloffset=+1]
include::platform/ref-enabling-automation-hub-collection-and-container-signing.adoc[leveloffset=+1]
include::platform/ref-adding-execution-nodes.adoc[leveloffset=+1]
include::platform/proc-add-eda-safe-plugin-var.adoc[leveloffset=+1]
include::platform/proc-update-aap-container.adoc[leveloffset=+1]
include::platform/proc-backup-aap-container.adoc[leveloffset=+1]
include::platform/proc-uninstalling-containerized-aap.adoc[leveloffset=+1]
Expand Down
92 changes: 0 additions & 92 deletions downstream/modules/platform/proc-installing-containerized-aap.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,98 +4,6 @@

= Installing containerized {PlatformNameShort}

[role="_abstract"]

You can control the installation of {PlatformNameShort} with inventory files. Inventory files define the hosts and containers used and created, variables for components, and other information needed to customize the installation.

Example inventory files are provided in this document that you can copy and change to quickly get started.

Inventory files for the growth and enterprise topologies are also found in the downloaded installer package:

* The default one named `inventory` is for the enterprise topology pattern.

* If you want to deploy the growth or all-in-one pattern you need to copy over or use the `inventory-growth` file instead.

Additionally, you can find example inventory files in link:{URLTopologies}/container-topologies[Container topologies] in _{TitleTopologies}_.

To use the example inventory files, replace the `< >` placeholders with your specific variables, and update the host names. Refer to the `README.md` file in the installation directory for more information about optional and required variables.

== Inventory file for online installation for containerized growth topology (all-in-one)

Use the example inventory file to perform an online installation for the containerized growth topology (all-in-one):

include::snippets/inventory-cont-a-env-a.adoc[]

[WARNING]
====
include::snippets/known-issue-container-content-syncing.adoc[]
====

== Inventory file for online installation for containerized enterprise topology

Use the example inventory file to perform an online installation for the containerized enterprise topology:

include::snippets/inventory-cont-b-env-a.adoc[]

.Redis configuration for an enterprise topology
include::snippets/redis-colocation-containerized.adoc[]
* By default the `redis_mode` is set to `cluster`.
** `redis_mode=cluster`

* For more information about Redis, see link:{URLPlanningGuide}/ha-redis_planning[Caching and queueing system] in _{TitlePlanningGuide}_.

== Additional information for configuring your inventory file

.Offline or bundled installation

* To perform an offline installation, add the following under the `[all:vars]` group:

----
bundle_install=true
# The bundle directory must include /bundle in the path
bundle_dir=<full path to the bundle directory>
----

.Configuring a HAProxy load balancer

* To configure a HAProxy load balancer in front of {Gateway} with a custom CA cert, set the following inventory file variables under the `[all:vars]` group:

----
custom_ca_cert=<path_to_cert_crt>
gateway_main_url=<https://load_balancer_url>
----

[NOTE]
====
HAProxy SSL passthrough mode is not supported with {Gateway}.
====

.Configuring shared storage for {HubName}

Shared storage is required when installing more than one instance of {HubName} with a `file` storage backend. When installing a single instance of the {HubName}, shared storage is optional.

* To configure shared storage for {HubName}, set the following variable in the inventory file, ensuring your network file system (NFS) share has read, write, and execute permissions:

----
hub_shared_data_path=<path_to_nfs_share>
----

* To change the mount options for your NFS share, use the `hub_shared_data_mount_opts` variable. This variable is optional and the default value is `rw,sync,hard`.


.Loading an {ControllerName} license file

* To define the location of your {ControllerName} license file, set the following variable in the inventory file:

----
controller_license_file=<full_path_to_your_manifest_zip_file>
----

//* To define the license file as part of the postinstall process instead, see xref:using-postinstall_{context}[Using the postinstall feature of containerized {PlatformNameShort}].


== Running the installation command

Use the following command to install containerized {PlatformNameShort}:

----
Expand Down
89 changes: 89 additions & 0 deletions downstream/modules/platform/ref-configuring-inventory-file.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
[id="configuring-inventory-file"]
= Configuring the inventory file

You can control the installation of {PlatformNameShort} with inventory files. Inventory files define the hosts and containers used and created, variables for components, and other information needed to customize the installation.

Example inventory files are provided in this document that you can copy and change to quickly get started.

Inventory files for the growth and enterprise topologies are also found in the downloaded installer package:

* The default one named `inventory` is for the enterprise topology pattern.

* If you want to deploy the growth or all-in-one pattern you need to copy over or use the `inventory-growth` file instead.

Additionally, you can find example inventory files in link:{URLTopologies}/container-topologies[Container topologies] in _{TitleTopologies}_.

To use the example inventory files, replace the `< >` placeholders with your specific variables, and update the host names. Refer to the `README.md` file in the installation directory for more information about optional and required variables.

== Inventory file for online installation for containerized growth topology (all-in-one)

Use the example inventory file to perform an online installation for the containerized growth topology (all-in-one):

include::snippets/inventory-cont-a-env-a.adoc[]

[WARNING]
====
include::snippets/known-issue-container-content-syncing.adoc[]
====

== Inventory file for online installation for containerized enterprise topology

Use the example inventory file to perform an online installation for the containerized enterprise topology:

include::snippets/inventory-cont-b-env-a.adoc[]

.Redis configuration for an enterprise topology
include::snippets/redis-colocation-containerized.adoc[]
* By default the `redis_mode` is set to `cluster`.
** `redis_mode=cluster`

* For more information about Redis, see link:{URLPlanningGuide}/ha-redis_planning[Caching and queueing system] in _{TitlePlanningGuide}_.

== Additional information for configuring your inventory file

.Offline or bundled installation

* To perform an offline installation, add the following under the `[all:vars]` group:

----
bundle_install=true
# The bundle directory must include /bundle in the path
bundle_dir=<full path to the bundle directory>
----

.Configuring a HAProxy load balancer

* To configure a HAProxy load balancer in front of {Gateway} with a custom CA cert, set the following inventory file variables under the `[all:vars]` group:

----
custom_ca_cert=<path_to_cert_crt>
gateway_main_url=<https://load_balancer_url>
----

[NOTE]
====
HAProxy SSL passthrough mode is not supported with {Gateway}.
====

.Configuring shared storage for {HubName}

Shared storage is required when installing more than one instance of {HubName} with a `file` storage backend. When installing a single instance of the {HubName}, shared storage is optional.

* To configure shared storage for {HubName}, set the following variable in the inventory file, ensuring your network file system (NFS) share has read, write, and execute permissions:

----
hub_shared_data_path=<path_to_nfs_share>
----

* To change the mount options for your NFS share, use the `hub_shared_data_mount_opts` variable. This variable is optional and the default value is `rw,sync,hard`.


.Loading an {ControllerName} license file

* To define the location of your {ControllerName} license file, set the following variable in the inventory file:

----
controller_license_file=<full_path_to_your_manifest_zip_file>
----

//* To define the license file as part of the postinstall process instead, see xref:using-postinstall_{context}[Using the postinstall feature of containerized {PlatformNameShort}].
139 changes: 131 additions & 8 deletions ...ules/platform/ref-enabling-automation-hub-collection-and-container-signing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,144 @@
:_mod-docs-content-type: REFERENCE

[id="enabling-automation-hub-collection-and-container-signing_{context}"]
= Enabling {HubNameStart} collection and container signing
= Enabling automation content collection and container signing

[role="_abstract"]
With {HubName} you can sign Ansible collections and container images. This feature is not enabled by default, and you must provide the GPG key.
Automation content signing is disabled by default. To enable it, the following installation variables are required in the inventory file:

----
#Collection signing
hub_collection_signing=true
hub_collection_signing_key=<full_path_to_collections_gpg_key>
hub_collection_signing_key=<full_path_to_collection_gpg_key>

#Container signing
hub_container_signing=true
hub_container_signing_key=<full_path_to_containers_gpg_key>
hub_container_signing_key=<full_path_to_container_gpg_key>
----

The following variables are required if the keys are protected by a passphrase:

----
#Collection signing
hub_collection_signing_pass=<gpg_key_passphrase>

#Container signing
hub_container_signing_pass=<gpg_key_passphrase>
----

The `hub_collection_signing_key` and `hub_container_signing_key` variables require the set up of keys before running an installation.

Automation content signing currently only supports GnuPG (GPG) based signature keys. For more information about GPG, see the link:https://www.gnupg.org/documentation/manpage.html[GnuPG man page].

[NOTE]
====
The algorithm and cipher used is the responsibility of the customer.
====

.Procedure

. On a RHEL9 server run the following command to create a new key pair for collection signing:
+
----
gpg --gen-key
----
+
. Enter your information for "Real name" and "Email address":
+
Example output:
+
----
gpg --gen-key
gpg (GnuPG) 2.3.3; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Note: Use "gpg --full-generate-key" for a full featured key generation dialog.

GnuPG needs to construct a user ID to identify your key.

Real name: Joe Bloggs
Email address: [email protected]
You selected this USER-ID:
"Joe Bloggs <[email protected]>"

Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
----
+
If this fails, your environment does not have the necessary prerequisite packages installed for GPG. Install the necessary packages to proceed.
+
. A dialog box will appear and ask you for a passphrase. This is optional but recommended.
. The keys are then generated, and produce output similar to the following:
+
----
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 022E4FBFB650F1C4 marked as ultimately trusted
gpg: revocation certificate stored as '/home/aapuser/.gnupg/openpgp-revocs.d/F001B037976969DD3E17A829022E4FBFB650F1C4.rev'
public and secret key created and signed.

pub rsa3072 2024-10-25 [SC] [expires: 2026-10-25]
F001B037976969DD3E17A829022E4FBFB650F1C4
uid Joe Bloggs <[email protected]>
sub rsa3072 2024-10-25 [E] [expires: 2026-10-25]
----
+
Note the expiry date that you can set based on company standards and needs.
+
. You can view all of your GPG keys by running the following command:
+
----
gpg --list-secret-keys --keyid-format=long
----
+
. To export the public key run the following command:
+
----
gpg --export -a --output collection-signing-key.pub <email_address_used_to_generate_key>
----
+
. To export the private key run the following command:
+
----
gpg -a --export-secret-keys <email_address_used_to_generate_key> > collection-signing-key.priv
----
+
. If a passphrase is detected, you will be prompted to enter the passphrase.
. To view the private key file contents, run the following command:
+
----
cat collection-signing-key.priv
----
+
Example output:
+
----
-----BEGIN PGP PRIVATE KEY BLOCK-----

lQWFBGcbN14BDADTg5BsZGbSGMHypUJMuzmIffzzz4LULrZA8L/I616lzpBHJvEs
sSN6KuKY1TcIwIDCCa/U5Obm46kurpP2Y+vNA1YSEtMJoSeHeamWMDd99f49ItBp

When the GPG key is protected by a passphrase, you must provide the passphrase.
<snippet>

j920hRy/3wJGRDBMFa4mlQg=
=uYEF
-----END PGP PRIVATE KEY BLOCK-----
----
hub_collection_signing_pass=<collections_gpg_key_passphrase>
hub_container_signing_pass=<containers_gpg_key_passphrase>
+
. Repeat steps 1 to 9 to create a key pair for container signing.
. Add the following variables to the inventory file and run the installation to create the signing services:
+
----
#Collection signing
hub_collection_signing=true
hub_collection_signing_key=/home/aapuser/aap/ansible-automation-platform-containerized-setup-2.5-2/collection-signing-key.priv
# This variable is required if the key is protected by a passphrase
hub_collection_signing_pass=<password>

#Container signing
hub_container_signing=true
hub_container_signing_key=/home/aapuser/aap/ansible-automation-platform-containerized-setup-2.5-2/container-signing-key.priv
# This variable is required if the key is protected by a passphrase
hub_container_signing_pass=<password>
----
Loading