### Initialize Sphinx Project and Build Docsite

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/QUICK_START.md

One-time setup for initializing the Sphinx project, installing the collection, and building the docsite. This includes activating the virtual environment, navigating to the project, installing the collection, initializing Sphinx, installing dependencies, building the site, and previewing it locally.

```bash
# 1. Activate virtual environment
source ~/venv_pb/bin/activate

# 2. Navigate to project root and install collection
cd /Users/shaik/graphiant-playbooks
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force

# 3. Navigate to collection directory
cd ansible_collections/graphiant/naas

# 4. Initialize Sphinx project (one-time setup)
antsibull-docs sphinx-init --use-current --dest-dir docs --squash-hierarchy graphiant.naas

# 5. Install dependencies
cd docs
pip install -r requirements-ee.txt

# 6. Build the docsite
./build.sh

# 7. Preview locally
cd _build/html
python3 -m http.server 8000
# Open http://localhost:8000 in your browser
```

--------------------------------

### Run Complete Network Setup Playbook

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Command to execute the complete network setup playbook.

```bash
ansible-playbook playbooks/complete_network_setup.yml
```

--------------------------------

### Install Azure CLI on Linux

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Azure CLI on Linux by downloading and executing the installation script.

```bash
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
```

--------------------------------

### Install Required Packages

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/QUICK_START.md

Installs the necessary Python packages for building the documentation site. Ensure your virtual environment is activated.

```bash
# Activate virtual environment
source ~/venv_pb/bin/activate

# Install required packages
pip install ansible-core antsibull-docs sphinx sphinx-rtd-theme
```

--------------------------------

### Set Up Development Environment

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Create a Python virtual environment and install development dependencies using pip.

```bash
python3.12 -m venv venv
source venv/bin/activate
pip install -r ansible_collections/graphiant/naas/requirements-ee.txt
```

--------------------------------

### Install Development Tools for Linting

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Activate the virtual environment and install necessary Python packages for linting and formatting checks.

```bash
source venv/bin/activate
pip install black flake8 pylint djlint ansible-lint pre-commit
```

```bash
# Pylint needs ansible-core to resolve ansible.module_utils.* (same as python-lint in lint.yml)
pip install "ansible-core>=2.17"
```

--------------------------------

### Install Azure CLI on Windows

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Azure CLI on Windows using Chocolatey.

```bash
choco install azure-cli
```

--------------------------------

### Install Terraform on Windows

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Terraform CLI on Windows using Chocolatey. Ensure Chocolatey is installed first.

```powershell
choco install terraform
```

--------------------------------

### Install AWS CLI on Linux

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the AWS Command Line Interface on Linux by downloading and executing the installer script.

```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install
```

--------------------------------

### Subsequent Docsite Builds

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/QUICK_START.md

Run this command after the initial setup to rebuild the documentation site. Ensure you are in the correct directory.

```bash
cd ansible_collections/graphiant/naas/docs
./build.sh
```

--------------------------------

### Install AWS CLI on Windows

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the AWS Command Line Interface on Windows using Chocolatey.

```bash
choco install awscli
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Install pre-commit hooks for automated checks before committing. Run the hooks manually across all files to ensure compliance.

```bash
# Install pre-commit hooks (one-time setup)
pre-commit install
```

```bash
# Run hooks manually
pre-commit run --all-files
```

--------------------------------

### Install Google Cloud SDK on Windows

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Google Cloud SDK using Chocolatey on Windows. This is optional for GCP authentication.

```powershell
choco install gcloudsdk
```

--------------------------------

### Verify Google Cloud SDK Installation

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Checks the installed version of the Google Cloud SDK. This command is only relevant if the SDK has been installed.

```bash
gcloud --version
```

--------------------------------

### Install Terraform on macOS

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Terraform CLI on macOS using Homebrew. Ensure Homebrew is installed first.

```bash
brew install terraform
```

--------------------------------

### Clone and Install Collection from Source

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Clone the Graphiant Playbooks repository and install the collection from source. Ensure you are using a Python virtual environment.

```bash
git clone https://github.com/Graphiant-Inc/graphiant-playbooks.git
cd graphiant-playbooks

# Create virtual environment or activate an existing virtual environment
python3.12 -m venv venv
source venv/bin/activate

