Rename `powerplatform_solution` to `powerplatform_soultion_import`

[mawasile]

In order to clean up resource naming with new resource #1117 existing resource and data source will be renamed.

[AdamCoulterOz]

@mawasile

solution_import is a bad resource name because it describes the implementation mechanism, not the target state. Terraform resources should model the thing being managed. For the managed case, the target state is not “run an import”; it is “this solution package/version is installed in this environment”.

There are two distinct solution models here:

• Managed: closed artifact, fixed version, reproducible package deployment.
• Unmanaged: open solution container, mutable by design, where internal drift is expected.

Those are different resource models. But that does not imply the managed one should be named after the imperative API call used to realize it.

If we want two resources, the coherent names are powerplatform_managed_solution and powerplatform_unmanaged_solution. Alternatively, if the current contract is already entrenched, keep powerplatform_solution for the package-based/installable model and add a distinct unmanaged resource.

The proposed rename is conceptually wrong, not just disruptive as a breaking change. It turns a stateful resource into an action label, and that is bad Terraform design even if there were no existing users.

[mawasile]

I understand your point that you are making. The issue with powerplatform_managed_solution and powerplatform_unmanaged_solution is that, you are correct and manage do represent "finished thing" and unmanage "work in progress" many people do not follow those best practices and those have such separation of concerns in their mental maps. Then we will have two solution resources that do completely different things. So if I want to import an unamange solution for some reason I have to use `powerplatform_manage_solution" resource?

If those resources are doing different operations, (import vs record CRUD) they have to indicate it in their name to differentiate. When powerplatform_solution would be left as it is (which is a way better scenario) then new resource should be clear that its managing record and adding "unmanage" in name doesn't feel for me clear enough. Maybe powerplatform_solution_record?

[AdamCoulterOz]

Thanks @mawasile, I appreciate the discussion on this.

The issue with powerplatform_managed_solution and powerplatform_unmanaged_solution is that, you are correct and manage do represent "finished thing" and unmanaged "work in progress" many people do not follow those best practices and those have such separation of concerns in their mental maps. Then we will have two solution resources that do completely different things.

I wouldn't frame this as best practice, it reflects how the platform defines and uses these concepts, which helps keep the provider intuitive and predictable.

• unmanaged → mutable container for development
• managed → versioned, installable artefact

Terraform is typically used by platform / pipeline engineers, where that distinction is already important, so aligning the resource model to those concepts should reduce confusion rather than introduce it.

So if I want to import an unmanaged solution for some reason I have to use powerplatform_managed_solution resource?

I think this is where the Terraform model matters more than the API capability.

Terraform resources are most effective when they converge toward a stable desired state. Managed solutions fit that model reasonably well (versioned artefact, reproducible install).

Unmanaged solutions imported from a zip don’t really converge in the same way — they immediately diverge as soon as changes are made in the environment.

Because of that, importing unmanaged solutions feels closer to a bootstrap or development workflow step rather than a stable, long-lived Terraform-managed state. Tools like the PAC CLI or the portal are a better fit for that scenario.

That’s why I’d lean toward scoping a powerplatform_managed_solution resource to managed solutions only. If people ask for a way to import unmanaged solutions later, we can evaluate the use cases and decide if and how to support it.

If those resources are doing different operations, (import vs record CRUD) they have to indicate it in their name to differentiate. When powerplatform_solution would be left as it is (which is a way better scenario) then new resource should be clear that its managing record and adding "unmanaged" in name doesn't feel for me clear enough. Maybe powerplatform_solution_record?

I think the key distinction is the type of state being represented rather than the operation used to achieve it.

• unmanaged_solution → open container with fixed identity
• managed_solution → installed versioned artefact

Even if one is realised via import under the hood, naming based on the resulting state (e.g. managed_solution) is clearer than naming based on the mechanism (such as import or record). It also aligns with how these concepts are presented in the Power Platform UI and documentation.

Names like solution_record or solution_import expose implementation details rather than intent, which makes the provider harder to reason about over time.

Suggested Path Forward

A possible path forward could be:

1. Leave the existing powerplatform_solution resource as-is, but mark it as deprecated, with clear guidance in the documentation on migration paths.
2. Introduce two new resources with clear and scoped naming:
   • powerplatform_managed_solution
   • powerplatform_unmanaged_solution
3. Remove the deprecated powerplatform_solution resource in a future major release (e.g. 6–12 months), after giving users sufficient time to migrate.

[AdamCoulterOz]

@mawasile - I spent some time thinking about what a managed_solution resource could look like, because we have a chance to tighten it a lot more compared to the current solution resource. I documented it here: #1143