From c78318accfc3265bd261fcd89a25e21f8449784c Mon Sep 17 00:00:00 2001 From: Elaine Fonaro Date: Wed, 14 Dec 2022 12:08:10 -0300 Subject: [PATCH] Kubernetes Pod Core Dump Handler Minor editorial edits. Created the Kubernetes Pod Core Dump Handler doc. Updtaded the doc toctree to add this new file. Signed-off-by: Elaine Fonaro Change-Id: Ib9b45daf4c6b3e5ac54e0201c668346cda83d7db --- .../index-sysconf-kub-78f0e1e9ca5a.rst | 1 + ...etes-pod-coredump-handler-54d27a0fd2ec.rst | 107 ++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 doc/source/system_configuration/kubernetes/kubernetes-pod-coredump-handler-54d27a0fd2ec.rst diff --git a/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst b/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst index 5c44626af..18d30ba7c 100644 --- a/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst +++ b/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst @@ -186,3 +186,4 @@ Customize Core Dumps change-the-default-coredump-configuration-51ff4ce0c9ae + kubernetes-pod-coredump-handler-54d27a0fd2ec diff --git a/doc/source/system_configuration/kubernetes/kubernetes-pod-coredump-handler-54d27a0fd2ec.rst b/doc/source/system_configuration/kubernetes/kubernetes-pod-coredump-handler-54d27a0fd2ec.rst new file mode 100644 index 000000000..ad99f17c9 --- /dev/null +++ b/doc/source/system_configuration/kubernetes/kubernetes-pod-coredump-handler-54d27a0fd2ec.rst @@ -0,0 +1,107 @@ +.. _kubernetes-pod-coredump-handler-54d27a0fd2ec: + +================================ +Kubernetes Pod Core Dump Handler +================================ + +------------ +Introduction +------------ + +The default coredump handler (systemd-coredump) is not capable of limiting the +namespace access and has a global configuration for any application on the +system. To solve these issues a new Kubernetes aware core dump handler was created, +allowing the configuration of the coredump on a per pod basis and limiting the +namespace access. The Pod Core Dump Handler allows you to set the ``core_pattern`` +on a per Pod basis. When applications running on pods generate core dumps, they +are sent to Kubernetes Coredump Handler for handling according to the pod +annotations configurations. + +Individual Pods can control the core dump handling by specifying Kubernetes Pod +annotations that instruct the core dump handler for specific applications. In +this way, the core dump will have a specific size, will be saved at a +specific folder with a specific name, and you can allocate disk space on a +per-pod basis. + +See below the Kubernetes Pod Annotations. + +-------------------------- +Kubernetes Pod Annotations +-------------------------- + +The following are application annotations available for core dump configuration: + +``--starlingx.io/core_pattern``: (default “core.PID”) + This annotation is used to determine the path in the pod namespace where the + core dump file is saved and the name that the core dump should have. In the + example below, the pattern is saving inside the pod on the ``/coredump-log`` + path (folder available in this specific pod). It is also possible to format + the filename using arguments described in the core documentation. For + more information see https://man7.org/linux/man-pages/man5/core.5.html. This + annotation is required if you want to use the Kubernetes core dump handler. + If this annotation is not used, the default core dump handler (systemd-coredump) + will be used. + +``--starlingx.io/core_compression``: none|lz4 (default “none”) + This annotation is used to determine whether the file will be compressed. + Using the "lz4" option, the file will be compressed, decreasing the file + size. Use "none" or don't configure this annotation to not compress the + file. + +``--starlingx.io/core_max_size``: (defaults to 0 - unlimited). + This annotation sets the maximum core dump file size. It can be set from bytes + to gigabytes or as a percentage of total amount of disk space. If the file + is larger than the defined size, the file will be truncated. + +``--starlingx.io/core_max_used``: (defaults to 0 - unlimited) + This annotation sets the maximum amount of disk space to be used when saving + the core dump. If the file is larger than the remaining space, the file will + be truncated. + +``--starlingx.io/core_min_free``: (defaults to 0 - unlimited) + This annotation sets the minimum amount of disk space to keep free when saving + the core dump. If the file is larger than the remaining space, the + file will be truncated. + +where: + +``--pattern`` + supports the core_pattern defined by the core documentation. For + more information see https://man7.org/linux/man-pages/man5/core.5.html. + +``--size`` + supports standard size suffixes B, K, M, G or percentage (0 to disable) + + +YAML Example with all ``kubernetes-coredump-handler`` configuration annotations: + +.. code-block:: + + kind: Pod + apiVersion: v1 + metadata: + name: dummy-pod-with-annotation + annotations: { + starlingx.io/core_pattern: "/coredump-log/core.%P.%u.%g.%s.%t.%e", + starlingx.io/core_compression: lz4, + starlingx.io/core_max_size: 200k, + starlingx.io/core_max_used: 50%, + starlingx.io/core_min_free: 20% + } + spec: + containers: + - name: dummy-pod-with-annotation + image: ubuntu + command: ["/bin/bash", "-ec", "while :; do echo '.'; sleep 5 ; done"] + volumeMounts: + - name: hostpath-volume + mountPath: /coredump-log + volumes: + - name: hostpath-volume + hostPath: + path: /var/lib/systemd/coredump/ + restartPolicy: Never + + + +