graphiant.naas.graphiant_macsec module – Configure interface MACsec (802.1AE) on Edge/Gateway devices

Note

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

New in graphiant.naas 26.5.0

Synopsis

• Configures MACsec on main LAN interfaces (ethernet or LAG) via PUT /v1/devices/{device_id}/config under edge.interfaces.{name}.interface.macsec.macsec or edge.lagInterfaces.{name}.interface.macsec.macsec.

• Supports enabling/disabling MACsec, configuring encryption enforcement mode, key server priority, pre-shared keys (PSK), and SAK profile settings (replay protection window and rekey interval).

• Supply macsec_config_file for a bulk macsec list, and/or device with interfaces to run a single device or override one device from the file.

• Add or rotate PSKs with presharedKeys entries (up to 3 per interface). Each key requires a unique nickname, future startTime (Unix seconds or UTC datetime string such as 2029-12-11 11:12:13), cak, ckn, and cipherSuite (AES_128_CMAC or AES_256_CMAC). AES-128 requires a 32-digit hex CAK; AES-256 requires 64-digit hex CAK. ckn is 2–64 hex digits.

• Remove a PSK with state: absent on the key entry (sends psk: null). At least one PSK must remain when MACsec is enabled.

• Existing PSK nicknames cannot be updated in place (CAK, CKN, startTime, cipher suite). To rotate, add a new presharedKeys entry with a unique nickname, then remove the old key with state: absent. Listing an unchanged existing key in YAML is idempotent and does not re-push the PSK.

• CAK is sensitive. Omit cak from YAML or interfaces; set ckn (plaintext) on each presharedKeys entry and supply vault_devices_macsec_psk (device → interface → ckn → cak) via Ansible Vault. Or set cak in YAML/module params for dev/local only. Diff output redacts CAK values and uses cakConfigured booleans.

• Idempotent merge per interface field. Partial updates are supported (e.g. enabled: false, keyServerPriority only, PSK rotation, SAK-only). Configure-only (no deconfigure operation).

• Requires a software image with MACsec support on the target device. The API returns an error when MACsec is unsupported on the device image.

Requirements

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

• python >= 3.7

• graphiant-sdk >= 26.5.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
device string	Portal device hostname for get_device_id. With macsec_config_file, optional overrides. Required when macsec_config_file is omitted (single-device mode).
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
interfaces dictionary	Map of main interface name to MACsec settings (ethernet or LAG only; not subinterfaces). Each value may include enabled, encryptionEnforcementMode, keyServerPriority, presharedKeys, and sakConfiguration.
macsec_config_file aliases: macsec_file string	Path to YAML (optional if device is set with interfaces). Relative paths resolve using the collection config path (see GRAPHIANT_CONFIGS_PATH). Top-level key macsec is a list of dicts; each dict has one key, the portal device name.
operation string	Only configure is supported. Choices: "configure" ← (default)
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	Only present is supported. Choices: "present" ← (default)
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_devices_macsec_psk dictionary	Nested map device → interface → ckn → cak from Ansible Vault via include_vars (key vault_devices_macsec_psk in configs/vault_secrets.yml). When YAML or interfaces omit cak but include ckn, the module looks up CAK by ckn. Explicit cak in YAML or module params is not overwritten. Default: {}

Attributes

Attribute	Support	Description
check_mode	Support: full	Supports check mode similarly to other device config modules.
diff_mode	Support: full	Supports Ansible’s --diff for pending edge branch updates.

Notes

Note

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

• When using macsec_config_file, set ckn on each key in YAML, omit cak, and pass vault_devices_macsec_psk loaded from configs/vault_secrets.yml (see playbooks/macsec_management.yml). Plaintext cak in YAML is for dev/local testing only.

• With ansible-playbook --check, writes are skipped but changed reflects whether an apply would update at least one device. Use --diff to preview details.diff_plan and Ansible diff.

• Use graphiant.naas.graphiant_macsec_info to query MACsec monitoring status (GET /v2/monitoring/macsec/{device_id}/status).

See Also

See also

graphiant.naas.graphiant_macsec_info

Query MACsec secure/unsecure monitoring status per interface.

graphiant.naas.graphiant_interfaces

Configure LAN/WAN interfaces before applying MACsec.

graphiant.naas.graphiant_lag_interfaces

Configure LAG interfaces before applying MACsec on LAGs.

Examples

# Load vault_secrets.yml with M(ansible.builtin.include_vars) first (see macsec_management.yml).

- name: Apply MACsec from sample_macsec.yaml
  graphiant.naas.graphiant_macsec:
    operation: configure
    macsec_config_file: "sample_macsec.yaml"
    vault_devices_macsec_psk: "{{ vault_devices_macsec_psk | default({}) }}"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  register: macsec_result
  no_log: true

- name: Enable MACsec on a LAG interface (secrets from vault or module params)
  graphiant.naas.graphiant_macsec:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-1-sdktest"
    vault_devices_macsec_psk: "{{ vault_devices_macsec_psk | default({}) }}"
    interfaces:
      LAG1:
        enabled: true
        encryptionEnforcementMode: MACSEC_ENFORCEMENT_MODE_MUST_ENCRYPT
        keyServerPriority: 200
        presharedKeys:
          - nickname: macsec-key-1
            startTime: "2029-12-11 11:12:13"
            ckn: "853c6a4eb4f21c58a5bfeb9600dd26e8e045ded866b02a45f5f52cebadcd5956"
            cipherSuite: AES_256_CMAC
            useXpnForCipherSuite: true
        sakConfiguration:
          replayProtectionWindowSize: 64
          rekeyInterval: 3600
  no_log: true

- name: Disable MACsec on an interface
  graphiant.naas.graphiant_macsec:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-1-sdktest"
    interfaces:
      LAG1:
        enabled: false

- name: Rotate MACsec keys (add new key, remove old)
  graphiant.naas.graphiant_macsec:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-1-sdktest"
    interfaces:
      GigabitEthernet7/0/0:
        presharedKeys:
          - nickname: key1
            state: absent
          - nickname: key2
            startTime: "2029-12-11 23:12:13"
            ckn: "24"
            cipherSuite: AES_256_CMAC
    vault_devices_macsec_psk: "{{ vault_devices_macsec_psk | default({}) }}"
  no_log: true

- name: Update SAK replay window only
  graphiant.naas.graphiant_macsec:
    operation: configure
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    device: "edge-1-sdktest"
    interfaces:
      LAG1:
        sakConfiguration:
          replayProtectionWindowSize: 128

Return Values

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

Key	Description
changed boolean	Whether configuration was pushed to at least one device. Returned: always
configured_devices list / elements=string	Device names where an update was applied. Returned: when supported
details dictionary	Structured payload from the manager (device 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 device branch would change
macsec_config_file string	Path to the YAML file used, if any. Returned: when provided
msg string	Human-readable result (includes detailed logs when enabled). Returned: always
operation string	Operation performed (always configure). Returned: always
skipped_devices list / elements=string	Device names skipped because state already matched. Returned: when supported

Authors

• Graphiant Team (@graphiant)

Collection links

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