crowdstrike.falcon.host_group module – Manage Falcon host groups
Note
This module is part of the crowdstrike.falcon collection (version 4.9.1).
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 crowdstrike.falcon.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: crowdstrike.falcon.host_group.
New in crowdstrike.falcon 4.10.0
Synopsis
Create, update, delete, and manage Falcon host groups.
Supports static, dynamic, and staticByID group types.
Can manage host group membership by adding or removing hosts.
Provides idempotent operations that only make changes when necessary.
Requirements
The below requirements are needed on the host that executes this module.
Host Groups [READ, WRITE] API scope
crowdstrike-falconpy >= 1.3.0
python >= 3.6
Parameters
Parameter |
Comments |
|---|---|
FQL (Falcon Query Language) filter for dynamic group membership. Required when group_type=dynamic. Ignored for static and staticByID groups. Examples: |
|
The registered result of the crowdstrike.falcon.auth module, or a dictionary containing the access_token and cloud keys. If provided, the client_id, client_secret, member_cid, and cloud options are ignored. Useful when needing to make multiple API calls to avoid rate limiting issues. |
|
The OAuth2 access token to use for authentication. |
|
The CrowdStrike cloud region to use. This can differ from the module’s cloud argument due to autodiscovery. |
|
The CrowdStrike API client ID to use. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike API secret that corresponds to the client ID. See the Falcon documentation for more information about API clients. The |
|
The CrowdStrike cloud region to use. All clouds are automatically discovered if not specified, except for the The Choices:
|
|
A description for the host group. Only used when state=present. |
|
Extended headers that are prepended to the default headers dictionary. |
|
The type of host group to create or validate.
Cannot be changed after group creation. Choices:
|
|
The action to perform with the hosts specified in hosts.
Requires hosts to be specified. Choices:
|
|
The ID of an existing host group. Can be used with state=absent for deletion by ID. If provided with state=present, the module will update the existing group. Note: Either name or host_group is required for state=absent. |
|
List of host IDs (AIDs) to add to or remove from the host group. Use with host_action to specify the operation. Only applicable for existing groups and when state=present. |
|
The CrowdStrike member CID for MSSP authentication. See the Falcon documentation for more information about API clients. The |
|
The name of the host group. Required when state=present and creating a new group. Can be used for state=absent to delete by name (supports true idempotency). Cannot be used to rename existing groups (use host_group to identify the group). |
|
The desired state of the host group.
Choices:
|
|
Custom User-Agent string to use for requests to the API. The user agent string is prepended to the default user agent string ( See RFC 7231 for more information. The |
Notes
Note
Idempotency: This module is idempotent and will only make changes when the current state differs from the desired state.
Group Types: The group type cannot be changed after creation. To change a group’s type, delete the existing group and create a new one.
Dynamic Groups: Assignment rules for dynamic groups are evaluated by CrowdStrike’s backend and may take some time to reflect membership changes.
Host Management: Adding or removing hosts only works with existing groups. Host operations are performed after group creation/update operations.
Examples
# PRIMARY WORKFLOW: Name-based Operations
- name: Create a static host group using names (recommended)
crowdstrike.falcon.host_group:
name: "Web Servers"
description: "All web server hosts in the environment"
group_type: static
- name: Create a dynamic host group with assignment rules
crowdstrike.falcon.host_group:
name: "Linux Production Hosts"
description: "All Linux hosts with production tags"
group_type: dynamic
assignment_rule: "platform_name:'Linux'+tags:'production'"
- name: Create a staticByID host group for device ID management
crowdstrike.falcon.host_group:
name: "Critical Infrastructure"
description: "Manually assigned critical infrastructure hosts"
group_type: staticByID
- name: Update an existing group using name (detects changes automatically)
crowdstrike.falcon.host_group:
name: "Web Servers"
description: "Updated description for all web server hosts"
- name: Update dynamic group assignment rule using name
crowdstrike.falcon.host_group:
name: "Linux Production Hosts"
assignment_rule: "platform_name:'Linux'+(tags:'production'+tags:'web')"
- name: Delete a host group using name (true idempotency - recommended)
crowdstrike.falcon.host_group:
name: "Web Servers"
state: absent
# TRUE IDEMPOTENCY PATTERN: Same Task Definition for Entire Lifecycle
- name: Manage host group lifecycle with identical task definition
crowdstrike.falcon.host_group:
name: "Application Servers"
description: "All application server hosts"
group_type: static
state: "{{ desired_state }}" # 'present' for create/update, 'absent' for delete
- name: Complete dynamic group lifecycle example
crowdstrike.falcon.host_group:
name: "Windows Domain Controllers"
description: "All Windows domain controller hosts"
group_type: dynamic
assignment_rule: "platform_name:'Windows'+tags:'domain-controller'"
state: "{{ lifecycle_state | default('present') }}"
# HOST MANAGEMENT: Adding and Removing Hosts from Groups
- name: Create group first, then manage hosts using returned ID
crowdstrike.falcon.host_group:
name: "Database Servers"
description: "All database server hosts"
group_type: static
register: db_group_result
- name: Add hosts to the database group
crowdstrike.falcon.host_group:
host_group: "{{ db_group_result.host_group.id }}"
hosts:
- "15dbb9d8f06b45fe9f61eb46e829d986"
- "2ae94761f78e4a6d9e2f8b5c4d1a7b3e"
host_action: add
- name: Remove specific hosts from the group
crowdstrike.falcon.host_group:
host_group: "{{ db_group_result.host_group.id }}"
hosts:
- "15dbb9d8f06b45fe9f61eb46e829d986"
host_action: remove
# DYNAMIC HOST MANAGEMENT: Using host_ids Lookup Plugin
- name: Create group and populate with Windows hosts dynamically
crowdstrike.falcon.host_group:
name: "Windows Production Servers"
description: "All Windows hosts in production environment"
group_type: static
hosts: "{{ lookup('crowdstrike.falcon.host_ids', 'platform_name:\"Windows\"+tags:\"production\"') }}"
host_action: add
# ID-BASED OPERATIONS: When Working with Existing Groups
- name: Update existing group using ID (when you have the group ID)
crowdstrike.falcon.host_group:
host_group: "a1b2c3d4e5f6789012345678901234ab"
description: "Updated description using group ID"
- name: Delete a host group using ID (legacy approach)
crowdstrike.falcon.host_group:
host_group: "a1b2c3d4e5f6789012345678901234ab"
state: absent
# ADVANCED PATTERNS: Complex Assignment Rules and Error Handling
- name: Create dynamic group with complex FQL assignment rule
crowdstrike.falcon.host_group:
name: "High-Risk Linux Servers"
description: "Linux servers requiring enhanced monitoring"
group_type: dynamic
assignment_rule: "platform_name:'Linux'+(tags:'production'+tags:'database'+!tags:'patched')"
- name: Conditional group management with error handling
crowdstrike.falcon.host_group:
name: "{{ group_name }}"
description: "{{ group_description | default('Managed by Ansible') }}"
group_type: "{{ group_type | default('static') }}"
assignment_rule: "{{ assignment_rule | default(omit) }}"
state: present
register: group_result
failed_when: false # Handle errors gracefully
- name: Verify group creation succeeded before proceeding
ansible.builtin.assert:
that:
- group_result is succeeded
- group_result.host_group.name == group_name
fail_msg: "Failed to create or update host group {{ group_name }}"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Results of host management actions (add/remove hosts). Returned: when host_action is performed |
|
List of host IDs that failed to be added or removed. Returned: when some hosts fail |
|
The error code returned by the API. Returned: success Sample: |
|
The host ID that failed. Returned: success Sample: |
|
The error message returned by the API. Returned: success Sample: |
|
List of host IDs that were successfully added or removed. Returned: success Sample: |
|
Information about the host group that was created, updated, or managed. Returned: when state=present |
|
The assignment rule for dynamic groups. Returned: when group_type=dynamic Sample: |
|
The user who created the host group. Returned: success Sample: |
|
The timestamp when the host group was created. Returned: success Sample: |
|
The description of the host group. Returned: success Sample: |
|
The type of host group (static, dynamic, or staticByID). Returned: success Sample: |
|
The unique identifier of the host group. Returned: success Sample: |
|
The user who last modified the host group. Returned: success Sample: |
|
The timestamp when the host group was last modified. Returned: success Sample: |
|
The name of the host group. Returned: success Sample: |