From c2fa30f2034153928792449a068ae65a358fef62 Mon Sep 17 00:00:00 2001 From: blitzeditor <132305943+blitzeditor@users.noreply.github.com> Date: Wed, 19 Jun 2024 08:00:55 -0700 Subject: [PATCH] Doc: Minor grammar edits. (#3362) Co-authored-by: JulioPDX Co-authored-by: Claus Holbech Co-authored-by: Carl Buchmann Co-authored-by: gmuloc --- README.md | 2 +- ansible_collections/arista/avd/README.md | 2 +- .../intro-to-ansible-and-avd.md | 42 +++++++++---------- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 0d81479531e..c6a31a35a1a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ AVD Documentation: - **Flexibility with Open Data Models:** Extensible fabric-wide network models, simplifying configuration, delivering consistency, and reducing errors - **Simplification through Multi-Domain Automation:** A framework that can automate the data center, campus or wide area network, enabled by a consistent EOS software image and management platform -- **Comprehensive Workflows:** Automating the full life cycle of network provisioning from config generation to pre and post-deployment validation, and self-documentation of the network +- **Comprehensive Workflows:** Automating the full life cycle of network provisioning from config generation to pre- and post-deployment validation, and self-documentation of the network ## Reference designs diff --git a/ansible_collections/arista/avd/README.md b/ansible_collections/arista/avd/README.md index fcf97c6f876..73f88010a59 100644 --- a/ansible_collections/arista/avd/README.md +++ b/ansible_collections/arista/avd/README.md @@ -10,7 +10,7 @@ - **Flexibility with Open Data Models:** Extensible fabric-wide network models, simplifying configuration, delivering consistency, and reducing errors - **Simplification through Multi-Domain Automation:** A framework that can automate the data center, campus or wide area network, enabled by a consistent EOS software image and management platform -- **Comprehensive Workflows:** Automating the full life cycle of network provisioning from config generation to pre and post-deployment validation, and self-documentation of the network +- **Comprehensive Workflows:** Automating the full life cycle of network provisioning from config generation to pre- and post-deployment validation, and self-documentation of the network AVD Documentation: diff --git a/ansible_collections/arista/avd/docs/getting-started/intro-to-ansible-and-avd.md b/ansible_collections/arista/avd/docs/getting-started/intro-to-ansible-and-avd.md index 55e76428be2..a483a43b332 100644 --- a/ansible_collections/arista/avd/docs/getting-started/intro-to-ansible-and-avd.md +++ b/ansible_collections/arista/avd/docs/getting-started/intro-to-ansible-and-avd.md @@ -8,15 +8,15 @@ ## Day 1 Operation -Imagine being asked to configure a **layer 3 leaf spine (L3LS)** network from scratch: +Imagine being asked to configure a **Layer 3 leaf spine (L3LS)** network from scratch: ![Figure: Arista Leaf Spine topology](../_media/getting-started/single-dc.svg) -Traditionally, one would configure the switches manually using a laptop, console cable, and USB key to load the correct EOS software image and configuration. Of course, the configuration would be manually generated using snippets from the relevant Arista design guides or copied/pasted from existing devices. Configurations must be manually adapted to every device, which is time-consuming and error-prone. Imagine a new pair of leaf switches or new VRFs/VLANs were added to the network; changes would need to be made to most of the devices. +Traditionally, one would configure the switches manually using a laptop, console cable, and USB key to load the correct EOS software image and configuration. Of course, the configuration would be manually generated, using snippets from the relevant Arista design guides, or copying/pasting from existing devices. Configurations would have to be manually adapted to each and every device, which is time consuming and prone to errors. Consider what would happen if a new pair of leaf switches or new VRFs/VLANs are added to the network - changes would need to be made to most of the devices. -Using Arista Validated Designs (AVD), this task is automated, greatly simplified, and made considerably faster. All the basic network configuration is guaranteed to be identical across the entire fabric from day one. No longer do you have to manually inspect each device for errors or differences. AVD will ensure the consistency and accuracy of your configuration not only for initial deployment but for all subsequent network changes. +Using Arista Validated Designs (AVD), this task is automated, greatly simplified, and made considerably faster. All the basic network configuration is guaranteed to be identical across the entire fabric from day one. No longer do you have to manually inspect each device for errors or differences. AVD will ensure the consistency and accuracy of your configuration not only for initial deployment, but for all subsequent network changes. -AVD is based on best practices from [Arista Design and Deployment Guides](https://www.arista.com/en/solutions/design-guides), meaning you get the full benefit of Arista's experience deploying large-scale leaf spine fabrics. AVD fully integrates with Arista CloudVision, which adds a change control workflow, continuous compliance check, network topology overview, real-time streaming telemetry including flow-based data, and more. +AVD is also based on best practice from [Arista Design and Deployment Guides](https://www.arista.com/en/solutions/design-guides), meaning you get the full benefit of Arista's experience in deploying large scale leaf-spine fabrics. AVD fully integrates with Arista CloudVision, which adds a change control workflow, continuous compliance check, and network topology overview as well as real-time streaming telemetry including flow-based data and more. ## What is Ansible? @@ -27,14 +27,14 @@ is an automation engine that can be used for many purposes including: - Configuration management - Application deployment -It's easily extended through the use of Ansible Collections - essentially prepackaged groups of Ansible components such as playbooks, roles, modules and plugins - that are distributed through [Ansible Galaxy](https://galaxy.ansible.com/home). +It's easily extended through the use of Ansible Collections - essentially prepackaged groups of Ansible components such as playbooks, roles, modules, and plugins - that are distributed through [Ansible Galaxy](https://galaxy.ansible.com/home). Between the core Ansible software and third-party-contributed collections, we can use Ansible to carry out almost any automated task on a network, server, or cloud platform in a consistent, secure, and distributed way. Consistency of tasks carried out is assured through idempotency - that the outcome of an operation is only performed once and only if necessary, no matter how many times that process is carried out. A simple example of idempotency would be a pair of on/off buttons for a machine - no matter how many times you push 'on,' the device will only turn on once. -Unlike other tools, Ansible doesn't use a proprietary communications mechanism or agent on the device being managed. Instead, it leverages industry-standard protocols for device access, including SSH and REST APIs. This also means that Ansible doesn't require the setup of any unique infrastructure - it's entirely possible to automate tasks using nothing but your laptop or desktop computer (but a central deployment server is recommended). +Unlike other tools, Ansible does not use a proprietary communications mechanism or agent on the device being managed. Instead, it leverages industry-standard protocols for device access, including SSH and REST APIs. This also means that Ansible does not require the setup of any unique infrastructure - it is entirely possible to automate tasks using nothing but your laptop or desktop computer (but a central deployment server is recommended). Ansible describes tasks in a structured language called [YAML](https://yaml.org). Unlike other languages such as JSON and XML, YAML was designed to be human-readable. YAML will be covered further later on in the section @@ -60,11 +60,11 @@ that allow the user to generate and deploy best-practice configurations to Arist The illustration above shows the arista.avd collection as a box with a red background on the right-hand side. -When designing an EVPN/VXLAN L3LS fabric, you don't need to spend hours reading through the [Arista Design and Deployment Guides](https://www.arista.com/en/solutions/design-guides). Instead, the AVD collection will implement those rules and guidelines. +When designing an EVPN/VXLAN L3LS fabric, you do not need to spend hours reading through the [Arista Design and Deployment Guides](https://www.arista.com/en/solutions/design-guides). Instead, the AVD collection will implement those rules and guidelines. AVD is an opinionated collection, meaning field experiences and best practices from actual deployments at Arista customers are included. With AVD, users get up and running quickly without inventing every part of the network configuration from scratch. This means the user must provide only the most basic information to get a new fabric up and running. -Parameters which need to be defined by the user include (but aren't limited to): +Parameters which need to be defined by the user include (but are not limited to): - Username/password for network devices and CloudVision - OOB management IP range @@ -84,11 +84,11 @@ It's important to note when and perhaps more importantly, when not to use AVD. AVD is designed to generate and deploy complete configuration files where the network device's running configuration is entirely replaced. As such, caution should be exercised when running AVD against an existing manually configured network. We can take various approaches under such circumstances: -- Compare AVD-generated configurations against the device running configurations; make changes to the AVD input data and iterate until the configurations are functionally equivalent. -- Use AVD to generate partial configurations that we can apply to devices in such a way that won't destroy existing manual configurations. +- Compare AVD-generated configurations against device running configurations; make changes to the AVD input data and iterate until the configurations are functionally equivalent. +- Use AVD to generate partial configurations that we can apply to devices in such a way that will not destroy the existing manual configuration. - Use AVD to generate configurations part-based on automation, part-based on manual configuration included into AVD using AVD's `structured_configuration`, `raw_eos_cli` or `custom_template` facilities. -Automating the provisioning of network infrastructure makes the most sense when the network is built from repeatable building blocks. These allow for code reuse and the abstraction of data. For example, point-to-point links are allocated IP subnets from a much larger pool in most leaf-spine networks. This is a tedious job for a human to design and configure but is an ideal candidate to be automated. However, automation may take longer to achieve in a network that has evolved rather than been designed from the ground up. +Automating the provisioning of network infrastructure makes the most sense when the network is built from repeatable building blocks. These allow for code reuse and the abstraction of data. For example, point-to-point links are allocated IP subnets from a much larger pool in most leaf-spine networks. This is a tedious job for a human to design and configure, but is an ideal candidate to be automated. However, automation may take longer to achieve in a network that has evolved rather than one designed from the ground up. ## Change your mindset and culture @@ -108,7 +108,7 @@ This is defined in the Ansible ***inventory***. Per the official Ansible documen Please note that the example above is taken from the Ansible AVD Examples repository, specifically the `Single-DC-L3LS`. -The exact name of the inventory file isn't important but is provided to Ansible in the `ansible.cfg` file for the project or as `ansible-playbook -i ./inventory.yml` when later running Ansible. +The exact name of the inventory file is not important, but is provided to Ansible in the `ansible.cfg` file for the project or as `ansible-playbook -i ./inventory.yml` when later running Ansible. ### Inventories @@ -134,7 +134,7 @@ all: ansible_host: 172.16.1.12 ``` -However, going forward, we expect that all hostnames specified are resolvable hence the entire inventory file looks as follows: +However, going forward, we expect that all hostnames specified are resolvable, hence the entire inventory file appears as follows: ```yaml --- @@ -169,11 +169,11 @@ all: DC1_L2_LEAVES: ``` -Don't confuse ***hosts*** with servers or similar. A host can be anything that can be accessed via SSH or an API, to be managed by Ansible, including Arista switches. +Do not confuse ***hosts*** with servers or similar. A host can be anything that can be accessed via SSH or an API, to be managed by Ansible, including Arista switches. The settings inside the inventory.yml file are defined in a tree-like structure using ***groups***. Groups can contain hosts or other groups - making it easier to apply a common configuration to a group of devices. -The ***all*** line at the top is a default group that contains all ***hosts***, i.e., all switches. So don't worry too much about that for now. +The ***all*** line at the top is a default group that contains all ***hosts***, i.e., all switches. So do not worry too much about that for now. The ***children:*** keyword is used to define "groups of groups," i.e., just an internal keyword to differentiate between hosts and groups. @@ -189,7 +189,7 @@ More information about Ansible inventories can be found [here](https://docs.ansi ### Organizing host and group variables AVD makes use of variables defined in the inventory to generate the EOS configuration files necessary to configure the devices. While these -variables can be stored in the main inventory file described earlier, it's highly recommended to use separate files for host and group +variables can be stored in the main inventory file described earlier, it is highly recommended to use separate files for host and group variables. Like the inventory.yml file, the host and group variables are also stored in dedicated folders named accordingly in YAML files. ### Group Variables @@ -273,7 +273,7 @@ local_users: no_password: true ``` -The above snippet defines a number of defaults that apply to all children of FABRIC along with configuration specific to each leaf pair and finally each individual leaf switch. +The snippet above defines a number of defaults that apply to all children of FABRIC along with configurations specific to each leaf pair and finally each individual leaf switch. We can override group variables by specifying host variables for specific devices. (see [DEFAULT_HASH_BEHAVIOUR](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-hash-behaviour)). The order of precedence is (from lowest to highest): @@ -359,11 +359,11 @@ While this play shows both the `eos_designs` and `eos_cli_config_gen` roles used ## System of Record -In a legacy network where configuration isn't administered centrally, you have very little control of the relationship between the configuration you *intend* to be applied to the network and the configuration *running* on the network. You might have centralized low-level design documents describing how the network should function in great detail, but you don't have much but the best intentions to ensure that your **entire** network is working as you intended. As a result, it takes only a single configuration mistake on a single device to create havoc. +In a legacy network where configuration is not administered centrally, you have very little control of the relationship between the configuration you *intend* to be applied to the network and the configuration *running* on the network. You might have centralized low-level design documents describing how the network should function in great detail, but you do not have much but the best intentions to ensure that your **entire** network is working as you intended. As a result, it takes only a single configuration mistake on a single device to create havoc. -Since operating many networking devices also typically results in having many networking engineers, there is even more room for error. Different people do things differently, and repetitive tasks aren't always executed in the same manner. +Since operating many networking devices also typically results in having many networking engineers, there is even more room for error. Different people do things differently, and repetitive tasks are not always executed in the same manner. -With AVD, you define not only the topology of your network centrally but also which services are used where in a central repository of text files. Furthermore, because this data is stored in text files, it's possible to apply version control (for example, using tools like git, subversion, or mercurial) to this System of Record, giving you visibility of when the intended configuration was changed and by whom. +With AVD, you define not only the topology of your network centrally, but also which services are used where in a central repository of text files. Furthermore, because this data is stored in text files, it is possible to apply version control (for example, using tools like git, subversion, or mercurial) to this system of record, giving you visibility of when the intended configuration was changed and by whom. This System of Record means you have a complete overview of your designed network configuration without looking at individual network devices. An additional benefit of AVD is that by design, you always have a network configuration backup. Including automated documentation in markdown format, you no longer have to remember to update documentation about which interface is connected to which device, etc., whenever you change something on a device. Instead, it's all done automatically based on the configuration built and applied to the network devices by Ansible every time you execute the playbooks. @@ -477,7 +477,7 @@ These tasks, while relatively simple, can be time-consuming simply because they - Adding/removing new leaf switches. - Adding/removing new VLANs. - Creating/modifying/deleting port profiles. -- Configuring/modifying ports towards end systems. +- Configuring/modifying ports toward end systems. Making these changes could involve many hours of planning to generate configuration snippets to apply during a change window.