# Install collection dependencies
pip install -r ansible_collections/graphiant/naas/requirements-ee.txt

# Install collection from source
pip install ansible-core
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force
```

--------------------------------

### Preview Docusite Locally

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Starts a simple HTTP server in the build directory to preview the generated documentation site locally. Access the site by navigating to http://localhost:8000 in your web browser.

```bash
cd _build/html
python3 -m http.server 8000
```

--------------------------------

### GCP Project Configuration Example

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Use this configuration when your VPC and subnet already exist. Ensure resource names match exactly in GCP.

```hcl
# GCP Project Configuration
project_id = "your-project-id"
region     = "us-central1"
zone       = "us-central1-a"

# Use existing VPC (default: true)
use_existing_vpc = true
vpc_name         = "your-existing-vpc-name"

# Use existing subnet (default: true)
use_existing_subnet = true
subnet_name         = "your-existing-subnet-name"

# Cloud Router Configuration
router_name = "graphiant-cloud-router"
router_asn  = 16550

# InterConnect Configuration
vlan_a_name = "vlan-attachment-a"
vlan_b_name = "vlan-attachment-b"
mtu         = 1440  # Valid values: 1440 or 1500

```

--------------------------------

### Ansible Module Structure Example

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Provides a template for creating Ansible modules, including DOCUMENTATION, EXAMPLES, and RETURN sections, along with the main module logic. Ensure idempotency and handle errors gracefully. Supports check mode.

```python
#!/usr/bin/python
# -*- coding: utf-8 -*-

DOCUMENTATION = r'''
---
module: your_module
short_description: Brief description
description:
  - Detailed description
options:
  option_name:
    description: Option description
    required: true
    type: str
'''

EXAMPLES = r'''
- name: Example task
  graphiant.naas.your_module:
    option_name: value
'''

RETURN = r'''
result:
  description: Result description
  returned: always
  type: dict
'''

from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            option_name=dict(type='str', required=True),
        ),
        supports_check_mode=True
    )
    module.exit_json(changed=False, result={})

if __name__ == '__main__':
    main()

```

--------------------------------

### Install Terraform on Linux

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Terraform CLI on Debian/Ubuntu-based Linux distributions. Requires root privileges for installation.

```bash
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
sudo apt-get update && sudo apt-get install terraform
```

--------------------------------

### Verify Azure CLI Installation

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Checks the installed version of the Azure CLI.

```bash
az version
```

--------------------------------

### Install Azure CLI on macOS

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Azure CLI on macOS using the Homebrew package manager.

```bash
brew install azure-cli
```

--------------------------------

### Install Google Cloud SDK on macOS

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the Google Cloud SDK using Homebrew on macOS. This is optional for GCP authentication.

```bash
brew install --cask google-cloud-sdk
```

--------------------------------

### Install Ansible Collection from Source

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Installs the Ansible collection directly from its source directory. The --force flag ensures that the collection is reinstalled even if it's already present.

```bash
# Activate virtual environment
source ~/venv_pb/bin/activate

# Navigate to project root
cd /Users/shaik/graphiant-playbooks

# Install the collection from source
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force
```

--------------------------------

### Install Sphinx Dependencies

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Installs the Python dependencies required for the Sphinx documentation build, as specified in the requirements-ee.txt file.

```bash
cd docs
pip install -r requirements-ee.txt
```

--------------------------------

### Run End-to-End Integration Test

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Execute the 'hello_test.yml' playbook to test the installed Graphiant NaaS collection. This playbook verifies module loading, API connectivity, and configuration.

```bash
# Run test playbook
ansible-playbook ~/.ansible/collections/ansible_collections/graphiant/naas/playbooks/hello_test.yml
```

--------------------------------

### Install Antsibul Documentation Tools

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Install 'antsibull-docs' and 'antsibull-changelog' for validating collection documentation. These tools are used for linting module and changelog documentation.

```bash
# Install antsibull-docs
pip install antsibull-docs antsibull-changelog
```

--------------------------------

### Install Development Tools for Linting

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Install the necessary Python development tools for linting and code formatting, including black, flake8, pylint, djlint, and ansible-lint. Ensure your virtual environment is activated.

```bash
source venv/bin/activate
pip install black flake8 pylint djlint ansible-lint pre-commit
```

--------------------------------

### Test Collection Build and Dependencies

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/RELEASE.md

Install dependencies and run sanity tests for the collection, specifying the Python version to use.

```bash
pip install -r requirements-ee.txt --upgrade
ansible-test sanity --python 3.12
```

--------------------------------

### Install AWS CLI on macOS

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Installs the AWS Command Line Interface on macOS using Homebrew.

```bash
brew install awscli
```

--------------------------------

### Credential Management with YAML Anchors

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

This example demonstrates secure credential management using YAML anchors for reusable parameter definitions. It configures network interfaces using the `graphiant_interfaces` module.

```yaml
vars:
  graphiant_client_params: &graphiant_client_params
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

