Skip to content

AAP-68189: Update RHEL appliance docs for GA readiness #5918

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

Open
jklech-work wants to merge 1 commit into
base: main
Choose a base branch
from
Open

AAP-68189: Update RHEL appliance docs for GA readiness #5918

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
2 changes: 2 additions & 0 deletions downstream/assemblies/devtools/assembly-self-service-install-rhel-appliance.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ include::devtools/proc-self-service-install-vmware.adoc[leveloffset=+1]

include::devtools/proc-self-service-initial-config-wizard.adoc[leveloffset=+1]

include::devtools/proc_deploy-a-rhel-appliance-in-a-disconnected-environment.adoc[leveloffset=+1]

include::devtools/ref-self-service-portal-cli-commands.adoc[leveloffset=+1]

include::devtools/ref-self-service-rhel-troubleshooting.adoc[leveloffset=+1]
Expand Down
26 changes: 22 additions & 4 deletions downstream/modules/devtools/con-self-service-rhel-appliances.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

[role="_abstract"]

The {SelfService} RHEL 9 virtual machine appliances provide pre-configured virtual machines that you can deploy across multiple virtualization platforms.
The {SelfService} {RHEL} virtual machine appliances provide pre-configured virtual machines that you can deploy across multiple virtualization platforms.

The appliances are available in the following formats:

Expand All @@ -30,16 +30,34 @@ QEMU for local testing:: Deploy the appliance on your local machine for testing

== Initial configuration

After starting the appliance, an interactive configuration wizard guides you through the initial setup. The wizard prompts you to configure:
The appliance supports multiple methods for providing initial configuration:

Interactive wizard:: An interactive text-based wizard guides you through the setup. The wizard runs automatically on first boot if no other configuration source is detected.

cloud-init user-data:: For cloud and {OCPVShort} deployments, provide SSH keys and portal configuration through cloud-init user-data. The appliance configures itself automatically on first boot.

VMware OVF properties:: For VMware deployments, provide SSH keys and portal configuration through `guestinfo` properties set in `vSphere`.

Pre-seeded configuration file:: Place a YAML configuration file at `/etc/portal/config.yaml` before first boot for automated deployment without interactive prompts.

The configuration wizard prompts you to configure:

* SSH key authentication for administrative access
* Network settings
* {PlatformNameShort} OAuth application credentials
* {PlatformNameShort} admin token for authentication

After the configuration wizard completes, the appliance displays the portal URL that you can access from your browser.
After the initial configuration completes, the appliance displays the portal URL that you can access from your browser.

[NOTE]
====
You cannot log in to the virtual machine console with a username and password after the wizard completes. Administrative access is available only through SSH using the key you provided during initial configuration.
After the initial configuration completes, the admin user account is locked and console login is disabled. Administrative access is available only through SSH using the key you provided during configuration.
====

== Disconnected environments

You can deploy {SelfService} appliances in disconnected or air-gapped environments.
The pre-built appliance images include all required container images and plug-ins, so no external network access is required during initial deployment.

For appliance upgrades in disconnected environments, a mirror registry or OCI archive provides the updated container images.
The `portal-registry-login` command authenticates to a private registry mirror.
95 changes: 95 additions & 0 deletions ...odules/devtools/proc_deploy-a-rhel-appliance-in-a-disconnected-environment.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
:_newdoc-version: 2.18.7
:_template-generated: 2026-04-09
:_mod-docs-content-type: PROCEDURE

[id="deploy-a-rhel-appliance-in-a-disconnected-environment_{context}"]
= Deploy a RHEL appliance in a disconnected environment

[role="_abstract"]
Deploy the {SelfService} RHEL appliance in a disconnected or air-gapped environment where the appliance has no access to external registries or the internet.
The pre-built appliance images include all required container images and plug-ins, so no external network access is required during initial deployment.

.Prerequisites

* You have downloaded the appliance disk image (QCOW2 or VMDK) from the Red Hat Customer Portal on a connected system.
* You have a method to transfer the disk image to the disconnected environment (for example, portable media or a secure file transfer system).
* You have a virtualization platform available in the disconnected environment ({OCPVShort}, VMware vSphere, or KVM/QEMU).

.Procedure

. On a connected system, download the appliance disk image from the link:https://access.redhat.com[Red Hat Customer Portal].

. Transfer the disk image to the disconnected environment using your organization's approved transfer method.

. Deploy the appliance on your virtualization platform following the standard deployment procedure for your environment:
+
* For {OCPVShort}, see xref:proc-self-service-install-openshift-virt_{context}[Deploying on OpenShift Virtualization].
* For VMware vSphere, see xref:proc-self-service-install-vmware_{context}[Deploying on VMware vSphere].

. Complete the initial configuration wizard.
+
The appliance starts and runs without external network access because all required container images and plug-ins are pre-loaded in the appliance image.

