Skip to content

Commit

Permalink
Update the container proxy installation doc (#2685)
Browse files Browse the repository at this point in the history 
Document the use of mgrpxy to install the container proxy both for
podman and kubernetes.
  • Loading branch information
@cbosdo
cbosdo authored Jan 16, 2024
1 parent f7d4ea8 commit 9891bb6
Show file tree
Hide file tree
Showing 3 changed files with 28 additions and 133 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
45 changes: 16 additions & 29 deletions modules/installation-and-upgrade/pages/proxy-container-installation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -118,52 +118,39 @@ 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.
====



=== 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.



Expand Down
114 changes: 10 additions & 104 deletions modules/installation-and-upgrade/pages/proxy-container-k3s-installation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]``<K3S_HOST_FQDN>`` with the FQDN of your k3s host):
On the container host machine, install [literal]``k3s`` (replace [literal]``<K3S_HOST_FQDN>`` with the FQDN of your k3s host):

----
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik --disable=servicelb --tls-san=<K3S_HOST_FQDN>" sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--tls-san=<K3S_HOST_FQDN>" 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/<K3S_HOST_FQDN>/' >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.

Expand All @@ -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.

0 comments on commit 9891bb6

Please sign in to comment.