Introduction

A Kubernetes postStart hook can run a command immediately after a container starts. Using curl in that hook is a common way to notify another service, warm an endpoint, or perform a lightweight registration step, but it needs to be done carefully because hook failures affect container startup.

How postStart Actually Behaves

The postStart hook runs after the container process is created, but Kubernetes does not guarantee that your application is already ready to serve requests. That distinction matters. A successful hook does not replace a readiness probe, and a failing hook can cause the container to be restarted.

You configure the hook under the container's lifecycle section. The hook can use an exec action, which is the most common choice when you want to invoke curl:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: api-worker
5spec:
6  containers:
7    - name: app
8      image: curlimages/curl:8.7.1
9      command: ["/bin/sh", "-c", "sleep 3600"]
10      lifecycle:
11        postStart:
12          exec:
13            command:
14              - /bin/sh
15              - -c
16              - >
17                curl -fsS --retry 5 --retry-delay 2
18                http://config-service.default.svc.cluster.local/register?pod=api-worker

This command uses:

• '-f to fail on HTTP errors'
• '-sS to stay quiet but still print errors'
• '--retry to tolerate short startup races'

If the hook exits with a non-zero status, Kubernetes treats it as a container startup failure.

When curl in postStart Is a Good Fit

postStart is reasonable when the action is short, idempotent, and non-interactive. Good examples include sending a registration call, pulling a small piece of dynamic configuration, or pinging a local sidecar to perform a one-time warm-up.

Here is a more realistic example where an application tells an internal control plane that it exists:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: report-api
5spec:
6  replicas: 2
7  selector:
8    matchLabels:
9      app: report-api
10  template:
11    metadata:
12      labels:
13        app: report-api
14    spec:
15      containers:
16        - name: report-api
17          image: my-registry/report-api:1.4.0
18          lifecycle:
19            postStart:
20              exec:
21                command:
22                  - /bin/sh
23                  - -c
24                  - >
25                    curl -fsS --retry 10 --retry-delay 1
26                    -X POST
27                    -H 'Content-Type: application/json'
28                    -d '{"service":"report-api","instance":"$(hostname)"}'
29                    http://registry.default.svc.cluster.local/register

The example is useful only if the image contains curl and a shell. Minimal production images often omit both, so verify that first.

Choosing Between postStart, initContainers, and Probes

A lot of startup bugs come from using postStart for the wrong job.

Use an initContainer when the task must complete before the main container starts at all. That is the better choice for downloading files, running migrations, or waiting on another service.

Use a readiness probe when you want Kubernetes to decide whether traffic should reach the pod. A postStart hook does not make a pod safe for traffic by itself.

Use postStart when the action is tied to container startup but does not need separate image packaging or long-running coordination.

For example, warming a local endpoint is often fine:

1lifecycle:
2  postStart:
3    exec:
4      command:
5        - /bin/sh
6        - -c
7        - >
8          until curl -fsS http://127.0.0.1:8080/internal/cache-warm;
9          do sleep 1; done

That said, keep the loop bounded. An unbounded wait can make startup failures harder to diagnose.

Making the Hook Safer

There are three practical rules for curl in startup hooks.

First, make the request idempotent. Container restarts happen, and a hook may run more than once. A registration endpoint should tolerate duplicates.

Second, fail fast with useful errors. Silent retries without -f or -S can make debugging painful.

Third, avoid external dependencies when possible. A pod whose startup depends on a remote HTTP call becomes less reliable than one that starts independently and reports status later.

If you need custom logic, place it in a small shell script shipped with the image:

1#!/bin/sh
2set -eu
3
4curl -fsS --retry 5 --retry-delay 2 \
5  http://config-service.default.svc.cluster.local/bootstrap

Then call the script from postStart. This keeps the YAML readable and makes local testing easier.

Common Pitfalls

The most common mistake is assuming postStart means "after the app is ready." It does not. If the hook talks to the application's own port, add retry logic or move the behavior elsewhere.

Another failure mode is forgetting that the image might not include curl. Distroless and slim images commonly exclude it. In those cases, either add the binary explicitly or use a different startup mechanism.

Timeouts are another problem. A slow HTTP dependency can keep restarting the container if the hook continually fails. Keep the action small and bounded.

Finally, do not put critical business logic in a startup hook unless you are comfortable treating a hook failure as an application failure. Kubernetes will.

Summary

• 'postStart runs after container creation, not after application readiness.'
• 'curl works well for short, idempotent startup notifications or warm-up calls.'
• Always assume the hook may be retried because the container can restart.
• Prefer initContainers for blocking setup and readiness probes for traffic gating.
• Fail clearly, bound retries, and make sure the image really contains curl.