. Verify that the portal services are running:
+
[source,terminal]
----
sudo portal-status
----

.Verification

* Verify that the portal URL is accessible from your browser.
* Verify that all services show a healthy status in the `portal-status` output.

.Next steps

* To apply future appliance upgrades in a disconnected environment, configure authentication to a private registry mirror that hosts the {SelfService} container images:
+
.. On a connected system, mirror the {SelfService} container images from `registry.redhat.io` to your private registry.
.. On the appliance, authenticate to your private registry mirror:
+
[source,terminal]
----
sudo portal-registry-login <your_mirror_registry>
----
+
.. Verify that the credentials are valid:
+
[source,terminal]
----
sudo portal-registry-login --test
----
+
If authentication fails, verify that the mirror registry is reachable from the appliance, check that any custom CA certificates are trusted, and verify your credentials are correct.
+
.. Switch the appliance to track images from your mirror registry (one-time operation):
+
[source,terminal]
----
sudo bootc switch <your_mirror_registry>/<image_path>
----
+
The system reboots automatically after applying the change.
+
.. For subsequent upgrades, pull the latest update:
+
[source,terminal]
----
sudo bootc upgrade --apply
----
+
The system reboots automatically. Wait for the system to restart, then reconnect via SSH.
+
.. If an upgrade causes issues, roll back to the previous version:
+
[source,terminal]
----
sudo bootc rollback
----

[role="_additional-resources"]
.Additional resources

* xref:ref-self-service-portal-cli-commands_{context}[Portal CLI commands reference]
* xref:ref-self-service-rhel-troubleshooting_{context}[Troubleshooting RHEL appliances]
132 changes: 110 additions & 22 deletions downstream/modules/devtools/ref-self-service-portal-cli-commands.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ You can access the appliance using SSH with the key you provided during initial

[source,terminal,subs="+attributes"]
----
ssh -i /path/to/ssh-key/id_ed25519 -p <port-number> admin@<VM_IP>
ssh -i /path/to/ssh-key/id_ed25519 -p <port_number> admin@<VM_IP>
----

Replace the following placeholders:

* `/path/to/ssh-key/id_ed25519` with the path to your SSH private key.
* `<port-number>` with the SSH port number (default is 22).
* `<port_number>` with the SSH port number (default is 22).
* `<VM_IP>` with the IP address or hostname of your appliance.

== Available commands
Expand All @@ -30,44 +30,57 @@ The following commands are available for managing the {SelfService} appliance:
=== portal-config

Manages the portal configuration settings.
Use `portal-config` to view, modify, export, import, or roll back configuration on an already-configured appliance.

*Usage:*

[source,terminal,subs="+attributes"]
----
sudo portal-config show # View current configuration
sudo portal-config edit # Modify configuration settings
sudo portal-config show # View current configuration
sudo portal-config show --secrets # View configuration including sensitive values
sudo portal-config edit # Open interactive configuration editor
sudo portal-config export --format yaml # Export configuration to stdout
sudo portal-config import /path/to/config.yaml # Import configuration from file
sudo portal-config set KEY=VALUE # Set a single configuration value
sudo portal-config rollback --list # List configuration snapshots
sudo portal-config rollback --previous # Roll back to most recent snapshot
sudo portal-config regenerate-secrets # Regenerate portal secrets
----

*Description:*

* `portal-config show` displays the current portal configuration, including {PlatformNameShort} connection details and service settings.
* `portal-config edit` opens an interactive editor to modify the portal configuration.

Use `portal-config` to update existing configuration settings after the initial setup is complete.
* `portal-config show` displays the current portal configuration, including {PlatformNameShort} connection details and service settings. Add `--secrets` to display sensitive values (requires root).
* `portal-config edit` opens the interactive setup wizard pre-filled with the current configuration (requires root).
* `portal-config export` exports the current configuration to stdout. Use `--format` to specify the output format (`yaml` or `env`).
* `portal-config import` imports a configuration from a YAML or `.env` file.
* `portal-config set` sets a single configuration key-value pair, for example `AAP_HOST_URL=https://aap.example.com`.
* `portal-config rollback` lists or restores previous configuration snapshots. Use `--previous` to roll back to the most recent snapshot, or specify a timestamp to roll back to a specific entry.
* `portal-config regenerate-secrets` regenerates portal secrets (requires root).

=== portal-setup

Runs the initial configuration wizard or imports a configuration.
Runs the initial configuration wizard or applies a configuration file non-interactively.

*Usage:*

[source,terminal,subs="+attributes"]
----
sudo portal-setup # Run the initial configuration wizard
sudo portal-setup import # Import a configuration file
sudo portal-setup # Interactive wizard
sudo portal-setup --config /path/to/config.env # Pre-fill wizard from config file
sudo portal-setup --config /path/to/config.env --accept-defaults # Non-interactive mode
----

