Update documentation

Signed-off-by: Arjun Raja Yogidas <[email protected]>

Author: coderbirju

cmd/nerdctl/container/container_health_check_linux_test.go

@@ -19,6 +19,7 @@ package container
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
@@ -37,9 +38,6 @@ import (
 )
 
 func TestContainerHealthCheckBasic(t *testing.T) {
-	if rootlessutil.IsRootless() {
-		t.Skip("healthcheck tests are skipped in rootless environment")
-	}
 
 	testCase := nerdtest.Setup()
 
@@ -138,10 +136,6 @@ func TestContainerHealthCheckBasic(t *testing.T) {
 }
 
 func TestContainerHealthCheckAdvance(t *testing.T) {
-	if rootlessutil.IsRootless() {
-		t.Skip("healthcheck tests are skipped in rootless environment")
-	}
-
 	testCase := nerdtest.Setup()
 
 	// Docker CLI does not provide a standalone healthcheck command.
@@ -399,6 +393,43 @@ func TestContainerHealthCheckAdvance(t *testing.T) {
 				}
 			},
 		},
+		{
+			Description: "Healthcheck emits large output repeatedly",
+			Setup: func(data test.Data, helpers test.Helpers) {
+				helpers.Ensure("run", "-d", "--name", data.Identifier(),
+					"--health-cmd", "yes X | head -c 60000",
+					"--health-interval", "1s", "--health-timeout", "2s",
+					testutil.CommonImage, "sleep", nerdtest.Infinity)
+				nerdtest.EnsureContainerStarted(helpers, data.Identifier())
+			},
+			Cleanup: func(data test.Data, helpers test.Helpers) {
+				helpers.Anyhow("rm", "-f", data.Identifier())
+			},
+			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
+				for i := 0; i < 3; i++ {
+					helpers.Ensure("container", "healthcheck", data.Identifier())
+					time.Sleep(2 * time.Second)
+				}
+				return helpers.Command("inspect", data.Identifier())
+			},
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: 0,
+					Output: expect.All(func(_ string, t tig.T) {
+						inspect := nerdtest.InspectContainer(helpers, data.Identifier())
+						h := inspect.State.Health
+						debug, _ := json.MarshalIndent(h, "", "  ")
+						t.Log(string(debug))
+						assert.Assert(t, h != nil, "expected health state")
+						assert.Equal(t, h.Status, healthcheck.Healthy)
+						assert.Assert(t, len(h.Log) >= 3, "expected at least 3 health log entries")
+						for _, log := range h.Log {
+							assert.Assert(t, len(log.Output) >= 1024, fmt.Sprintf("each output should be >= 1024 bytes, was: %s", log.Output))
+						}
+					}),
+				}
+			},
+		},
 		{
 			Description: "Health log in inspect keeps only the latest 5 entries",
 			Setup: func(data test.Data, helpers test.Helpers) {
@@ -587,13 +618,10 @@ func TestHealthCheck_SystemdIntegration_Basic(t *testing.T) {
 					"--health-interval", "2s",
 					testutil.CommonImage, "sleep", "30")
 				nerdtest.EnsureContainerStarted(helpers, data.Identifier())
-				// Wait for a healthcheck to execute
-				time.Sleep(2 * time.Second)
 			},
 			Cleanup: func(data test.Data, helpers test.Helpers) {
 				// Ensure proper cleanup of systemd units
 				helpers.Anyhow("stop", data.Identifier())
-				time.Sleep(500 * time.Millisecond) // Allow systemd cleanup
 				helpers.Anyhow("rm", "-f", data.Identifier())
 			},
 			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
@@ -617,9 +645,7 @@ func TestHealthCheck_SystemdIntegration_Basic(t *testing.T) {
 					"--health-interval", "1s",
 					testutil.CommonImage, "sleep", "30")
 				nerdtest.EnsureContainerStarted(helpers, data.Identifier())
-				time.Sleep(2 * time.Second)               // Wait for at least one health check to execute
 				helpers.Ensure("kill", data.Identifier()) // Kill the container
-				time.Sleep(3 * time.Second)               // Wait to allow any potential extra healthchecks (shouldn't happen)
 			},
 			Cleanup: func(data test.Data, helpers test.Helpers) {
 				// Container is already killed, just remove it

docs/healthchecks.md

@@ -2,25 +2,29 @@
 
 `nerdctl` supports Docker-compatible health checks for containers, allowing users to monitor container health via a user-defined command.
 
-Currently, health checks can be triggered manually using the nerdctl container healthcheck command. Automatic orchestration (e.g., periodic checks) will be added in a future update.
+## Configuration Options
 
 Health checks can be configured in multiple ways:
 
-1. At container creation time using nerdctl run or nerdctl create with `--health-*` flags
+1. At container creation time using `nerdctl run` or `nerdctl create` with these flags:
+   - `--health-cmd`: Command to run to check health
+   - `--health-interval`: Time between running the check (default: 30s)
+   - `--health-timeout`: Maximum time to allow one check to run (default: 30s)
+   - `--health-retries`: Consecutive failures needed to report unhealthy (default: 3)
+   - `--health-start-period`: Start period for the container to initialize before starting health-retries countdown
+   - `--no-healthcheck`: Disable any container-specified HEALTHCHECK
+
 2. At image build time using HEALTHCHECK in a Dockerfile
-3. In docker-compose.yaml files, if using nerdctl compose
 
-When a container is created, nerdctl determines the health check configuration based on the following priority:
+**Note:** The `--health-start-interval` option is currently not supported by nerdctl.
 
-1. **CLI flags** take highest precedence (e.g., `--health-cmd`, etc.)
-2. If no CLI flags are set, nerdctl will use any health check defined in the image.
-3. If neither is present, no health check will be configured
+## Configuration Priority
 
-Example:
+When a container is created, nerdctl determines the health check configuration based on this priority:
 
-```bash
-nerdctl run --name web --health-cmd="curl -f http://localhost || exit 1" --health-interval=30s --health-timeout=5s --health-retries=3 nginx
-```
+1. CLI flags take highest precedence (e.g., `--health-cmd`, etc.)
+2. If no CLI flags are set, nerdctl will use any health check defined in the image
+3. If neither is present, no health check will be configured
 
 ### Disabling Health Checks
 
@@ -37,15 +41,54 @@ configured health check inside the container and reports the result. It serves a
 health checks, especially in scenarios where external scheduling is used.
 
 Example:
-
 ```
 nerdctl container healthcheck <container-id>
 ```
 
-### Future Work (WIP)
+## Automatic Health Checks with systemd
+
+On Linux systems with systemd, nerdctl automatically creates and manages systemd timer units to execute health checks at the configured intervals. This provides reliable scheduling and execution of health checks without requiring a persistent daemon.
+
+### Requirements for Automatic Health Checks
+
+- systemd must be available on the system
+- Container must not be running in rootless mode
+- Environment variable `DISABLE_HC_SYSTEMD` must not be set to "true"
+
+### How It Works
 
-Since nerdctl is daemonless and does not have a persistent background process, we rely on systemd(or external schedulers)
-to invoke nerdctl container healthcheck at configured intervals. This allows periodic health checks for containers in a
-systemd-based environment. We are actively working on automating health checks, where we will listen to container lifecycle
-events and generate appropriate systemd service and timer units. This will enable nerdctl to support automated,
-Docker-compatible health checks by leveraging systemd for scheduling and lifecycle integration.
+1. When a container with health checks is created, nerdctl:
+   - Creates a systemd timer unit for the container
+   - Configures the timer according to the health check interval
+   - Starts monitoring the container's health status
+
+2. The health check status can be one of:
+   - `starting`: During container initialization
+   - `healthy`: When health checks are passing
+   - `unhealthy`: After specified number of consecutive failures
+## Examples
+
+1. Basic health check that verifies a web server:
+```bash
+nerdctl run -d --name web \
+  --health-cmd="curl -f http://localhost/ || exit 1" \
+  --health-interval=5s \
+  --health-retries=3 \
+  nginx
+```
+
+2. Health check with initialization period:
+```bash
+nerdctl run -d --name app \
+  --health-cmd="./health-check.sh" \
+  --health-interval=30s \
+  --health-timeout=10s \
+  --health-retries=3 \
+  --health-start-period=60s \
+  myapp
+```
+
+3. Disable health checks:
+```bash
+nerdctl run --no-healthcheck myapp
+```

go.mod

@@ -120,7 +120,7 @@ require (
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.1 // indirect
 	github.com/sasha-s/go-deadlock v0.3.5 // indirect
 	//gomodjail:unconfined
-	github.com/sirupsen/logrus v1.9.3
+	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/smallstep/pkcs7 v0.1.1 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
 	github.com/stefanberger/go-pkcs11uri v0.0.0-20230803200340-78284954bff6 // indirect

pkg/containerutil/containerutil.go

@@ -359,11 +359,6 @@ func Stop(ctx context.Context, container containerd.Container, timeout *time.Dur
 		}
 	}()
 
-	// Clean up healthcheck units if configured.
-	// if err := healthcheck.RemoveTransientHealthCheckFiles(ctx, container); err != nil {
-	// 	return fmt.Errorf("failed to clean up healthcheck units for container %s", container.ID())
-	// }
-
 	if timeout == nil {
 		t, ok := l[labels.StopTimeout]
 		if !ok {
@@ -505,11 +500,6 @@ func Pause(ctx context.Context, client *containerd.Client, id string) error {
 		return err
 	}
 
-	// Clean up healthcheck units if configured.
-	// if err := healthcheck.RemoveTransientHealthCheckFiles(ctx, container); err != nil {
-	// 	return fmt.Errorf("failed to clean up healthcheck units for container %s", container.ID())
-	// }
-
 	switch status.Status {
 	case containerd.Paused:
 		return fmt.Errorf("container %s is already paused", id)

pkg/healthcheck/healthcheck_manager_linux.go

@@ -25,7 +25,6 @@ import (
 	"strings"
 
 	"github.com/coreos/go-systemd/v22/dbus"
-	"github.com/sirupsen/logrus"
 
 	containerd "github.com/containerd/containerd/v2/client"
 	"github.com/containerd/log"
@@ -47,12 +46,9 @@ func CreateTimer(ctx context.Context, container containerd.Container) error {
 
 	containerID := container.ID()
 	hcName := hcUnitName(containerID, true)
-	logrus.Debugf("Creating healthcheck timer unit: %s", hcName)
+	log.G(ctx).Debugf("Creating healthcheck timer unit: %s", hcName)
 
 	cmd := []string{}
-	if rootlessutil.IsRootless() {
-		cmd = append(cmd, "--user")
-	}
 	if path := os.Getenv("PATH"); path != "" {
 		cmd = append(cmd, "--setenv=PATH="+path)
 	}
@@ -61,7 +57,7 @@ func CreateTimer(ctx context.Context, container containerd.Container) error {
 	cmd = append(cmd, "--unit", hcName, "--on-unit-inactive="+hc.Interval.String(), "--timer-property=AccuracySec=1s")
 
 	cmd = append(cmd, "nerdctl", "container", "healthcheck", containerID)
-	if logrus.IsLevelEnabled(logrus.DebugLevel) {
+	if log.G(ctx).Logger.IsLevelEnabled(log.DebugLevel) {
 		cmd = append(cmd, "--debug")
 	}
 
@@ -71,7 +67,7 @@ func CreateTimer(ctx context.Context, container containerd.Container) error {
 	}
 	defer conn.Close()
 
-	logrus.Debugf("creating healthcheck timer with: systemd-run %s", strings.Join(cmd, " "))
+	log.G(ctx).Debugf("creating healthcheck timer with: systemd-run %s", strings.Join(cmd, " "))
 	run := exec.Command("systemd-run", cmd...)
 	if out, err := run.CombinedOutput(); err != nil {
 		return fmt.Errorf("systemd-run failed: %w\noutput: %s", err, strings.TrimSpace(string(out)))
@@ -81,7 +77,6 @@ func CreateTimer(ctx context.Context, container containerd.Container) error {
 }
 
 // StartTimer starts the healthcheck timer unit.
-// TODO if we persist hcName to container state, pass that to this function.
 func StartTimer(ctx context.Context, container containerd.Container) error {
 	hc := extractHealthcheck(ctx, container)
 	if hc == nil {
@@ -124,17 +119,7 @@ func RemoveTransientHealthCheckFiles(ctx context.Context, container containerd.C
 
 // RemoveTransientHealthCheckFilesByID stops and cleans up the transient timer and service using just the container ID.
 func RemoveTransientHealthCheckFilesByID(ctx context.Context, containerID string) error {
-	// Don't proceed if systemd is unavailable or disabled
-	if !defaults.IsSystemdAvailable() || os.Getenv("DISABLE_HC_SYSTEMD") == "true" {
-		return nil
-	}
-
-	// Skip healthchecks in rootless environments to avoid systemd DBUS permission issues
-	if rootlessutil.IsRootless() {
-		return nil
-	}
-
-	logrus.Debugf("Removing healthcheck timer unit: %s", containerID)
+	log.G(ctx).Debugf("Removing healthcheck timer unit: %s", containerID)
 
 	conn, err := dbus.NewSystemConnectionContext(context.Background())
 	if err != nil {
@@ -150,15 +135,15 @@ func RemoveTransientHealthCheckFilesByID(ctx context.Context, containerID string
 	tChan := make(chan string)
 	if _, err := conn.StopUnitContext(context.Background(), timer, "ignore-dependencies", tChan); err == nil {
 		if msg := <-tChan; msg != "done" {
-			logrus.Warnf("timer stop message: %s", msg)
+			log.G(ctx).Warnf("timer stop message: %s", msg)
 		}
 	}
 
 	// Stop service
 	sChan := make(chan string)
 	if _, err := conn.StopUnitContext(context.Background(), service, "ignore-dependencies", sChan); err == nil {
 		if msg := <-sChan; msg != "done" {
-			logrus.Warnf("service stop message: %s", msg)
+			log.G(ctx).Warnf("service stop message: %s", msg)
 		}
 	}