Feature/add commit all action

[gmcarneiro-palo]

Add panos_commit_all action for Panorama push to devices

Overview

This PR implements a new Terraform action panos_commit_all that enables pushing committed configuration from Panorama to managed device groups. This complements the existing panos_commit action to provide a complete commit-and-push workflow for Panorama users.

Motivation

Currently, the provider has a panos_commit action that commits pending changes to Panorama, but there's no way to push those committed changes to managed devices. Users need to manually push via the Panorama UI or use external scripts, breaking the infrastructure-as-code workflow.

This action fills that gap by providing a native Terraform way to perform the "Push to Devices" operation.

What's New

Core Features

1. Automatic Device Group Discovery

   • Automatically detects all device groups in Panorama
   • Uses operational command (show dg-hierarchy) with config API fallback
   • Supports multiple XML response formats for cross-version compatibility

2. Selective Device Group Targeting

   • Optional device_groups parameter to push to specific groups only
   • Useful for staged rollouts and testing
   • Example: Push to production only, skip staging

3. Clear Workflow Separation

   • Explicitly separates "commit" from "push" operations
   • Mirrors Panorama UI workflow: Commit → Push to Devices
   • Prevents confusion about what the action does

Implementation Details

Files Added:

• internal/provider/commit_all.go - Action framework and schema
• internal/provider/commit_all_crud.go - Core API implementation
• docs/actions/commit_all.md - Comprehensive documentation (505 lines)
• examples/COMMIT_ALL_EXAMPLES.md - Usage guide and comparisons

Files Modified:

• internal/provider/provider.go - Register new action

Key Technical Decisions:

• Uses PAN-OS XML API type=commit&action=all with <commit-all><shared-policy> structure
• Implements job polling to wait for completion (2-second intervals)
• Provides detailed error messages for common issues
• No state tracking (actions are stateless by design)

Usage Examples

Basic Usage

provider "panos" {
  hostname = "panorama.example.com"
  api_key  = var.panos_api_key
}

resource "panos_security_policy" "example" {
  location = {
    device_group = { name = "Production" }
  }

  rules = [{
    name                  = "Allow-Web"
    source_zones          = ["trust"]
    destination_zones     = ["untrust"]
    applications          = ["web-browsing"]
    action                = "allow"
  }]
}

# Step 1: Commit changes to Panorama
action "panos_commit" "commit_to_panorama" {}

# Step 2: Push to all device groups
action "panos_commit_all" "push_to_all" {}

# Step 3: Or push to specific device groups only
action "panos_commit_all" "push_to_production" {
  config {
    device_groups = ["Production", "DMZ"]
  }
}

Workflow

# 1. Apply resources (creates pending changes)
terraform apply

# 2. Commit changes to Panorama
terraform action -invoke commit_to_panorama

# 3. Push to devices
terraform action invoke push_to_all
# OR push to specific groups
terraform action invoke push_to_production

Automated Workflow with Lifecycle Hooks

resource "panos_security_policy" "auto_deploy" {
  # ... configuration ...

  lifecycle {
    action_trigger {
      events  = [after_create, after_update]
      actions = [
        action.panos_commit.commit_to_panorama,
        action.panos_commit_all.push_to_production
      ]
    }
  }
}

Configuration Reference

device_groups (Optional)

- Type: List of strings
- Default: All device groups in Panorama
- Example: ["Production", "DMZ", "Branch-Offices"]

When specified, only pushes configuration to the listed device groups. When omitted, pushes to all device groups.

Testing

Tested on:
- Panorama version: 11.2.6
- Terraform: 1.14.3
- Provider: 2.0.x (local build)

Test scenarios:
- ✅ Push to all device groups (auto-discovery)
- ✅ Push to specific device groups via device_groups parameter
- ✅ Push to multiple device groups
- ✅ Error handling when no device groups exist
- ✅ Job polling and completion
- ✅ Lifecycle action_trigger integration

Documentation

Comprehensive Documentation Included

- Action Reference (docs/actions/commit_all.md):
  - Overview and workflow explanation
  - Configuration reference
  - 10+ usage examples
  - Comparison with panos_commit
  - CI/CD integration examples
  - Troubleshooting guide
- Examples Guide (examples/COMMIT_ALL_EXAMPLES.md):
  - Comparison of Terraform Actions vs curl methods
  - Quick start guide
  - Best practices
  - Security considerations
  - Example Terraform configurations for older versions

## Breaking Changes

None. This is a new feature with no impact on existing functionality.

## Backward Compatibility

- ✅ Fully backward compatible
- ✅ Does not modify existing actions or resources
- ✅ Optional parameter (device_groups) defaults to safe behavior
- ✅ Works alongside existing panos_commit action

## Requirements

- Terraform 1.14+ (for Actions support)
- Panorama (not standalone firewalls)
- At least one device group configured in Panorama

## Migration Notes

For users currently using curl scripts or null_resource for commit-all:
1. Replace curl-based scripts with this action
2. Follow the documented workflow: commit → push
3. See examples/COMMIT_ALL_EXAMPLES.md for migration examples


## Checklist

[x] Implementation complete
[x] Documentation written
[x] Examples provided
[x] Manual testing performed
[x] No breaking changes
[x] Backward compatible


---
Note: This action requires Terraform 1.14+ which introduced Actions support.