tasks:
  - name: Configure interfaces
    graphiant.naas.graphiant_interfaces:
      <<: *graphiant_client_params
      interface_config_file: "config.yaml"
      operation: "configure_lan_interfaces"
```

--------------------------------

### Build and Preview Docsite

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/SUMMARY.md

Steps to activate a virtual environment, navigate to the docs directory, build the docsite using a script, and then serve the built HTML locally for preview.

```bash
# Activate virtual environment
source ~/venv_pb/bin/activate

# Navigate to docs directory
cd ansible_collections/graphiant/naas/docs

# Build the docsite
./build.sh

# Preview locally
cd build/html
python3 -m http.server 8000
# Open http://localhost:8000 in your browser
```

--------------------------------

### Clone Graphiant Playbooks Repository

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/README.md

Clone the Graphiant playbooks repository to get started with the Ansible collection. Ensure you have Git installed.

```bash
# Clone the repository
git clone https://github.com/Graphiant-Inc/graphiant-playbooks.git
cd graphiant-playbooks
```

--------------------------------

### Input Validation in Python

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/SECURITY.md

Implement input validation to ensure data integrity and prevent potential security issues. This example validates that a host string starts with a valid protocol.

```python
# ✅ GOOD - Input validation
def validate_host(host):
    if not host.startswith(('https://', 'http://')):
        raise ValueError("Host must start with http:// or https://")
    # Additional validation...
    return host
```

--------------------------------

### Example Ansible Vault File Structure for VPN Keys

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/CREDENTIAL_MANAGEMENT_GUIDE.md

Demonstrates how to structure sensitive data, such as Site-to-Site VPN preshared keys, within an Ansible Vault file. This structure allows for easy variable access in playbooks.

```yaml
# Site-to-Site VPN Preshared Keys
vault_site_to_site_vpn_keys:
  vpn-name-1: "your-preshared-key-1"
  vpn-name-2: "your-preshared-key-2"

```

```bash
# Run with vault
ansible-playbook playbook.yml --ask-vault-pass

```

--------------------------------

### Secure Environment Variable Setup

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/SECURITY.md

Set sensitive environment variables like API credentials using `export` for secure usage. Avoid committing `.env` files containing secrets to repositories.

```bash
# ✅ GOOD - Set in environment
export GRAPHIANT_HOST="https://api.graphiant.com"
export GRAPHIANT_USERNAME="your_username"
export GRAPHIANT_PASSWORD="your_password"
```

```bash
# ❌ BAD - Don't commit to .env files in repository
echo "GRAPHIANT_PASSWORD=mypassword" >> .env
```

--------------------------------

### Build Documentation from Collection Directory

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/docs/README.md

Navigate to the collection directory and run the build script for documentation.

```bash
cd ansible_collections/graphiant/naas
./docs/build.sh
```

--------------------------------

### Build Documentation Site

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/docs/README.md

Execute this script from the repository root to build the documentation site.

```bash
python scripts/build_docsite.sh
```

--------------------------------

### Ansible Playbook with YAML Anchors for Credentials

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

This example demonstrates using YAML anchors for defining reusable parameters like host, username, and password in Ansible playbooks. It shows configuration of interfaces and BGP.

```yaml
vars:
  graphiant_client_params: &graphiant_client_params
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

tasks:
  - name: Task 1
    graphiant.naas.graphiant_interfaces:
      <<: *graphiant_client_params
      interface_config_file: "config.yaml"
      operation: "configure_lan_interfaces"
      detailed_logs: true

  - name: Task 2
    graphiant.naas.graphiant_bgp:
      <<: *graphiant_client_params
      bgp_config_file: "bgp.yaml"
      operation: "configure"
      detailed_logs: true
