Roles documentation

README.md

@@ -27,7 +27,7 @@ This repository includes:
 - `aws_controllers`
 - `aws_edges`
 - `aws_teardown`
-- `common`
+- cisco.sdwan_deployment.common`
 - `azure_controllers`
 - `azure_edges`
 - `azure_teardown`

roles/aws_controllers/README.md

@@ -0,0 +1,75 @@
+# Ansible Role: aws_controllers
+
+The `aws_controllers` Ansible role is designed to deploy a Cisco SD-WAN controller topology on AWS cloud infrastructure. It follows the topology outlined in the official Cisco documentation and currently supports the deployment of vManage, vBond, and vSmart instances.
+
+NOTE: Role must be used on localhost - API requests to AWS via boto are done from local machine.
+
+## Role description
+
+The `aws_controllers` role automates the deployment of Cisco SD-WAN controllers (vManage, vBond, and vSmart) in AWS. Key functionalities include:
+
+- Validating AWS dependencies and user sessions.
+- Discovering or using provided network infrastructure settings.
+- Ensuring all required deployment variables are set.
+- Creating EC2 instances for each controller type and managing deployment order.
+- Storing deployment data and verifying instance reachability post-setup.
+
+## Requirements
+
+- `cisco.sdwan_deployment` collection installed
+- Ansible 2.16 or higher.
+- Ansible AWS modules (`amazon.aws` collection) installed.
+- Boto3 and Botocore Python libraries installed on the controlling machine to interact with AWS APIs.
+- AWS CLI configured with the appropriate permissions to create and manage AWS resources.
+- AWS EC2 AMIs for vManage, vBond, and vSmart instances must be available in your AWS account.
+
+## Dependencies
+
+- A role named `cisco.sdwan_deployment.common` that provides tasks for checking AWS boto3 requirements, probing user sessions, and asserting required variables.
+- A role named `aws_network_infrastructure` that gathers information about the network resources if not already provided by the user.
+
+## Role Variables
+
+### Defaults (`defaults/main.yml`)
+
+- `organization_name`: Name of the organization deploying the controllers. Must be defined by the user.
+- `aws_region`: AWS region where resources will be deployed (default: `us-east-1`).
+- `aws_vpc_name`, `aws_security_group_name`: Default naming convention for VPC and security group.
+- `aws_tag_creator`: Tag used to mark resources created in AWS.
+- `aws_key_name`: AWS SSH key pair name.
+- `admin_username`, `admin_password`: Default credentials for controllers.
+- `vbond_port`, `default_vbond_ip`: Default port and IP for vBond.
+- `aws_vmanage_ami_id`, `aws_vmanage_instance_type`: AMI ID and instance type for vManage.
+- `aws_vbond_ami_id`, `aws_vbond_instance_type`: AMI ID and instance type for vBond.
+- `aws_vsmart_ami_id`, `aws_vsmart_instance_type`: AMI ID and instance type for vSmart.
+- `site_id_vmanage`, `site_id_vbond`, `site_id_vsmart`: Default site IDs for each controller.
+
+### Vars (`vars/main.yml`)
+
+- `results_dir`: Directory to store deployment results.
+- `aws_deployed_controllers_data`: File to store data of deployed controllers.
+- `userdata_vmanage_path`, `userdata_vbond_path`, `userdata_vsmart_path`: Paths to user data configurations for each controller type.
+
+### Required Variables
+
+The following variables must be set prior to executing the role:
+
+- `organization_name`: The name of your organization, used as a prefix for Azure resources.
+- `az_location`: The Azure region where resources will be deployed.
+- `az_resource_group`: The name of the Azure resource group for the deployment.
+- `az_network_security_group`: The name of the Azure Network Security Group.
+- `az_subnets`: A list of subnet definitions for the Azure Virtual Network.
+- `admin_username`: Administrator username for the SD-WAN controller instances.
+- `admin_password`: Administrator password for the SD-WAN controller instances.
+
+## Example Playbook
+
+See [Example playbooks](https://github.com/cisco-open/ansible-collection-sdwan-deployment/tree/main/playbooks).
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/aws_controllers/meta/main.yml

@@ -1 +1,17 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
 ---
+
+galaxy_info:
+  author: Arkadiusz Cichon <[email protected]>
+  description: Deploy Cisco SD-WAN Controllers on AWS
+  license: GPL-3.0-or-later
+  min_ansible_version: "2.16.6"
+
+  galaxy_tags:
+    - cisco
+    - sdwan
+    - catalystwan
+    - networking
+
+dependencies: []

roles/aws_edges/README.md

@@ -0,0 +1,77 @@
+# AWS Edges Ansible Role Documentation
+
+## Overview
+
+The `aws_edges` role, part of the `cisco.sdwan_deployment` collection, facilitates the deployment of Cisco SD-WAN edge devices (cEdges) within an AWS environment.
+
+NOTE: Role must be used on localhost - API requests to AWS via boto are done from local machine.
+
+## Role description
+
+The `aws_edges` role is an essential component of the `cisco.sdwan_deployment` collection and focuses on the automated deployment of Cisco SD-WAN edge devices (cEdges) in the AWS cloud. Key functionalities include:
+
+- Validating dependencies on boto3 and botocore for AWS interactions.
+- Confirming the presence of an active AWS user session.
+- Discovering or incorporating provided network configurations such as VPC, security groups, and subnets.
+- Asserting the availability of all necessary variables for the deployment of edge devices.
+- Deploying EC2 instances for cEdge devices and configuring them according to specified parameters.
+- Organizing deployment results and confirming the operational status of the instances through SSH reachability checks.
+
+## Requirements
+
+- `cisco.sdwan_deployment` collection installed
+- Ansible 2.16 or higher.
+- Ansible AWS modules (`amazon.aws` collection) installed.
+- Boto3 and Botocore Python libraries installed on the controlling machine to interact with AWS APIs.
+- AWS CLI configured with the appropriate permissions to create and manage AWS resources.
+- AWS EC2 AMIs for vManage, vBond, and vSmart instances must be available in your AWS account.
+
+## Dependencies
+
+- A role named cisco.sdwan_deployment.common`  that provides tasks for AWS boto3 requirements, user session checks, variable verifications, instance checks, and deployment fact gathering.
+- Prepared network infrastructure used to deploy instances to (VPC, subnets etc.)
+
+## Role Variables
+
+### Defaults (`defaults/main.yml`)
+
+- `organization_name`: Name of the organization. Must be defined by the user.
+- `aws_region`: AWS region where resources will be deployed (default: `us-east-1`).
+- `aws_vpc_name`, `aws_security_group_name`: Defaults for naming VPC and security group resources.
+- `aws_tag_creator`: Tag for identifying the creator of AWS resources.
+- `aws_key_name`: AWS SSH key pair name for EC2 instances.
+- `admin_username`, `admin_password`: Default admin credentials for edge devices.
+- `vbond_port`, `default_vbond_ip`: Default vBond communication settings.
+- `aws_cedge_ami_id`, `aws_cedge_instance_type`: AMI ID and instance type for cEdge devices.
+- `edge_instances`: List of edge device instances to be deployed.
+
+### Vars (`vars/main.yml`)
+
+- `results_dir`: Directory where deployment results will be stored.
+- `aws_deployed_edges_data`: File to store data of deployed edge devices.
+- `userdata_cedge_path`: Path to the user data configuration for cEdge devices.
+
+### Required variables
+
+The following variables must be set prior to executing the role:
+
+- `organization_name`: Identifier for your organization, used for naming AWS resources.
+- `aws_region`: AWS region to host the resources.
+- `aws_availibility_zone`: Specific AWS availability zone within the selected region.
+- `admin_password`: Password for administrative access to controller instances.
+- `aws_vpc_config`: Configuration details for the AWS VPC.
+- `aws_security_group_config`: Settings for the AWS security group.
+- `aws_subnets_config`: Specifications for the AWS subnets.
+- `aws_cedge_ami_id`: AMI ID for the Cisco Edge compute instances.
+
+## Example Playbook
+
+See [Example playbooks](https://github.com/cisco-open/ansible-collection-sdwan-deployment/tree/main/playbooks).
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/aws_edges/meta/main.yml

@@ -1 +1,17 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
 ---
+
+galaxy_info:
+  author: Arkadiusz Cichon <[email protected]>
+  description: Deploy Cisco SD-WAN cEdges (C8000V) on AWS
+  license: GPL-3.0-or-later
+  min_ansible_version: "2.16.6"
+
+  galaxy_tags:
+    - cisco
+    - sdwan
+    - catalystwan
+    - networking
+
+dependencies: []

roles/aws_network_infrastructure/README.md

@@ -0,0 +1,70 @@
+# AWS Network Infrastructure Ansible Role Documentation
+
+## Overview
+
+The role provided here is designed to establish foundational network infrastructure within an AWS environment as a prerequisite for deploying other resources.
+
+NOTE: This role should be executed on localhost as it performs API requests to AWS via boto from the local machine.
+
+## Role Description
+
+This role focuses on creating and configuring the necessary network components in AWS, such as VPCs, subnets, security groups, and internet gateways. The key functionalities include:
+
+- Validating boto3 and botocore dependencies, ensuring that AWS SDKs are available for Python.
+- Confirming the user's AWS session is active for making API requests.
+- Asserting that all required variables are provided to configure the network infrastructure.
+- Preparing a results directory to store infrastructure deployment information.
+- Creating and managing AWS network infrastructure elements using the provided configurations.
+
+## Requirements
+
+- `cisco.sdwan_deployment` collection installed.
+- Ansible 2.16 or higher.
+- Ansible AWS modules (`amazon.aws` collection) installed.
+- Boto3 and Botocore Python libraries installed on the controlling machine to interact with AWS APIs.
+- AWS CLI configured with the appropriate permissions to create and manage AWS resources.
+
+## Dependencies
+
+- A role named cisco.sdwan_deployment.common`  that includes tasks for checking AWS boto3 requirements, probing the user's AWS session, and verifying required variables.
+
+## Role Variables
+
+### Defaults (`defaults/main.yml`)
+
+- `aws_allowed_subnets`: VPN subnets allowed to connect to AWS Elastic IPs.
+- `organization_name`: Name of the organization. Must be defined by the user.
+- `aws_region`: AWS region where resources will be deployed (default: `us-east-1`).
+- `aws_availibility_zone`: AWS availability zone for resource deployment (default: `us-east-1a`).
+- `aws_vpc_name`, `aws_vpc_cidr`: Defaults for naming and CIDR of the VPC.
+- `aws_igw_name`: Name for the AWS Internet Gateway.
+- `aws_subnets`: List of subnet configurations for the VPC.
+- `aws_route_table_name`: Name for the VPC's route table.
+- `aws_security_group_name`: Name for the security group.
+- `aws_vpn_name`, `aws_eip_name`, `aws_nacl_name`: Names for VPN, Elastic IP, and network ACL.
+
+### Vars (`vars/main.yml`)
+
+- `results_dir`: Directory where deployment results will be stored.
+- `aws_deployed_network_data`: File to store data of deployed network components.
+
+### Required Variables
+
+Before running the role, define the following variables:
+
+- `organization_name`: The name of your organization, influencing AWS resource naming.
+- `aws_region`: The AWS region for deploying resources.
+- `aws_availibility_zone`: The desired AWS availability zone within the region.
+- `aws_allowed_subnets`: List of subnets allowed to interact with the AWS resources.
+
+## Example Playbook
+
+See [Example playbooks](https://github.com/cisco-open/ansible-collection-sdwan-deployment/tree/main/playbooks).
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/aws_network_infrastructure/meta/main.yml

@@ -1,4 +1,17 @@
 # Copyright 2024 Cisco Systems, Inc. and its affiliates
-# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ---
+
+galaxy_info:
+  author: Arkadiusz Cichon <[email protected]>
+  description: Deploy Network resource (VPCs, IGws, subnets etc.) required for Cisco SD-WAN Infrastructure
+  license: GPL-3.0-or-later
+  min_ansible_version: "2.16.6"
+
+  galaxy_tags:
+    - cisco
+    - sdwan
+    - catalystwan
+    - networking
+
+dependencies: []

roles/aws_teardown/README.md

@@ -0,0 +1,55 @@
+# AWS Teardown Ansible Role Documentation
+
+## Overview
+
+The `aws_teardown` role is designed to safely decommission and remove AWS resources that were previously deployed, ensuring that all associated components are properly cleaned up.
+
+NOTE: This role should be executed on localhost as it performs API requests to AWS via boto from the local machine.
+
+## Role Description
+
+This role provides a systematic approach to tearing down AWS resources, with a strong emphasis on safety and confirmation. Key functionalities include:
+
+- Prompting the user for confirmation before proceeding with the teardown to avoid accidental deletions.
+- Verifying that the user's AWS session is active to ensure API call capability.
+- Retrieving details of the VPC created by the user and confirming its existence.
+- Gathering information about all subnets associated with the VPC.
+- Conditionally terminating specific EC2 instances or removing all resources within the VPC, including subnets, route tables, internet gateways, and the VPC itself.
+
+## Requirements
+
+- `cisco.sdwan_deployment` collection installed.
+- Ansible 2.16 or higher.
+- Ansible AWS modules (`amazon.aws` collection) installed.
+- Boto3 and Botocore Python libraries installed on the controlling machine to interact with AWS APIs.
+- AWS CLI configured with the appropriate permissions to delete AWS resources.
+
+## Dependencies
+
+- A role named cisco.sdwan_deployment.common`  that includes tasks for probing the user's AWS session.
+
+## Role Variables
+
+### Defaults (`defaults/main.yml`)
+
+- `organization_name`: Name of the organization. Must be defined by the user.
+- `teardown_resources_data_path`: Path where the teardown data JSON file will be stored.
+- `teardown_only_instances`: Boolean value to indicate if only EC2 instances should be torn down.
+- `teardown_specific_instances`: Boolean value to indicate if specific EC2 instances should be torn down.
+- `aws_region`: AWS region where resources were deployed (default: `us-east-1`).
+- `aws_availibility_zone`: AWS availability zone used for resource deployment (default: `us-east-1a`).
+- `aws_vpc_name`, `aws_security_group_name`: Names for the VPC and security group to be removed.
+
+## Example Playbook
+
+See [Example playbooks](https://github.com/cisco-open/ansible-collection-sdwan-deployment/tree/main/playbooks).
+
+These playbook reuse configuration files that might be used as example for your configuration
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/aws_teardown/meta/main.yml

@@ -0,0 +1,17 @@
+# Copyright 2024 Cisco Systems, Inc. and its affiliates
+
+---
+
+galaxy_info:
+  author: Arkadiusz Cichon <[email protected]>
+  description: Teardown Cisco SD-WAN devices and required network resources from AWS
+  license: GPL-3.0-or-later
+  min_ansible_version: "2.16.6"
+
+  galaxy_tags:
+    - cisco
+    - sdwan
+    - catalystwan
+    - networking
+
+dependencies: []