graphiant.naas.graphiant_data_assurance module – Manage Graphiant Data Assurance policies

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_data_assurance.

New in graphiant.naas 26.8.0

Synopsis 

Create, update, or delete Graphiant Data Assurance policies via the portal API.
Reads a structured YAML config file and applies the desired state to the Graphiant portal.
Policies may also be supplied directly through the DataAssurancePolicies and ContentFilterPolicies module parameters, used instead of or together with the config file. When both are given, module parameters are overlaid on the config file per policy name and override the config-file values.
Both assurance policies (with flexAlgo) and block-by-URL/app policies (without flexAlgo) are entries in the DataAssurancePolicies list and are sent to the /v1/data/assurance/assurances/global endpoint.
Block-by-category policies are entries in the ContentFilterPolicies list and are sent to the /v1/global/content-filters endpoint. Each blocks one or more domain categories (by name, resolved to a domain category ID) with an optional allowedUrlList (“Allowed URL List”) applied as per-category exception wildcards. Both lists are managed by the same module and operations from a single config file.
Configure is idempotent: compares the intended config against live portal state and
skips the update when already matched.
Deconfigure is idempotent: policies not found are silently skipped.
Deleting a policy is a two-step flow: the portal requires a policy to be unassigned from all sites before deletion, so the module first updates it to a detached config (no sites, empty apps/rules) and then deletes it.
With ansible-playbook --check, writes are skipped but changed reflects whether an apply would modify at least one policy. Use --diff to preview details.diff_plan.

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.
ContentFilterPolicies list / elements=dictionary	Block-by-category (content-filter) policies supplied directly as module parameters, as an alternative (or supplement) to the `ContentFilterPolicies` list in the config file. Merged with the config file the same way as `DataAssurancePolicies` (keyed by `name`).
allowedUrlList list / elements=string	Wildcard URLs allowed through despite the category block (applied as per-category exceptions).
categories list / elements=string	Domain category names to block (resolved to domain category IDs).
lanNames list / elements=string	LAN segment names the policy applies to. Omit to apply to all segments.
name string / required	Policy name (unique key used to match/override config-file policies).
siteListId integer	Explicit site list ID (used when `siteListName` is not given).
siteListName string	Name of a site list to scope the policy to (resolved to its portal site list ID).
useAllSites boolean	Apply the policy to all enterprise sites. Mutually exclusive with `siteListName`. Choices: `false` `true`
data_assurance_config_file string	Path to the Data Assurance YAML config file. Can be an absolute path or relative to the configured config_path. Supported top-level keys are `DataAssurancePolicies` (assurance and block-by-URL/app policies) and `ContentFilterPolicies` (block-by-category policies). Both are optional lists; either or both may be present. Each `DataAssurancePolicies` entry is either an assurance policy (includes `flexAlgo`) or a block/protection policy (omits `flexAlgo`), sent to the assurances endpoint. Each `ContentFilterPolicies` entry blocks domain `categories` and is sent to the content-filters endpoint. Each entry must have at minimum a `name` field. Configuration files support Jinja2 templating syntax. Optional. Omit it to configure entirely from the `DataAssurancePolicies` and/or `ContentFilterPolicies` module parameters. At least one of `data_assurance_config_file`, `DataAssurancePolicies`, or `ContentFilterPolicies` is required.
DataAssurancePolicies list / elements=dictionary	Assurance and block-by-URL/app policies supplied directly as module parameters, as an alternative (or supplement) to the `DataAssurancePolicies` list in the config file. When both are provided, these entries are overlaid on the config file keyed by policy `name`: a field set here overrides the config-file value for that field, and a policy not present in the file is added.
apps list / elements=dictionary	Applications to assure or block.
bucketId integer	Raw integer bucket ID (use instead of `profileName` for values not mapped).
builtinAppId integer	Graphiant built-in application ID (auto-filled from telemetry when omitted).
customAppId integer	Enterprise custom application ID (auto-filled from telemetry when omitted).
isDomain boolean	Whether the app name is a domain (auto-filled from telemetry when omitted). Choices: `false` `true`
name string / required	Application name (validated against the profile’s bucket telemetry).
profileName string	Human-readable assurance profile name (resolved to an integer `bucketId`).
servers list / elements=dictionary	Specific back-end servers to scope to (auto-filled from telemetry when omitted).
ip string	Server IP address.
port integer	Server port.
protocol string	Server transport protocol (e.g. `tcp`, `udp`).
useAllServers boolean	Scope to all observed back-end servers. Choices: `false` `true`
flexAlgo string	Flex-algo name defining the SLA metric. Omit for block/protection policies.
lanNames list / elements=string	LAN segment names the policy applies to. Omit to apply to all segments.
name string / required	Policy name (unique key used to match/override config-file policies).
siteListId integer	Explicit site list ID (used when `siteListName` is not given).
siteListName string	Name of a site list to scope the policy to (resolved to its portal site list ID).
useAllSites boolean	Apply the policy to all enterprise sites. Mutually exclusive with `siteListName`. Choices: `false` `true`
detailed_logs boolean	Enable detailed logging. Choices: `false` ← (default) `true`
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	Specific operation to perform. `configure` creates or updates policies listed under `DataAssurancePolicies`. Idempotent — skips policies whose live config already matches the desired state. `deconfigure` deletes listed policies (detaches sites and clears apps/rules via an update, then deletes). Idempotent — skips policies not found. Choices: `"configure"` `"deconfigure"`
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 for Data Assurance policies. `present` maps to `configure` when `operation` is omitted. `absent` maps to `deconfigure` when `operation` is omitted. 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`.

Attributes 

Attribute	Support	Description
check_mode	Support: full In check mode, no writes are sent to the portal, but the module still reads current policy state to determine whether changes would be made. Payloads that would be sent are logged with a `[check_mode]` prefix when `detailed_logs` is enabled.	Supports check mode.
diff_mode	Support: full When run with `--diff` and at least one policy would change, the module returns a `diff` dictionary (`before` / `after` strings). Structured entries are also in `details.diff_plan`, each with `policy`, `action`, `before`, and `after`.	Supports Ansible’s `--diff` for pending Data Assurance policy updates.

Notes 

Note

Site scoping: use useAllSites: true to apply a policy to all enterprise sites, or siteListName: "<name>" to scope it to a named site list. The module resolves the name to the portal site list ID and raises an error if it is not found.
flexAlgo is the flex-algo name that defines the SLA metric for path selection (e.g. test-all-cores, hestia-all-cores). Use /v1/data/assurance/flex-algos to list available values. Omit for block/protection policies. When specified, the name is validated against the flex-algos that exist in the enterprise; the module fails with an error listing the available values if it is not found.
lanNames is a list of LAN segment names (strings) that scope which segments the assurance policy applies to. Omit or leave empty to apply to all LAN segments. When specified, each name is validated against the LAN segments that exist in the enterprise; the module fails with an error listing the available values if any is not found.
Under apps, each entry represents one application to assure or block. Use profileName (human-readable string such as Graphiant_Assured or Threat_Blocked) to specify the assurance profile — the module resolves it to the corresponding integer bucketId. Use builtinAppId (Graphiant built-in application ID) or customAppId (enterprise custom application ID) to identify the application. useAllServers (bool) and servers (list of {ip, port, protocol}) further scope to specific back-end servers.
App name validation and auto-fill: for each app the module looks up the app name in its profile’s bucket (bucket-apps API, keyed by profileName/bucketId over a ~30-day window). It validates the name exists in that bucket and auto-fills isDomain, builtinAppId, and customAppId from the matched bucket app when they are not provided (values you supply always take precedence). It also auto-fills servers ({ip, port, protocol}) from the bucket-app-servers telemetry when you do not provide any. If the bucket returns no apps for the window, the module fails with an error since the app name cannot be validated.
Validation and telemetry auto-fill apply to new apps. When updating an existing policy, an app already present in it reuses its currently stored servers/hints for any field you did not set, and the telemetry lookup is skipped — so re-running configure with an unchanged config stays idempotent even though telemetry is time-windowed and can drift.

Examples 

# Provide policies through the config file, the inline parameters, or both — at least one of
# data_assurance_config_file / DataAssurancePolicies / ContentFilterPolicies is required.

# Configure Data Assurance policies from a YAML file.
- name: Configure Data Assurance policies
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    data_assurance_config_file: "sample_data_assurance_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: da_result
  no_log: true

# Configure Data Assurance policies directly from module parameters (no config file).
- name: Configure Data Assurance policies inline
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    DataAssurancePolicies:
      - name: assurance-policy-1
        useAllSites: true
        flexAlgo: test-all-cores
        apps:
          - name: tcp
            profileName: General_Assured
            useAllServers: true
    ContentFilterPolicies:
      - name: block-gambling
        useAllSites: true
        categories:
          - Gambling
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  no_log: true

# Use a config file as the base and override one policy's field via module parameters.
- name: Configure from file with an inline override
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    data_assurance_config_file: "sample_data_assurance_policies.yaml"
    DataAssurancePolicies:
      - name: assurance-policy-1
        flexAlgo: hestia-all-cores
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  no_log: true

# Flexible task — accept whichever source the caller supplies (file, inline, or both).
# Unset vars are dropped via default(omit) so only the provided source(s) are passed.
- name: Configure Data Assurance policies from any source
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    data_assurance_config_file: "{{ config_file | default(omit) }}"
    DataAssurancePolicies: "{{ data_assurance_policies | default(omit) }}"
    ContentFilterPolicies: "{{ content_filter_policies | default(omit) }}"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  no_log: true

# Deconfigure (delete) Data Assurance policies.
- name: Deconfigure Data Assurance policies
  graphiant.naas.graphiant_data_assurance:
    operation: deconfigure
    data_assurance_config_file: "sample_data_assurance_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  no_log: true

# Preview changes without pushing (check mode).
- name: Preview Data Assurance configure (dry run)
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    data_assurance_config_file: "sample_data_assurance_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  check_mode: true
  register: da_preview

# Preview per-policy diffs (run playbook with --diff or set diff: true on the task).
- name: Preview Data Assurance policy changes
  graphiant.naas.graphiant_data_assurance:
    operation: configure
    data_assurance_config_file: "sample_data_assurance_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  diff: true
  register: da_diff

Return Values 

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

Key	Description
changed boolean	Whether the operation modified at least one policy. In check mode (`--check`), no writes are sent, but `changed` reflects whether changes would be made. Returned: always
configured list / elements=string	Policy names that were created or updated (when changed=true). Returned: when supported
data_assurance_config_file string	The config file used for the operation. Returned: always
deleted list / elements=string	Policy names that were deleted (when deconfigure and changed=true). Returned: when supported
details dictionary	Raw manager result details (includes `diff_plan`, configured/skipped/deleted lists). Each `diff_plan` entry has `policy`, `action` (create/update), `before`, and `after` normalized config snapshots. Returned: when supported
diff dictionary	Ansible diff output when run with `--diff` and at least one policy would change. Built from `details.diff_plan` as JSON `before` / `after` strings per policy. Returned: when diff mode is enabled and `details.diff_plan` is non-empty
msg string	Result message (includes detailed logs when enabled). Returned: always
operation string	The operation performed. Returned: always
skipped_policies list / elements=string	Policy names that were skipped because desired state already matched. Returned: when supported

Authors

Graphiant Team (@graphiant)

graphiant.naas.graphiant_data_assurance module – Manage Graphiant Data Assurance policies

Synopsis

Requirements

Parameters

Attributes

Notes

Examples

Return Values