Preparation

When the mirror is ready #

Machine shtil (administrator’s workstation) #

Machine shtil is a workstation or jump host with Linux OS, from which the shtil utility is called.

The following must be done on the machine:

• Podman is available from the bundle; the executable file is located in PATH. If running shtil on the same host where the mirror is initialized, do not manually install Podman/Docker. If you are using Docker and the mirror has a self-signed or corporate CA, trust in the mirror is configured at the Docker daemon level before running shtil; the --bootstrap-insecure flag is not enough for the primary docker pull.
• There is network access to the FQDN of the mirror via HTTPS (port according to the mirror settings, usually 443).
• The GUI script (install-gui) requires sufficient permissions to work with the /tmp directory, usually when run as root or via sudo.

The shtil executable file is included in the bundle. After unpacking the bundle, copy the utility to the shtil machine and make the file executable:

chmod +x ./shtil

The shtil version must match the bundle version.

Commands for checking before installation #

Below are typical checks before running shtil. Substitute MIRROR-FQDN and VIP addresses from your schema (see requirements).

DNS: mirror name is resolved (machine quiet and node if necessary) #

getent hosts FQDN-MIRRORS

Success Criteria: The output contains the IP address of the mirror.

If there are no records: configure a corporate DNS or local resolver; Without resolution, nodes and shtil will not be able to access the mirror via HTTPS. For a temporary diagnosis, you can check the local /etc/hosts, but a permanent solution must comply with your infrastructure policy.

HTTPS to mirror (shtil machine or node) #

curl -I --connect-timeout 10 https://FQDN-MIRRORS

Success criterion: in the response HTTP/1.1 200 or HTTP/2 200 (or other successful code from your Nginx/mirror).

If there is no answer or there is an error - follow the steps:

1. Check the detailed output: it will show where the break is - DNS, TCP, TLS or server response.

curl -vI --connect-timeout 10 https://FQDN-MIRRORS

2. Check that the mirror port is accessible from the shtil machine and from the cluster nodes. If the mirror listens on something other than 443, specify the actual port:

curl -vI --connect-timeout 10 https://FQDN-MIRROR:PORT

3. If there is a TLS error with a self-signed certificate, the following can be used for diagnostics:

curl -vkI --connect-timeout 10 https://FQDN-MIRRORS

For a production installation, negotiate trust in the CA or use the --bootstrap-insecure / --bootstrap-registry-certs-dir flags when running shtil (see installation process).

Setting up a Docker mirror trust #

The --bootstrap-insecure and --bootstrap-registry-certs-dir flags affect containerd inside the bootstrap cluster (via hosts.toml or CA mounting). These flags do not configure the local Docker daemon to be trusted.

The initial TLS check at docker pull is performed by the Docker daemon itself before the bootstrap cluster is launched. For a mirror with a self-signed or other untrusted certificate, --bootstrap-insecure alone is not enough: before starting the installation, configure trust in the mirror in one of the following ways.

sudo mkdir -p /etc/docker/certs.d/FQDN-MIRRORS
sudo cp /path/to/ca.crt /etc/docker/certs.d/FQDN-MIRRORS/ca.crt

{
  "insecure-registries": ["FQDN-MIRRORS"]
}

sudo systemctl restart docker

If trust in the mirror for Docker is not configured, the installer displays a warning in advance, and if docker pull fails, an error with the specific path /etc/docker/certs.d/<registry-host:port>/ca.crt for your mirror.

If the test fails after diagnostics: Before starting the installation, eliminate DNS, routing, firewall or mirror certificate settings.

Mirror host: stm status #

stm status

Success Criteria: Mirror components are in working order (see command output).

If stm is not found: run the command from the directory with the unpacked bundle or add the path to stm to PATH.

If the components are stopped: start the mirror and check again:

stm start

stm status

If the status is still not working, check the availability of Nginx ports, the certificate and the mirror initialization parameters.

Checking that virtual IP addresses are free #

