Deploy a RHEL appliance in a disconnected environment

Deploy the Ansible automation portal RHEL appliance in a disconnected or air-gapped environment where the appliance has no access to external registries or the internet.

Before you begin

You have downloaded the appliance disk image (QCOW2 or VMDK) from the This content is not included.Red Hat Ansible Automation Platform downloads page on a connected system.
You have a method to transfer the disk image to the disconnected environment (for example, removable media, secure file transfer, or an internal mirror registry).
You have a virtualization platform available in the disconnected environment (Red Hat OpenShift Virtualization, VMware vSphere, or KVM).
You have network connectivity from the appliance to your Ansible Automation Platform instance (internal network).
You have Ansible Automation Platform credentials: host URL, API token, OAuth client ID, and OAuth client secret. See This content is not included.Pre-installation configuration in the installation guide.
You have an SSH key pair for appliance access.

About this task

The appliance image includes everything needed to run without pulling content from external registries:

Pre-bundled Ansible plugins: Dynamic plugins are extracted at build time and stored at /usr/share/portal/plugins/. The appliance loads plugins from the local filesystem, not from a registry.
Pre-pulled container images: The Ansible automation portal and PostgreSQL container images are embedded in the appliance image. No container image pulls occur at runtime.
Self-signed SSL certificates: Generated locally at first boot. You can replace them with your own certificates after deployment.
No registry authentication required: The appliance starts and runs without registry credentials. Registry authentication is only needed for future upgrades.

Procedure

Transfer the appliance image

Transfer the disk image from a connected machine to your disconnected environment. Choose the method that fits your network topology.
Removable media: Copy the disk image directly to the disconnected host using removable media (USB drive, portable storage) or a secure file transfer mechanism.
1. On a connected machine, download the QCOW2 or VMDK disk image from the This content is not included.Red Hat Ansible Automation Platform downloads page.
2. Copy the disk image to removable media.
3. Transfer the media to the disconnected environment and copy the image to the target host. For example, for a KVM deployment:
```
$ rsync --progress /media/usb/portal-appliance.qcow2 /var/lib/libvirt/images/portal-appliance.qcow2
```
Internal mirror registry: If your disconnected environment has an internal container registry, you can copy the bootc container image to your mirror and build disk images from it.
1. On a connected machine, copy the bootc container image to your internal registry:
```
$ skopeo copy \
  docker://registry.redhat.io/ansible-automation-platform/bootc-automation-portal-rhel9:<version> \
  docker://mirror.internal.example.com:5000/ansible-automation-platform/bootc-automation-portal-rhel9:<version>
```
2. If your mirror registry uses a self-signed certificate, add the CA certificate to the system trust store on the machine where you will build the disk image:
```
$ sudo cp ca.crt /etc/pki/ca-trust/source/anchors/
$ sudo update-ca-trust
```
3. Build the disk image from the mirror registry in your disconnected environment. Refer to the Red Hat documentation for building bootc disk images from a custom registry source.
4. Deploy the resulting disk image using the standard installation procedure for your platform.

Deploy the appliance

Deploy the appliance on your virtualization platform following the standard deployment procedure for your environment:
- For RHEL with KVM, see Install Ansible automation portal on RHEL with KVM.
- For Red Hat OpenShift Virtualization, see Install Ansible automation portal on Red Hat OpenShift Virtualization.
- For VMware vSphere, see Install Ansible automation portal on VMware vSphere.

Configure the appliance

Provide initial configuration through cloud-init, VMware guestinfo properties, or a pre-seeded configuration file.
The cloud-init configuration for a disconnected deployment is the same as a connected deployment. Use the templates from Configure the appliance at first boot.

The following differences apply in a disconnected environment:
- Source control integrations require network access. The integrations.github and integrations.gitlab cloud-init fields require network access to the source control service. If your disconnected environment has internal GitHub Enterprise or GitLab instances, configure these fields with the internal hostnames.
- Set network.base_url to match your internal DNS or IP. Set network.base_url to the hostname or IP address that users will use to access the Ansible automation portal RHEL appliance on your internal network. If omitted, the appliance auto-detects the VM IP address.
Minimal cloud-init template for disconnected deployment:
```
#cloud-config

users:
  - name: <username>
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - "<your-ssh-public-key>"

aap:
  host_url: "https://<internal-aap-host>"
  token: "<aap-api-token>"
  oauth:
    client_id: "<oauth-client-id>"
    client_secret: "<oauth-client-secret>"

database:
  type: builtin
  builtin:
    password: "auto"
    admin_password: "auto"
```

Verify the installation

SSH into the Ansible automation portal RHEL appliance:
```
$ ssh <username>@<appliance-ip>
```
Check that all three services are running:
```
$ sudo systemctl status portal postgres devtools
```
All three services (portal, postgres, devtools) should show active (running).

Alternatively, use the portal management CLI for detailed diagnostics:
```
$ sudo ansible-portal status
```
Verify that the Ansible automation portal is accessible:
```
$ curl -fk https://<appliance-address>
```
Verify that Ansible plugins loaded from the local filesystem:
```
$ sudo podman exec portal ls /opt/app-root/src/dynamic-plugins-root/
```
You should see plugin directories listed. These plugins were loaded from the pre-baked files at /usr/share/portal/plugins/, not from a registry.

Set up registry credentials for upgrades (optional)

If you plan to upgrade the appliance using bootc upgrade from registry.redhat.io or a mirror registry, log in to the container registry and save the credentials:
```
$ sudo podman login --authfile /etc/ostree/auth.json registry.redhat.io
```
The /etc/ostree/auth.json file is what bootc upgrade and bootc switch use for registry authentication.

If no registry is available for image upgrades, you can bypass the registry authentication gate:
```
$ sudo touch /etc/portal/.registry-auth-override
```
This override marker allows the appliance to start without registry credentials. It is preserved across backups, restores, and bootc upgrades.

Results

Verify that the portal URL is accessible from your browser.
Verify that all services show a healthy status.

What to do next

For appliance upgrades in disconnected environments, see Upgrade the appliance in a disconnected environment.