.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. meta::
  :antsibull-docs: 2.26.0

.. Anchors

.. _ansible_collections.stephrobert.scaleway.resource_id_lookup:

.. Anchors: short name for ansible.builtin

.. Title

stephrobert.scaleway.resource_id lookup -- Resolve a Scaleway resource name into its identifier
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This lookup plugin is part of the `stephrobert.scaleway collection <https://galaxy.ansible.com/ui/repo/published/stephrobert/scaleway/>`_ (version 0.7.0).

    It is not included in ``ansible-core``.
    To check whether it is installed, run :code:`ansible-galaxy collection list`.

    To install it, use: :code:`ansible\-galaxy collection install stephrobert.scaleway`.
    You need further requirements to be able to use this lookup plugin,
    see :ref:`Requirements <ansible_collections.stephrobert.scaleway.resource_id_lookup_requirements>` for details.

    To use it in a playbook, specify: :code:`stephrobert.scaleway.resource_id`.

.. version_added

.. rst-class:: ansible-version-added

New in stephrobert.scaleway 0.6.0

.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- Half of the modules in this collection act on a sub\-resource carrying its own identifier, which only the matching :literal:`\_info` module returns. This lookup returns that identifier from the name you already know, so a playbook does not have to call a module, register its result and dig a UUID out of it.
- The resolution table is derived from the versioned API contracts, never written by hand. A resource that stops being listable, or that loses its :literal:`name` field upstream, leaves the table at the next generation instead of staying a promise.
- The name must match exactly. The Scaleway :literal:`name` query filter matches by prefix, which the contract states itself for Instances: :literal:`server1` returns both :literal:`server100` and :literal:`server1`. The filter is sent to avoid paginating a whole fleet, and the exact comparison is always done locally.


.. Aliases


.. Requirements

.. _ansible_collections.stephrobert.scaleway.resource_id_lookup_requirements:

Requirements
------------
The below requirements are needed on the local controller node that executes this lookup.

- scaleway \>= 2.9.0




.. Terms

Terms
-----

.. tabularcolumns:: \X{1}{3}\X{2}{3}

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1
  :class: longtable ansible-option-table

  * - Parameter
    - Comments

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-_terms"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-_terms:

      .. rst-class:: ansible-option-title

      **Terms**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-_terms" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string` / :ansible-option-required:`required`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The identifier parameter you are trying to fill, such as :literal:`server\_id`.

      Exactly one, because a lookup that resolved several at once could not say which scope belonged to which.


      .. raw:: html

        </div>





.. Options

Keyword parameters
------------------

This describes keyword parameters of the lookup. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
examples: ``lookup('stephrobert.scaleway.resource_id', key1=value1, key2=value2, ...)`` and ``query('stephrobert.scaleway.resource_id', key1=value1, key2=value2, ...)``

