Graphiant Playbooks

Automated network infrastructure and configuration management for Graphiant Network-as-a-Service (NaaS).

Refer Graphiant Docs to get started with Graphiant Network-as-a-Service (NaaS) offerings.

Graphiant API Authentication

Automation in this repository talks to the Graphiant API using a access token or username/password.

# Set Graphiant API Endpoint URL
export GRAPHIANT_HOST="https://api.graphiant.com"

Option 1: Set Graphiant API ACCESS TOKEN

# Fetch a Graphiant API access token using the graphiant CLI
graphiant login
source ~/.graphiant/env.sh

# Optional: reload shell configuration so the token is available in new terminals
source ~/.zshrc

# Verify the variable is set without printing its value
[ -n "$GRAPHIANT_ACCESS_TOKEN" ] && echo "GRAPHIANT_ACCESS_TOKEN is set"

The Ansible collection accepts access_token on modules and honors GRAPHIANT_ACCESS_TOKEN when set (bearer auth is used before username/password when the token is valid). See Credential Management Guide.

Option 2: Set Graphiant Portal User Login Credentials

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.) or export for the session
export GRAPHIANT_USERNAME="your_username"
export GRAPHIANT_PASSWORD="your_password"

# Verify the variables are set without printing their values. Avoid echoing them or piping env through grep—that exposes secrets.
[ -n "$GRAPHIANT_USERNAME" ] && echo "GRAPHIANT_USERNAME is set"
[ -n "$GRAPHIANT_PASSWORD" ] && echo "GRAPHIANT_PASSWORD is set"

Pass username / password (or your vault equivalents) into playbooks and roles as required by each module.

📚 Documentation

• Official Documentation: Graphiant Playbooks Guide <-> Graphiant Automation Docs
• Ansible community package: The graphiant.naas collection is part of the Ansible community package (the curated ansible distribution). Official collection and module docs live on Ansible's site: Graphiant.Naas - Ansible Documentation (collection index and plugin index).
• Ansible Collection: Ansible Galaxy Collection - graphiant.naas
• Changelog: changelogs/changelog.yaml - Version history and release notes
• Security Policy: SECURITY.md - Security best practices and vulnerability reporting

Components

Component	Description	Documentation
Ansible Collection	Ansible modules for Graphiant NaaS automation (v26.7.0); bundled in the Ansible community package	📖 Collection README · 📖 Ansible docs (graphiant.naas)
Terraform Modules	Infrastructure as Code for cloud connectivity	📖 Documentation
CI/CD Pipelines	Automated testing, linting, building, and releasing	📖 GitHub
Docker Support	Containerized execution environment	📖 Documentation

Quick Start

Prerequisites

• Python 3.7+ (compatible with ansible-core 2.17, 2.18, 2.19, and 2.20)
• Ansible Core 2.17+
• Terraform v1.14+

Ansible Collection (Recommended)

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

# Create virtual environment
python3.7 -m venv venv
source venv/bin/activate

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

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

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

Example Playbook:

---
- name: Configure Graphiant network
  hosts: localhost
  gather_facts: false
  vars:
    graphiant_client_params: &graphiant_client_params
      host: "{{ graphiant_host }}"
      username: "{{ graphiant_username }}"
      password: "{{ graphiant_password }}"

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

See the Ansible Collection README for complete documentation and Examples Guide for detailed usage examples.

Key Features

• Idempotent Operations: All modules correctly report changed: false when no modifications occur
• Structured Results: Manager methods return detailed results with changed, created, skipped, and deleted fields
• Graceful Error Handling: Handles "object not found" errors gracefully in deconfigure operations
• Jinja2 Template Support: Configuration files support Jinja2 templating for dynamic generation
• Comprehensive Logging: Optional detailed logging for debugging and troubleshooting
• Automated Releases: GitHub Actions workflow for building, publishing, and creating releases

Python Library