```

--------------------------------

### Build Documentation Site (Docs Directory)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/README.md

Navigate to the `docs` directory and run the `build.sh` script to build the HTML documentation site.

```bash
cd docs
./build.sh
```

--------------------------------

### Build Documentation Site (Collection Root)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/README.md

Execute the `build_docsite.sh` script from the collection root directory to build the HTML documentation site.

```bash
# From collection root
python ../../scripts/build_docsite.sh
```

--------------------------------

### Install Graphiant Ansible Collection

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/README.md

Installs the Graphiant Ansible collection from source or Ansible Galaxy. Ensure you have a Python virtual environment activated and dependencies installed.

```bash
python3.7 -m venv venv
source venv/bin/activate
pip install -r ansible_collections/graphiant/naas/requirements-ee.txt
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force
```

```bash
ansible-galaxy collection install graphiant.naas
```

--------------------------------

### Install Collection from Ansible Galaxy

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Install the Graphiant Inc. Graphiant Playbooks collection directly from Ansible Galaxy. This method requires prior installation of collection dependencies.

```bash
# Install collection dependencies in a virtual environment
pip install -r ansible_collections/graphiant/naas/requirements-ee.txt

# Install collection from Ansible Galaxy
ansible-galaxy collection install graphiant.naas
```

--------------------------------

### Verify AWS CLI Installation

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Checks if the AWS CLI is installed and displays its version.

```bash
aws --version
```

--------------------------------

### Configure LAN and WAN interfaces together

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use this playbook to configure both LAN and WAN interfaces simultaneously. Ensure the sample configuration files are correctly specified.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag configure --check
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag configure
```

--------------------------------

### Run Interface Management Playbook (Check Mode)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the `interface_management.yml` playbook in check mode to preview WAN interface and circuit configurations without applying changes.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag wan --check
```

--------------------------------

### Run Playbook to Create Sites and Attach Objects

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the site management playbook to perform both site creation and object attachment. Use the `--check` flag for a dry run.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag configure --check
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag configure
```

--------------------------------

### Run Site Creation Playbook

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the site management playbook to configure sites. Use the `--check` flag for a dry run.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag configure_sites --check
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag configure_sites
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag configure_sites --check
```

--------------------------------

### Configure Sites using Graphiant Module

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use the `graphiant.naas.graphiant_sites` module to create sites. Ensure `state` is set to `present` and `operation` to `configure_sites`. Detailed logs are enabled.

```yaml
- name: Configure Sites (Create Sites)
  graphiant.naas.graphiant_sites:
    <<: *graphiant_client_params
    site_config_file: "sample_sites.yaml"
    operation: "configure_sites"
    detailed_logs: true
    state: present
  register: configure_sites_result
  tags: ['configure_sites']

- name: Display Configure Sites Result
  ansible.builtin.debug:
    msg: "{{ configure_sites_result.msg }}"
  when: configure_sites_result is defined and configure_sites_result.msg is defined
  tags: ['configure_sites']
```

--------------------------------

### Verify Terraform Installation

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Checks the installed Terraform version. Requires Terraform CLI to be in the system's PATH.

```bash
terraform version
```

--------------------------------

### Verify Graphiant NaaS Collection Installation

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Verify that the 'graphiant.naas' collection has been successfully installed by listing it using 'ansible-galaxy'.

```bash
ansible-galaxy collection list graphiant.naas
```

--------------------------------

### Deploy Documentation to Existing Site via rsync

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Uses rsync to efficiently copy the built HTML documentation files to a remote server. This is useful for integrating the collection documentation into an existing documentation infrastructure.

```bash
# From collection directory
cd ansible_collections/graphiant/naas
# Example: Copy to your docs server
rsync -av docs/build/html/ user@docs-server:/path/to/docs/graphiant-playbooks/
```

--------------------------------

### Troubleshooting: Install Collection

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/QUICK_START.md

Solution for the 'unable to locate collection' error. This involves installing the collection using ansible-galaxy.

```bash
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force
```

--------------------------------

### Alternative Custom Build Script

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/QUICK_START.md

Executes a custom build script for the documentation site. Navigate to the collection directory before running.

```bash
# Navigate to collection directory
cd ansible_collections/graphiant/naas

