diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 7d60a2d..29aa0df 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-25T18:36:03","documenter_version":"1.5.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-08-06T18:09:51","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 4864226..60d5c82 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,8 +1,8 @@ -API · K8sDeputy.jl
GitHub

API

K8sDeputy.Deputy — Type
Deputy(; shutdown_handler=nothing, shutdown_handler_timeout::Period=Second(5))

Construct an application Deputy which provides health check endpoints.

Keywords

  • shutdown_handler (optional): A zero-argument function which allows the user to provide a custom callback function for when shutdown!(::Deputy) is called.
  • shutdown_handler_timeout::Period (optional): Specifies the maximum execution duration of a shutdown_handler.
source
K8sDeputy.serve! — Function
K8sDeputy.serve!(deputy::Deputy, [host], [port::Integer]; kwargs...) -> HTTP.Server

Starts a non-blocking HTTP.Server responding to requests to deputy health checks. The following health check endpoints are available:

  • /health/live: Is the server is alive/running?
  • /health/ready: Is the server ready (has readied!(deputy) been called)?

These endpoints will respond with HTTP status 200 OK on success or 503 Service Unavailable on failure.

Arguments

  • host (optional): The address to listen to for incoming requests. Defaults to Sockets.localhost.
  • port::Integer (optional): The port to listen on. Defaults to the port number specified by the environmental variable DEPUTY_HEALTH_CHECK_PORT, otherwise 8081.

Any kwargs provided are passed to HTTP.serve!.

source
K8sDeputy.readied! — Function
readied!(deputy::Deputy) -> Nothing

Mark the application as "ready". Sets the readiness endpoint to respond with successful responses.

source
K8sDeputy.shutdown! — Function
shutdown!(deputy::Deputy) -> Nothing

Initiates a shutdown of the application by:

  1. Mark the application as shutting down ("non-live").
  2. Executing the deputy's shutdown_handler (if defined).
  3. Exiting the current Julia process.

If a deputy.shutdown_handler is defined it must complete within the deputy.shutdown_handler_timeout or a warning will be logged and the Julia process will immediately exit. Any exceptions that occur in the deputy.shutdown_handler will also be logged and result in the Julia process exiting.

A shutdown_handler may optionally call exit if a user wants to specify the exit status. By default shutdown! uses an exit status of 1.

source
K8sDeputy.graceful_terminator — Function
graceful_terminator(f; set_entrypoint::Bool=true) -> Nothing

Register a zero-argument function to be called when graceful_terminate is called targeting this process. The user-defined function f is expected to call exit to terminate the Julia process. The graceful_terminator function is only allowed to be called once within a Julia process.

Keywords

  • set_entrypoint::Bool (optional): Sets the calling Julia process as the "entrypoint" to be targeted by default when running graceful_terminate in another Julia process. Users who want to utilize graceful_terminator in multiple Julia processes should use set_entrypoint=false and specify process IDs when calling graceful_terminate. Defaults to true.

Examples

app_status = AppStatus()
+API · K8sDeputy.jl
GitHub
API
K8sDeputy.Deputy — Type
Deputy(; shutdown_handler=nothing, shutdown_handler_timeout::Period=Second(5))
Construct an application Deputy which provides health check endpoints.
Keywords
  • shutdown_handler (optional): A zero-argument function which allows the user to provide a custom callback function for when shutdown!(::Deputy) is called.
  • shutdown_handler_timeout::Period (optional): Specifies the maximum execution duration of a shutdown_handler.
source
K8sDeputy.serve! — Function
K8sDeputy.serve!(deputy::Deputy, [host], [port::Integer]; kwargs...) -> HTTP.Server
Starts a non-blocking HTTP.Server responding to requests to deputy health checks. The following health check endpoints are available:
  • /health/live: Is the server is alive/running?
  • /health/ready: Is the server ready (has readied!(deputy) been called)?
These endpoints will respond with HTTP status 200 OK on success or 503 Service Unavailable on failure.
Arguments
  • host (optional): The address to listen to for incoming requests. Defaults to Sockets.localhost.
  • port::Integer (optional): The port to listen on. Defaults to the port number specified by the environmental variable DEPUTY_HEALTH_CHECK_PORT, otherwise 8081.
Any kwargs provided are passed to HTTP.serve!.
source
K8sDeputy.readied! — Function
readied!(deputy::Deputy) -> Nothing
Mark the application as "ready". Sets the readiness endpoint to respond with successful responses.
source
K8sDeputy.shutdown! — Function
shutdown!(deputy::Deputy) -> Nothing
Initiates a shutdown of the application by:
  1. Mark the application as shutting down ("non-live").
  2. Executing the deputy's shutdown_handler (if defined).
  3. Exiting the current Julia process.