*Description:*

* `portal-setup` launches the interactive configuration wizard, which is the same wizard that runs automatically on first boot.
* `portal-setup import` imports a previously exported configuration file.
* `portal-setup --config` pre-fills the wizard with values from a configuration file.
* `portal-setup --config --accept-defaults` applies the configuration non-interactively without prompting.

[IMPORTANT]
====
*Difference between portal-setup and portal-config:*

* Use `portal-setup` to run the complete initial configuration wizard or to import an entire configuration from a file. This command is typically used during initial deployment or when migrating to a new appliance.
* Use `portal-setup` to run the complete initial configuration wizard or to apply an entire configuration from a file. This command is typically used during initial deployment or when migrating to a new appliance.
* Use `portal-config` to view or modify individual configuration settings on an already-configured appliance. This command is used for day-to-day configuration updates.
====

Expand All @@ -79,7 +92,8 @@ Checks the status of portal services.

[source,terminal,subs="+attributes"]
----
portal-status
sudo portal-status # One-shot status display
sudo portal-status --watch # Refresh status every 5 seconds
----

*Description:*
Expand All @@ -92,6 +106,7 @@ Displays the current status of all {SelfService} services, including:
* Network connectivity status

Use this command to verify that all services are running correctly after installation or troubleshooting.
Use `--watch` to continuously monitor service status.

*Example output:*

Expand All @@ -113,26 +128,99 @@ Creates a backup of the portal configuration and data.

[source,terminal,subs="+attributes"]
----
sudo portal-backup
sudo portal-backup --output /path/to/backup
sudo portal-backup # Interactive backup (select content)
sudo portal-backup --full # Full backup (all items)
sudo portal-backup --minimal # Required items only
sudo portal-backup --list # List existing backups
sudo portal-backup --export /path/to/dir/ # Copy latest backup to a directory
----

*Description:*

Creates a backup archive containing the portal configuration, settings, and data. Use this command before making significant configuration changes or for disaster recovery planning.

The backup includes:
* `portal-backup` without options starts an interactive backup where you select the content to include.
* `portal-backup --full` creates a complete backup of all configuration and data.
* `portal-backup --minimal` backs up only the required configuration items.
* `portal-backup --list` lists existing backups.
* `portal-backup --export` copies the latest backup to the specified directory. If no backup exists, one is created first.

[NOTE]
====
Store backup files in a secure location. Backup archives contain sensitive credentials. Protect them accordingly.
====

=== portal-apply

* Portal configuration settings
* {PlatformNameShort} OAuth application credentials
* User customizations
* Service configurations
Applies a configuration file and optionally restarts services.

*Usage:*

[source,terminal,subs="+attributes"]
----
sudo portal-apply --config /path/to/config.env
sudo portal-apply --config config.yaml --test-connections
----

*Description:*

Applies portal configuration from a YAML, JSON, or `.env` file.

* `--config` specifies the configuration file to apply (required).
* `--test-connections` tests the {PlatformNameShort} and database connections before applying the configuration.
* `--output-json` outputs the result as JSON.

=== portal-restore

Restores the portal from a backup.

*Usage:*

[source,terminal,subs="+attributes"]
----
sudo portal-restore --list # List available backups
sudo portal-restore --latest # Restore the newest backup
sudo portal-restore /path/to/backup.tar.gz # Restore a specific backup file
----

*Description:*

Restores the portal configuration and data from a backup created by `portal-backup`.

* `portal-restore --list` lists all available backups.
* `portal-restore --latest` restores from the most recent backup.
* `portal-restore` with a file path restores from a specific backup archive.

[NOTE]
====
Store backup files in a secure location. Backup archives contain sensitive credentials and should be protected accordingly.
Restoring a backup overwrites the current portal configuration. Create a backup of the current state before restoring if you want to preserve it.
====

=== portal-registry-login

Manages container registry credentials for pulling portal images.

*Usage:*

[source,terminal,subs="+attributes"]
----
sudo portal-registry-login # Log in to registry.redhat.io (default)
sudo portal-registry-login quay.io # Log in to a specific registry
sudo portal-registry-login --test # Test stored credentials
sudo portal-registry-login --logout # Remove stored credentials
----

*Description:*

Manages authentication to container registries used for pulling {SelfService} images and updates.

* `portal-registry-login` without arguments prompts for credentials for `registry.redhat.io`.
* Specify a registry hostname to authenticate to a different registry.
* `--test` verifies that stored credentials are valid.
* `--logout` removes stored credentials for the registry.

Use this command to configure registry authentication for `bootc upgrade` operations. In disconnected environments, use this command to authenticate to your private registry mirror.

== Additional resources

* For information about the initial configuration wizard, see xref:proc-self-service-initial-config-wizard_{context}[Completing the initial configuration wizard].
Expand Down
Loading