# Run the custom build script
./docs/build_docsite.sh
```

--------------------------------

### Initialize Terraform Configuration

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Initializes the Terraform working directory. This command downloads provider plugins and sets up the backend.

```bash
terraform init
```

--------------------------------

### Configure Sites and Attach Objects using Graphiant Module

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use the `graphiant.naas.graphiant_sites` module for a combined operation of creating sites and attaching objects. Ensure `state` is set to `present` and `operation` to `configure`. Detailed logs are enabled.

```yaml
- name: Configure Sites (Create Sites + Attach Objects)
  graphiant.naas.graphiant_sites:
    <<: *graphiant_client_params
    site_config_file: "sample_sites.yaml"
    operation: "configure"
    detailed_logs: true
    state: present
  register: configure_result
  tags: ['configure']

- name: Display Configure Result
  ansible.builtin.debug:
    msg: "{{ configure_result.msg }}"
  when: configure_result is defined and configure_result.msg is defined
  tags: ['configure']
```

--------------------------------

### Install Dependencies

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/RELEASE.md

Installs necessary Python packages for the Ansible collection's execution environment. Ensure you are in the correct directory before running.

```bash
cd ansible_collections/graphiant/naas
pip install -r requirements-ee.txt
```

--------------------------------

### Run E2E Integration Test

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Execute the 'hello_test.yml' playbook to verify the collection's functionality. Set Graphiant API credentials and optionally enable debug output.

```bash
# Set credentials
export GRAPHIANT_HOST="https://api.graphiant.com"
export GRAPHIANT_USERNAME="your_username"
export GRAPHIANT_PASSWORD="your_password"
```

```bash
# Optional: Enable pretty output for detailed_logs
export ANSIBLE_STDOUT_CALLBACK=debug
```

```bash
# Run hello_test.yml to verify collection works (also runs in CI as e2e-integration-test)
ansible-playbook ~/.ansible/collections/ansible_collections/graphiant/naas/playbooks/hello_test.yml
```

--------------------------------

### Run Interface Management Playbook

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the `interface_management.yml` playbook to configure WAN circuits and interfaces. This playbook applies the specified configurations.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag wan
```

--------------------------------

### Install Required Python Packages

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Installs necessary Python packages for building Ansible collection documentation. This includes ansible-core, antsibull-docs, Sphinx, and the Sphinx-Ansible-Theme.

```bash
pip install ansible-core antsibull-docs sphinx sphinx-ansible-theme
```

--------------------------------

### Verify Ansible Collection Build

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/RELEASE.md

Commands to verify the integrity and installation of the built Ansible collection. Includes local installation, listing, and running sanity tests.

```bash
# Install the collection locally
ansible-galaxy collection install build/graphiant-naas-25.11.2.tar.gz --force

# Verify installation
ansible-galaxy collection list graphiant.naas

# Run sanity tests
cd ansible_collections/graphiant/naas
ansible-test sanity --python 3.12
```

--------------------------------

### Build HTML with Sphinx (Manual)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Builds the HTML documentation site using Sphinx from the generated RST files. This command assumes a Sphinx project is already set up, including a conf.py file.

```bash
cd docs
sphinx-build -b html . _build/html
```

--------------------------------

### Check Current Version (Quick Reference)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/VERSION_MANAGEMENT.md

A concise command to display the current collection version from `_version.py`.

```bash
# Check current version
python -c "from _version import __version__; print(__version__)"
```

--------------------------------

### Install Requirements for Offline Unit Tests

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Install necessary Python packages for running offline unit tests, including requirements for the execution environment and specific unit testing dependencies.

```bash
cd ansible_collections/graphiant/naas
pip install -r requirements-ee.txt -r tests/unit/requirements.txt
```

--------------------------------

