Building cloud images for orcharhino

Use this section to build and register images to orcharhino.

You can use a preconfigured CentOS Stream KVM guest QCOW2 image:

These images contain cloud-init. To function properly, they must use ec2-compatible metadata services for provisioning an SSH key.

For the KVM guest images:

  • The root account in the image is disabled, but sudo access is granted to a special user named cloud-user.

  • There is no root password set for this image. The root password is locked in /etc/shadow by placing !! in the second field.

Creating custom CentOS Stream images

Prerequisites

  • Use a Linux host machine to create an image. In this example, we use a CentOS Stream 7 Workstation.

  • Use virt-manager on your workstation to complete this procedure. If you create the image on a remote server, connect to the server from your workstation with virt-manager.

  • A CentOS Stream 7 or 6 ISO file (see CentOS Stream 7.4 Binary DVD or CentOS Stream 6.9 Binary DVD).

For more information about installing a CentOS Stream Workstation, see the CentOS Stream 7 Installation Guide.

Before you can create custom images, install the following packages:

  • Install libvirt, qemu-kvm, and graphical tools:

    $ yum install virt-manager virt-viewer libvirt qemu-kvm

  • Install the following command line tools:

    $ yum install virt-install libguestfs-tools-c

In the following procedures, enter all commands with the [root@host]# prompt on the workstation that hosts the libvirt environment.

Supported clients in registration

orcharhino supports the following operating systems and architectures for registration.

Supported host operating systems

The hosts can use the following operating systems:

  • AlmaLinux

  • Amazon Linux

  • CentOS

  • Debian

  • Oracle Linux

  • Red Hat Enterprise Linux

  • Rocky Linux

  • SUSE Linux Enterprise Server

  • Ubuntu

Supported host architectures

The hosts can use the following architectures:

  • x86_64/amd64 is supported for all operating systems

  • aarch64 and ppc64le is supported for certain operating systems

    For more information, see orcharhino Client for CentOS Stream in the ATIX Service Portal.

Configuring a host for registration

Configure your host for registration to orcharhino Server or orcharhino Proxy Server. You can use a configuration management tool to configure multiple hosts at once.

Prerequisites

  • The host must be using a supported operating system. For more information, see supported clients in registration.

  • The system clock on your orcharhino Server and any orcharhino Proxy Servers must be synchronized across the network. If the system clock is not synchronized, SSL certificate verification might fail. For example, you can use the Chrony suite for timekeeping.

Procedure

  1. Enable and start a time-synchronization tool on your host. The host must be synchronized with the same NTP server as orcharhino Server and any orcharhino Proxy Servers.

    • On CentOS Stream 7 and later:

      $ systemctl enable --now chronyd

    • On CentOS Stream 6:

      $ chkconfig --add ntpd
$ chkconfig ntpd on
$ service ntpd start

  2. Deploy the SSL CA file on your host so that the host can make a secured registration call.

    1. Find where orcharhino stores the SSL CA file by navigating to Administer > Settings > Authentication and locating the value of the SSL CA file setting.

    2. Transfer the SSL CA file to your host securely, for example by using scp.

    3. Login to your host by using SSH.

    4. Copy the certificate to the truststore:

      • On CentOS Stream:

        $ cp My_SSL_CA_file.pem /etc/pki/ca-trust/source/anchors

    5. Update the truststore:

      • On CentOS Stream:

        $ update-ca-trust

Registering a host

You can register a host by using registration templates and set up various integration features and host tools during the registration process.

Prerequisites

  • Your user account has a role assigned that grants the create_hosts permission.

  • You must have root privileges on the host that you want to register.

  • You have configured the host for registration. For more information, see Configuring a Host for Registration.

  • You must either install curl or wget on the host that you want to register.

  • orcharhino Server, any orcharhino Proxy Servers, and your host must be synchronized with the same NTP server, and have a time synchronization tool enabled and running.

  • An activation key must be available for your host. For more information, see Managing Activation Keys in Managing Content.

  • orcharhino Client for CentOS Stream repository for the operating system version of the host is synchronized on orcharhino Server and enabled in the activation key you use.

  • If you want to use orcharhino Proxy Servers instead of your orcharhino Server, ensure that you have configured your orcharhino Proxy Servers accordingly. For more information, see Configuring orcharhino Proxy for Host Registration and Provisioning in Installing orcharhino Proxy Server.

  • If your orcharhino Server or orcharhino Proxy Server is behind an HTTP proxy, configure the Subscription Manager on your host to use the HTTP proxy for connection.

  • You have configured the operating system entry on orcharhino for CentOS Stream.

    You can use a script to add operating system entries to your orcharhino Server.

    On your orcharhino Server, uncomment the operating systems and orcharhino Client for CentOS Stream that you want to add in /etc/orcharhino-ansible/or_operating_systems_vars.yaml, replace the default organization and location names, and run /opt/orcharhino/automation/play_operating_systems.sh. For more information, see /usr/share/orcharhino-ansible/README.md on your orcharhino Server.
