graphiant.naas.graphiant_site_to_site_vpn module – Manage Graphiant Site-to-Site VPN configuration

Note

This module is part of the graphiant.naas collection (version 26.3.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install graphiant.naas. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: graphiant.naas.graphiant_site_to_site_vpn.

New in graphiant.naas 26.2.0

Synopsis

• This module provides comprehensive Site-to-Site VPN management for Graphiant Edge devices.

• Supports Site-to-Site VPN creation and deletion with static or BGP routing.

• All operations use Jinja2 templates for consistent configuration deployment.

• Configuration files support Jinja2 templating for dynamic generation.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.7

• graphiant-sdk >= 26.3.0

Parameters

Parameter	Comments
access_token string	Bearer token for API authentication (for example, from graphiant login, which opens a browser for sign-in (SSO or non-SSO) and retrieves the token). If not passed as a module argument, the collection reads GRAPHIANT_ACCESS_TOKEN (set after graphiant login when you source ~/.graphiant/env.sh). When a bearer token is present (module argument or environment), it takes precedence over username and password. If no valid token is available, the module authenticates with username and password when both are supplied.
detailed_logs boolean	Enable detailed logging output for troubleshooting and monitoring. When enabled, provides comprehensive logs of all Site-to-Site VPN operations. Logs are captured and included in the result_msg for display using ansible.builtin.debug module. Choices: false ← (default) true
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	The specific Site-to-Site VPN operation to perform. create: Create Site-to-Site VPN connections on edge devices. delete: Delete Site-to-Site VPN connections from edge devices. Choices: "create" "delete"
password string	Graphiant portal password for authentication. Required for password-based login when no valid bearer token is available from access_token or GRAPHIANT_ACCESS_TOKEN.
site_to_site_vpn_config_file string / required	Path to the Site-to-Site VPN configuration YAML file. Required for all operations. Can be an absolute path or relative path. Relative paths are resolved using the configured config_path. Configuration files support Jinja2 templating syntax for dynamic generation. File must contain Site-to-Site VPN definitions with device names and VPN configurations.
state string	The desired state of the Site-to-Site VPN configuration. present: Maps to create when operation not specified. absent: Maps to delete when operation not specified. Choices: "present" ← (default) "absent"
username string	Graphiant portal username for authentication. Required for password-based login when no valid bearer token is available from access_token or GRAPHIANT_ACCESS_TOKEN.
vault_bgp_md5_passwords dictionary	Dict of VPN name to BGP MD5 password (create only). Pass from playbook vars loaded from encrypted vault_secrets.yml; secrets in memory only. Key must match the VPN name in the config. Optional; BGP VPNs without an entry get no md5Password. Default: {}
vault_site_to_site_vpn_keys dictionary	Dict of VPN name to preshared key (create only). Pass from playbook vars loaded from encrypted vault_secrets.yml; secrets in memory only. Key must match the VPN name in the S2S config. Required for create when the config defines VPNs that need a preshared key. Default: {}

Attributes

Attribute	Support	Description
check_mode	Support: full When run with --check, the module logs the exact payloads that would be pushed with a [check_mode] prefix so you can see what configuration would be applied. The module does not perform state comparison, so changed may be True even when the configuration is already applied.	Supports check mode. In check mode, no configuration is pushed to the devices but payloads that would be pushed are logged with [check_mode].

Notes

Note

• Check mode (--check): No config is pushed; payloads that would be pushed are logged with [check_mode].

• Site-to-Site VPN Operations:

• - Create: Create Site-to-Site VPN connections on edge devices.

• - Delete: Remove Site-to-Site VPN connections from edge devices.

• Configuration files support Jinja2 templating syntax for dynamic configuration generation.

• The module automatically resolves device names to IDs.

• All operations are idempotent and safe to run multiple times.

• Create: The module compares intended config to existing device state (ipsecTunnels). If they match, no config is pushed and changed is false.

• Delete: Only VPNs that exist on the device are removed; a second delete is a no-op and returns changed false.

• Circuits and interfaces must be configured first before applying Site-to-Site VPN.

• Vault (create only): vault_site_to_site_vpn_keys, vault_bgp_md5_passwords.

• Use encrypted configs/vault_secrets.yml, configs/vault-password-file.sh; no plaintext.

• Load with ansible.builtin.include_vars (no_log true); pass dicts so secrets stay in memory.

• Vault key must match VPN name. See configs/vault_secrets.yml.example. Run with --vault-password-file configs/vault-password-file.sh.

See Also

See also

graphiant.naas.graphiant_interfaces

Configure interfaces before setting up Site-to-Site VPN

graphiant.naas.graphiant_device_config

Alternative method for device configuration

Examples

# Playbook: use encrypted configs/vault_secrets.yml (from vault_secrets.yml.example),
# decrypt with configs/vault-password-file.sh (ANSIBLE_VAULT_PASSPHRASE). Run with:
#   ansible-playbook site_to_site_vpn.yml --vault-password-file configs/vault-password-file.sh --tags create

- name: Create Site-to-Site VPN (vault dicts from include_vars; secrets in memory only)
  graphiant.naas.graphiant_site_to_site_vpn:
    operation: create
    site_to_site_vpn_config_file: "sample_site_to_site_vpn.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    vault_site_to_site_vpn_keys: "{{ vault_site_to_site_vpn_keys | default({}) }}"
    vault_bgp_md5_passwords: "{{ vault_bgp_md5_passwords | default({}) }}"
    detailed_logs: true
  no_log: true
  register: vpn_result

- name: Delete Site-to-Site VPN
  graphiant.naas.graphiant_site_to_site_vpn:
    operation: delete
    site_to_site_vpn_config_file: "sample_site_to_site_vpn.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

- name: Create using state (pass vault dicts when creating)
  graphiant.naas.graphiant_site_to_site_vpn:
    state: present
    site_to_site_vpn_config_file: "sample_site_to_site_vpn.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    vault_site_to_site_vpn_keys: "{{ vault_site_to_site_vpn_keys | default({}) }}"
    vault_bgp_md5_passwords: "{{ vault_bgp_md5_passwords | default({}) }}"
  no_log: true

- name: Delete using state
  graphiant.naas.graphiant_site_to_site_vpn:
    state: absent
    site_to_site_vpn_config_file: "sample_site_to_site_vpn.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Whether the operation made changes to the system. true when config was pushed to at least one device; false when intended state already matched (create) or no VPNs to delete (delete). Returned: always Sample: true
msg string	Result message from the operation, including detailed logs when detailed_logs is enabled. Returned: always Sample: "Successfully created Site-to-Site VPN"
operation string	The operation that was performed. One of create or delete. Returned: always Sample: "create"
site_to_site_vpn_config_file string	The Site-to-Site VPN configuration file used for the operation. Returned: always Sample: "sample_site_to_site_vpn.yaml"

Authors

• Graphiant Team (@graphiant)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)
• Report an issue
• View source code
• Communication