ansible/ansible-podman-collections
1
0
Fork 0
mirror of https://github.com/containers/ansible-podman-collections.git synced 2026-02-04 07:11:49 +00:00
Code Activity

Add podman search (#770)

Browse source 
* Add podman_search module

Signed-off-by: Derek <derek@frisbeeworld.com>
This commit is contained in:
Derek Waters 2024-06-03 16:49:29 +10:00 • committed by GitHub
parent 4cb8404b7b
commit 38d95029e8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 463 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

8
ci/playbooks/containers/podman_search.yml Normal file
View file

@ -0,0 +1,8 @@
---
- hosts: all
gather_facts: true
tasks:
- include_role:
name: podman_search
vars:
ansible_python_interpreter: "{{ _ansible_python_interpreter }}"

274
docs/podman_search_module.html Normal file
View file

@ -0,0 +1,274 @@
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="2.11.0" name="antsibull-docs" />
<title>containers.podman.podman_search module – Search for remote images using podman &#8212; Python documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=12dfc556" />
<link rel="stylesheet" type="text/css" href="_static/antsibull-minimal.css?v=9c1ca88e" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="containers.podman.podman_secret module – Manage podman secrets" href="podman_secret_module.html" />
<link rel="prev" title="containers.podman.podman_save module – Saves podman image to tar file" href="podman_save_module.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
</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-search-module"></span><section id="containers-podman-podman-search-module-search-for-remote-images-using-podman">
<h1>containers.podman.podman_search module – Search for remote images using podman<a class="headerlink" href="#containers-podman-podman-search-module-search-for-remote-images-using-podman" title="Link to this heading"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This module is part of the <a class="reference external" href="https://galaxy.ansible.com/ui/repo/published/containers/podman/">containers.podman collection</a> (version 1.14.0).</p>
<p>It is not included in <code class="docutils literal notranslate"><span class="pre">ansible-core</span></code>.
To check whether it is installed, run <code class="code docutils literal notranslate"><span class="pre">ansible-galaxy</span> <span class="pre">collection</span> <span class="pre">list</span></code>.</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_search</span></code>.</p>
</div>
<nav class="contents local" 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="#parameters" id="id2">Parameters</a></p></li>
<li><p><a class="reference internal" href="#notes" id="id3">Notes</a></p></li>
<li><p><a class="reference internal" href="#examples" id="id4">Examples</a></p></li>
<li><p><a class="reference internal" href="#return-values" id="id5">Return Values</a></p></li>
</ul>
</nav>
<section id="synopsis">
<h2><a class="toc-backref" href="#id1" role="doc-backlink">Synopsis</a><a class="headerlink" href="#synopsis" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Search for remote images using <code class="docutils literal notranslate"><span class="pre">podman</span></code></p></li>
</ul>
</section>
<section id="parameters">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Parameters</a><a class="headerlink" href="#parameters" title="Link to this heading"></a></h2>
<table class="longtable ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Comments</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-executable"></div><p class="ansible-option-title" id="ansible-collections-containers-podman-podman-search-module-parameter-executable"><strong>executable</strong></p>
<a class="ansibleOptionLink" href="#parameter-executable" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Path to <code class="docutils literal notranslate"><span class="pre">podman</span></code> executable if it is not in the <code class="docutils literal notranslate"><span class="pre">$PATH</span></code> on the machine running <code class="docutils literal notranslate"><span class="pre">podman</span></code></p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-option-default docutils literal notranslate"><span class="pre">&quot;podman&quot;</span></code></p>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-limit"></div><p class="ansible-option-title" id="ansible-collections-containers-podman-podman-search-module-parameter-limit"><strong>limit</strong></p>
<a class="ansibleOptionLink" href="#parameter-limit" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Limit the number of image results returned from the search (per image registry)</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-option-default docutils literal notranslate"><span class="pre">25</span></code></p>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-list_tags"></div><p class="ansible-option-title" id="ansible-collections-containers-podman-podman-search-module-parameter-list-tags"><strong>list_tags</strong></p>
<a class="ansibleOptionLink" href="#parameter-list_tags" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Whether or not to return the list of tags associated with each image</p>
<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><strong><span class="pre">false</span></strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-term"></div><p class="ansible-option-title" id="ansible-collections-containers-podman-podman-search-module-parameter-term"><strong>term</strong></p>
<a class="ansibleOptionLink" href="#parameter-term" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span> / <span class="ansible-option-required">required</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>The search term to look for. Will search all default registries unless a registry is defined in the search term.</p>
</div></td>
</tr>
</tbody>
</table>
</section>
<section id="notes">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Notes</a><a class="headerlink" href="#notes" title="Link to this heading"></a></h2>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>Podman may required elevated privileges in order to run properly.</p></li>
</ul>
</div>
</section>
<section id="examples">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></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">Search for any rhel images</span>
<span class="w"> </span><span class="nt">containers.podman.podman_search</span><span class="p">:</span>
<span class="w"> </span><span class="nt">term</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;rhel&quot;</span>
<span class="w"> </span><span class="nt">limit</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</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">Gather info on a specific remote image</span>
<span class="w"> </span><span class="nt">containers.podman.podman_search</span><span class="p">:</span>
<span class="w"> </span><span class="nt">term</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8&quot;</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">Gather tag info on a known remote image</span>
<span class="w"> </span><span class="nt">containers.podman.podman_search</span><span class="p">:</span>
<span class="w"> </span><span class="nt">term</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8&quot;</span>
<span class="w"> </span><span class="nt">list_tags</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">True</span>
</pre></div>
</div>
</section>
<section id="return-values">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Return Values</a><a class="headerlink" href="#return-values" title="Link 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 class="longtable ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd"><th class="head"><p>Key</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-images"></div><p class="ansible-option-title" id="ansible-collections-containers-podman-podman-search-module-return-images"><strong>images</strong></p>
<a class="ansibleOptionLink" href="#return-images" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">list</span> / <span class="ansible-option-elements">elements=string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>info from all or specified images</p>
<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> always</p>
<p class="ansible-option-line ansible-option-sample"><strong class="ansible-option-sample-bold">Sample:</strong> <code class="ansible-option-sample docutils literal notranslate"><span class="pre">[{&quot;Automated&quot;:</span> <span class="pre">&quot;&quot;,</span> <span class="pre">&quot;Description&quot;:</span> <span class="pre">&quot;Red</span> <span class="pre">Hat</span> <span class="pre">Enterprise</span> <span class="pre">Linux</span> <span class="pre">Atomic</span> <span class="pre">Image</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">minimal,</span> <span class="pre">fully</span> <span class="pre">supported</span> <span class="pre">base</span> <span class="pre">image.&quot;,</span> <span class="pre">&quot;Index&quot;:</span> <span class="pre">&quot;registry.access.redhat.com&quot;,</span> <span class="pre">&quot;Name&quot;:</span> <span class="pre">&quot;registry.access.redhat.com/rhel7-atomic&quot;,</span> <span class="pre">&quot;Official&quot;:</span> <span class="pre">&quot;&quot;,</span> <span class="pre">&quot;Stars&quot;:</span> <span class="pre">0,</span> <span class="pre">&quot;Tags&quot;:</span> <span class="pre">[&quot;1.0&quot;,</span> <span class="pre">&quot;1.1&quot;,</span> <span class="pre">&quot;1.1.1-devel&quot;]}]</span></code></p>
</div></td>
</tr>
</tbody>
</table>
<section id="authors">
<h3>Authors<a class="headerlink" href="#authors" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Derek Waters (&#64;derekwaters)</p></li>
</ul>
</section>
<section id="collection-links">
<h3>Collection links<a class="headerlink" href="#collection-links" title="Link to this heading"></a></h3>
<ul class="ansible-links">
<li><span><a aria-role="button" class="ansible-link reference external" href="https://github.com/containers/ansible-podman-collections/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc" rel="noopener external" target="_blank">Issue Tracker</a></span></li>
<li><span><a aria-role="button" class="ansible-link reference external" href="https://github.com/containers/ansible-podman-collections" rel="noopener external" target="_blank">Repository (Sources)</a></span></li>
</ul>
</section>
</section>
</section>
</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>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="podman_container_module.html">containers.podman.podman_container module – Manage podman containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_container_exec_module.html">containers.podman.podman_container_exec module – Executes a command in a running container.</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_container_info_module.html">containers.podman.podman_container_info module – Gather facts about containers using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_containers_module.html">containers.podman.podman_containers module – Manage podman containers in a batch</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_export_module.html">containers.podman.podman_export module – Export a podman container</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_generate_systemd_module.html">containers.podman.podman_generate_systemd module – Generate systemd unit from a pod or a container</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_image_module.html">containers.podman.podman_image module – Pull images for use by podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_image_info_module.html">containers.podman.podman_image_info module – Gather info about images using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_import_module.html">containers.podman.podman_import module – Import Podman container from a tar file.</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_load_module.html">containers.podman.podman_load module – Load image from a tar file.</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_login_module.html">containers.podman.podman_login module – Login to a container registry using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_login_info_module.html">containers.podman.podman_login_info module – Return the logged-in user if any for a given registry</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_logout_module.html">containers.podman.podman_logout module – Log out of a container registry using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_network_module.html">containers.podman.podman_network module – Manage podman networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_network_info_module.html">containers.podman.podman_network_info module – Gather info about podman networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_play_module.html">containers.podman.podman_play module – Play kubernetes YAML file using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_pod_module.html">containers.podman.podman_pod module – Manage Podman pods</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_pod_info_module.html">containers.podman.podman_pod_info module – Gather info about podman pods</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_prune_module.html">containers.podman.podman_prune module – Allows to prune various podman objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_runlabel_module.html">containers.podman.podman_runlabel module – Run given label from given image</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_save_module.html">containers.podman.podman_save module – Saves podman image to tar file</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">containers.podman.podman_search module – Search for remote images using podman</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_secret_module.html">containers.podman.podman_secret module – Manage podman secrets</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_secret_info_module.html">containers.podman.podman_secret_info module – Gather info about podman secrets</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_tag_module.html">containers.podman.podman_tag module – Add an additional name to a local image</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_volume_module.html">containers.podman.podman_volume module – Manage Podman volumes</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_volume_info_module.html">containers.podman.podman_volume_info module – Gather info about podman volumes</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="podman_unshare_become.html">containers.podman.podman_unshare become – Run tasks using podman unshare</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="buildah_connection.html">containers.podman.buildah connection – Interact with an existing buildah container</a></li>
<li class="toctree-l1"><a class="reference internal" href="podman_connection.html">containers.podman.podman connection – Interact with an existing podman container</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="podman_save_module.html" title="previous chapter">containers.podman.podman_save module – Saves podman image to tar file</a></li>
<li>Next: <a href="podman_secret_module.html" title="next chapter">containers.podman.podman_secret module – Manage podman secrets</a></li>
</ul></li>
</ul>
</div>
<search 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>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&#169;.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 7.3.7</a>
&amp; <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="_sources/podman_search_module.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

131
plugins/modules/podman_search.py Normal file
View file

@ -0,0 +1,131 @@
#!/usr/bin/python
# Copyright (c) 2024 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
module: podman_search
author:
- Derek Waters (@derekwaters)
short_description: Search for remote images using podman
notes:
- Podman may required elevated privileges in order to run properly.
description:
- Search for remote images using C(podman)
options:
executable:
description:
- Path to C(podman) executable if it is not in the C($PATH) on the machine running C(podman)
default: 'podman'
type: str
term:
description:
- The search term to look for. Will search all default registries unless a registry is defined in the search term.
type: str
required: True
limit:
description:
- Limit the number of image results returned from the search (per image registry)
required: False
default: 25
type: int
list_tags:
description:
- Whether or not to return the list of tags associated with each image
required: False
default: False
type: bool
'''
EXAMPLES = r"""
- name: Search for any rhel images
containers.podman.podman_search:
term: "rhel"
limit: 3
- name: Gather info on a specific remote image
containers.podman.podman_search:
term: "myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8"
- name: Gather tag info on a known remote image
containers.podman.podman_search:
term: "myimageregistry.com/ansible-automation-platform/ee-minimal-rhel8"
list_tags: True
"""
RETURN = r"""
images:
description: info from all or specified images
returned: always
type: list
sample: [
{
"Automated": "",
"Description": "Red Hat Enterprise Linux Atomic Image is a minimal, fully supported base image.",
"Index": "registry.access.redhat.com",
"Name": "registry.access.redhat.com/rhel7-atomic",
"Official": "",
"Stars": 0,
"Tags": ["1.0", "1.1", "1.1.1-devel"]
}
]
"""
import json
from ansible.module_utils.basic import AnsibleModule
def search_images(module, executable, term, limit, list_tags):
command = [executable, 'search', term, '--format', 'json']
command.extend(['--limit', "{0}".format(limit)])
if list_tags:
command.extend(['--list-tags'])
rc, out, err = module.run_command(command)
if rc != 0:
module.fail_json(msg="Unable to gather info for '{0}': {1}".format(term, err))
return out
def main():
module = AnsibleModule(
argument_spec=dict(
executable=dict(type='str', default='podman'),
term=dict(type='str', required=True),
limit=dict(type='int', required=False, default=25),
list_tags=dict(type='bool', required=False, default=False)
),
supports_check_mode=True,
)
executable = module.params['executable']
term = module.params.get('term')
limit = module.params.get('limit')
list_tags = module.params.get('list_tags')
executable = module.get_bin_path(executable, required=True)
result_str = search_images(module, executable, term, limit, list_tags)
if result_str == "":
results = []
else:
try:
results = json.loads(result_str)
except json.decoder.JSONDecodeError:
module.fail_json(msg='Failed to parse JSON output from podman search: {out}'.format(out=result_str))
results = dict(
changed=False,
images=results
)
module.exit_json(**results)
if __name__ == '__main__':
main()

50
tests/integration/targets/podman_search/tasks/main.yml Normal file
View file

@ -0,0 +1,50 @@
- name: Test podman_search
block:
- name: Search for an invalid image
containers.podman.podman_search:
term: invalidtermnope
executable: "{{ test_executable | default('podman') }}"
register: info_0
- name: Check results for no matching images
assert:
that:
- info_0.images | length == 0
- name: Search for matching images
containers.podman.podman_search:
term: etcd
executable: "{{ test_executable | default('podman') }}"
register: info_1
- name: Check results for matching images
assert:
that:
- info_1.images | length > 0
- name: Search for a specific image
containers.podman.podman_search:
term: registry.access.redhat.com/rhel7/rsyslog
executable: "{{ test_executable | default('podman') }}"
register: info_2
- name: Check result for matching image
assert:
that:
- info_2.images | length == 1
- info_2.images[0].Index == "registry.access.redhat.com"
- info_2.images[0].Name == "registry.access.redhat.com/rhel7/rsyslog"
- name: Search for specific image tags
containers.podman.podman_search:
term: registry.access.redhat.com/rhel7/rsyslog
list_tags: true
executable: "{{ test_executable | default('podman') }}"
register: info_3
- name: Check result for image tags
assert:
that:
- info_3.images | length == 1
- info_3.images[0].Tags | length > 0