### Run Circuit Management Playbook (Check Mode)

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the `circuit_management.yml` playbook in check mode to preview static route configurations without applying changes. This is useful for verifying changes before deployment.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/circuit_management.yml --tag static_routes --check
```

--------------------------------

### Troubleshoot Docker Container

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/Docker.md

Commands to check the logs of the Graphiant Playbooks container and verify the Ansible collection installation.

```bash
# Check container logs
docker logs graphiant-playbooks
```

```bash
# Verify collection
docker run -it graphiant-playbooks ansible-galaxy collection list graphiant.naas
```

--------------------------------

### Manage Graphiant Sites with Ansible

Source: https://context7.com/graphiant-inc/graphiant-playbooks/llms.txt

Use this playbook to create, attach objects to, and deconfigure Graphiant sites. It requires a sample_sites.yaml file for configuration.

```yaml
---
- name: Manage Graphiant sites
  hosts: localhost
  gather_facts: false
  vars:
    graphiant_client_params: &graphiant_client_params
      host: "{{ lookup('env', 'GRAPHIANT_HOST') }}"
      username: "{{ lookup('env', 'GRAPHIANT_USERNAME') }}"
      password: "{{ lookup('env', 'GRAPHIANT_PASSWORD') }}"

  tasks:
    - name: Create sites and attach objects
      graphiant.naas.graphiant_sites:
        <<: *graphiant_client_params
        site_config_file: "sample_sites.yaml"
        operation: "configure"
        detailed_logs: true
      register: configure_result

    - name: Attach global objects to existing sites
      graphiant.naas.graphiant_sites:
        <<: *graphiant_client_params
        site_config_file: "sample_site_attachments.yaml"
        operation: "attach_objects"
        detailed_logs: true

    - name: Detach objects and delete sites
      graphiant.naas.graphiant_sites:
        <<: *graphiant_client_params
        site_config_file: "sample_sites.yaml"
        operation: "deconfigure"
        state: absent

# Run: ansible-playbook playbook.yml --check
# Run: ansible-playbook playbook.yml

```

--------------------------------

### Verify Ansible Collection Accessibility

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Lists the installed Ansible collections to verify that the target collection is recognized and accessible by Ansible.

```bash
ansible-doc --list graphiant.naas
```

--------------------------------

### Get AWS Transit Gateway Details

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Retrieves Transit Gateway IDs, their state, and the Amazon-side ASN in a table format.

```bash
aws ec2 describe-transit-gateways --query 'TransitGateways[*].[TransitGatewayId,State,AmazonSideAsn]' --output table
```

--------------------------------

### Verify Ansible Collection Dependencies

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/SECURITY.md

Ensure the integrity and security of installed Ansible collections by verifying them using `ansible-galaxy collection verify`.

```bash
# Check Ansible collection dependencies
ansible-galaxy collection verify graphiant.naas
```

--------------------------------

### Create Data Exchange Customers

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use this playbook to create Data Exchange customers. Ensure the configuration file is correctly specified.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/de_workflows/02_dataex_create_customers.yml --check
ansible-playbook ansible_collections/graphiant/naas/playbooks/de_workflows/02_dataex_create_customers.yml
```

```yaml
- name: Create Data Exchange customers
  graphiant.naas.graphiant_data_exchange:
    <<: *graphiant_client_params
    operation: create_customers
    config_file: "de_workflows_configs/sample_data_exchange_customers.yaml"
    # config_file: "de_workflows_configs/sample_data_exchange_customers_scale.yaml" # Scale testing
    # config_file: "de_workflows_configs/sample_data_exchange_customers_scale2.yaml" # Scale testing2
    detailed_logs: true
  register: create_customers_result

- name: Display customers creation result
  ansible.builtin.debug:
    msg: "{{ create_customers_result.msg }}"
```

--------------------------------

### Get AWS Direct Connect Gateway Details

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Displays Direct Connect Gateway IDs, names, and the Amazon-side ASN in a table.

```bash
aws directconnect describe-direct-connect-gateways --query 'directConnectGateways[*].[directConnectGatewayId,directConnectGatewayName,amazonSideAsn]' --output table
```

--------------------------------

### Configure Syslog Servers

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

