-
Notifications
You must be signed in to change notification settings - Fork 23.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Meraki scenario guide #41827
Merged
Merged
Meraki scenario guide #41827
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
e094041
Initial commit for the Meraki scenario guide
kbreit a2c9e0b
Added Meraki guide to indexes, fixed an error
kbreit c2a4414
Added common parameters to scenario guide
kbreit 1ba3e2e
Add additional information for first draft
kbreit c3d10c0
Fix .rst formatting error
kbreit d84ac93
Added section about handling returned data. More to come.
kbreit 7ef4115
Small formatting changes
kbreit File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,128 @@ | ||
.. _meraki_guide: | ||
|
||
Cisco Meraki Guide | ||
================== | ||
|
||
|
||
.. _meraki_guide_intro: | ||
|
||
What is Cisco Meraki? | ||
--------------------- | ||
|
||
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. | ||
|
||
MS Switches | ||
........... | ||
|
||
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. | ||
|
||
MX Firewalls | ||
............ | ||
|
||
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. | ||
|
||
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. | ||
|
||
Using the Meraki modules | ||
------------------------ | ||
|
||
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>`. | ||
|
||
.. code-block:: yaml | ||
|
||
- name: Query SNMP settings | ||
meraki_snmp: | ||
api_key: abc123 | ||
org_name: AcmeCorp | ||
state: query | ||
delegate_to: localhost | ||
|
||
Information about a particular object can be queried. For example, the `meraki_admin <meraki_admin_module>` module supports | ||
|
||
.. code-block:: yaml | ||
|
||
- name: Gather information about Jane Doe | ||
meraki_admin: | ||
api_key: abc123 | ||
org_name: AcmeCorp | ||
state: query | ||
email: janedoe@email.com | ||
delegate_to: localhost | ||
|
||
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``) | ||
|
||
use_proxy | ||
Whether to use a proxy for any communication. | ||
|
||
validate_certs | ||
Determine whether certificates should be validated or trusted. (Defaults to ``yes``) | ||
|
||
These are the common parameters which are used for most every module. | ||
|
||
org_name | ||
Name of organization to perform actions in. | ||
|
||
org_id | ||
ID of organization to perform actions in. | ||
|
||
net_name | ||
Name of network to perform actions in. | ||
|
||
net_id | ||
ID of network to perform actions in. | ||
|
||
state | ||
General specification of what action to take. ``query`` does lookups. ``present`` creates or edits. ``absent`` deletes. | ||
|
||
.. hint:: 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. | ||
|
||
Meraki Authentication | ||
..................... | ||
|
||
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. | ||
|
||
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 :ref:`playbooks_vault` for more information. | ||
|
||
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. | ||
|
||
Returned Data Structures | ||
........................ | ||
|
||
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. | ||
|
||
.. code-block:: yaml | ||
|
||
[ | ||
{ | ||
'orgAccess': 'full', | ||
'name': 'John Doe', | ||
'tags': [], | ||
'networks': [], | ||
'email': 'john@doe.com', | ||
'id': '12345677890' | ||
} | ||
] | ||
|
||
Handling Returned Data | ||
...................... | ||
|
||
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. | ||
|
||
Error Handling | ||
.............. | ||
|
||
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. | ||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would make this 'json' instead.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm trying to do this in the backport and really struggling. Is json not a valid option or do I need to include quotes?