1
0
Fork 0
mirror of https://github.com/containers/ansible-podman-collections.git synced 2026-02-04 07:11:49 +00:00
ansible-podman-collections/docs/podman_generate_systemd_module.html
Andrew Imeson 18a939a167
Fix typos and spelling errors (#639)
Found with codespell

Signed-off-by: Andrew Imeson <andrew@andrewimeson.com>
2023-09-05 11:30:15 +03:00

547 lines
No EOL
39 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>containers.podman.podman_generate_systemd Generate systemd unit from a pod or a container &#8212; Python documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
<link rel="stylesheet" type="text/css" href="_static/antsibull-minimal.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<span class="target" id="ansible-collections-containers-podman-podman-generate-systemd-module"></span><div class="section" id="containers-podman-podman-generate-systemd-generate-systemd-unit-from-a-pod-or-a-container">
<h1>containers.podman.podman_generate_systemd Generate systemd unit from a pod or a container<a class="headerlink" href="#containers-podman-podman-generate-systemd-generate-systemd-unit-from-a-pod-or-a-container" title="Permalink to this heading"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This plugin is part of the <a class="reference external" href="https://galaxy.ansible.com/containers/podman">containers.podman collection</a> (version 1.10.1).</p>
<p>To install it use: <code class="code docutils literal notranslate"><span class="pre">ansible-galaxy</span> <span class="pre">collection</span> <span class="pre">install</span> <span class="pre">containers.podman</span></code>.</p>
<p>To use it in a playbook, specify: <code class="code docutils literal notranslate"><span class="pre">containers.podman.podman_generate_systemd</span></code>.</p>
</div>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#synopsis" id="id1">Synopsis</a></p></li>
<li><p><a class="reference internal" href="#requirements" id="id2">Requirements</a></p></li>
<li><p><a class="reference internal" href="#parameters" id="id3">Parameters</a></p></li>
<li><p><a class="reference internal" href="#notes" id="id4">Notes</a></p></li>
<li><p><a class="reference internal" href="#examples" id="id5">Examples</a></p></li>
<li><p><a class="reference internal" href="#return-values" id="id6">Return Values</a></p></li>
</ul>
</div>
<div class="section" id="synopsis">
<h2><a class="toc-backref" href="#id1">Synopsis</a><a class="headerlink" href="#synopsis" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>Generate systemd .service unit file(s) from a pod or a container</p></li>
<li><p>Support Ansible check mode</p></li>
</ul>
</div>
<div class="section" id="requirements">
<h2><a class="toc-backref" href="#id2">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this heading"></a></h2>
<p>The below requirements are needed on the host that executes this module.</p>
<ul class="simple">
<li><p>Podman installed on target host</p></li>
</ul>
</div>
<div class="section" id="parameters">
<h2><a class="toc-backref" href="#id3">Parameters</a><a class="headerlink" href="#parameters" title="Permalink to this heading"></a></h2>
<table border=0 cellpadding=0 class="documentation-table">
<tr>
<th colspan="1">Parameter</th>
<th>Choices/<font color="blue">Defaults</font></th>
<th width="100%">Comments</th>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-after"></div>
<b>after</b>
<a class="ansibleOptionLink" href="#parameter-after" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">list</span>
/ <span style="color: purple">elements=string</span> </div>
</td>
<td>
</td>
<td>
<div>Add the systemd unit after (<code>After=</code>) option, that ordering dependencies between the list of dependencies and this service.</div>
<div>This option may be specified more than once.</div>
<div>User-defined dependencies will be appended to the generated unit file</div>
<div>But any existing options such as needed or defined by default (e.g. <code>online.target</code>) will not be removed or overridden.</div>
<div>Only with Podman 4.0.0 and above</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-container_prefix"></div>
<b>container_prefix</b>
<a class="ansibleOptionLink" href="#parameter-container_prefix" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
</td>
<td>
<div>Set the systemd unit name prefix for containers.</div>
<div>If not set, use the default defined by podman, <code>container</code>.</div>
<div>Refer to podman-generate-systemd(1) man page for more information.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-dest"></div>
<b>dest</b>
<a class="ansibleOptionLink" href="#parameter-dest" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">path</span>
</div>
</td>
<td>
</td>
<td>
<div>Destination of the generated systemd unit file(s)</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-env"></div>
<b>env</b>
<a class="ansibleOptionLink" href="#parameter-env" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">dictionary</span>
</div>
</td>
<td>
</td>
<td>
<div>Set environment variables to the systemd unit files.</div>
<div>Keys are the environment variable names, and values are the environment variable values</div>
<div>Only with Podman 4.3.0 and above</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-executable"></div>
<b>executable</b>
<a class="ansibleOptionLink" href="#parameter-executable" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
<b>Default:</b><br/><div style="color: blue">"podman"</div>
</td>
<td>
<div><code>Podman</code> executable name or full path</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-name"></div>
<b>name</b>
<a class="ansibleOptionLink" href="#parameter-name" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
/ <span style="color: red">required</span> </div>
</td>
<td>
</td>
<td>
<div>Name of the pod or container to export</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-new"></div>
<b>new</b>
<a class="ansibleOptionLink" href="#parameter-new" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">boolean</span>
</div>
</td>
<td>
<ul style="margin: 0; padding: 0"><b>Choices:</b>
<li><div style="color: blue"><b>no</b>&nbsp;&larr;</div></li>
<li>yes</li>
</ul>
</td>
<td>
<div>Generate unit files that create containers and pods, not only start them.</div>
<div>Refer to podman-generate-systemd(1) man page for more information.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-no_header"></div>
<b>no_header</b>
<a class="ansibleOptionLink" href="#parameter-no_header" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">boolean</span>
</div>
</td>
<td>
<ul style="margin: 0; padding: 0"><b>Choices:</b>
<li><div style="color: blue"><b>no</b>&nbsp;&larr;</div></li>
<li>yes</li>
</ul>
</td>
<td>
<div>Do not generate the header including meta data such as the Podman version and the timestamp.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-pod_prefix"></div>
<b>pod_prefix</b>
<a class="ansibleOptionLink" href="#parameter-pod_prefix" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
</td>
<td>
<div>Set the systemd unit name prefix for pods.</div>
<div>If not set, use the default defined by podman, <code>pod</code>.</div>
<div>Refer to podman-generate-systemd(1) man page for more information.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-requires"></div>
<b>requires</b>
<a class="ansibleOptionLink" href="#parameter-requires" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">list</span>
/ <span style="color: purple">elements=string</span> </div>
</td>
<td>
</td>
<td>
<div>Set the systemd unit requires (Requires=) option.</div>
<div>Similar to wants, but declares a stronger requirement dependency.</div>
<div>Only with Podman 4.0.0 and above</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-restart_policy"></div>
<b>restart_policy</b>
<a class="ansibleOptionLink" href="#parameter-restart_policy" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
<ul style="margin: 0; padding: 0"><b>Choices:</b>
<li>no-restart</li>
<li>on-success</li>
<li>on-failure</li>
<li>on-abnormal</li>
<li>on-watchdog</li>
<li>on-abort</li>
<li>always</li>
</ul>
</td>
<td>
<div>Restart policy of the service</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-restart_sec"></div>
<b>restart_sec</b>
<a class="ansibleOptionLink" href="#parameter-restart_sec" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">integer</span>
</div>
</td>
<td>
</td>
<td>
<div>Configures the time to sleep before restarting a service (as configured with restart-policy).</div>
<div>Takes a value in seconds.</div>
<div>Only with Podman 4.0.0 and above</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-separator"></div>
<b>separator</b>
<a class="ansibleOptionLink" href="#parameter-separator" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>
</td>
<td>
<div>Systemd unit name separator between the name/id of a container/pod and the prefix.</div>
<div>If not set, use the default defined by podman, <code>-</code>.</div>
<div>Refer to podman-generate-systemd(1) man page for more information.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-start_timeout"></div>
<b>start_timeout</b>
<a class="ansibleOptionLink" href="#parameter-start_timeout" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">integer</span>
</div>
</td>
<td>
</td>
<td>
<div>Override the default start timeout for the container with the given value in seconds.</div>
<div>Only with Podman 4.0.0 and above</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-stop_timeout"></div>
<b>stop_timeout</b>
<a class="ansibleOptionLink" href="#parameter-stop_timeout" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">integer</span>
</div>
</td>
<td>
</td>
<td>
<div>Override the default stop timeout for the container with the given value in seconds.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-use_names"></div>
<b>use_names</b>
<a class="ansibleOptionLink" href="#parameter-use_names" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">boolean</span>
</div>
</td>
<td>
<ul style="margin: 0; padding: 0"><b>Choices:</b>
<li>no</li>
<li><div style="color: blue"><b>yes</b>&nbsp;&larr;</div></li>
</ul>
</td>
<td>
<div>Use name of the containers for the start, stop, and description in the unit file.</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="parameter-wants"></div>
<b>wants</b>
<a class="ansibleOptionLink" href="#parameter-wants" title="Permalink to this option"></a>
<div style="font-size: small">
<span style="color: purple">list</span>
/ <span style="color: purple">elements=string</span> </div>
</td>
<td>
</td>
<td>
<div>Add the systemd unit wants (<code>Wants=</code>) option, that this service is (weak) dependent on.</div>
<div>This option may be specified more than once.</div>
<div>This option does not influence the order in which services are started or stopped.</div>
<div>User-defined dependencies will be appended to the generated unit file</div>
<div>But any existing options such as needed or defined by default (e.g. <code>online.target</code>) will not be removed or overridden.</div>
<div>Only with Podman 4.0.0 and above</div>
</td>
</tr>
</table>
<br/></div>
<div class="section" id="notes">
<h2><a class="toc-backref" href="#id4">Notes</a><a class="headerlink" href="#notes" title="Permalink to this heading"></a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>You can store your systemd unit files in <code class="docutils literal notranslate"><span class="pre">/etc/systemd/user/</span></code> for system wide usage</p></li>
<li><p>Or you can store them in <code class="docutils literal notranslate"><span class="pre">~/.config/systemd/user/</span></code> for usage at a specific user</p></li>
<li><p>If you indicate a pod, the systemd units for it and all its containers will be generated</p></li>
<li><p>Create all your pods, containers and their dependencies before generating the systemd files</p></li>
<li><p>If a container or pod is already started before you do a <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">daemon</span> <span class="pre">reload</span></code>, systemd will not see the container or pod as started</p></li>
<li><p>Stop your container or pod before you do a <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">daemon</span> <span class="pre">reload</span></code>, then you can start them with <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">start</span> <span class="pre">my_container.service</span></code></p></li>
</ul>
</div>
</div>
<div class="section" id="examples">
<h2><a class="toc-backref" href="#id5">Examples</a><a class="headerlink" href="#examples" title="Permalink to this heading"></a></h2>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example of creating a container and integrate it into systemd</span><span class="w"></span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">A postgres container must exist, stopped</span><span class="w"></span>
<span class="w"> </span><span class="nt">containers.podman.podman_container</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local</span><span class="w"></span>
<span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">docker.io/library/postgres:latest</span><span class="w"></span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">stopped</span><span class="w"></span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Systemd unit files for postgres container must exist</span><span class="w"></span>
<span class="w"> </span><span class="nt">containers.podman.podman_generate_systemd</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local</span><span class="w"></span>
<span class="w"> </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">~/.config/systemd/user/</span><span class="w"></span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Postgres container must be started and enabled on systemd</span><span class="w"></span>
<span class="w"> </span><span class="nt">ansible.builtin.systemd</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">container-postgres_local</span><span class="w"></span>
<span class="w"> </span><span class="nt">daemon_reload</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">yes</span><span class="w"></span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">started</span><span class="w"></span>
<span class="w"> </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">yes</span><span class="w"></span>
<span class="c1"># Generate the unit files, but store them on an Ansible variable</span><span class="w"></span>
<span class="c1"># instead of writing them on target host</span><span class="w"></span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Systemd unit files for postgres container must be generated</span><span class="w"></span>
<span class="w"> </span><span class="nt">containers.podman.podman_generate_systemd</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local</span><span class="w"></span>
<span class="w"> </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local_systemd_unit</span><span class="w"></span>
<span class="c1"># Generate the unit files with environment variables sets</span><span class="w"></span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Systemd unit files for postgres container must be generated</span><span class="w"></span>
<span class="w"> </span><span class="nt">containers.podman.podman_generate_systemd</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local</span><span class="w"></span>
<span class="w"> </span><span class="nt">env</span><span class="p">:</span><span class="w"></span>
<span class="w"> </span><span class="nt">POSTGRES_USER</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my_app</span><span class="w"></span>
<span class="w"> </span><span class="nt">POSTGRES_PASSWORD</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">example</span><span class="w"></span>
<span class="w"> </span><span class="nt">register</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgres_local_systemd_unit</span><span class="w"></span>
</pre></div>
</div>
</div>
<div class="section" id="return-values">
<h2><a class="toc-backref" href="#id6">Return Values</a><a class="headerlink" href="#return-values" title="Permalink to this heading"></a></h2>
<p>Common return values are documented <span class="xref std std-ref">here</span>, the following are the fields unique to this module:</p>
<table border=0 cellpadding=0 class="documentation-table">
<tr>
<th colspan="1">Key</th>
<th>Returned</th>
<th width="100%">Description</th>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="return-podman_command"></div>
<b>podman_command</b>
<a class="ansibleOptionLink" href="#return-podman_command" title="Permalink to this return value"></a>
<div style="font-size: small">
<span style="color: purple">string</span>
</div>
</td>
<td>always</td>
<td>
<div>A copy of the podman command used to generate the systemd unit(s)</div>
<br/>
<div style="font-size: smaller"><b>Sample:</b></div>
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">podman generate systemd my_webapp</div>
</td>
</tr>
<tr>
<td colspan="1">
<div class="ansibleOptionAnchor" id="return-systemd_units"></div>
<b>systemd_units</b>
<a class="ansibleOptionLink" href="#return-systemd_units" title="Permalink to this return value"></a>
<div style="font-size: small">
<span style="color: purple">dictionary</span>
</div>
</td>
<td>always</td>
<td>
<div>A copy of the generated systemd .service unit(s)</div>
<br/>
<div style="font-size: smaller"><b>Sample:</b></div>
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{&#x27;container-postgres_local&#x27;: &#x27; #Content of the systemd .servec unit for postgres_local container&#x27;, &#x27;pod-my_webapp&#x27;: &#x27; #Content of the systemd .servec unit for my_webapp pod&#x27;}</div>
</td>
</tr>
</table>
<br/><br/><div class="section" id="authors">
<h3>Authors<a class="headerlink" href="#authors" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>Sébastien Gendre (&#64;CyberFox001)</p></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">Python</a></h1>
<h3>Navigation</h3>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 5.0.2</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="_sources/podman_generate_systemd_module.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>