diff --git a/content/guides/dhi-backstage.md b/content/guides/dhi-backstage.md index 1a8a3b35e10..01bf4f7f986 100644 --- a/content/guides/dhi-backstage.md +++ b/content/guides/dhi-backstage.md @@ -430,7 +430,7 @@ docker exec -it sh OCI runtime exec failed: exec failed: unable to start container process: ... ``` -Use [Docker Debug](/dhi/how-to/debug/) if you need to troubleshoot a running distroless container. +Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container. > [!NOTE] > @@ -480,4 +480,4 @@ Different scanners detect different issues. Running all three gives you the most - [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line. - [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages. - [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images. -- [Docker Debug](/dhi/how-to/debug/) — troubleshoot distroless containers that have no shell. +- [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell. diff --git a/content/guides/dhi-openshift.md b/content/guides/dhi-openshift.md index c15aedf8a58..d347f604178 100644 --- a/content/guides/dhi-openshift.md +++ b/content/guides/dhi-openshift.md @@ -620,6 +620,6 @@ and use `COPY --chown` to transfer results. - [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide. - [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization. -- [Debug a container](/dhi/how-to/debug/) — troubleshoot distroless containers with Docker Debug (local development). +- [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development). - [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints. - [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images. diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index ee04a6de5bc..6c4e8c12401 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -1,6 +1,6 @@ --- title: How-tos -description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging. +description: Step-by-step guidance for working with Docker Hardened Images, from discovery to governance. weight: 20 params: grid_discover: @@ -63,17 +63,12 @@ params: description: Learn how to use image policies with Docker Scout for Docker Hardened Images. icon: policy link: /dhi/how-to/policies/ - grid_troubleshoot: - - title: Debug a Docker Hardened Image - description: Use Docker Debug to inspect a running container based on a hardened image without modifying it. - icon: terminal - link: /dhi/how-to/debug/ --- This section provides practical, task-based guidance for working with Docker Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or integrating them into a production CI/CD pipeline, these topics cover the key -tasks across the adoption journey, from discovery to debugging. +tasks across the adoption journey: discover, adopt, verify, and govern. The topics are organized around the typical lifecycle of working with DHIs, but you can use them as needed based on your specific workflow. @@ -111,11 +106,3 @@ Enforce policies to maintain security and compliance. {{< grid items="grid_govern" >}} - -## Troubleshoot - -Debug containers based on DHIs without modifying the image. - -{{< grid - items="grid_troubleshoot" ->}} \ No newline at end of file diff --git a/content/manuals/dhi/how-to/debug.md b/content/manuals/dhi/how-to/debug.md deleted file mode 100644 index 11b87ab5fe5..00000000000 --- a/content/manuals/dhi/how-to/debug.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Debug a Docker Hardened Image container -linkTitle: Debug a container -weight: 60 -keywords: debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container -description: Learn how to use Docker Debug to troubleshoot Docker Hardened Images (DHI) locally or in production. ---- - -Docker Hardened Images (DHI) prioritize minimalism and security, which means -they intentionally leave out many common debugging tools (like shells or package -managers). This makes direct troubleshooting difficult without introducing risk. -To address this, you can use [Docker -Debug](/reference/cli/docker/debug/), a secure workflow that -temporarily attaches an ephemeral debug container to a running service or image -without modifying the original image. - -This guide shows how to debug Docker Hardened Images locally during development. -With Docker Debug, you can also debug containers remotely using the `--host` -option. - -## Use Docker Debug - -### Step 1: Run a container from a Hardened Image - -Start with a DHI-based container that simulates an issue: - -```console -$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" -``` - -This container doesn't include a shell or tools like `ps`, `top`, or `cat`. - -If you try: - -```console -$ docker exec -it myapp sh -``` - -You'll see: - -```console -exec: "sh": executable file not found in $PATH -``` - -### Step 2: Use Docker Debug to inspect the container - -Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. - -```console -$ docker debug myapp -``` - -From here, you can inspect running processes, network status, or mounted files. - -For example, to check running processes: - -```console -$ ps aux -``` - -Type `exit` to leave the container when done. - -## Alternative debugging approaches - -In addition to using Docker Debug, you can also use the following approaches for -debugging DHI containers. - -### Use the -dev variant - -Docker Hardened Images offer a `-dev` variant that includes a shell -and a package manager to install debugging tools. Simply replace the image tag -with `-dev`: - -```console -$ docker run -it --rm dhi.io/python:3.13-dev sh -``` - -Type `exit` to leave the container when done. Note that using the `-dev` variant -increases the attack surface and it is not recommended as a runtime for -production environments. - -### Mount debugging tools with image mounts - -You can use the image mount feature to mount debugging tools into your container -without modifying the base image. - -#### Step 1: Run a container from a Hardened Image - -Start with a DHI-based container that simulates an issue: - -```console -$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" -``` - -#### Step 2: Mount debugging tools into the container - -Run a new container that mounts a tool-rich image (like `busybox`) into -the running container's namespace: - -```console -$ docker run --rm -it --pid container:myapp \ - --mount type=image,source=busybox,destination=/dbg,ro \ - dhi.io/python:3.13 /dbg/bin/sh -``` - -This mounts the BusyBox image at `/dbg`, giving you access to its tools while -keeping your original container image unchanged. Since the hardened Python image -doesn't include standard utilities, you need to use the full path to the mounted -tools: - -```console -$ /dbg/bin/ls / -$ /dbg/bin/ps aux -$ /dbg/bin/cat /etc/os-release -``` - -Type `exit` to leave the container when done. - -## What's next - -This guide covered three approaches for debugging Docker Hardened Images: - -- Docker Debug: Attach an ephemeral debug container without modifying the original image -- `-dev` variants: Use development images that include debugging tools -- Image mount: Mount tool-rich images like BusyBox to access debugging utilities - -Each method helps you troubleshoot hardened containers while maintaining -security. Docker Debug and image mounts avoid modifying your production images, -while `-dev` variants provide convenience during development. - -If you encounter issues related to permissions, ports, missing shells, or -package managers, see [Troubleshoot Docker Hardened Images](../troubleshoot.md) -for recommended solutions and workarounds. \ No newline at end of file diff --git a/content/manuals/dhi/troubleshoot.md b/content/manuals/dhi/troubleshoot.md index 24ba650fc36..f3d86b07c82 100644 --- a/content/manuals/dhi/troubleshoot.md +++ b/content/manuals/dhi/troubleshoot.md @@ -3,27 +3,132 @@ title: Troubleshoot description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access. weight: 40 tags: [Troubleshooting] -keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager +keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container +aliases: +- /dhi/how-to/debug/ --- -The following are common issues you may encounter while migrating to or using -Docker Hardened Images (DHIs), along with recommended solutions. +This page covers debugging techniques and common issues you may encounter while +migrating to or using Docker Hardened Images (DHIs). ## General debugging -Docker Hardened Images are optimized for security and runtime performance. As -such, they typically don't include a shell or standard debugging tools. The -recommended way to troubleshoot containers built on DHIs is by using [Docker -Debug](./how-to/debug.md). +Docker Hardened Images prioritize minimalism and security, which means +they intentionally leave out many common debugging tools (like shells or package +managers). This makes direct troubleshooting difficult without introducing risk. +To address this, you can use [Docker +Debug](/reference/cli/docker/debug/), a secure workflow that +temporarily attaches an ephemeral debug container to a running service or image +without modifying the original image. -Docker Debug allows you to: +This section shows how to debug Docker Hardened Images locally during development. +With Docker Debug, you can also debug containers remotely using the `--host` +option. -- Attach a temporary debug container to your existing container. -- Use a shell and familiar tools such as `curl`, `ps`, `netstat`, and `strace`. -- Install additional tools as needed in a writable, ephemeral layer that - disappears after the session. +### Use Docker Debug -## Permissions +#### Step 1: Run a container from a Hardened Image + +Start with a DHI-based container that simulates an issue: + +```console +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" +``` + +This container doesn't include a shell or tools like `ps`, `top`, or `cat`. + +If you try: + +```console +$ docker exec -it myapp sh +``` + +You'll see: + +```console +exec: "sh": executable file not found in $PATH +``` + +#### Step 2: Use Docker Debug to inspect the container + +Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. + +```console +$ docker debug myapp +``` + +From here, you can inspect running processes, network status, or mounted files. + +For example, to check running processes: + +```console +$ ps aux +``` + +Type `exit` to leave the container when done. + +### Alternative debugging approaches + +In addition to using Docker Debug, you can also use the following approaches for +debugging DHI containers. + +#### Use the -dev variant + +Docker Hardened Images offer a `-dev` variant that includes a shell +and a package manager to install debugging tools. Simply replace the image tag +with `-dev`: + +```console +$ docker run -it --rm dhi.io/python:3.13-dev sh +``` + +Type `exit` to leave the container when done. Note that using the `-dev` variant +increases the attack surface and it is not recommended as a runtime for +production environments. + +#### Mount debugging tools with image mounts + +You can use the image mount feature to mount debugging tools into your container +without modifying the base image. + +##### Step 1: Run a container from a hardened image + +Start with a DHI-based container that simulates an issue: + +```console +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" +``` + +##### Step 2: Mount debugging tools into the container + +Run a new container that mounts a tool-rich image (like `busybox`) into +the running container's namespace: + +```console +$ docker run --rm -it --pid container:myapp \ + --mount type=image,source=busybox,destination=/dbg,ro \ + dhi.io/python:3.13 /dbg/bin/sh +``` + +This mounts the BusyBox image at `/dbg`, giving you access to its tools while +keeping your original container image unchanged. Since the hardened Python image +doesn't include standard utilities, you need to use the full path to the mounted +tools: + +```console +$ /dbg/bin/ls / +$ /dbg/bin/ps aux +$ /dbg/bin/cat /etc/os-release +``` + +Type `exit` to leave the container when done. + +## Common issues + +The following are specific issues you may encounter when working with Docker +Hardened Images, along with recommended solutions. + +### Permissions DHIs run as a nonroot user by default for enhanced security. This can result in permission issues when accessing files or directories. Ensure your application @@ -34,7 +139,7 @@ To find out which user a DHI runs as, check the repository page for the image on Docker Hub. See [View image variant details](./how-to/explore.md#image-variant-details) for more information. -## Privileged ports +### Privileged ports Nonroot containers cannot bind to ports below 1024 by default. This is enforced by both the container runtime and the kernel (especially in Kubernetes and @@ -45,7 +150,7 @@ port (1025 or higher). For example `docker run -p 80:8080 my-image` maps port 8080 in the container to port 80 on the host, allowing you to access it without needing root privileges. -## No shell +### No shell Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev` @@ -56,10 +161,10 @@ To find out which shell, if any, a DHI has, check the repository page for the image on Docker Hub. See [View image variant details](./how-to/explore.md#image-variant-details) for more information. -Also, use [Docker Debug](./how-to/debug.md) when you need shell -access to a running container. +Also, use Docker Debug when you need shell access to a running container. For +more details, see [General debugging](#general-debugging). -## Entry point differences +### Entry point differences DHIs may define different entry points compared to Docker Official Images (DOIs) or other community images. @@ -68,7 +173,7 @@ To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the image on Docker Hub. See [View image variant details](./how-to/explore.md#image-variant-details) for more information. -## No package manager +### No package manager Runtime Docker Hardened Images are stripped down for security and minimal attack surface. As a result, they don't include a package manager such as `apk` or