You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Pull Request Description
## Summary
[Provide a brief description of the changes in this PR]
### Issue Reference
Fixes #[Issue Number]
### Motivation and Context
- Why is this change needed?
- What problem does it solve?
- If it fixes an open issue, please link to the issue here
### Dependencies
- List any dependencies that are required for this change
- Include any configuration changes needed
- Note any version updates required
## Type of Change
Please mark the relevant option with an `x`:
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] 📝 Documentation update (Wiki/README/Code comments)
- [ ] ♻️ Refactor (code improvement without functional changes)
- [ ] 🎨 Style update (formatting, renaming)
- [ ] 🔧 Configuration change
- [ ] 📦 Dependency update
## Testing
- [ ] I have added unit tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have tested this code in the following browsers/environments:
[list environments]
## Quality Checklist
- [ ] I have reviewed my own code before requesting review
- [ ] I have verified there are no other open Pull Requests for the same
update/change
- [ ] All CI/CD pipelines pass without errors or warnings
- [ ] My code follows the established style guidelines of this project
- [ ] I have added necessary documentation (if appropriate)
- [ ] I have commented my code, particularly in complex areas
- [ ] I have made corresponding changes to the README and other relevant
documentation
- [ ] My changes generate no new warnings
- [ ] I have performed a self-review of my own code
- [ ] My code is properly formatted according to project standards
## Screenshots/Recordings (if appropriate)
[Add screenshots or recordings that demonstrate the changes]
## Additional Notes
[Add any additional information that might be helpful for reviewers]
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,9 +67,9 @@ Please refer to the [Getting Started](https://registry.terraform.io/providers/de
67
67
-**Microsoft Graph API Support**: Integrates with both v1.0 and beta Microsoft Graph API endpoint sets, to support both generally available and preview features.
68
68
-**Microsoft Graph SDK Adoption**: The provider leverages the Microsoft Graph API through the Kiota-generated graphSDKs, allowing for a strongly typed development experience.
69
69
70
-
## Project Status
70
+
## Provider Comparison
71
71
72
-
For information about this project's status in relation to the official terraform-provider-msgraph provider, see the [Project Status](./docs/development/project_status.md) documentation.
72
+
For information and a comparison between this provider in relation to the msft official terraform-provider-msgraph provider, see the [Provider Comparison](./docs/development/provider_comparison.md) documentation.
# Project Status in light of terraform-provider-msgraph
1
+
# Provider Comparison in light of terraform-provider-msgraph
2
2
3
-
In July 2025 microsoft released the [terraform-provider-msgraph](https://github.com/hashicorp/terraform-provider-msgraph) partner provider. This provider is developed by Microsoft and is the official provider for Microsoft Graph API. However there are some distinct differences between the two projects and the approaches taken for interacting with Microsoft M365.
3
+
In July 2025 microsoft released the [terraform-provider-msgraph](https://github.com/hashicorp/terraform-provider-msgraph) partner provider. This provider is developed by Microsoft and is the official provider for Microsoft Graph API. When choosing between the two providers, it's important to consider the scope and approach of each provider, there are some distinct differences between the two providers and the approaches taken for interacting with Microsoft M365.
4
4
5
5
## Scope
6
6
@@ -23,39 +23,118 @@ As such the scope is broader than the terraform-provider-msgraph provider.
23
23
24
24
## API Interactions and Developer Experience
25
25
26
-
The fundamental difference between these providers lies in their approach to API interactions and the level of abstraction provided to users.
27
-
28
-
### terraform-provider-msgraph Approach
29
-
30
-
The terraform-provider-msgraph provider is a **thin wrapper** around the Microsoft Graph API. It provides four generic resource types:
31
-
32
-
-`msgraph_resource` - Generic resource for any Graph API endpoint
33
-
-`msgraph_resource_action` - For performing actions on resources
34
-
-`msgraph_resource_collection` - For managing reference collections
35
-
-`msgraph_update_resource` - For updating subset of properties
36
-
37
-
**Users must:**
38
-
- Understand Graph API endpoint structures and request/response schemas
39
-
- Manually construct request bodies using the exact Graph API syntax
40
-
- Orchestrate multiple API calls across different resources for complex operations
41
-
- Handle state management and consistency issues manually
42
-
- Understand Graph API-specific concepts like OData query parameters, reference collections, etc.
43
-
44
-
### This Provider's Approach
45
-
46
-
This provider uses the Kiota-generated GraphSDKs built from Microsoft's schema to interact with the Graph API, but provides **significant abstraction** above that:
47
-
48
-
**Single Resource Abstractions:**
49
-
- Each resource type (e.g., `microsoft365_graph_beta_group_license_assignment`) represents a complete business operation
50
-
- Users work with intuitive, strongly-typed configuration schemas
51
-
- Complex API orchestration is handled automatically behind the scenes
52
-
- Built-in retry logic, error handling, and state management
53
-
54
-
**Automatic API Call Chaining:**
55
-
- Complex resources that require multiple API calls are handled transparently
56
-
- Create/Read/Update/Delete operations automatically perform all necessary API calls
57
-
- State synchronization with proper retry logic for eventual consistency
58
-
- Users don't need to understand the underlying API complexity
26
+
The fundamental difference between these providers lies in their approach to API interactions and the level of abstraction provided to users. This section provides a detailed analysis of how each provider handles the complexity of the Microsoft Graph API and the resulting impact on developer productivity.
27
+
28
+
### Understanding Microsoft Graph API Complexity
29
+
30
+
Before comparing the providers, it's important to understand the inherent complexity of the Microsoft Graph API that both providers must handle:
31
+
32
+
**API Characteristics:**
33
+
-**Multi-step Operations**: Many business operations require multiple sequential API calls across different endpoints
34
+
-**Eventual Consistency**: Microsoft Graph uses eventual consistency, meaning writes may not be immediately visible in reads
35
+
-**Complex Request Bodies**: Many operations require nested JSON structures with specific OData type annotations
36
+
-**State Dependencies**: Resource creation often requires reading state from multiple related endpoints
37
+
-**Error Handling Complexity**: Different endpoints have different retry requirements and error response formats
38
+
-**Assignment Management**: Device management resources require separate assignment API calls to be functional
39
+
40
+
**Real-world Example - Windows Update Ring:**
41
+
Creating a functional Windows Update Ring involves:
42
+
1. POST to `/deviceManagement/deviceConfigurations` (create policy)
43
+
2. POST to `/deviceManagement/deviceConfigurations/{id}/assign` (assign to groups)
44
+
3. GET with `$expand=assignments` (verify complete state)
45
+
4. Handle eventual consistency between configuration and assignment APIs
46
+
5. Manage complex assignment target structures with filter relationships
47
+
48
+
This complexity exists regardless of which provider you use - the question is how each provider handles it.
49
+
50
+
### terraform-provider-msgraph Approach: Direct API Exposure
51
+
52
+
The terraform-provider-msgraph provider is a **thin wrapper** around the Microsoft Graph API that directly exposes the API's complexity to users. This approach prioritizes flexibility and API completeness over developer experience.
53
+
54
+
#### Resource Architecture
55
+
The provider offers four generic resource types that map directly to HTTP operations:
56
+
57
+
-**`msgraph_resource`** - Generic resource for any Graph API endpoint (POST/GET/PATCH/DELETE)
58
+
-**`msgraph_resource_action`** - For performing actions on resources (POST actions like assign, send, etc.)
59
+
-**`msgraph_resource_collection`** - For managing reference collections ($ref endpoints)
60
+
-**`msgraph_update_resource`** - For updating subset of properties (PATCH operations)
61
+
62
+
#### Developer Requirements
63
+
**Graph API Expertise Required:**
64
+
-**Endpoint Knowledge**: Deep understanding of Graph API URL structures (`/deviceManagement/deviceConfigurations`, `/groups/{id}/assignLicense`, etc.)
-**Dependency Management**: Manual `depends_on` declarations to ensure proper operation sequencing
73
+
-**State Management**: Separate data sources needed to read complete resource state
74
+
-**Error Handling**: No built-in retry logic for Graph API-specific issues (throttling, eventual consistency)
75
+
-**Lifecycle Management**: Manual handling of create/update/delete operation differences
76
+
77
+
#### Development Workflow Impact
78
+
**Configuration Complexity:**
79
+
- Users must translate business requirements into multiple low-level API operations
80
+
- Each business operation may require 3-5 separate Terraform resources
81
+
- Configuration files become verbose and API-centric rather than business-focused
82
+
- Changes require understanding the impact across multiple interdependent resources
83
+
84
+
**Debugging and Maintenance:**
85
+
- Issues require deep Graph API troubleshooting knowledge
86
+
- Error messages are raw HTTP/JSON responses without business context
87
+
- Updates require understanding how each API endpoint handles partial modifications
88
+
- Testing requires knowledge of Graph API test patterns and mock strategies
89
+
90
+
### This Provider's Approach: Business-Focused Abstraction
91
+
92
+
This provider uses the Kiota-generated GraphSDKs built from Microsoft's schema to interact with the Graph API, but provides **significant abstraction** that shields users from API complexity while maintaining full functionality.
93
+
94
+
#### Resource Architecture
95
+
The provider offers purpose-built resources that represent complete business operations:
96
+
97
+
-**Domain-Specific Resources**: Each resource type (e.g., `microsoft365_graph_beta_device_management_windows_update_ring`) represents a complete business workflow
98
+
-**Strongly-Typed Schemas**: Terraform configuration uses intuitive field names and validation rather than raw JSON
99
+
-**Embedded Relationships**: Related operations (assignments, settings, dependencies) are managed within single resources
100
+
-**Business Logic Integration**: Resources understand the business context and handle complex workflows automatically
101
+
102
+
#### Developer Experience Benefits
103
+
**Business Domain Focus:**
104
+
-**Declarative Configuration**: Users describe desired end-state rather than API operation sequences
105
+
-**Intuitive Field Names**: Configuration uses business-friendly terminology (`allow_windows11_upgrade` vs `allowWindows11Upgrade`)
106
+
-**Built-in Validation**: Schema validation catches configuration errors before API calls
107
+
-**Contextual Documentation**: Each field includes business context and impact descriptions
108
+
-**IDE Support**: Strongly-typed schemas enable autocomplete, validation, and documentation in IDEs
109
+
110
+
**Automatic Complexity Management:**
111
+
-**API Call Chaining**: Single resource operations automatically trigger multiple coordinated API calls
112
+
-**State Synchronization**: Built-in retry logic handles eventual consistency across all related endpoints
113
+
-**Error Translation**: Raw Graph API errors are translated into actionable business context
114
+
-**Lifecycle Optimization**: Create/update/delete operations use the most efficient API patterns automatically
115
+
-**Dependency Resolution**: Resources automatically handle prerequisite operations and timing
116
+
117
+
#### Technical Implementation
118
+
**Under the Hood Automation:**
119
+
-**Multi-Endpoint Coordination**: Single Terraform operations may trigger anything from 1-10 Graph API calls across different endpoints
120
+
-**Eventual Consistency Handling**: Built-in wait/retry patterns for Microsoft's asynchronous operations
121
+
-**Assignment Management**: Automatic construction of complex assignment target objects with proper type annotations
122
+
-**State Reconciliation**: Resources automatically detect and correct configuration drift
123
+
-**Error Recovery**: Intelligent retry logic with exponential backoff for transient API issues
124
+
125
+
**Development Workflow Impact:**
126
+
**Configuration Simplicity:**
127
+
- Business requirements map directly to single resource declarations
128
+
- Changes are made at the business logic level rather than API operation level
129
+
- Configuration files are concise and focused on business outcomes
130
+
- Testing focuses on business functionality rather than API mechanics
131
+
132
+
**Operational Benefits:**
133
+
-**Faster Development**: Developers work at business abstraction level
134
+
-**Reduced Errors**: API complexity is encapsulated and tested within the provider
135
+
-**Easier Maintenance**: admin focused changes don't require API expertise
136
+
-**Better Debugging**: Error messages provide business context and suggested resolutions
137
+
-**Consistent Patterns**: All resources follow similar patterns regardless of underlying API complexity
0 commit comments