Procedure

  1. In the orcharhino management UI, navigate to Hosts > Register Host.

  2. Enter the details for how you want the registered hosts to be configured.

  3. On the General tab, in the Activation Keys field, enter one or more activation keys to assign to hosts.

  4. If you want to use wget to register your host to orcharhino, select wget in the Download Utility dropdown. By default, orcharhino generates a curl command.

  5. If your host does not trust the SSL certificate of your orcharhino Server, select the Insecure option. During the first call, your host downloads the CA file from orcharhino. Your host will use this CA file to connect to orcharhino Server with all future calls.

    ATIX AG recommends that you avoid insecure calls.

    If an attacker, located in the network between orcharhino and your host, fetches the CA file from the first insecure call, the attacker will be able to access the content of the API calls to and from your host and the JSON Web Tokens (JWT). Therefore, if you have chosen to deploy SSH keys during registration, the attacker will be able to access your host using the SSH key.

  6. In the Repositories field, click Add repositories for registration.

    On the Repository list window, add content that is required before performing the registration. For example, it can be useful to make the subscription-manager package available for the purpose of the registration.

    • In the Repository field, enter a repository to be added before the registration is performed. For CentOS Stream, enter the path to the orcharhino Client for CentOS Stream repository, for example http://orcharhino.example.com/pulp/content/Example/Library/custom/centos_client/centos_client/.

    • Optional: In the Repository GPG key URL field, specify the public key to verify the signatures of GPG-signed packages. It needs to be specified in the ASCII form with the GPG public key header.

    You do not have to specify repositories if you provide them in an activation key. To verify synchronized Yum content, you can use orcharhino API to get associated GPG public keys of repositories. For example, https://orcharhino.example.com/katello/api/v2/repositories/My_Repository_ID/gpg_key_content.

  7. Optional: In the Token lifetime (hours) field, change the validity duration of the JSON Web Token (JWT) that orcharhino uses for authentication. The duration of this token defines how long the generated registration command works. You can set the duration to 0 – 999 999 hours or unlimited.

    Note that orcharhino applies the permissions of the user who generates the registration command to authorization of your host. If the user loses or gains additional permissions, the permissions of the JWT change too. Therefore, do not delete, block, or change permissions of the user during the token duration.

    The scope of the JWTs is limited to the registration endpoints only and cannot be used anywhere else.

  8. Click Generate.

  9. Copy the generated registration command.

  10. On the host that you want to register, run the copied command as root.

CLI procedure

  1. Use the hammer host-registration generate-command to generate the registration command to register the host.

  2. On the host that you want to register, run the registration command as root.

For more information, see the Hammer CLI help with hammer host-registration generate-command --help.

Ansible procedure

  • Use the "`theforeman.foreman`".registration_command module.

For more information, see the Ansible module documentation with ansible-doc "`theforeman.foreman`".registration_command.

API procedure

  • Use the POST /api/registration_commands resource.

For more information, see the full API reference at https://orcharhino.example.com/apidoc/v2.html.

Installing and configuring Puppet agent manually

You can install and configure the Puppet agent on a host manually. A configured Puppet agent is required on the host for Puppet integration with your orcharhino. For more information about Puppet, see Configuring Hosts Using Puppet.

Prerequisites
Procedure

  1. Log in to the host as the root user.

  2. Install the Puppet agent package:

    $ dnf install puppet-agent

  3. Add the Puppet agent to PATH in your current shell using the following script:

    . /etc/profile.d/puppet-agent.sh

  4. Configure the Puppet agent. Set the environment parameter to the name of the Puppet environment to which the host belongs:

    $ puppet config set server orcharhino.example.com --section agent
