graphiant.naas.graphiant_gateway_services module – Manage Graphiant Gateway Services (cloud gateway and connectivity)

Note

This module is part of the graphiant.naas collection (version 26.10.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_gateway_services.

New in graphiant.naas 26.9.0

Synopsis

• Manages Graphiant Gateway Services via POST/PUT/DELETE /v1/gateways. Two service types are supported under the top-level gatewayServices key in the config file: cloudGateway (cloud peering for AWS, Azure, GCP, and Oracle) and connectivity (site-to-site IPSec VPN gateway, ipsecGatewayPeers).

• The create operation is idempotent create-or-update. Services that do not exist are created; existing connectivity services are updated in place when the config changes, and services that already match are skipped. To change a service, edit the config file and re-run create.

• Update is not supported for cloud gateway services (create/delete only). Only connectivity services can be updated; a re-run of create against an unchanged cloud gateway is skipped rather than updated.

• Region names, LAN segment names, and speeds in the config file are resolved to the API regionId/vrfId and the S-prefixed speed enum (e.g. 1Gbps -> S1Gbps) before the request is sent. Region, LAN segment, and any connectivity vpnProfile names are validated against the enterprise before any gateway is pushed, failing fast with the list of available values when a name is not found.

Requirements

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

• python >= 3.7

• graphiant-sdk >= 26.10.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 in the task result message. Choices: false ← (default) true
force_update boolean	Re-push every matching connectivity gateway (PUT) even when the idempotency comparison finds no change. Tunnel psk, inside CIDRs, and BGP md5Password are excluded from the comparison (they are auto-generated/auto-allocated per apply when left null), so a rotated secret is not otherwise detected. Set this to true after changing a PSK/MD5 value to make it take effect. Applies to create only and to connectivity gateways only; cloud gateways are never updated (change one via delete + create). Choices: false ← (default) true
gateway_services_config_file string / required	Path to the YAML configuration file containing the gatewayServices definition. Relative paths resolve using the collection config path (see GRAPHIANT_CONFIGS_PATH).
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	Operation to perform. create creates services that do not exist and updates existing connectivity services (idempotent). delete removes the services defined in the config file. When omitted, it is derived from state (present -> create, absent -> delete). 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.
state string	Desired state, used to derive operation when operation is not set. 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_gateway_bgp_md5_passwords dictionary	Connectivity BGP MD5 passwords, keyed by gateway name (ipsecGatewayPeers.name). Used to fill routing.bgp.md5Password when left null in the config (BGP routing only); a non-null value in the config takes precedence. Optional — if unset, BGP runs without MD5. Structure: {<gateway name>: <md5 password>}. Default: {}
vault_gateway_ipsec_psks dictionary	Connectivity tunnel pre-shared keys, keyed by gateway name then peer name then tunnel. Each tunnel psk is sourced by one of three modes, in precedence order: (1) DIRECT INPUT — a non-null psk in the config file is used as-is; (2) VAULT — a psk left null in the config is filled from this dict when a matching gateway/peer/tunnel entry exists; (3) API AUTO-FILL — a psk left null with no matching vault entry is auto-generated by the portal. Add entries here only for tunnels you want vault to supply. Structure: {<gateway name>: {peer-1: {tunnel1: <psk>, tunnel2: <psk>}, peer-2: {...}}}. The peer key is peer-<N>, 1-based over remotePeers. Default: {}

Attributes

Attribute	Support	Description
check_mode	Support: full In check mode, no configuration is pushed; the module still reads current state to determine whether changes would be made.	Supports check mode.
diff_mode	Support: full When the playbook runs with --diff and a service would change, the module returns a diff dictionary (before / after). Structured entries are also in details.	Supports Ansible’s --diff for pending gateway service changes.

Notes

Note

• Configuration files support Jinja2 templating syntax for dynamic value substitution.

• With ansible-playbook --check, writes are skipped but changed reflects whether an apply would create, update, or delete at least one service. Use --diff to preview the pending changes.

See Also

See also

graphiant.naas.graphiant_site_to_site_vpn

Per-edge site-to-site IPSec VPN (device-level, distinct from gateway connectivity).

graphiant.naas.graphiant_global_config

Global routing policies (filters) referenced by cloud gateway routingPolicy.

Examples

- name: Create or update gateway services from YAML
  graphiant.naas.graphiant_gateway_services:
    operation: create
    gateway_services_config_file: "sample_gateway_services_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: gateway_services_create_result

- name: Preview changes without applying (dry run)
  graphiant.naas.graphiant_gateway_services:
    operation: create
    gateway_services_config_file: "sample_gateway_services_config.yaml"
    access_token: "{{ graphiant_access_token }}"
  check_mode: true
  diff: true

- name: Delete gateway services defined in YAML
  graphiant.naas.graphiant_gateway_services:
    operation: delete
    gateway_services_config_file: "sample_gateway_services_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  register: gateway_services_delete_result

# Connectivity tunnel PSK sourcing — three modes (see also sample_gateway_services_config.yaml):
#   1. DIRECT INPUT : set psk inline in the config file, e.g. tunnel1: { psk: "my-preshared-key" }
#   2. VAULT        : leave psk null in the config and provide it via vault_gateway_ipsec_psks below
#   3. API AUTO-FILL: leave psk null in the config with no vault entry; the portal generates one
- name: Create gateway services with vault-supplied PSK (mode 2)
  graphiant.naas.graphiant_gateway_services:
    operation: create
    gateway_services_config_file: "sample_gateway_services_config.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    vault_gateway_ipsec_psks:
      test:                 # gateway name (ipsecGatewayPeers.name)
        peer-1:             # peer-<N>, 1-based over remotePeers
          tunnel2: "{{ vault_gateway_test_peer1_tunnel2_psk }}"
  register: gateway_services_create_result

Return Values

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

Key	Description
changed boolean	Whether at least one gateway service was created, updated, or deleted. Returned: always
created list / elements=string	Names of gateway services that were created. Returned: when operation is create
deleted list / elements=string	Names of gateway services that were deleted. Returned: when operation is delete
details dictionary	Structured payload from the manager (service lists, diff plan, etc.). Returned: always
diff dictionary	Ansible --diff payload when changes would be applied. Returned: when playbook uses --diff and at least one service would change
gateway_services_config_file string	Path to the YAML file used. Returned: always
msg string	Human-readable result (includes detailed logs when enabled). Returned: always
operation string	Operation performed (create or delete). Returned: always
skipped_services list / elements=string	Names of gateway services skipped because state already matched. Returned: always
updated list / elements=string	Names of connectivity gateway services that were updated in place. Returned: when operation is create

Authors

• Graphiant Team (@graphiant)

Collection links

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