From 9891bb6618134f7d5c57dd6ad764178227db707d Mon Sep 17 00:00:00 2001 From: Cedric Bosdonnat Date: Tue, 16 Jan 2024 10:23:55 +0100 Subject: [PATCH] Update the container proxy installation doc (#2685) Document the use of mgrpxy to install the container proxy both for podman and kubernetes. --- CHANGELOG.md | 2 + .../pages/proxy-container-installation.adoc | 45 +++---- .../proxy-container-k3s-installation.adoc | 114 ++---------------- 3 files changed, 28 insertions(+), 133 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c48aad6c9b1..dabd4e6c435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,5 @@ +- Updated the proxy installation in Installation and Upgrade Guide to use + the mgrpxy tool - Added note about refreshing pillar data in Salt Guide (bsc#1189047) - Added and fixed configuration details in Troubleshooting Renaming Server in Administration Guide diff --git a/modules/installation-and-upgrade/pages/proxy-container-installation.adoc b/modules/installation-and-upgrade/pages/proxy-container-installation.adoc index 6ba768a6a5f..447242d82b8 100644 --- a/modules/installation-and-upgrade/pages/proxy-container-installation.adoc +++ b/modules/installation-and-upgrade/pages/proxy-container-installation.adoc @@ -84,28 +84,28 @@ For more information about registering Salt client to the {productname} Server, {productname} Proxy containers are using [literal]``podman`` and [literal]``systemd`` to run and manage all proxy containers. -First step is to install container control files provided by package [literal]``uyuni-proxy-systemd-services``. +First step is to install the [literal]``mgrpxy`` utility provided by the package of the same name. -[[proc-installation-proxy-containers-services]] -.Procedure: Installation of container services for {productname} Proxy +[[proc-installation-proxy-containers-mgrpxy]] +.Procedure: Installation of container utility tool [literal]``mgrpxy`` for {productname} Proxy . Assign [literal]``Containers Module`` software channel to the container host in the {productname}. For more information about assigning software channels to the system, see xref:administration:channel-management.adoc[]. . Log in as `root` on the container host. -. Manually install {productname} Proxy service package: +. Manually install [literal]``mgrpxy`` package: + ---- -zypper install uyuni-proxy-systemd-services +zypper install mgrpxy ---- [[installation-proxy-containers-customize-config]] -== Customize {productname} Proxy configuration +== Install {productname} Proxy containers {productname} Proxy containers require some volumes to be mounted for long term storage. Those volumes are automatically created by [literal]``podman`` and can be listed using the [command]``podman volume ls`` command. @@ -118,21 +118,15 @@ The volumes are named: To override default volume settings, create the volumes prior to the first start of the pod using the [command]``podman volume create`` command. -It is possible to add custom arguments passed to podman container pod to [path]``/etc/sysconfig/uyuni-proxy-systemd-services.config``: +To install the systemd service starting the {productname} proxy, run the [command]``mgrpxy install podman /path/to/config.tar.gz`` command. ----- -EXTRA_POD_ARGS='' ----- +It is possible to add custom arguments passed to podman container pod with the one or more [literal]``--podman-arg`` parameters to the install command. -In this file it is possible to modify tag to use for container images: - ----- -TAG=latest ----- +It is possible to modify the tag to use for container images with the [literal]``--tag=latest`` parameter to the install command. [IMPORTANT] ==== -Changing the [path]``uyuni-proxy-systemd-services.config`` file and especially the [literal]``TAG`` setting is dangerous and can cause a non-functional system. +Changing the containers images and version parameters is dangerous and can cause a non-functional system. ==== @@ -140,30 +134,23 @@ Changing the [path]``uyuni-proxy-systemd-services.config`` file and especially t === Using a custom container image for a service By default, the {productname} Proxy suite is set to use the same image version and registry path for each of its services. -However, it is possible to override the default values for a specific service. -The [literal]``uyuni-proxy`` CLI bundled with the package, runs [command]``update image`` with the following parameters: - -- [literal]``-s`` for the service name -- [literal]``-t`` for the version tag -- [literal]``-r`` for the registry path +However, it is possible to override the default values for a specific service using the install parameters ending with [literal]``-tag`` and [literal]``-image``. For example, use it like this: ---- -uyuni-proxy update image -s httpd -t 0.1.0 -r registry.opensuse.org/uyuni +mgrpxy install podman --httpd-tag 0.1.0 --httpd-image registry.opensuse.org/uyuni/proxy-httpd /path/to/config.tar.gz ---- -It adjusts the configuration file for the httpd service, where [path]``registry.opensuse.org/uyuni`` is the registry and [literal]``0.1.0`` is the version tag, before restarting it. +It adjusts the configuration file for the httpd service, where [path]``registry.opensuse.org/uyuni/proxy-httpds`` is the image to use and [literal]``0.1.0`` is the version tag, before restarting it. -To reset the values to defaults, run the proxy reset command, specifying the service with the [literal]``-s`` parameter: +To reset the values to defaults, run the install command again without those parameters: ---- -uyuni-proxy reset -s httpd +mgrpxy install podman /path/to/config.tar.gz ---- -This command first resets the configuration of the [literal]``httpd`` service to the global defaults and then reloads it. - -For more information, see [command]``uyuni-proxy --help``. +This command first resets the configuration of all services to the global defaults and then reloads it. diff --git a/modules/installation-and-upgrade/pages/proxy-container-k3s-installation.adoc b/modules/installation-and-upgrade/pages/proxy-container-k3s-installation.adoc index 618fe6a84a9..72746831b60 100644 --- a/modules/installation-and-upgrade/pages/proxy-container-k3s-installation.adoc +++ b/modules/installation-and-upgrade/pages/proxy-container-k3s-installation.adoc @@ -4,116 +4,33 @@ [[installation-proxy-containers-k3s-k3s]] == Installing k3s -On the container host machine, install [literal]``k3s`` without the load balancer and traefik router (replace [literal]```` with the FQDN of your k3s host): +On the container host machine, install [literal]``k3s`` (replace [literal]```` with the FQDN of your k3s host): ---- -curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik --disable=servicelb --tls-san=" sh - +curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--tls-san=" sh - ---- -[[installation-proxy-containers-k3s-cluster-access]] -== Configuring cluster access - -[literal]``helm`` needs a configuration file to connect to the target kubernetes cluster. - -On the cluster server machine run the following command to create the [path]``kubeconfig-k3s.yaml`` configuration file. -The [path]``kubeconfig-k3s.yaml`` file can be optionally transferred to a work machine: - ----- -kubectl config view --flatten=true | sed 's/127.0.0.1//' >kubeconfig-k3s.yaml ----- - -Before calling [literal]``helm``, run: +[[installation-proxy-containers-k3s-helm]] +== Installing tools ----- -export KUBECONFIG=/path/to/kubeconfig-k3s.yaml ----- +The installation requires the [literal]``mgrpxy`` and [literal]``helm`` packages. -[[installation-proxy-containers-k3s-helm]] -== Installing helm +TODO The [literal]``mgrpxy`` package is available in the TBD repository. [NOTE] ==== The Containers Module is required to install [literal]``helm``. ==== -To install it run: - ----- -zypper in helm ----- - -[[installation-proxy-containers-k3s-metallb]] -== Installing [literal]``metalLB`` - -[literal]``MetalLB`` is the load balancer that will expose the {productname} proxy pod services to the outside world. -To install it, run: - ----- -helm repo add metallb https://metallb.github.io/metallb -helm install --create-namespace -n metallb metallb metallb/metallb ----- - -[literal]``MetalLB`` still requires a configuration to know the virtual IP address range to be used. -In this example, the virtual IP addresses will be from [literal]``192.168.122.240`` to [literal]``192.168.122.250``, but that range could be lowered to a single address if the host only exposes the {productname} proxy. -These addresses need to be a subset of the server network. - -Create a [path]``metallb-config.yaml`` configuration file with the following settings and an IP address range that aligns with the deployed network: - ----- -apiVersion: metallb.io/v1beta1 -kind: IPAddressPool -metadata: - name: l2-pool - namespace: metallb -spec: - addresses: - - 192.168.122.240-192.168.122.250 ---- -apiVersion: metallb.io/v1beta1 -kind: L2Advertisement -metadata: - name: l2 - namespace: metallb -spec: - ipAddressPools: - - l2-pool ----- - -Apply this configuration by running: +To install them run: ---- -kubectl apply -f metallb-config.yaml +zypper in helm mgrpxy ---- - [[installation-proxy-containers-k3s-deploy]] == Deploying the {productname} proxy helm chart -Create a configuration file forcing the IP address that [literal]``MetalLB`` will use for the {productname} Proxy services. -This IP address needs to be the one to which the proxy FQDN entered when creating the proxy configuration. -It also needs to be resolvable from both the {productname} Server and the client systems to connect to the proxy. - -This example will use [literal]``192.168.122.241``. - -Create a [path]``custom-values.yaml`` file with the following content. -If the [literal]``MetalLB`` IP address range only contains a single address, the last line can be removed. - ----- -services: - annotations: - metallb.universe.tf/allow-shared-ip: key-to-share-ip - metallb.universe.tf/loadBalancerIPs: 192.168.122.241 ----- - - -[NOTE] -==== -The parameter [literal]``metallb.universe.tf/allow-shared-ip`` does not need changing. - -You need to adjust the parameter [literal]``metallb.universe.tf/loadBalancerIPs`` to your network setup. -==== - - To configure the storage of the volumes to be used by the {productname} Proxy pod, define persistent volumes for the following claims. If you do not customize the storage configuration, k3s will automatically create the storage volumes for you. @@ -124,21 +41,10 @@ The persistent volume claims are named: * [literal]``/tftp-boot-pv-claim`` Create the configuration for the {productname} Proxy as documented in xref:installation-and-upgrade:proxy-container-setup.adoc[]. -Copy and extract the configuration [literal]``tar.gz`` file and then deploy the helm chart: +Copy the configuration [literal]``tar.gz`` file and then install: -ifeval::[{uyuni-content} == true] ----- -tar xf /path/to/config.tar.gz -helm install uyuni-proxy oci://registry.opensuse.org/uyuni/proxy -f config.yaml -f httpd.yaml -f ssh.yaml -f custom-values.yaml ---- -endif::[] - -ifeval::[{suma-content} == true] +mgrpxy install kubernetes /path/to/config.tar.gz ---- -tar xf /path/to/config.tar.gz -helm install uyuni-proxy oci://registry.suse.com/suse/manager/4.3/proxy -f config.yaml -f httpd.yaml -f ssh.yaml -f custom-values.yaml ----- -endif::[] - For more information see link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[] (kubernetes) or link:https://rancher.com/docs/k3s/latest/en/storage/[] (k3s) documentation.