On each IP address from the Control Plane subnet that will be used as a KubeAPI or Ingress VIP and is not already assigned to a host interface, run the following check:

ping -c 2 IP

Replace IP with a real address (for example, ping -c 2 10.11.12.100).

Success criterion: nodes in the subnet do not respond to ping for the selected VIP (the address is free under kube-vip).

If the node responds: the selected IP is already in use - select another free IP from the Control Plane subnet and repeat the check. If ICMP is not allowed on your network, discuss with your network administrator another way to check if the address is available.

Node: SELinux (if distribution with SELinux) #

getenforce

If the getenforce command is not available: on a distribution without SELinux, this subsection do not use.

Output options:

• enforcing — the policy is applied (for an agreed scenario, a transition to permissive or disabled is required, or a separate policy as agreed with IS).
• permissive - warnings without blocking (suitable if agreed with information security).
• disabled — the policy is not loaded (suitable if agreed with IS).

If the mode is enforcing and you need to disable SELinux before installation (after agreement with IS):

sudo sed -i 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config

After this, reboot:

sudo reboot

Uzel: time and NTP #

timedatectl status

With Chrony installed:

chronyc tracking

Success Criteria: Time is synchronized; the discrepancy with the shtil machine is not significant for your policy (a large discrepancy is a risk for certificates and etcd).

If the chronyc command is not available: use timedatectl first and compare date; If necessary, configure or install Chrony according to your OS documentation.

If the time is out of sync: configure NTP or Chrony on the nodes, the shtil machine, and the mirror host, then retest.

Node: Package Repositories #

Debian/Ubuntu:

sudo apt update

RHEL and compatible (if dnf is present):

sudo dnf repolist

If dnf is not present:

sudo yum repolist

Success Criteria: No errors due to completely inaccessible repositories.

If the test fails: disable inaccessible OS repositories or configure available package sources in a closed loop based on your organization’s policy. Repeat the command. While the package index update fails due to inaccessible repositories, the installation may fail during the OS package steps.

Working with providers #

Before installation, select an infrastructure provider and prepare it for the appropriate scenario. For the general scheme - provider instances, IP pools and VM templates - see the page How to work with providers in the platform.

oVirt and similar providers #

If oVirt, zVirt, HostVM, EDIT Virtualization or ROSA Virtualization is selected, prepare the virtualization environment before starting the installation: an account with the necessary rights, Datacenter, Cluster, a network with a VNIC and DHCP profile. Details are on the page oVirt and similar providers.

For management cluster nodes, create a virtual machine template in advance. When using a mirror, specify in stc template the same registry that will be used when deploying the platform.

VMware vSphere #

If VMware vSphere is selected, prepare vCenter: an account with service roles, Datacenter, Resource Pool, Network, Datastore and the path for storing the VM. Details are on the VMware vSphere page.

For management cluster nodes, create a virtual machine template in advance. Make sure that the template is connected to the network from which future VMs will receive addresses via DHCP, and prepared with closed loop registry parameters.

Provider Shturval v2 #

If you choose this providerraise physical or virtual hosts before installation. Resource and OS requirements are on the page with requirements, and the procedure for adding hosts is on the page Shturval v2.

Locally generate a key without passphrase and copy it to each node:

ssh-keygen -t ed25519 -f ./shturval -N ""

ssh-copy-id -i ./shturval.pub shturval@10.11.12.1

Repeat ssh-copy-id for each host IP address (substitute your user and addresses). The SSH key must be without passphrase. The user (for example, shturval) must have sudo without a password on all target nodes.

ssh -i /path/to/private_key USER@NODE

ssh -i /path/to/private_key USER@NODE 'sudo -n true'

Success criterion: login using a key without asking for a key password; the second call ends with code 0.

If SSH login is unsuccessful: check the host’s IP or FQDN, user, private key path, key file permissions, and that the public key has been copied to the host. Ensure that the sshd service on the host is accepting connections and is not being blocked by the firewall.

If sudo -n true fails: configure sudo to run without prompting for a password for the installation user, for example via sudoers according to your organization’s rules.