host_group

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.

Added in version 4.10.0

Parameters

Parameter	Type	Required	Default	Description
assignment_rule	str	No		FQL (Falcon Query Language) filter for dynamic group membership. Required when I(group_type=dynamic). Ignored for static and staticByID groups. “Examples: C(platform_name:‘Linux’), C(tags:‘production’+os_version:‘Server’).”
description	str	No		A description for the host group. Only used when I(state=present).
group_type	str	No	static	The type of host group to create or validate. C(static) groups contain manually assigned hosts. C(dynamic) groups automatically include hosts based on assignment rules. C(staticByID) groups contain hosts assigned by their device IDs. Cannot be changed after group creation.
host_action	str	No		The action to perform with the hosts specified in I(hosts). C(add) adds hosts to the group. C(remove) removes hosts from the group. Requires I(hosts) to be specified.
host_group	str	No		The ID of an existing host group. Can be used with I(state=absent) for deletion by ID. If provided with I(state=present), the module will update the existing group. “B(Note): Either I(name) or I(host_group) is required for I(state=absent).”
hosts	list	No		List of host IDs (AIDs) to add to or remove from the host group. Use with I(host_action) to specify the operation. Only applicable for existing groups and when I(state=present).
name	str	No		The name of the host group. Required when I(state=present) and creating a new group. Can be used for I(state=absent) to delete by name (supports true idempotency). Cannot be used to rename existing groups (use I(host_group) to identify the group).
state	str	No	present	The desired state of the host group. C(present) ensures the host group exists with the specified configuration. C(absent) ensures the host group does not exist.

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

Key	Type	Description
host_group		-
action_results		-