Document how to use the metalk8s-utils image

CHANGELOG.md

@@ -42,6 +42,14 @@
   [MetalK8s documentation](https://metal-k8s.readthedocs.io/en/2.7.0/operation/cluster_and_service_configuration.html#prometheus-configuration-customization)
   (PR [#2968](https://github.com/scality/metalk8s/pull/2968))
 
+- The `screen` and `tmux` terminal multiplexers are now installed in the
+  `metalk8s-utils` container image
+  (PR [#2995](https://github.com/scality/metalk8s/pull/2995))
+
+- The `bash-completion` completions for the `kubectl` command are now included
+  in the `metalk8s-utils` container image
+  (PR [#2995](https://github.com/scality/metalk8s/pull/2995))
+
 ### Bug fixes
 
 - [#2908](https://github.com/scality/metalk8s/issues/2908) - Make upgrade script

docs/Makefile

@@ -5,7 +5,7 @@ default: help
 .PHONY: default
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
@@ -56,4 +56,4 @@ diagrams-svg: $(patsubst %.uml,%.svg,$(SOURCES))
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -4,6 +4,7 @@ pushd %~dp0
 
 REM Command file for Sphinx documentation
 
+set SPHINXOPTS=-n
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
@@ -30,7 +31,7 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :livehtml

docs/operation/index.rst

@@ -21,4 +21,5 @@ do not have a working MetalK8s_ setup.
    account_administration
    cluster_and_service_configuration
    cluster_monitoring
+   metalk8s-utils
    troubleshooting

docs/operation/metalk8s-utils.rst

@@ -0,0 +1,105 @@
+Using the ``metalk8s-utils`` Image
+==================================
+A MetalK8s installation comes with a container image called ``metalk8s-utils``
+in the embedded registry. This image contains several tools an operator can use
+to analyze a cluster environment or troubleshoot various system issues.
+
+The image can be used to create a *Pod* on a node, after which a shell inside
+the container can be created to run the various utilities. Depending on the
+use-case, the *Pod* could be created using the host network namespace, the host
+PID namespace, elevated privileges, mounting host directories as volumes, etc.
+
+See the ``metalk8s-utils``
+:download:`Dockerfile <../../images/metalk8s-utils/Dockerfile>` for a list of
+all packages installed in the image.
+
+A Simple Shell
+--------------
+To run a ``metalk8s-utils`` container as a simple shell, execute the following
+command:
+
+.. parsed-literal::
+
+    kubectl run shell \\
+        --image=metalk8s-registry-from-config.invalid/metalk8s-|version|/metalk8s-utils:|version| \\
+        --restart=Never \\
+        --attach \\
+        --stdin \\
+        --tty \\
+        --rm
+
+This will create a *Pod* called ``shell`` with a container running the
+``metalk8s-utils`` image, and present you with a shell in this container.
+
+.. note::
+
+   This procedure expects no other ``shell`` *Pod* to be running. Adjust the
+   name accordingly, or use a dedicated namespace if conflicts occur.
+
+A Long-Running Container
+------------------------
+In the example above, the lifetime of the container is tied to the invocation
+of ``kubectl run``. In some situations it's more efficient to keep such
+container running and attach to it (and detach from it) dynamically.
+
+* Create the *Pod*:
+
+.. parsed-literal::
+
+    kubectl run shell \\
+        --image=metalk8s-registry-from-config.invalid/metalk8s-|version|/metalk8s-utils:|version| \\
+        --restart=Never \\
+        --command -- sleep infinity
+
+This creates the ``shell`` *Pod* including a ``metalk8s-utils`` container
+running ``sleep infinity``, effectivelly causing the *Pod* to remain alive
+until deleted.
+
+* Get a shell in the container::
+
+    kubectl exec -ti shell -- bash
+
+.. note::
+
+   The :program:`screen` and :program:`tmux` utilities are installed in the
+   image for terminal multiplexing.
+
+* Exit the shell to detach
+
+* Remove the *Pod* once the container is no longer needed::
+
+    kubectl delete pod shell
+
+A Shell on a Particular Node
+----------------------------
+To pin the *Pod* in which the ``metalk8s-utils`` container is launched to a
+particular node, add the following options to a suitable ``kubectl run``
+invocation::
+
+    --overrides='{ "apiVersion": "v1", "spec": { "nodeName": "NODE_NAME" } }'
+
+.. note::
+
+   In the above, replace ``NODE_NAME`` by the desired node name.
+
+A Shell in the Host Network Namespace
+-------------------------------------
+To run a ``metalk8s-utils`` container in the host network namespace, e.g.,
+to use utilities such as ``ip``, ``iperf`` or ``tcpdump`` as if they're
+executed on the host, add the following options to a suitable
+``kubectl run`` invocation::
+
+    --overrides='{ "apiVersion": "v1", "spec": { "hostNetwork": true } }'
+
+.. note::
+
+   If multiple ``overrides`` need to be combined, the JSON objects must be
+   merged.
+
+.. todo::
+
+   - Adding tolerations for various taints when using `nodeName`
+   - Mounting a host directory
+   - Exposing Salt and containerd sockets
+   - Running a privileged container, exposing the host `/dev` in the container
+     for `parted` etc. to work

images/metalk8s-utils/Dockerfile

@@ -95,15 +95,19 @@ RUN yum install -y epel-release && \
         rsync \
         salt-master \
         salt-minion \
+        screen \
         socat \
         strace \
         sysstat \
         tcpdump \
         telnet \
+        tmux \
         util-linux \
         vim \
         wget \
         wireshark \
         xfsprogs \
         && \
     yum clean all
+
+RUN kubectl completion bash > /etc/bash_completion.d/kubectl

tox.ini

@@ -72,10 +72,9 @@ commands =
     doc8 docs/
     {toxinidir}/docs/build.cmd {posargs:html}
 passenv =
-    O
     READTHEDOCS
 setenv =
-    SPHINXOPTS=-j4 -n -W
+    O = -W {env:O:}
 
 [doc8]
 ignore-path = docs/_build,docs/requirements.txt