kubexit

README

kubexit

Command supervisor for coordinated Kubernetes pod container termination.

Tombstones

kubexit carves a tombstone at ${KUBEXIT_GRAVEYARD}/${KUBEXIT_NAME} to mark the birth and death of the process it supervises:

1. When a wrapped app starts, kubexit will write a tombstone with a Born timestamp.
2. When a wrapped app exits, kubexit will update the tombstone with a Died timestamp and the ExitCode.

Tombstone Content:

Born: <timestamp>
Died: <timestamp>
ExitCode: <int>

Birth Dependencies

With kubexit, you can define birth dependencies between processes that are wrapped with kubexit and configured with the same graveyard.

Unlike death dependencies, birth dependencies only work within a Kubernetes pod, because kubexit watches pod container readiness, rather than implementing its own readiness checks.

Kubexit will block the execution of the dependent container process (ex: a stateless webapp) until the dependency container (ex: a sidecar proxy) is ready.

The primary use case for this feature is Kubernetes sidecar proxies, where the proxy needs to come up before the primary container process, otherwise the primary process egress calls will fail unitl the proxy is up.

Death Dependencies

With kubexit, you can define death dependencies between processes that are wrapped with kubexit and configured with the same graveyard.

If the dependency process (ex: a stateless webapp) exits before the dependent process (ex: a sidecar proxy), kubexit will detect the tombstone update (Died: <timestamp>) and send the TERM signal to the dependent process.

The primary use case for this feature is Kubernetes Jobs, where a sidecar container needs to be gracefully shutdown when the primary container exits, otherwise the Job will never complete.

Config

kubexit is configured with environment variables only, to make it easy to configure in Kubernetes and minimize entrypoint/command changes.

Tombstone:

• KUBEXIT_NAME - The name of the tombstone file to use. Must match the name of the Kubernetes pod container, if using birth dependency.
• KUBEXIT_GRAVEYARD - The file path of the graveyard directory, where tombstones will be read and written.

Death Dependency:

• KUBEXIT_DEATH_DEPS - The name(s) of this process death dependencies, comma separated.
• KUBEXIT_GRACE_PERIOD - Duration to wait for this process to exit after a graceful termination, before being killed. Default: 30s.

Birth Dependency:

• KUBEXIT_BIRTH_DEPS - The name(s) of this process birth dependencies, comma separated.
• KUBEXIT_BIRTH_TIMEOUT - Duration to wait for all birth dependencies to be ready. Default: 30s.
• KUBEXIT_POD_NAME - The name of the Kubernetes pod that this process and all its siblings are in.
• KUBEXIT_NAMESPACE - The name of the Kubernetes namespace that this pod is in.

Install

While kubexit can easily be installed on your local machine, the primary use cases require execution within Kubernetes pod containers. So the recommended method of installation is to either side-load kubexit using a shared volume and an init container, or build kubexit into your own container images.

Build from source:

go get github.com/karlkfi/kubexit/cmd/kubexit

Copy from pre-built Alpine-based container image in a multi-stage build:

FROM karlkfi/kubexit:latest AS kubexit

FROM alpine:3.11
RUN apk --no-cache add ca-certificates tzdata
COPY --from=kubexit /bin/kubexit /bin/
ENTRYPOINT ["kubexit"]

Copy from init container to ephemeral volume:

volumes:
- name: kubexit
  emptyDir: {}

initContainers:
- name: kubexit
  image: karlkfi/kubexit:latest
  command: ['cp', '/bin/kubexit', '/kubexit/kubexit']
  volumeMounts:
  - mountPath: /kubexit
    name: kubexit

Examples

• Client Server Job
• CloudSQL Proxy Job