This playbook configures global syslog servers using the `graphiant_global_config` module. The `operation: "configure"` and `state: present` parameters are used, with configuration details from `sample_global_syslog_servers.yaml`.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/complete_network_setup.yml --tag syslog --check
ansible-playbook ansible_collections/graphiant/naas/playbooks/complete_network_setup.yml --tag syslog
```

```yaml
- name: Configure global syslog servers
  graphiant.naas.graphiant_global_config:
    <<: *graphiant_client_params
    config_file: "sample_global_syslog_servers.yaml"
    operation: "configure"
    detailed_logs: true
    state: present
  register: syslog_result
  tags: ['global_config', 'syslog']

- name: Display syslog result
  ansible.builtin.debug:
    msg: "{{ syslog_result.msg }}"
  tags: ['global_config', 'syslog']
```

--------------------------------

### Run Playbook to Attach Objects to Sites

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the site management playbook to attach global system objects to sites. Use the `--check` flag for a dry run. Prerequisite: global objects must already exist.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag attach_objects --check
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag attach_objects
```

--------------------------------

### Bump Project Version

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Scripts to automate version bumping for patch, minor, or major releases. After bumping, update changelogs and install dependencies.

```bash
# From repository root
# Patch release (bug fixes)
python scripts/bump_version.py patch

# Minor release (new features)
python scripts/bump_version.py minor

# Major release (breaking changes)
python scripts/bump_version.py major

# Set specific version
python scripts/bump_version.py 26.3.0
```

--------------------------------

### Configure LAN interfaces

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

This playbook is used to configure LAN interfaces. It utilizes the `configure_lan_interfaces` operation with `state: present`. Ensure `sample_interface_config.yaml` is correctly configured.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag lan --check
ansible-playbook ansible_collections/graphiant/naas/playbooks/interface_management.yml --tag lan
```

```yaml
- name: Configure LAN interfaces only
  graphiant.naas.graphiant_interfaces:
    <<: *graphiant_client_params
    interface_config_file: "sample_interface_config.yaml"
    operation: "configure_lan_interfaces"
    detailed_logs: true
    state: present
  tags: ['interfaces', 'lan']
  register: configure_result

- name: Display LAN Interface Configuration Results
  ansible.builtin.debug:
    msg: "{{ configure_result.msg }}"
  when: configure_result is defined and configure_result.msg is defined
  tags: ['interfaces', 'lan']
```

--------------------------------

### Sync All Version Files

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/VERSION_MANAGEMENT.md

Run this command to synchronize version information across all relevant files. This is a key step for resolving version mismatch errors.

```bash
python scripts/bump_version.py <version>
```

--------------------------------

### Vault Setup for Site-to-Site VPN

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

These commands set up the Ansible Vault for securing sensitive VPN credentials. Ensure the vault password file is correctly configured.

```bash
cp ansible_collections/graphiant/naas/configs/vault_secrets.yml.example ansible_collections/graphiant/naas/configs/vault_secrets.yml
export ANSIBLE_VAULT_PASSPHRASE="*************"
ansible-vault encrypt ansible_collections/graphiant/naas/configs/vault_secrets.yml --vault-password-file ansible_collections/graphiant/naas/configs/vault-password-file.sh
```

--------------------------------

### Get Subnet Details

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Retrieve detailed information about a specific subnet to confirm it exists in the correct VPC and region. This is useful for troubleshooting VPC/Subnet Not Found errors.

```bash
# Get subnet details (to verify it's in the correct VPC)
gcloud compute networks subnets describe subnet-name --region=us-central1 --project=your-project-id

```

--------------------------------

### Run Circuit Management Playbook

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the `circuit_management.yml` playbook to configure circuits, including adding WAN circuit static routes. This playbook applies the specified circuit configurations.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/circuit_management.yml --tag static_routes
```

--------------------------------

### Run Ansible Playbook Linting

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Lint Ansible playbooks using ansible-lint. Ensure the collection is installed first. This command checks playbooks located in the specified directory.

```bash
# Ansible playbook linting (runs in CI, requires collection to be installed first)
ansible-galaxy collection install ansible_collections/graphiant/naas/ --force
ansible-lint --config-file ~/.ansible/collections/ansible_collections/graphiant/naas/.ansible-lint ~/.ansible/collections/ansible_collections/graphiant/naas/playbooks/
```

--------------------------------

### Required Project and Network Configuration

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Essential parameters for project setup, network configuration, and deployment control. Ensure Transit Gateway and DirectConnect Gateway ASNs are distinct.

