From 838e4e3f0230a89e35e7f10a54f3e7d56f4cb50d Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 11 Dec 2023 19:09:57 +0100 Subject: [PATCH] Add Alicloud, Online, Packet, and Scaleway scenario guides (#7714) * Add Alicloud, Packet, and Scaleway scenario guides. These were taken from https://github.com/ansible/ansible-documentation/tree/3f12228c79f2e1aafd52e3f9be15444a4746ec3e/docs/docsite/rst/scenario_guides and adjusted to reality. * Fix references. * Add Online guide. * Add BOTMETA entries. * Use FQCN. * Improve code formatting and indentation. * Update BOTMETA. --- .github/BOTMETA.yml | 33 +++ docs/docsite/extra-docs.yml | 6 + docs/docsite/rst/guide_alicloud.rst | 96 +++++++++ docs/docsite/rst/guide_online.rst | 49 +++++ docs/docsite/rst/guide_packet.rst | 214 +++++++++++++++++++ docs/docsite/rst/guide_scaleway.rst | 320 ++++++++++++++++++++++++++++ tests/sanity/extra/botmeta.py | 6 +- 7 files changed, 723 insertions(+), 1 deletion(-) create mode 100644 docs/docsite/rst/guide_alicloud.rst create mode 100644 docs/docsite/rst/guide_online.rst create mode 100644 docs/docsite/rst/guide_packet.rst create mode 100644 docs/docsite/rst/guide_scaleway.rst diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index ff40380769..fc498404ba 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1405,6 +1405,39 @@ files: maintainers: felixfontein $tests/fqdn_valid.py: maintainers: vbotka +######################### + docs/docsite/rst/filter_guide.rst: {} + docs/docsite/rst/filter_guide_abstract_informations.rst: {} + docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst: + maintainers: keilr + docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst: + maintainers: felixfontein giner + docs/docsite/rst/filter_guide_abstract_informations_grouping.rst: + maintainers: felixfontein + docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst: + maintainers: vbotka + docs/docsite/rst/filter_guide_conversions.rst: + maintainers: Ajpantuso kellyjonbrazil + docs/docsite/rst/filter_guide_creating_identifiers.rst: + maintainers: Ajpantuso + docs/docsite/rst/filter_guide_paths.rst: {} + docs/docsite/rst/filter_guide_selecting_json_data.rst: {} + docs/docsite/rst/filter_guide_working_with_times.rst: + maintainers: resmo + docs/docsite/rst/filter_guide_working_with_unicode.rst: + maintainers: Ajpantuso + docs/docsite/rst/filter_guide_working_with_versions.rst: + maintainers: ericzolf + docs/docsite/rst/guide_alicloud.rst: + maintainers: xiaozhu36 + docs/docsite/rst/guide_online.rst: + maintainers: remyleone + docs/docsite/rst/guide_packet.rst: + maintainers: baldwinSPC nurfet-becirevic t0mk teebes + docs/docsite/rst/guide_scaleway.rst: + maintainers: $team_scaleway + docs/docsite/rst/test_guide.rst: + maintainers: felixfontein ######################### tests/: labels: tests diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml index 2171031ac1..529573606c 100644 --- a/docs/docsite/extra-docs.yml +++ b/docs/docsite/extra-docs.yml @@ -8,3 +8,9 @@ sections: toctree: - filter_guide - test_guide + - title: Cloud Guides + toctree: + - guide_alicloud + - guide_online + - guide_packet + - guide_scaleway diff --git a/docs/docsite/rst/guide_alicloud.rst b/docs/docsite/rst/guide_alicloud.rst new file mode 100644 index 0000000000..f38bd8df6e --- /dev/null +++ b/docs/docsite/rst/guide_alicloud.rst @@ -0,0 +1,96 @@ +.. + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later + +.. _ansible_collections.community.general.docsite.guide_alicloud: + +Alibaba Cloud Compute Services Guide +==================================== + +Introduction +```````````` + +The community.general collection contains several modules for controlling and managing Alibaba Cloud Compute Services (Alicloud). This guide +explains how to use the Alicloud Ansible modules together. + +All Alicloud modules require ``footmark`` - install it on your control machine with ``pip install footmark``. + +Cloud modules, including Alicloud modules, are usually executed on your local machine (the control machine) with ``connection: local``, rather than on remote machines defined in your hosts. + +Normally, you'll use the following pattern for plays that provision Alicloud resources: + +.. code-block:: yaml + + - hosts: localhost + connection: local + vars: + - ... + tasks: + - ... + +Authentication +`````````````` + +You can specify your Alicloud authentication credentials (access key and secret key) by passing them as +environment variables or by storing them in a vars file. + +To pass authentication credentials as environment variables: + +.. code-block:: console + + export ALICLOUD_ACCESS_KEY='Alicloud123' + export ALICLOUD_SECRET_KEY='AlicloudSecret123' + +To store authentication credentials in a vars file, encrypt them with :ref:`Ansible Vault ` to keep them secure, then list them: + +.. code-block:: yaml + + --- + alicloud_access_key: "--REMOVED--" + alicloud_secret_key: "--REMOVED--" + +Note that if you store your credentials in a vars file, you need to refer to them in each Alicloud module. For example: + +.. code-block:: yaml+jinja + + - community.general.ali_instance: + alicloud_access_key: "{{ alicloud_access_key }}" + alicloud_secret_key: "{{ alicloud_secret_key }}" + image_id: "..." + +Provisioning +```````````` + +Alicloud modules create Alicloud ECS instances (:ansplugin:`community.general.ali_instance#module`) and retrieve information on these (:ansplugin:`community.general.ali_instance_info#module`). + +You can use the ``count`` parameter to control the number of resources you create or terminate. For example, if you want exactly 5 instances tagged ``NewECS``, set the ``count`` of instances to 5 and the ``count_tag`` to ``NewECS``, as shown in the last task of the example playbook below. If there are no instances with the tag ``NewECS``, the task creates 5 new instances. If there are 2 instances with that tag, the task creates 3 more. If there are 8 instances with that tag, the task terminates 3 of those instances. + +If you do not specify a ``count_tag``, the task creates the number of instances you specify in ``count`` with the ``instance_name`` you provide. + +.. code-block:: yaml+jinja + + # alicloud_setup.yml + + - hosts: localhost + connection: local + + tasks: + - name: Create a set of instances + community.general.ali_instance: + instance_type: ecs.n4.small + image_id: "{{ ami_id }}" + instance_name: "My-new-instance" + instance_tags: + Name: NewECS + Version: 0.0.1 + count: 5 + count_tag: + Name: NewECS + allocate_public_ip: true + max_bandwidth_out: 50 + register: create_instance + +In the example playbook above, data about the instances created by this playbook is saved in the variable defined by the ``register`` keyword in the task. + +Each Alicloud module offers a variety of parameter options. Not all options are demonstrated in the above example. See each individual module for further details and examples. diff --git a/docs/docsite/rst/guide_online.rst b/docs/docsite/rst/guide_online.rst new file mode 100644 index 0000000000..c233b403e8 --- /dev/null +++ b/docs/docsite/rst/guide_online.rst @@ -0,0 +1,49 @@ +.. + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later + +.. _ansible_collections.community.general.docsite.guide_online: + +**************** +Online.net Guide +**************** + +Introduction +============ + +Online is a French hosting company mainly known for providing bare-metal servers named Dedibox. +Check it out: `https://www.online.net/en `_ + +Dynamic inventory for Online resources +-------------------------------------- + +Ansible has a dynamic inventory plugin that can list your resources. + +1. Create a YAML configuration such as ``online_inventory.yml`` with this content: + + .. code-block:: yaml + + plugin: community.general.online + +2. Set your ``ONLINE_TOKEN`` environment variable with your token. + + You need to open an account and log into it before you can get a token. + You can find your token at the following page: `https://console.online.net/en/api/access `_ + +3. You can test that your inventory is working by running: + + .. code-block:: console + + $ ansible-inventory -v -i online_inventory.yml --list + + +4. Now you can run your playbook or any other module with this inventory: + + .. code-block:: ansible-output + + $ ansible all -i online_inventory.yml -m ping + sd-96735 | SUCCESS => { + "changed": false, + "ping": "pong" + } diff --git a/docs/docsite/rst/guide_packet.rst b/docs/docsite/rst/guide_packet.rst new file mode 100644 index 0000000000..9de5e3f614 --- /dev/null +++ b/docs/docsite/rst/guide_packet.rst @@ -0,0 +1,214 @@ +.. + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later + +.. _ansible_collections.community.general.docsite.guide_packet: + +********************************** +Packet.net Guide +********************************** + +Introduction +============ + +`Packet.net `_ is a bare metal infrastructure host that is supported by the community.general collection through six cloud modules. The six modules are: + +- :ansplugin:`community.general.packet_device#module`: manages servers on Packet. You can use this module to create, restart and delete devices. +- :ansplugin:`community.general.packet_ip_subnet#module`: assign IP subnet to a bare metal server +- :ansplugin:`community.general.packet_project#module`: create/delete a project in Packet host +- :ansplugin:`community.general.packet_sshkey#module`: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. +- :ansplugin:`community.general.packet_volume#module`: create/delete a volume in Packet host +- :ansplugin:`community.general.packet_volume_attachment#module`: attach/detach a volume to a device in the Packet host + +Note, this guide assumes you are familiar with Ansible and how it works. If you are not, have a look at their :ref:`docs ` before getting started. + +Requirements +============ + +The Packet modules connect to the Packet API using the `packet-python package `_. You can install it with pip: + +.. code-block:: console + + $ pip install packet-python + +In order to check the state of devices created by Ansible on Packet, it is a good idea to install one of the `Packet CLI clients `_. Otherwise you can check them through the `Packet portal `_. + +To use the modules you will need a Packet API token. You can generate an API token through the Packet portal `here `__. The simplest way to authenticate yourself is to set the Packet API token in an environment variable: + +.. code-block:: console + + $ export PACKET_API_TOKEN=Bfse9F24SFtfs423Gsd3ifGsd43sSdfs + +If you are not comfortable exporting your API token, you can pass it as a parameter to the modules. + +On Packet, devices and reserved IP addresses belong to `projects `_. In order to use the packet_device module, you need to specify the UUID of the project in which you want to create or manage devices. You can find a project's UUID in the Packet portal `here `_ (it is just under the project table) or through one of the available `CLIs `_. + + +If you want to use a new SSH key pair in this tutorial, you can generate it to ``./id_rsa`` and ``./id_rsa.pub`` as: + +.. code-block:: console + + $ ssh-keygen -t rsa -f ./id_rsa + +If you want to use an existing key pair, just copy the private and public key over to the playbook directory. + + +Device Creation +=============== + +The following code block is a simple playbook that creates one `Type 0 `_ server (the ``plan`` parameter). You have to supply ``plan`` and ``operating_system``. ``location`` defaults to ``ewr1`` (Parsippany, NJ). You can find all the possible values for the parameters through a `CLI client `_. + +.. code-block:: yaml+jinja + + # playbook_create.yml + + - name: Create Ubuntu device + hosts: localhost + tasks: + + - community.general.packet_sshkey: + key_file: ./id_rsa.pub + label: tutorial key + + - community.general.packet_device: + project_id: + hostnames: myserver + operating_system: ubuntu_16_04 + plan: baremetal_0 + facility: sjc1 + +After running ``ansible-playbook playbook_create.yml``, you should have a server provisioned on Packet. You can verify through a CLI or in the `Packet portal `__. + +If you get an error with the message "failed to set machine state present, error: Error 404: Not Found", please verify your project UUID. + + +Updating Devices +================ + +The two parameters used to uniquely identify Packet devices are: "device_ids" and "hostnames". Both parameters accept either a single string (later converted to a one-element list), or a list of strings. + +The ``device_ids`` and ``hostnames`` parameters are mutually exclusive. The following values are all acceptable: + +- device_ids: ``a27b7a83-fc93-435b-a128-47a5b04f2dcf`` + +- hostnames: ``mydev1`` + +- device_ids: ``[a27b7a83-fc93-435b-a128-47a5b04f2dcf, 4887130f-0ccd-49a0-99b0-323c1ceb527b]`` + +- hostnames: ``[mydev1, mydev2]`` + +In addition, hostnames can contain a special ``%d`` formatter along with a ``count`` parameter that lets you easily expand hostnames that follow a simple name and number pattern; in other words, ``hostnames: "mydev%d", count: 2`` will expand to [mydev1, mydev2]. + +If your playbook acts on existing Packet devices, you can only pass the ``hostname`` and ``device_ids`` parameters. The following playbook shows how you can reboot a specific Packet device by setting the ``hostname`` parameter: + +.. code-block:: yaml+jinja + + # playbook_reboot.yml + + - name: reboot myserver + hosts: localhost + tasks: + + - community.general.packet_device: + project_id: + hostnames: myserver + state: rebooted + +You can also identify specific Packet devices with the ``device_ids`` parameter. The device's UUID can be found in the `Packet Portal `_ or by using a `CLI `_. The following playbook removes a Packet device using the ``device_ids`` field: + +.. code-block:: yaml+jinja + + # playbook_remove.yml + + - name: remove a device + hosts: localhost + tasks: + + - community.general.packet_device: + project_id: + device_ids: + state: absent + + +More Complex Playbooks +====================== + +In this example, we will create a CoreOS cluster with `user data `_. + + +The CoreOS cluster will use `etcd `_ for discovery of other servers in the cluster. Before provisioning your servers, you will need to generate a discovery token for your cluster: + +.. code-block:: console + + $ curl -w "\n" 'https://discovery.etcd.io/new?size=3' + +The following playbook will create an SSH key, 3 Packet servers, and then wait until SSH is ready (or until 5 minutes passed). Make sure to substitute the discovery token URL in ``user_data``, and the ``project_id`` before running ``ansible-playbook``. Also, feel free to change ``plan`` and ``facility``. + +.. code-block:: yaml+jinja + + # playbook_coreos.yml + + - name: Start 3 CoreOS nodes in Packet and wait until SSH is ready + hosts: localhost + tasks: + + - community.general.packet_sshkey: + key_file: ./id_rsa.pub + label: new + + - community.general.packet_device: + hostnames: [coreos-one, coreos-two, coreos-three] + operating_system: coreos_beta + plan: baremetal_0 + facility: ewr1 + project_id: + wait_for_public_IPv: 4 + user_data: | + #cloud-config + coreos: + etcd2: + discovery: https://discovery.etcd.io/ + advertise-client-urls: http://$private_ipv4:2379,http://$private_ipv4:4001 + initial-advertise-peer-urls: http://$private_ipv4:2380 + listen-client-urls: http://0.0.0.0:2379,http://0.0.0.0:4001 + listen-peer-urls: http://$private_ipv4:2380 + fleet: + public-ip: $private_ipv4 + units: + - name: etcd2.service + command: start + - name: fleet.service + command: start + register: newhosts + + - name: wait for ssh + ansible.builtin.wait_for: + delay: 1 + host: "{{ item.public_ipv4 }}" + port: 22 + state: started + timeout: 500 + loop: "{{ newhosts.results[0].devices }}" + + +As with most Ansible modules, the default states of the Packet modules are idempotent, meaning the resources in your project will remain the same after re-runs of a playbook. Thus, we can keep the ``packet_sshkey`` module call in our playbook. If the public key is already in your Packet account, the call will have no effect. + +The second module call provisions 3 Packet Type 0 (specified using the ``plan`` parameter) servers in the project identified by the ``project_id`` parameter. The servers are all provisioned with CoreOS beta (the ``operating_system`` parameter) and are customized with cloud-config user data passed to the ``user_data`` parameter. + +The ``packet_device`` module has a ``wait_for_public_IPv`` that is used to specify the version of the IP address to wait for (valid values are ``4`` or ``6`` for IPv4 or IPv6). If specified, Ansible will wait until the GET API call for a device contains an Internet-routeable IP address of the specified version. When referring to an IP address of a created device in subsequent module calls, it is wise to use the ``wait_for_public_IPv`` parameter, or ``state: active`` in the packet_device module call. + +Run the playbook: + +.. code-block:: console + + $ ansible-playbook playbook_coreos.yml + +Once the playbook quits, your new devices should be reachable through SSH. Try to connect to one and check if etcd has started properly: + +.. code-block:: console + + tomk@work $ ssh -i id_rsa core@$one_of_the_servers_ip + core@coreos-one ~ $ etcdctl cluster-health + +If you have any questions or comments let us know! help@packet.net diff --git a/docs/docsite/rst/guide_scaleway.rst b/docs/docsite/rst/guide_scaleway.rst new file mode 100644 index 0000000000..f3b7b24e0e --- /dev/null +++ b/docs/docsite/rst/guide_scaleway.rst @@ -0,0 +1,320 @@ +.. + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later + +.. _ansible_collections.community.general.docsite.guide_scaleway: + +************** +Scaleway Guide +************** + +Introduction +============ + +`Scaleway `_ is a cloud provider supported by the community.general collection through a set of plugins and modules. +Those modules are: + +- :ansplugin:`community.general.scaleway_compute#module`: manages servers on Scaleway. You can use this module to create, restart and delete servers. +- :ansplugin:`community.general.scaleway_compute_private_network#module` +- :ansplugin:`community.general.scaleway_container#module` +- :ansplugin:`community.general.scaleway_container_info#module` +- :ansplugin:`community.general.scaleway_container_namespace_info#module` +- :ansplugin:`community.general.scaleway_container_namespace#module` +- :ansplugin:`community.general.scaleway_container_registry_info#module` +- :ansplugin:`community.general.scaleway_container_registry#module` +- :ansplugin:`community.general.scaleway_database_backup#module` +- :ansplugin:`community.general.scaleway_function#module` +- :ansplugin:`community.general.scaleway_function_info#module` +- :ansplugin:`community.general.scaleway_function_namespace_info#module` +- :ansplugin:`community.general.scaleway_function_namespace#module` +- :ansplugin:`community.general.scaleway_image_info#module` +- :ansplugin:`community.general.scaleway_ip#module` +- :ansplugin:`community.general.scaleway_ip_info#module` +- :ansplugin:`community.general.scaleway_lb#module` +- :ansplugin:`community.general.scaleway_organization_info#module` +- :ansplugin:`community.general.scaleway_private_network#module` +- :ansplugin:`community.general.scaleway_security_group#module` +- :ansplugin:`community.general.scaleway_security_group_info#module` +- :ansplugin:`community.general.scaleway_security_group_rule#module` +- :ansplugin:`community.general.scaleway_server_info#module` +- :ansplugin:`community.general.scaleway_snapshot_info#module` +- :ansplugin:`community.general.scaleway_sshkey#module`: adds a public SSH key from a file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. +- :ansplugin:`community.general.scaleway_user_data#module` +- :ansplugin:`community.general.scaleway_volume#module`: manages volumes on Scaleway. +- :ansplugin:`community.general.scaleway_volume_info#module` + +The plugins are: + +- :ansplugin:`community.general.scaleway#inventory`: inventory plugin + + +.. note:: + This guide assumes you are familiar with Ansible and how it works. + If you are not, have a look at :ref:`ansible_documentation` before getting started. + +Requirements +============ + +The Scaleway modules and inventory script connect to the Scaleway API using `Scaleway REST API `_. +To use the modules and inventory script you will need a Scaleway API token. +You can generate an API token through the `Scaleway console's credential page `__. +The simplest way to authenticate yourself is to set the Scaleway API token in an environment variable: + +.. code-block:: console + + $ export SCW_TOKEN=00000000-1111-2222-3333-444444444444 + +If you are not comfortable exporting your API token, you can pass it as a parameter to the modules using the ``api_token`` argument. + +If you want to use a new SSH key pair in this tutorial, you can generate it to ``./id_rsa`` and ``./id_rsa.pub`` as: + +.. code-block:: console + + $ ssh-keygen -t rsa -f ./id_rsa + +If you want to use an existing key pair, just copy the private and public key over to the playbook directory. + +How to add an SSH key? +====================== + +Connection to Scaleway Compute nodes use Secure Shell. +SSH keys are stored at the account level, which means that you can reuse the same SSH key in multiple nodes. +The first step to configure Scaleway compute resources is to have at least one SSH key configured. + +:ansplugin:`community.general.scaleway_sshkey#module` is a module that manages SSH keys on your Scaleway account. +You can add an SSH key to your account by including the following task in a playbook: + +.. code-block:: yaml+jinja + + - name: "Add SSH key" + community.general.scaleway_sshkey: + ssh_pub_key: "ssh-rsa AAAA..." + state: "present" + +The ``ssh_pub_key`` parameter contains your ssh public key as a string. Here is an example inside a playbook: + + +.. code-block:: yaml+jinja + + - name: Test SSH key lifecycle on a Scaleway account + hosts: localhost + gather_facts: false + environment: + SCW_API_KEY: "" + + tasks: + + - community.general.scaleway_sshkey: + ssh_pub_key: "ssh-rsa AAAAB...424242 developer@example.com" + state: present + register: result + + - ansible.builtin.assert: + that: + - result is success and result is changed + +How to create a compute instance? +================================= + +Now that we have an SSH key configured, the next step is to spin up a server! +:ansplugin:`community.general.scaleway_compute#module` is a module that can create, update and delete Scaleway compute instances: + +.. code-block:: yaml+jinja + + - name: Create a server + community.general.scaleway_compute: + name: foobar + state: present + image: 00000000-1111-2222-3333-444444444444 + organization: 00000000-1111-2222-3333-444444444444 + region: ams1 + commercial_type: START1-S + +Here are the parameter details for the example shown above: + +- ``name`` is the name of the instance (the one that will show up in your web console). +- ``image`` is the UUID of the system image you would like to use. + A list of all images is available for each availability zone. +- ``organization`` represents the organization that your account is attached to. +- ``region`` represents the Availability Zone which your instance is in (for this example, ``par1`` and ``ams1``). +- ``commercial_type`` represents the name of the commercial offers. + You can check out the Scaleway pricing page to find which instance is right for you. + +Take a look at this short playbook to see a working example using ``scaleway_compute``: + +.. code-block:: yaml+jinja + + - name: Test compute instance lifecycle on a Scaleway account + hosts: localhost + gather_facts: false + environment: + SCW_API_KEY: "" + + tasks: + + - name: Create a server + register: server_creation_task + community.general.scaleway_compute: + name: foobar + state: present + image: 00000000-1111-2222-3333-444444444444 + organization: 00000000-1111-2222-3333-444444444444 + region: ams1 + commercial_type: START1-S + wait: true + + - ansible.builtin.debug: + var: server_creation_task + + - ansible.builtin.assert: + that: + - server_creation_task is success + - server_creation_task is changed + + - name: Run it + community.general.scaleway_compute: + name: foobar + state: running + image: 00000000-1111-2222-3333-444444444444 + organization: 00000000-1111-2222-3333-444444444444 + region: ams1 + commercial_type: START1-S + wait: true + tags: + - web_server + register: server_run_task + + - ansible.builtin.debug: + var: server_run_task + + - ansible.builtin.assert: + that: + - server_run_task is success + - server_run_task is changed + +Dynamic Inventory Plugin +======================== + +Ansible ships with :ansplugin:`community.general.scaleway#inventory`. +You can now get a complete inventory of your Scaleway resources through this plugin and filter it on +different parameters (``regions`` and ``tags`` are currently supported). + +Let us create an example! +Suppose that we want to get all hosts that got the tag web_server. +Create a file named ``scaleway_inventory.yml`` with the following content: + +.. code-block:: yaml+jinja + + plugin: community.general.scaleway + regions: + - ams1 + - par1 + tags: + - web_server + +This inventory means that we want all hosts that got the tag ``web_server`` on the zones ``ams1`` and ``par1``. +Once you have configured this file, you can get the information using the following command: + +.. code-block:: console + + $ ansible-inventory --list -i scaleway_inventory.yml + +The output will be: + +.. code-block:: json + + { + "_meta": { + "hostvars": { + "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d": { + "ansible_verbosity": 6, + "arch": "x86_64", + "commercial_type": "START1-S", + "hostname": "foobar", + "ipv4": "192.0.2.1", + "organization": "00000000-1111-2222-3333-444444444444", + "state": "running", + "tags": [ + "web_server" + ] + } + } + }, + "all": { + "children": [ + "ams1", + "par1", + "ungrouped", + "web_server" + ] + }, + "ams1": {}, + "par1": { + "hosts": [ + "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d" + ] + }, + "ungrouped": {}, + "web_server": { + "hosts": [ + "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d" + ] + } + } + +As you can see, we get different groups of hosts. +``par1`` and ``ams1`` are groups based on location. +``web_server`` is a group based on a tag. + +In case a filter parameter is not defined, the plugin supposes all values possible are wanted. +This means that for each tag that exists on your Scaleway compute nodes, a group based on each tag will be created. + +Scaleway S3 object storage +========================== + +`Object Storage `_ allows you to store any kind of objects (documents, images, videos, and so on). +As the Scaleway API is S3 compatible, Ansible supports it natively through the amazon.aws modules: :ansplugin:`amazon.aws.s3_bucket#module`, :ansplugin:`amazon.aws.s3_object#module`. + +You can find many examples in the `scaleway_s3 integration tests `_. + +.. code-block:: yaml+jinja + + - hosts: myserver + vars: + scaleway_region: nl-ams + s3_url: https://s3.nl-ams.scw.cloud + environment: + # AWS_ACCESS_KEY matches your scaleway organization id available at https://cloud.scaleway.com/#/account + AWS_ACCESS_KEY: 00000000-1111-2222-3333-444444444444 + # AWS_SECRET_KEY matches a secret token that you can retrieve at https://cloud.scaleway.com/#/credentials + AWS_SECRET_KEY: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee + module_defaults: + group/amazon.aws.aws: + s3_url: '{{ s3_url }}' + region: '{{ scaleway_region }}' + tasks: + # use a fact instead of a variable, otherwise template is evaluate each time variable is used + - ansible.builtin.set_fact: + bucket_name: "{{ 99999999 | random | to_uuid }}" + + # "requester_pays:" is mandatory because Scaleway does not implement related API + # another way is to use amazon.aws.s3_object and "mode: create" ! + - amazon.aws.s3_bucket: + name: '{{ bucket_name }}' + requester_pays: + + - name: Another way to create the bucket + amazon.aws.s3_object: + bucket: '{{ bucket_name }}' + mode: create + encrypt: false + register: bucket_creation_check + + - name: add something in the bucket + amazon.aws.s3_object: + mode: put + bucket: '{{ bucket_name }}' + src: /tmp/test.txt # needs to be created before + object: test.txt + encrypt: false # server side encryption must be disabled diff --git a/tests/sanity/extra/botmeta.py b/tests/sanity/extra/botmeta.py index 3b6c348344..459d3ba14d 100755 --- a/tests/sanity/extra/botmeta.py +++ b/tests/sanity/extra/botmeta.py @@ -18,6 +18,10 @@ from voluptuous.humanize import humanize_error IGNORE_NO_MAINTAINERS = [ + 'docs/docsite/rst/filter_guide.rst', + 'docs/docsite/rst/filter_guide_abstract_informations.rst', + 'docs/docsite/rst/filter_guide_paths.rst', + 'docs/docsite/rst/filter_guide_selecting_json_data.rst', 'plugins/cache/memcached.py', 'plugins/cache/redis.py', 'plugins/callback/cgroup_memory_recap.py', @@ -197,7 +201,7 @@ def main(): # Scan all files unmatched = set(files) - for dirs in ('plugins', 'tests', 'changelogs'): + for dirs in ('docs/docsite/rst', 'plugins', 'tests', 'changelogs'): for dirpath, dirnames, filenames in os.walk(dirs): for file in sorted(filenames): if file.endswith('.pyc'):