diff options
Diffstat (limited to 'ansible_collections/cisco/meraki/README.md')
| -rw-r--r-- | ansible_collections/cisco/meraki/README.md | 132 |
1 files changed, 51 insertions, 81 deletions
diff --git a/ansible_collections/cisco/meraki/README.md b/ansible_collections/cisco/meraki/README.md index 56534396d..f7dc05f6a 100644 --- a/ansible_collections/cisco/meraki/README.md +++ b/ansible_collections/cisco/meraki/README.md @@ -1,117 +1,81 @@ -# Ansible Collection - cisco.meraki +# Ansible Modules for Meraki -## Ansible Modules for Meraki +The Meraki-Ansible project provides an Ansible collection for managing and automating your Cisco Meraki environment. It consists of a set of modules and roles for performing tasks related to Meraki. -The meraki-ansible project provides an Ansible collection for managing and automating your Cisco Meraki environment. It consists of a set of modules and roles for performing tasks related to Meraki. +# Quick Start Guide -This collection has been tested and supports Cisco Meraki v1.33.0 - -*Note: This collection is not compatible with versions of Ansible before v2.14.* - -Other versions of this collection have support for previous Cisco Meraki versions. The recommended versions are listed below on the [Compatibility matrix](https://github.com/meraki/dashboard-api-ansible#compatibility-matrix). - -## Compatibility matrix - -| Cisco Meraki version | Ansible "cisco.meraki" version | Python "DashboardAPI" version | -|--------------------------|------------------------------|-------------------------------| -| 1.33.0 | 2.17.0 |1.33.0 | - -*Notes*: - - -1. The "Python 'meraki' SDK version" column has the minimum recommended version used when testing the Ansible collection. This means you could use later versions of the Python "meraki" than those listed. -2. The "Cisco Meraki version" column has the value of the `meraki_version` you should use for the Ansible collection. - -## Installing according to Compatibility Matrix - -For example, for Cisco Meraki 1.33.0, it is recommended to use Ansible "cisco.meraki" v1.0.0 and Python "meraki DashboardAPI" v1.33.0. - -To get the Python Meraki SDK v1.33.0 in a fresh development environment: -``` -pip install meraki -``` - -To get the Ansible collection v1.0.0 in a fresh development environment: -``` -ansible-galaxy collection install cisco.meraki -f -``` - -## Requirements -- Ansible >= 2.9 -- [Python Meraki SDK](https://github.com/meraki/dashboard-api-python) v1.33.0 or newer -- Python >= 3.6, as the Meraki SDK doesn't support Python version 2.x - -## Install -Ansible must be installed ([Install guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) +## Installation +1. Ansible must be installed ([Install guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) ``` pip install ansible ``` -Python Meraki SDK must be installed +2. Python Meraki SDK must be installed ``` pip install meraki ``` -Install the collection ([Galaxy link](https://galaxy.ansible.com/cisco/meraki)) +3. Install the collection ([Galaxy link](https://galaxy.ansible.com/cisco/meraki)) ``` ansible-galaxy collection install cisco.meraki -f ``` -## Use -First, your Meraki API key needs to be available for the playbook to use. You can leverage environment variables `export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73`, or create a `credentials.yml` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/credentials.yml) file. +## Initial Configuration + +1. First, your Meraki API key needs to be available for the playbook to use. You can leverage environment variables `export MERAKI_DASHBOARD_API_KEY=6bec40cf957de430a6f1f2baa056b99a4fac9ea0`, or create a `credentials.yml` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/credentials.yml) file. **Note:** Storing your API key in an unencrypted text file is not recommended for security reasons. -``` ---- -meraki_api_key: "ABC" -meraki_base_url: "https://api.meraki.com/api/v1" -meraki_single_request_timeout: "" -meraki_certificate_path: "" -meraki_requests_proxy: True -meraki_wait_on_rate_limit: 60 -meraki_nginx_429_retry_wait_time: 60 -meraki_action_batch_retry_wait_time: 60 -meraki_retry_4xx_error: False -meraki_retry_4xx_error_wait_time: 60 -meraki_maximum_retries: 2 -meraki_output_log: True -meraki_log_file_prefix: "meraki_api_" -meraki_log_path: "" -meraki_print_console: True -meraki_suppress_logging: False -meraki_simulate: False -meraki_be_geo_id: "" -meraki_caller: "" -meraki_use_iterator_for_get_pages: False -meraki_inherit_logging_config: False -``` - -Create a `hosts` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/hosts)) file that uses `[meraki_servers]` with your Cisco Meraki Settings: +2. Create a `hosts` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/hosts)) file that uses `[meraki_servers]` with your Cisco Meraki Settings: ``` [meraki_servers] meraki_server ``` - -Then, create a playbook `myplaybook.yml` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/who_am_i.yml)) referencing the variables in your credentials.yml file and specifying the full namespace path to the module, plugin and/or role: +3. Running your first "Hello, world" in Ansible +Create a playbook `who_am_i.yml` ([example](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/who_am_i.yml)): ``` --- -- hosts: localhost +- hosts: meraki_servers gather_facts: false tasks: - - name: Get all administered _identities _me + - name: Get my administered identities cisco.meraki.administered_identities_me_info: - meraki_suppress_logging: true register: result + - name: Show result + ansible.builtin.debug: + msg: "{{ result }}" ``` +This is a simple playbook that will (1) get the information about the Meraki admin user the API key belongs to and (2) print the information on the screen. Execute the playbook: ``` -ansible-playbook -i hosts myplaybook.yml +ansible-playbook -i hosts who_am_i.yml ``` -In the `playbooks` [directory](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/) you can find more examples and use cases. +4. Congratulations! You have just run your first Ansible playbook! -### See Also: +- - - +# Detailed Information -* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. +This collection has been tested and supports Cisco Meraki Dashboard API v1.33.0 + +*Note: This collection is not compatible with versions of Ansible before v2.14.* + +Other versions of this collection have support for previous Cisco Meraki versions. The recommended versions are listed below on the [Compatibility matrix](https://github.com/meraki/dashboard-api-ansible#compatibility-matrix). + +## Compatibility matrix + +| Cisco Meraki version | Ansible "cisco.meraki" version | Python "DashboardAPI" version | +|--------------------------|------------------------------|-------------------------------| +| 1.33.0 | 2.17.0 |1.33.0 | +| 1.44.1 | 2.18.0 |1.44.1 | + +*Notes*: + +1. The "Python `meraki` SDK version" column has the minimum recommended version used when testing the Ansible collection. This means you could use later versions of the Python "meraki" than those listed. +2. The "Cisco Meraki version" column has the value of the `meraki_version` you should use for the Ansible collection. + +## Requirements +- Ansible >= 2.9 +- [Python Meraki SDK](https://github.com/meraki/dashboard-api-python) v1.33.0 or newer +- Python >= 3.6, as the Meraki SDK doesn't support Python version 2.x ## Attention macOS users @@ -128,6 +92,12 @@ If that's the case try setting this environment variable: export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ``` +## Additional Resources +1. [Meraki's Ansible Collection Documentation](https://docs.ansible.com/ansible/latest/collections/cisco/meraki/index.html) +2. [Meraki Dashboard API Documentation](https://meraki.io/api) +3. [DevNet Learning Lab](https://developer.cisco.com/learning/labs/meraki-dashboard-ansible/introduction/) +4. [DevNet Sandbox](https://devnetsandbox.cisco.com/RM/Diagram/Index/a9487767-deef-4855-b3e3-880e7f39eadc?diagramType=Topology) + ## Contributing to this collection Ongoing development efforts and contributions to this collection are tracked as issues in this repository. |