The collection can also be used as a Python library:

# Set PYTHONPATH for direct Python usage
export PYTHONPATH=$(pwd)/ansible_collections/graphiant/naas/plugins/module_utils:$PYTHONPATH

from libs.graphiant_config import GraphiantConfig

config = GraphiantConfig(
    base_url="https://api.graphiant.com",
    username="user",
    password="pass"
)
config.interfaces.configure_lan_interfaces("interface_config.yaml")

See ansible_collections/graphiant/naas/tests/test.py for comprehensive Python library usage examples.

Terraform Modules

Deploy cloud connectivity infrastructure with Terraform:

# Azure ExpressRoute
cd terraform/gateway_services/azure
terraform init
terraform plan -var-file="../../configs/gateway_services/azure_config.tfvars"
terraform apply -var-file="../../configs/gateway_services/azure_config.tfvars"

# AWS Direct Connect
cd terraform/gateway_services/aws
terraform init
terraform plan -var-file="../../configs/gateway_services/aws_config.tfvars"
terraform apply -var-file="../../configs/gateway_services/aws_config.tfvars"

# GCP InterConnect
cd terraform/gateway_services/gcp
terraform init
terraform plan -var-file="../../configs/gateway_services/gcp_config.tfvars"
terraform apply -var-file="../../configs/gateway_services/gcp_config.tfvars"

See the Terraform README for detailed setup instructions.

Project Structure

graphiant-playbooks/
├── ansible_collections/graphiant/naas/               # Ansible collection 
│   ├── plugins/modules/                              # Ansible modules (23 modules)
│   ├── plugins/module_utils/                         # Python library code
│   ├── playbooks/                                    # Example playbooks
│   ├── configs/                                      # Configuration templates
│   ├── templates/                                    # Jinja2 templates
│   ├── docs/                                         # Documentation
│   ├── changelogs/changelog.yaml                     # Version history
│   ├── README.md                                     # Collection documentation
│   └── _version.py                                   # Centralized version management
├── terraform/                                        # Terraform modules
│   ├── gateway_services/                             # Cloud gateway services (AWS/Azure/GCP)
│   └── edge_services/                                # Edge services
├── scripts/                                          # Utility scripts
│   ├── build_collection.py                          # Collection build script
│   ├── bump_version.py                              # Version bumping script
│   ├── validate_collection.py                       # Collection validation script
│   └── build_docsite.sh                             # Documentation build script
├── .github/workflows/                                # GitHub Actions workflows
│   ├── lint.yml                                     # Linting workflow
│   ├── test.yml                                     # Test workflow (multi-version testing)
│   ├── build.yml                                    # Build workflow
│   ├── release.yml                                  # Release workflow (auto-tag/release)
│   └── README.md                                    # GitHub documentation
├── mypy.ini                                          # Mypy config (collection `plugins/` + `scripts/`)
├── SECURITY.md                                       # Security policy
├── CONTRIBUTING.md                                   # Contribution guidelines
├── CODE_OF_CONDUCT.md                               # Code of conduct
└── README.md                                         # This file

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup
• Code standards
• Lint, Pylint, and mypy (including mypy.ini and Python 3.7+ type-hint rules for the collection)
• Testing requirements
• Pull request process
• Branch protection requirements
• GPG signing requirements

See CODE_OF_CONDUCT.md for our community guidelines.

📄 License

This project is licensed under the GNU General Public License v3.0 or later (GPLv3+) - see the LICENSE file for details.

🆘 Support

• Official Documentation: Graphiant Playbooks Guide <-> Graphiant Automation Docs
• Changelog: changelogs/changelog.yaml - Version history and release notes
• Security: SECURITY.md - Security policy and vulnerability reporting
• Issues: GitHub Issues
• Email: support@graphiant.com

🔗 Related Projects

• Graphiant SDK Python
• Graphiant SDK Go

---

Made with ❤️ by the Graphiant Team