feat(permission_set_saas): create resource, datasource, example, docs

[ErmanShani]

[SLK-88696]

This change implements comprehensive support for RBAC v3 Permission Sets in Aqua SaaS environments through:

Core Components:

• New resource aquasec_permission_set_saas with full CRUD capabilities
• New data source aquasec_permissions_sets_saas for querying permission sets
• Client package implementing Permission Sets API operations
• Integration with RBAC v3 API endpoints

Client Package Changes:

• Added saasUrl constant for SaaS environment API endpoints
• New validateSaasEnv helper function to enforce SaaS-only operations:

• Validates operations against clientType (Saas/SaasDev)
• Returns descriptive errors for non-SaaS environments
• Used across all SaaS permission set operations

Resource Implementation Details:

• Configurable attributes:

• name (required, forces new resource)
• description (optional)
• ui_access (optional, defaults to true)
• is_super (optional, defaults to false)
• actions (optional list of allowed actions)

• Import functionality for existing permission sets
• State management with proper ID handling
• External modification detection and reconciliation
• Proper cleanup on resource deletion

Data Source Implementation:

• Lists all available permission sets
• Supports filtering by name and ui_access
• Returns full permission set details including actions
• Random ID generation for empty result sets

API Client Layer:

• Complete CRUD operation support
• Rate limiting implementation
• Proper error handling and status code validation
• Request authentication via Bearer tokens
• Validation for SaaS environment compatibility

Testing Coverage:

• Unit tests for resource CRUD operations
• Data source retrieval tests
• Error handling scenarios:

• Invalid configurations
• API failures
• External modifications
• Missing resources
• Permission validation

• Import/export functionality verification
• Edge cases for name lengths and action lists
• Test coverage exceeding 80%

Migration Support:

• Warning message for legacy resource users
• Documentation for migration path
• Backwards compatibility considerations
• Example configurations provided

Documentation:

• Resource and data source usage examples
• Attribute descriptions and constraints
• Import/export instructions
• Migration guide from legacy resource
• API endpoint references

This implementation provides:

1. Complete coverage of SaaS platform permissions beyond workload protection
2. Cleaner API interface through RBAC v3
3. Improved validation and error handling
4. Comprehensive testing coverage
5. Clear migration path from legacy implementations

Breaking Changes:

• SaaS customers should migrate from aquasec_permissions_sets to aquasec_permission_set_saas
• Legacy resource will display warning message for SaaS environments

Tested in SaaS environment with various permission configurations and external modification scenarios.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Shani Erman seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}