```hcl
# Project Configuration
project_name = "your-project"
aws_region   = "us-east-1"

# Deployment Control
skip_manual_steps = false  # Set to true after accepting Direct Connect connection

# Transit Gateway
tgw_asn_number = 64512  # Must be different from DirectConnect Gateway ASN

# DirectConnect Gateway
dx_gateway_name = "graphiant-dx-gateway"
dx_gateway_asn  = 64513  # Must be different from Transit Gateway ASN
dxgw_allowed_prefixes = ["10.0.0.0/16"]  # Prefixes to advertise to Graphiant

# DirectConnect Connection (from Graphiant - provided after Gateway Service request)
dx_connection_id   = "dx-xxxxx"  # Provided by Graphiant after Step 1
dx_connection_vlan = 100         # VLAN ID from the connection (obtained when accepting connection in Step 4b)

# Transit Virtual Interface
dx_vif_name      = "graphiant-transit-vif"
customer_bgp_asn = 30656  # Graphiant's ASN
transit_vif_mtu   = 8500   # Valid values: 1500 or 8500 (jumbo frames)
```

--------------------------------

### Run Site Deletion Playbook

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Execute the site management playbook to deconfigure (delete) sites. Use the `--check` flag for a dry run.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag deconfigure_sites --check
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag deconfigure_sites
```

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/site_management.yml --tag deconfigure_sites --check
```

--------------------------------

### Lint Python Code with Flake8

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/README.md

Lint Python code in the 'ansible_collections/graphiant/naas/plugins/' directory using 'flake8' with a maximum line length of 120. This checks for style guide violations.

```bash
# Python linting with flake8 (runs in CI)
flake8 ansible_collections/graphiant/naas/plugins/ --max-line-length=120
```

--------------------------------

### Run Python Linting with Flake8

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/CONTRIBUTING.md

Execute Flake8 to check Python code for style guide violations and potential errors, enforcing a maximum line length of 120 characters.

```bash
# Python code linting with flake8 (runs in CI)
flake8 ansible_collections/graphiant/naas/plugins/ --max-line-length=120
```

--------------------------------

### Prepare for GitHub Pages Deployment

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/DOCSITE_SETUP.md

Creates a new 'gh-pages' branch, removes all existing files, and cleans the working directory to prepare for copying the built documentation site.

```bash
# From project root
cd /Users/shaik/graphiant-playbooks
git checkout -b gh-pages
git rm -rf .
git clean -fxd
```

--------------------------------

### Configure Graphiant Filters

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use this playbook to configure global Graphiant filters. Ensure the `sample_global_graphiant_filters.yaml` file is correctly set up. The `state: present` ensures the filters are applied.

```bash
ansible-playbook ansible_collections/graphiant/naas/playbooks/complete_network_setup.yml --tag graphiant_filters --check
ansible-playbook ansible_collections/graphiant/naas/playbooks/complete_network_setup.yml --tag graphiant_filters
```

```yaml
- name: Configure global Graphiant filters
  graphiant.naas.graphiant_global_config:
    <<: *graphiant_client_params
    config_file: "sample_global_graphiant_filters.yaml"
    operation: "configure_graphiant_filters"
    detailed_logs: true
    state: present
  register: graphiant_filters_result
  tags: ['global_config', 'graphiant_filters']

- name: Display Graphiant filters result
  ansible.builtin.debug:
    msg: "{{ graphiant_filters_result.msg }}"
  tags: ['global_config', 'graphiant_filters']
```

--------------------------------

### Ansible Debug Callback for Clean Output

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/ansible_collections/graphiant/naas/docs/guides/EXAMPLES.md

Use the `ANSIBLE_STDOUT_CALLBACK=debug` environment variable to get cleaner output when running Ansible playbooks, especially when combined with verbose flags like `-vvv`.

```bash
export ANSIBLE_STDOUT_CALLBACK=debug
ansible-playbook playbook.yml -vvv
```

--------------------------------

### Verify Existing VPC

Source: https://github.com/graphiant-inc/graphiant-playbooks/blob/main/terraform/README.md

Use this command to list all VPC networks in your specified GCP project. Ensure the VPC name matches your configuration.

```bash
# Verify existing VPC
gcloud compute networks list --project=your-project-id

```