.. tabularcolumns:: \X{1}{3}\X{2}{3}

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1
  :class: longtable ansible-option-table

  * - Parameter
    - Comments

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-access_key"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-access_key:

      .. rst-class:: ansible-option-title

      **access_key**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-access_key" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Scaleway API access key.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_ACCESS\_KEY`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-api_allow_insecure"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-api_allow_insecure:

      .. rst-class:: ansible-option-title

      **api_allow_insecure**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-api_allow_insecure" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Reach the endpoint without verifying its TLS certificate.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`false`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-api_timeout"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-api_timeout:

      .. rst-class:: ansible-option-title

      **api_timeout**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-api_timeout" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`integer`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Seconds to wait for a single API call.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-api_url"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-api_url:

      .. rst-class:: ansible-option-title

      **api_url**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-api_url" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      URL of the Scaleway API endpoint.

      Point it at a local emulator to resolve names without credentials.

      Falls back to the Scaleway configuration file, then to :literal:`https://api.scaleway.com`. It carries no default on purpose: a default is never unset, so it would always override the profile.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_API\_URL`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config_file"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-config_file:

      .. rst-class:: ansible-option-title

      **config_file**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config_file" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`path`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Path to the Scaleway configuration file.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_CONFIG\_PATH`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-name"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-name:

      .. rst-class:: ansible-option-title

      **name**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-name" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string` / :ansible-option-required:`required`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Exact name of the resource to resolve.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-organization_id"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-organization_id:

      .. rst-class:: ansible-option-title

      **organization_id**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-organization_id" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Default Organization ID.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_DEFAULT\_ORGANIZATION\_ID`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-profile"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-profile:

      .. rst-class:: ansible-option-title

      **profile**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-profile" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Name of the profile to read in the Scaleway configuration file.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_PROFILE`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-project_id"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-project_id:

      .. rst-class:: ansible-option-title

      **project_id**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-project_id" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Default Project ID.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_DEFAULT\_PROJECT\_ID`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-region"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-region:

      .. rst-class:: ansible-option-title

      **region**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-region" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Region the resource lives in, for regional resources.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-secret_key"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-secret_key:

      .. rst-class:: ansible-option-title

      **secret_key**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-secret_key" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Scaleway API secret key.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Environment variable: :envvar:`SCW\_SECRET\_KEY`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-user_agent"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-user_agent:

      .. rst-class:: ansible-option-title

      **user_agent**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-user_agent" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Value of the User\-Agent header sent to the API.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-zone"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__parameter-zone:

      .. rst-class:: ansible-option-title

      **zone**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-zone" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Zone the resource lives in, for zoned resources.


      .. raw:: html

        </div>


.. Attributes


.. Notes

Notes
-----

.. note::
   - When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
     ``lookup('stephrobert.scaleway.resource_id', term1, term2, key1=value1, key2=value2)`` and ``query('stephrobert.scaleway.resource_id', term1, term2, key1=value1, key2=value2)``
   - Exactly one match returns the identifier. No exact match and several exact matches both fail, and the message names what was found. Returning the first of several candidates would make the playbook act on a resource nobody designated.
   - The credential options are declared here rather than inherited from the module documentation fragment. A module option carries no :literal:`env` key, so its default would silently win over the environment, and a lookup meant for a local emulator would reach the real Scaleway API instead.

.. Seealso


.. Examples

Examples
--------

.. code-block:: yaml+jinja

    - name: Reboot the machine named web-01 without knowing its identifier
      stephrobert.scaleway.instance_server_action:
        zone: fr-par-1
        server_id: >-
          {{ lookup('stephrobert.scaleway.resource_id', 'server_id',
                    zone='fr-par-1', name='web-01') }}
        action: reboot
      delegate_to: localhost

    - name: Update the backend named api of a named load balancer
      stephrobert.scaleway.lb_backend:
        zone: fr-par-1
        lb_id: "{{ load_balancer_id }}"
        backend_id: >-
          {{ lookup('stephrobert.scaleway.resource_id', 'backend_id',
                    zone='fr-par-1', lb_id=load_balancer_id, name='api') }}
        forward_port: 8080
      delegate_to: localhost

    - name: Resolve the load balancer itself, then a backend inside it
      ansible.builtin.set_fact:
        load_balancer_id: >-
          {{ lookup('stephrobert.scaleway.resource_id', 'lb_id',
                    zone='fr-par-1', name='public') }}



.. Facts


.. Return values

Return Value
------------

.. tabularcolumns:: \X{1}{3}\X{2}{3}

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1
  :class: longtable ansible-option-table

  * - Key
    - Description

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-_raw"></div>

      .. _ansible_collections.stephrobert.scaleway.resource_id_lookup__return-_raw:

      .. rst-class:: ansible-option-title

      **Return value**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-_raw" title="Permalink to this return value"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`list` / :ansible-option-elements:`elements=string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The identifier of the single resource carrying that exact name.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` success


      .. raw:: html

        </div>



..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Stéphane Robert (@stephrobert)


.. Extra links

Collection links
~~~~~~~~~~~~~~~~

.. ansible-links::

  - title: "Issue Tracker"
    url: "https://github.com/stephrobert/collection-scaleway/issues"
    external: true
  - title: "Repository (Sources)"
    url: "https://github.com/stephrobert/collection-scaleway"
    external: true


.. Parsing errors