Skip to content

Commit

Permalink
build based on 56159ec
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Mar 15, 2024
1 parent 10534d1 commit d2fa374
Show file tree
Hide file tree
Showing 18 changed files with 1,361 additions and 3 deletions.
2 changes: 1 addition & 1 deletion index.html
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
<!--This file is automatically generated by Documenter.jl-->
<meta http-equiv="refresh" content="0; url=./dev/"/>
<meta http-equiv="refresh" content="0; url=./stable/"/>
1 change: 1 addition & 0 deletions stable
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
v0.1.0
1 change: 1 addition & 0 deletions v0.1
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
v0.1.0
1 change: 1 addition & 0 deletions v0.1.0/.documenter-siteinfo.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-03-15T18:21:40","documenter_version":"1.3.0"}}
8 changes: 8 additions & 0 deletions v0.1.0/api/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>API · K8sDeputy.jl</title><meta name="title" content="API · K8sDeputy.jl"/><meta property="og:title" content="API · K8sDeputy.jl"/><meta property="twitter:title" content="API · K8sDeputy.jl"/><meta name="description" content="Documentation for K8sDeputy.jl."/><meta property="og:description" content="Documentation for K8sDeputy.jl."/><meta property="twitter:description" content="Documentation for K8sDeputy.jl."/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">K8sDeputy.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li><a class="tocitem" href="../quickstart/">Quickstart</a></li><li><a class="tocitem" href="../health_checks/">Health Checks</a></li><li><a class="tocitem" href="../graceful_termination/">Graceful Termination</a></li><li class="is-active"><a class="tocitem" href>API</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>API</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>API</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/beacon-biosignals/K8sDeputy.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/main/docs/src/api.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="API"><a class="docs-heading-anchor" href="#API">API</a><a id="API-1"></a><a class="docs-heading-anchor-permalink" href="#API" title="Permalink"></a></h1><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.Deputy" href="#K8sDeputy.Deputy"><code>K8sDeputy.Deputy</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Deputy(; shutdown_handler=nothing, shutdown_handler_timeout::Period=Second(5))</code></pre><p>Construct an application <code>Deputy</code> which provides health check endpoints.</p><p><strong>Keywords</strong></p><ul><li><code>shutdown_handler</code> (optional): A zero-argument function which allows the user to provide a custom callback function for when <code>shutdown!(::Deputy)</code> is called.</li><li><code>shutdown_handler_timeout::Period</code> (optional): Specifies the maximum execution duration of a <code>shutdown_handler</code>.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/health.jl#L8-L19">source</a></section></article><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.serve!" href="#K8sDeputy.serve!"><code>K8sDeputy.serve!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">K8sDeputy.serve!(deputy::Deputy, [host], [port::Integer]) -&gt; HTTP.Server</code></pre><p>Starts a non-blocking <code>HTTP.Server</code> responding to requests to <code>deputy</code> health checks. The following health check endpoints are available:</p><ul><li><code>/health/live</code>: Is the server is alive/running?</li><li><code>/health/ready</code>: Is the server ready (has <code>readied!(deputy)</code> been called)?</li></ul><p>These endpoints will respond with HTTP status <code>200 OK</code> on success or <code>503 Service Unavailable</code> on failure.</p><p><strong>Arguments</strong></p><ul><li><code>host</code> (optional): The address to listen to for incoming requests. Defaults to <code>Sockets.localhost</code>.</li><li><code>port::Integer</code> (optional): The port to listen on. Defaults to the port number specified by the environmental variable <code>DEPUTY_HEALTH_CHECK_PORT</code>, otherwise <code>8081</code>.</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/server.jl#L8-L26">source</a></section></article><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.readied!" href="#K8sDeputy.readied!"><code>K8sDeputy.readied!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">readied!(deputy::Deputy) -&gt; Nothing</code></pre><p>Mark the application as &quot;ready&quot;. Sets the readiness endpoint to respond with successful responses.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/health.jl#L24-L29">source</a></section></article><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.shutdown!" href="#K8sDeputy.shutdown!"><code>K8sDeputy.shutdown!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">shutdown!(deputy::Deputy) -&gt; Nothing</code></pre><p>Initiates a shutdown of the application by:</p><ol><li>Mark the application as shutting down (&quot;non-live&quot;).</li><li>Executing the deputy&#39;s <code>shutdown_handler</code> (if defined).</li><li>Exiting the current Julia process.</li></ol><p>If a <code>deputy.shutdown_handler</code> is defined it must complete within the <code>deputy.shutdown_handler_timeout</code> or a warning will be logged and the Julia process will immediately exit. Any exceptions that occur in the <code>deputy.shutdown_handler</code> will also be logged and result in the Julia process exiting.</p><p>A <code>shutdown_handler</code> may optionally call <code>exit</code> if a user wants to specify the exit status. By default <code>shutdown!</code> uses an exit status of <code>1</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/health.jl#L35-L51">source</a></section></article><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.graceful_terminator" href="#K8sDeputy.graceful_terminator"><code>K8sDeputy.graceful_terminator</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">graceful_terminator(f; set_entrypoint::Bool=true) -&gt; Nothing</code></pre><p>Register a zero-argument function to be called when <code>graceful_terminate</code> is called targeting this process. The user-defined function <code>f</code> is expected to call <code>exit</code> to terminate the Julia process. The <code>graceful_terminator</code> function is only allowed to be called once within a Julia process.</p><p><strong>Keywords</strong></p><ul><li><code>set_entrypoint::Bool</code> (optional): Sets the calling Julia process as the &quot;entrypoint&quot; to be targeted by default when running <code>graceful_terminate</code> in another Julia process. Users who want to utilize <code>graceful_terminator</code> in multiple Julia processes should use <code>set_entrypoint=false</code> and specify process IDs when calling <code>graceful_terminate</code>. Defaults to <code>true</code>.</li></ul><p><strong>Examples</strong></p><pre><code class="language-julia hljs">app_status = AppStatus()
graceful_terminator(() -&gt; shutdown!(app_status))</code></pre><p><strong>Kubernetes Setup</strong></p><p>When using Kubernetes (K8s) you can enable <a href="https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace">graceful termination</a> of a Julia process by defining a pod <a href="https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks"><code>preStop</code></a> container hook. Typically, K8s initiates graceful termination via the <code>TERM</code> signal but as Julia forcefully terminates when receiving this signal and Julia does not support user-defined signal handlers we utilize <code>preStop</code> instead.</p><p>The following K8s pod manifest snippet will specify K8s to call the user-defined function specified by the <code>graceful_terminator</code>:</p><pre><code class="language-yaml hljs">spec:
containers:
- lifecycle:
preStop:
exec:
command: [&quot;julia&quot;, &quot;-e&quot;, &quot;using K8sDeputy; graceful_terminate()&quot;]</code></pre><p>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 <code>[&quot;/bin/sh&quot;, &quot;-c&quot;, &quot;julia entrypoint.jl; sleep 1&quot;]</code> as this allows for both the Julia process and the <code>preStop</code> process to cleanly terminate.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/graceful_termination.jl#L33-L79">source</a></section></article><article class="docstring"><header><a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring"></a><a class="docstring-binding" id="K8sDeputy.graceful_terminate" href="#K8sDeputy.graceful_terminate"><code>K8sDeputy.graceful_terminate</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">graceful_terminate(pid::Integer=entrypoint_pid(); wait::Bool=true) -&gt; Nothing</code></pre><p>Initiates the execution of the <code>graceful_terminator</code> user callback in the process <code>pid</code>. See <code>graceful_terminator</code> for more details.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/beacon-biosignals/K8sDeputy.jl/blob/56159ecdde34df68f80cb728395aaca50cc7d6c2/src/graceful_termination.jl#L117-L122">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../graceful_termination/">« Graceful Termination</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.3.0 on <span class="colophon-date" title="Friday 15 March 2024 18:21">Friday 15 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit d2fa374

Please sign in to comment.