k3s API server POST retries without idempotency guarantee

Answer

k3s uses the standard Kubernetes API server. There is no k3s-specific server-side idempotency key or deduplication layer for POST create operations in either HA etcd or single-node SQLite mode. Idempotency for creates is a client responsibility, not a server-side feature in k3s.

Confirmed facts

• k3s forwards API requests to the underlying datastore without request-ID tracking for POST.
• The API server behavior is the same for etcd and SQLite: the API layer does not track request IDs to prevent duplicate processing of the same logical intent. Datastore atomicity is provided, but not request de-duplication.
• Standard Kubernetes semantics apply: a POST to create a named resource returns 409 Conflict on a repeat if the name already exists. A POST with generateName or no name can create a new resource on each retry.
• There is no supported k3s configuration or annotation to enforce idempotent creates for POST beyond standard Kubernetes API behavior.

Likely explanation

Client libraries such as client-go and kubectl --retry repeat the HTTP request on transient errors or timeouts. If the client times out after the server has committed the write, a retry will be processed as a new request. With a fixed name the API returns 409, which clients treat as success. With generated names the API creates duplicates.

Steps for this case

1. Avoid POST for repeatable operations. Use kubectl apply or server-side apply which uses PATCH/PUT and is the recommended idempotent alternative.
2. If POST must be used, provide a deterministic name in metadata.name. Do not rely on generateName for critical resources.
3. Handle 409 Conflict in client logic as an indication the previous create may have succeeded.

One missing diagnostic detail that changes the recommendation: are you using standard client-go/kubectl retry logic or a custom client with its own timeout and retry policy? The retry semantics and safe handling differ.