If a deputy.shutdown_handler is defined it must complete within the deputy.shutdown_handler_timeout or a warning will be logged and the Julia process will immediately exit. Any exceptions that occur in the deputy.shutdown_handler will also be logged and result in the Julia process exiting.
A shutdown_handler may optionally call exit if a user wants to specify the exit status. By default shutdown! uses an exit status of 1.
source
K8sDeputy.graceful_terminator — Function
graceful_terminator(f; set_entrypoint::Bool=true) -> Nothing
Register a zero-argument function to be called when graceful_terminate is called targeting this process. The user-defined function f is expected to call exit to terminate the Julia process. The graceful_terminator function is only allowed to be called once within a Julia process.
Keywords
  • set_entrypoint::Bool (optional): Sets the calling Julia process as the "entrypoint" to be targeted by default when running graceful_terminate in another Julia process. Users who want to utilize graceful_terminator in multiple Julia processes should use set_entrypoint=false and specify process IDs when calling graceful_terminate. Defaults to true.
Examples
app_status = AppStatus()
 graceful_terminator(() -> shutdown!(app_status))
Kubernetes Setup
When using Kubernetes (K8s) you can enable graceful termination of a Julia process by defining a pod preStop container hook. Typically, K8s initiates graceful termination via the TERM signal but as Julia forcefully terminates when receiving this signal and Julia does not support user-defined signal handlers we utilize preStop instead.
The following K8s pod manifest snippet will specify K8s to call the user-defined function specified by the graceful_terminator:
spec:
   containers:
     - lifecycle:
         preStop:
           exec:
-            command: ["julia", "-e", "using K8sDeputy; graceful_terminate()"]
Additionally, the entrypoint for the container should also not directly use the Julia process as the init process (PID 1). Instead, users should define their entrypoint similarly to ["/bin/sh", "-c", "julia entrypoint.jl; sleep 1"] as this allows for both the Julia process and the preStop process to cleanly terminate.
source
K8sDeputy.graceful_terminate — Function
graceful_terminate(pid::Int32=entrypoint_pid(); wait::Bool=true) -> Nothing
Initiates the execution of the graceful_terminator user callback in the process pid. See graceful_terminator for more details.
source

+            command: ["julia", "-e", "using K8sDeputy; graceful_terminate()"]

Additionally, the entrypoint for the container should also not directly use the Julia process as the init process (PID 1). Instead, users should define their entrypoint similarly to ["/bin/sh", "-c", "julia entrypoint.jl; sleep 1"] as this allows for both the Julia process and the preStop process to cleanly terminate.

source
K8sDeputy.graceful_terminate — Function
graceful_terminate(pid::Int32=entrypoint_pid(); wait::Bool=true) -> Nothing

Initiates the execution of the graceful_terminator user callback in the process pid. See graceful_terminator for more details.

source
diff --git a/dev/graceful_termination/index.html b/dev/graceful_termination/index.html index 155615b..6421371 100644 --- a/dev/graceful_termination/index.html +++ b/dev/graceful_termination/index.html @@ -36,4 +36,4 @@ volumes: - name: deputy-ipc emptyDir: - medium: Memory + medium: Memory diff --git a/dev/health_checks/index.html b/dev/health_checks/index.html index ed2a36b..a6ed11a 100644 --- a/dev/health_checks/index.html +++ b/dev/health_checks/index.html @@ -45,4 +45,4 @@ # Application code finally shutdown!(deputy) -end

Once shutdown! is called the following occurs:

  1. The liveness endpoint starts returning failure responses
  2. The deputy's shutdown_handler is called
  3. The Julia process is terminated

By default the shutdown_handler only has 5 seconds to complete. If your shutdown_handler requires more time to execute you can change the timeout by using the keyword shutdown_handler_timeout.

Depending on your application you may want to define multiple calls to shutdown!. For example you may want to call shutdown! from within graceful_terminator to enable graceful termination support for you application.

+end

Once shutdown! is called the following occurs:

  1. The liveness endpoint starts returning failure responses
  2. The deputy's shutdown_handler is called
  3. The Julia process is terminated

By default the shutdown_handler only has 5 seconds to complete. If your shutdown_handler requires more time to execute you can change the timeout by using the keyword shutdown_handler_timeout.

Depending on your application you may want to define multiple calls to shutdown!. For example you may want to call shutdown! from within graceful_terminator to enable graceful termination support for you application.

diff --git a/dev/index.html b/dev/index.html index dbd5f35..47f05b8 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · K8sDeputy.jl
GitHub

K8sDeputy.jl

CI codecov Code Style: YASGuide Stable Documentation Dev Documentation

Provides K8s health checks and graceful termination support on behalf of Julia services.

+Home · K8sDeputy.jl
GitHub

K8sDeputy.jl

CI codecov Code Style: YASGuide Stable Documentation Dev Documentation

Provides K8s health checks and graceful termination support on behalf of Julia services.

diff --git a/dev/objects.inv b/dev/objects.inv index b6e7d2b..5384a42 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ diff --git a/dev/quickstart/index.html b/dev/quickstart/index.html index da2dfdc..307b708 100644 --- a/dev/quickstart/index.html +++ b/dev/quickstart/index.html @@ -47,4 +47,4 @@ volumes: - name: deputy-ipc emptyDir: - medium: Memory + medium: Memory