diff options
Diffstat (limited to 'ansible_collections/cisco/meraki/README.md')
| -rw-r--r-- | ansible_collections/cisco/meraki/README.md | 275 |
1 files changed, 138 insertions, 137 deletions
diff --git a/ansible_collections/cisco/meraki/README.md b/ansible_collections/cisco/meraki/README.md index 9539f1a1f..56534396d 100644 --- a/ansible_collections/cisco/meraki/README.md +++ b/ansible_collections/cisco/meraki/README.md @@ -1,180 +1,181 @@ -# cisco.meraki Ansible Collection +# Ansible Collection - cisco.meraki -Ansible collection for managing and automating Cisco Meraki network environments. +## Ansible Modules for Meraki -See the CHANGELOG.md file for details of updates in each release. +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. -## Requirements - -* Ansible v2.10 or newer is required for collection support - -## What is Cisco Meraki? +This collection has been tested and supports Cisco Meraki v1.33.0 -Cisco Meraki is an easy-to-use, cloud-based, network infrastructure platform for enterprise environments. While most network hardware uses command-line interfaces (CLIs) for configuration, Meraki uses an easy-to-use Dashboard hosted in the Meraki cloud. No on-premises management hardware or software is required - only the network infrastructure to run your business. +*Note: This collection is not compatible with versions of Ansible before v2.14.* -### MS Switches +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). -Meraki MS switches come in multiple flavors and form factors. Meraki switches support 10/100/1000/10000 ports, as well as Cisco's mGig technology for 2.5/5/10Gbps copper connectivity. 8, 24, and 48 port flavors are available with PoE (802.3af/802.3at/UPoE) available on many models. +## Compatibility matrix -### MX Firewalls +| Cisco Meraki version | Ansible "cisco.meraki" version | Python "DashboardAPI" version | +|--------------------------|------------------------------|-------------------------------| +| 1.33.0 | 2.17.0 |1.33.0 | -Meraki's MX firewalls support full layer 3-7 deep packet inspection. MX firewalls are compatible with a variety of VPN technologies including IPSec, SSL VPN, and Meraki's easy-to-use AutoVPN. +*Notes*: -### MR Wireless Access Points -MR access points are enterprise-class, high-performance access points for the enterprise. MR access points have MIMO technology and integrated beamforming built-in for high performance applications. BLE allows for advanced location applications to be developed with no on-premises analytics platforms. +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. -## Using the Meraki modules +## Installing according to Compatibility Matrix -Meraki modules provide a user-friendly interface to manage your Meraki environment using Ansible. For example, details about SNMP settings for a particular organization can be discovered using the module `meraki_snmp <meraki_snmp_module>`. +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: ``` - - name: Query SNMP settings - meraki_snmp: - api_key: abc123 - org_name: AcmeCorp - state: query - delegate_to: localhost +pip install meraki ``` -Information about a particular object can be queried. For example, the `meraki_admin <meraki_admin_module>` module supports - +To get the Ansible collection v1.0.0 in a fresh development environment: ``` - - name: Gather information about Jane Doe - meraki_admin: - api_key: abc123 - org_name: AcmeCorp - state: query - email: janedoe@email.com - delegate_to: localhost +ansible-galaxy collection install cisco.meraki -f ``` -## Common Parameters - -All Ansible Meraki modules support the following parameters which affect communication with the Meraki Dashboard API. Most of these should only be used by Meraki developers and not the general public. - -* host - * Hostname or IP of Meraki Dashboard. - -* use_https - * Specifies whether communication should be over HTTPS. (Defaults to `yes`) +## 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 -* use_proxy - * Whether to use a proxy for any communication. +## Install +Ansible must be installed ([Install guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) +``` +pip install ansible +``` -* validate_certs - * Determine whether certificates should be validated or trusted. (Defaults to `yes`) +Python Meraki SDK must be installed +``` +pip install meraki +``` -These are the common parameters which are used for most every module. +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. +**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 +``` -* org_name - * Name of organization to perform actions in. +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 +``` -* org_id - * ID of organization to perform actions in. +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: +``` +--- +- hosts: localhost + gather_facts: false + tasks: + - name: Get all administered _identities _me + cisco.meraki.administered_identities_me_info: + meraki_suppress_logging: true + register: result -* net_name - * Name of network to perform actions in. +``` -* net_id - * ID of network to perform actions in. +Execute the playbook: +``` +ansible-playbook -i hosts myplaybook.yml +``` +In the `playbooks` [directory](https://github.com/meraki/dashboard-api-ansible/blob/main/playbooks/) you can find more examples and use cases. -* state - * General specification of what action to take. `query` does lookups. `present` creates or edits. `absent` deletes. +### See Also: -**Note:** Use the `org_id` and `net_id` parameters when possible. `org_name` and `net_name` require additional behind-the-scenes API calls to learn the ID values. `org_id` and `net_id` will perform faster. +* [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. -## Meraki Authentication +## Attention macOS users -All API access with the Meraki Dashboard requires an API key. An API key can be generated from the organization's settings page. Each play in a playbook requires the `api_key` parameter to be specified. +If you're using macOS you may receive this error when running your playbook: -The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See [Using Vaults in playbooks](https://docs.ansible.com/ansible/latest/user_guide/playbooks_vault.html) for more information. +``` +objc[34120]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. +objc[34120]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc_initializeAfterForkError to debug. +ERROR! A worker was found in a dead state +``` -Meraki's API returns a 404 error if the API key is not correct. It does not provide any specific error saying the key is incorrect. If you receive a 404 error, check the API key first. +If that's the case try setting this environment variable: +``` +export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES +``` -## Returned Data Structures +## Contributing to this collection -Meraki and its related Ansible modules return most information in the form of a list. For example, this is returned information by `meraki_admin` querying administrators. It returns a list even though there's only one. +Ongoing development efforts and contributions to this collection are tracked as issues in this repository. -``` - [ - { - "orgAccess": "full", - "name": "John Doe", - "tags": [], - "networks": [], - "email": "john@doe.com", - "id": "12345677890" - } - ] -``` +We welcome community contributions to this collection. If you find problems, need an enhancement or need a new module, please open an issue or create a PR against the [Cisco Meraki Ansible collection repository](https://github.com/meraki/dashboard-api-ansible/issues). -## Handling Returned Data +## Code of Conduct +This collection follows the Ansible project's +[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html). +Please read and familiarize yourself with this document. -Since Meraki's response data uses lists instead of properly keyed dictionaries for responses, certain strategies should be used when querying data for particular information. For many situations, use the `selectattr()` Jinja2 function. +## Releasing, Versioning and Deprecation -## Merging Existing and New Data +This collection follows [Semantic Versioning](https://semver.org/). More details on versioning can be found [in the Ansible docs](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-versions). -Ansible's Meraki modules do not allow for manipulating data. For example, you may need to insert a rule in the middle of a firewall ruleset. Ansible and the Meraki modules lack a way to directly merge to manipulate data. However, a playlist can use a few tasks to split the list where you need to insert a rule and then merge them together again with the new rule added. The steps involved are as follows: +New minor and major releases as well as deprecations will follow new releases and deprecations of the Cisco Meraki product, its REST API and the corresponding Python SDK, which this project relies on. -1. Create blank "front" and "back" lists. -``` - vars: - - front_rules: [] - - back_rules: [] -``` -2. Get existing firewall rules from Meraki and create a new variable. -``` - - name: Get firewall rules - meraki_mx_l3_firewall: - auth_key: abc123 - org_name: YourOrg - net_name: YourNet - state: query - delegate_to: localhost - register: rules - - set_fact: - original_ruleset: '{{rules.data}}' -``` -3. Write the new rule. The new rule needs to be in a list so it can be merged with other lists in an upcoming step. The blank `-` puts the rule in a list so it can be merged. -``` - - set_fact: - new_rule: - - - - comment: Block traffic to server - src_cidr: 192.0.1.0/24 - src_port: any - dst_cidr: 192.0.1.2/32 - dst_port: any - protocol: any - policy: deny -``` -4. Split the rules into two lists. This assumes the existing ruleset is 2 rules long. -``` - - set_fact: - front_rules: '{{front_rules + [ original_ruleset[:1] ]}}' - - set_fact: - back_rules: '{{back_rules + [ original_ruleset[1:] ]}}' -``` -5. Merge rules with the new rule in the middle. -``` - - set_fact: - new_ruleset: '{{front_rules + new_rule + back_rules}}' -``` -6. Upload new ruleset to Meraki. -``` - - name: Set two firewall rules - meraki_mx_l3_firewall: - auth_key: abc123 - org_name: YourOrg - net_name: YourNet - state: present - rules: '{{ new_ruleset }}' - delegate_to: localhost -``` -## Error Handling +## New collection modules -Ansible's Meraki modules will often fail if improper or incompatible parameters are specified. However, there will likely be scenarios where the module accepts the information but the Meraki API rejects the data. If this happens, the error will be returned in the `body` field for HTTP status of 400 return code. +The modules that were there before, usually with a `meraki` prefix, are maintained until version 2.x.x, with the same structure used in previous versions. The old modules will disappear in the next major release and only the new modules will remain. Each old module has its deprecation marking, indicating which is the new equivalent. -Meraki's API returns a 404 error if the API key is not correct. It does not provide any specific error saying the key is incorrect. If you receive a 404 error, check the API key first. 404 errors can also occur if improper object IDs (ex. `org_id`) are specified. +### Example +- Old module: + ```yml + - name: Create webhook + cisco.meraki.meraki_webhook: + auth_key: abc123 + state: present + org_name: YourOrg + net_name: YourNet + name: Test_Hook + url: https://webhook.url/ + shared_secret: shhhdonttellanyone + payload_template_name: 'Slack (included)' + delegate_to: localhost + ``` +- New module: + ```yml + - name: Create webhook + cisco.meraki.networks_webhooks_http_servers: + meraki_api_key: "{{meraki_api_key}}" + state: present + name: Test_Hook + networkId: "{{network_id}}" + payloadTemplate: + name: Slack (included) + payloadTemplateId: wpt_00001 + sharedSecret: shhhdonttellanyone + url: https://webhook.url/ + ``` |