$ puppet config set environment My_Puppet_Environment --section agent

  5. Start the Puppet agent service:

    $ puppet resource service puppet ensure=running enable=true

  6. Create a certificate for the host:

    $ puppet ssl bootstrap

  7. In the orcharhino management UI, navigate to Infrastructure > orcharhino Proxies.

  8. From the list in the Actions column for the required orcharhino Proxy Server, select Certificates.

  9. Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.

  10. On the host, run the Puppet agent again:

    $ puppet ssl bootstrap

Completing the CentOS Stream 7 image

Procedure

  1. Update the system:

    $ yum update

  2. Install the cloud-init packages:

    $ yum install cloud-utils-growpart cloud-init

  3. Open the /etc/cloud/cloud.cfg configuration file:

    $ vi /etc/cloud/cloud.cfg

  4. Under the heading cloud_init_modules, add:

    - resolv-conf

    The resolv-conf option automatically configures the resolv.conf when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain and other options.

  5. Open the /etc/sysconfig/network file:

    $ vi /etc/sysconfig/network

  6. Add the following line to avoid problems accessing the EC2 metadata service:

    NOZEROCONF=yes

  7. Un-register the virtual machine so that the resulting image does not contain the same subscription details for every instance cloned based on it:

    $ subscription-manager repos --disable=*
$ subscription-manager unregister

  8. Power off the instance:

    $ poweroff

  9. On your CentOS Stream Workstation, connect to the terminal as the root user and navigate to the /var/lib/libvirt/images/ directory:

    $ cd /var/lib/libvirt/images/

  10. Reset and clean the image using the virt-sysprep command so it can be used to create instances without issues:

    $ virt-sysprep -d rhel7

  11. Reduce image size using the virt-sparsify command. This command converts any free space within the disk image back to free space within the host:

    $ virt-sparsify --compress rhel7.qcow2 rhel7-cloud.qcow2

    This creates a new rhel7-cloud.qcow2 file in the location where you enter the command.

Completing the CentOS Stream 6 image

Procedure

  1. Update the system:

    $ yum update

  2. Install the cloud-init packages:

    $ yum install cloud-utils-growpart cloud-init

  3. Edit the /etc/cloud/cloud.cfg configuration file and under cloud_init_modules add:

    - resolv-conf

    The resolv-conf option automatically configures the resolv.conf configuration file when an instance boots for the first time. This file contains information related to the instance such as nameservers, domain, and other options.

  4. To prevent network issues, create the /etc/udev/rules.d/75-persistent-net-generator.rules file as follows:

    $ echo "#" > /etc/udev/rules.d/75-persistent-net-generator.rules

    This prevents /etc/udev/rules.d/70-persistent-net.rules file from being created. If /etc/udev/rules.d/70-persistent-net.rules is created, networking might not function properly when booting from snapshots (the network interface is created as "eth1" rather than "eth0" and IP address is not assigned).

  5. Add the following line to /etc/sysconfig/network to avoid problems accessing the EC2 metadata service:

    NOZEROCONF=yes

  6. Un-register the virtual machine so that the resulting image does not contain the same subscription details for every instance cloned based on it:

    $ subscription-manager repos --disable=*
$ subscription-manager unregister
$ yum clean all

  7. Power off the instance:

    $ poweroff

  8. On your CentOS Stream Workstation, log in as root and reset and clean the image using the virt-sysprep command so it can be used to create instances without issues:

    $ virt-sysprep -d rhel6

  9. Reduce image size using the virt-sparsify command. This command converts any free space within the disk image back to free space within the host:

    $ virt-sparsify --compress rhel6.qcow2 rhel6-cloud.qcow2

    This creates a new rhel6-cloud.qcow2 file in the location where you enter the command.

    You must manually resize the partitions of instances based on the image in accordance with the disk space in the flavor that is applied to the instance.

Next steps

  • Repeat the procedures for every image that you want to provision with orcharhino.

  • Move the image to the location where you want to store for future use.

Next steps

  • Repeat the procedures for every image that you want to provision with orcharhino.

  • Move the image to the location where you want to store for future use.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution Share Alike 4.0 International ("CC BY-SA 4.0") license. This page also contains text from the official Foreman documentation which uses the same license ("CC BY-SA 4.0").