Updates to documentation (#511)

* Refactor provider configuration and remove deprecated release notes templates * Refactor provider configuration and remove deprecated release notes templates --------- Co-authored-by: github-actions[bot] <[email protected]> Co-authored-by: mawasile <[email protected]>
microsoft · Oct 29, 2024 · 754f7a0 · 754f7a0
1 parent ba421a2
commit 754f7a0
Show file tree

Hide file tree

Showing 15 changed files with 278 additions and 247 deletions.
diff --git a/.changes/3.2.0.md b/.changes/3.2.0.md
@@ -0,0 +1,14 @@
+## 3.2.0 - 2024-10-29
+
+### ✨ Added
+
+* [#423](https://github.com/microsoft/terraform-provider-power-platform/issues/423) adding powerplatform_environment_group_rule_set. **Currently not supported when using service principal authentication**
+
+### 🪲 Fixed
+
+* [#499](https://github.com/microsoft/terraform-provider-power-platform/issues/499) Fixing issue that dlp policies does not apply all connectors and require reapply
+* [#502](https://github.com/microsoft/terraform-provider-power-platform/issues/502) powerplatform_environment fixed error during environment update when a custom domain is set
+
+### 📚 Documentation
+
+* [#414](https://github.com/microsoft/terraform-provider-power-platform/issues/414) Improved documentation of `data_record` with examples for app users, business units, teams, and roles
diff --git a/.changes/unreleased/added-20241022-103532.yaml b/.changes/unreleased/added-20241022-103532.yaml
diff --git a/.changes/unreleased/documentation-20241010-194509.yaml b/.changes/unreleased/documentation-20241010-194509.yaml
diff --git a/.changes/unreleased/fixed-20241023-150045.yaml b/.changes/unreleased/fixed-20241023-150045.yaml
diff --git a/.changes/unreleased/fixed-20241024-142026.yaml b/.changes/unreleased/fixed-20241024-142026.yaml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,21 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 3.2.0 - 2024-10-29
+
+### ✨ Added
+
+* [#423](https://github.com/microsoft/terraform-provider-power-platform/issues/423) adding powerplatform_environment_group_rule_set. **Currently not supported when using service principal authentication**
+
+### 🪲 Fixed
+
+* [#499](https://github.com/microsoft/terraform-provider-power-platform/issues/499) Fixing issue that dlp policies does not apply all connectors and require reapply
+* [#502](https://github.com/microsoft/terraform-provider-power-platform/issues/502) powerplatform_environment fixed error during environment update when a custom domain is set
+
+### 📚 Documentation
+
+* [#414](https://github.com/microsoft/terraform-provider-power-platform/issues/414) Improved documentation of `data_record` with examples for app users, business units, teams, and roles
+
 ## 3.1.0 - 2024-10-02
 
 ### ✨ Added

diff --git a/docs/guides/app_registration.md b/docs/guides/app_registration.md
@@ -7,7 +7,11 @@ description: |-
 
 # Creating an App Registration to use the Power Platform Provider
 
-You can follow this [guide](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app#register-an-application) to create an app registration.
+The following steps will guide you through the process of manually creating an App Registration in Azure Active Directory to use the Power Platform Provider, but if you would like a script to run, see the [bootstrap scripts in the Power Platform QuickStarts](https://github.com/microsoft/power-platform-terraform-quickstarts/blob/main/bootstrap/tenant-configuration/main.tf)
+
+## Register an Application
+
+[The basics of how to create an app registration in Entra](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app#register-an-application) are covered in Entra documentation.  Familiarize yourself with the process and then follow the steps below to create an app registration for the Power Platform Provider.
 
 ## API Permissions
 
@@ -23,87 +27,40 @@ Following API permissions are required to use the Terraform Power Platform provi
   - Licensing.Allocations.ReadWrite
   - Licensing.BillingPolicies.Read
   - Licensing.BillingPolicies.ReadWrite
-  - Licensing.IsvContracts.Read
-  - Licensing.IsvContracts.ReadWrite
+  - PowerApps.Apps.Play
+  - PowerApps.Apps.Read
+  - EnvironmentManagement.Environments.Read
+  - EnvironmentManagement.Groups.Read
+  - EnvironmentManagement.Groups.ReadWrite
+  - EnvironmentManagement.Settings.Read
+  - EnvironmentManagement.Settings.ReadWrite
 
 - PowerApps Service
   - User
 
-Or you can add them directly into your App Registration manifest:
-
-```json
-"requiredResourceAccess": [
-  {
-   "resourceAppId": "8578e004-a5c6-46e7-913e-12f58912df43",
-   "resourceAccess": [
-    {
-     "id": "61bfce59-bddc-493f-b20c-32af5e904b83",
-     "type": "Scope"
-    },
-    {
-     "id": "9dafb9c1-c236-48b1-b142-20dcaab58675",
-     "type": "Scope"
-    },
-    {
-     "id": "048eb363-c1da-41d5-9edf-423b605ff23e",
-     "type": "Scope"
-    },
-    {
-     "id": "73cf5c38-5257-4f28-8bbb-f78acf3290a4",
-     "type": "Scope"
-    },
-    {
-     "id": "25223ba4-e810-4f08-9803-cde4b2057a13",
-     "type": "Scope"
-    },
-    {
-     "id": "a8f422ae-8922-45d4-a8f1-275a6bd43077",
-     "type": "Scope"
-    },
-    {
-     "id": "adef0bc0-3a5b-457a-834c-cabd82f0a6d2",
-     "type": "Scope"
-    },
-    {
-     "id": "3f4998a4-cbb8-4e1e-9ea0-fd7fc110bb74",
-     "type": "Scope"
-    }
-   ]
-  },
-  {
-   "resourceAppId": "475226c6-020e-4fb2-8a90-7a972cbfc1d4",
-   "resourceAccess": [
-    {
-     "id": "0eb56b90-a7b5-43b5-9402-8137a8083e90",
-     "type": "Scope"
-    }
-   ]
-  },
-  {
-   "resourceAppId": "00000007-0000-0000-c000-000000000000",
-   "resourceAccess": [
-    {
-     "id": "78ce3f0f-a1ce-49c2-8cde-64b5c0896db4",
-     "type": "Scope"
-    }
-   ]
-  }
- ]
+!> Note: If you don't see Power Platform API showing up in the list when searching by GUID, it's possible that you still have access to it but the visibility isn't refreshed. To force a refresh run the below PowerShell script:
+
+```powershell
+#Install the Microsoft Entra the module
+Install-Module AzureAD
+
+Connect-AzureAD
+New-AzureADServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43 -DisplayName "Power Platform API"
 ```
 
->! Note: The `resourceAppId` values are the application IDs of the services in the Public cloud.  If you are using a sovereign cloud, you will need to use the appropriate application IDs for those services.
+!> Note: The `resourceAppId` values are the application IDs of the services in the Public cloud.  If you are [using a sovereign cloud](./nonpublic_clouds.md) the IDs will be different and you will need to use the appropriate application IDs for those services.
 
 ## Expose API
 
-In "Expose API" menu of your App Registration, you need to define your application ID URI:
+In "Expose an API" menu of your App Registration, you need to define your application ID URI:
 
 - Application ID URI: `api://<client_id>`, for example:
 
 ```plaintext
 api://powerplatform_provider_terraform
 ```
 
-- Add required scope:
+### Define scopes
 
 1. Scope Name: `access`
 1. Who can consent: `Admins and users`
@@ -113,39 +70,9 @@ api://powerplatform_provider_terraform
 1. User consent description: `Allows connection to backend services of Power Platform Terraform Provider`
 1. State: `Enabled`
 
-Or you can add them directly into your App Registration manifest:
-
-```json
- "oauth2Permissions": [
-  {
-   "adminConsentDescription": "Allows connection to backend services of Power Platform Terraform Provider",
-   "adminConsentDisplayName": "Work with Power Platform Terraform Provider",
-   "id": "2aedce72-ddc7-431d-920c-a321297ffdc2",
-   "isEnabled": true,
-   "lang": null,
-   "origin": "Application",
-   "type": "User",
-   "userConsentDescription": "Allows connection to backend services of Power Platform Terraform Provider",
-   "userConsentDisplayName": "Work with Power Platform Terraform Provider",
-   "value": "access"
-  }
- ],
-```
+### Authorizing client applications
 
-- You will finially need to preuthorize Azure CLI to access your API by adding client application `04b07795-8ddb-461a-bbee-02f9e1bf7b46`
-
-Or you can add them directly into your App Registration manifest:
-
-```json 
-"preAuthorizedApplications": [
-  {
-   "appId": "04b07795-8ddb-461a-bbee-02f9e1bf7b46",
-   "permissionIds": [
-    "2aedce72-ddc7-431d-920c-a321297ffdc2"
-   ]
-  }
- ]
-```
+You will finially need to preuthorize Azure CLI to access your API by adding client application `04b07795-8ddb-461a-bbee-02f9e1bf7b46`
 
 ## Usage
 
@@ -154,3 +81,5 @@ After above steps you should be able to authenticate using Azure CLI:
 ```bash
 az login --scope api://powerplatform_provider_terraform/.default
 ```
+
+If your tenant doesn't have any Azure subscriptions, you can use the `--allow-no-subscriptions` flag to login. If you are working in a web-based devcontainer and you need more control over the interactive login process you can use the `--use-device-code` flag.
diff --git a/docs/guides/release_notes.md b/docs/guides/release_notes.md
diff --git a/docs/index.md b/docs/index.md
@@ -23,7 +23,7 @@ terraform {
   required_providers {
     powerplatform = {
       source  = "microsoft/power-platform"
-      version = "~> 1.0" # Replace with the latest version
+      version = "~> 3.1" # Replace with the latest version
     }
   }
 }
@@ -176,7 +176,7 @@ In addition to the authentication options, the following options are also suppor
 
 | Name | Description | Default Value |
 |------|-------------|---------------|
-| `telemetry_optout` | Opting out of telemetry will remove the hostheader from the requests made to the Power Platform service.  There is no other telemetry data collected by the provider.  This may affect the ability to identify and troubleshoot issues with the provider. | `false` |
+| `telemetry_optout` | Opting out of telemetry will remove the hostheader and session id headers from the requests made to the Power Platform service.  There is no other telemetry data collected by the provider.  This may affect the ability to identify and troubleshoot issues with the provider. | `false` |
 
 ## Resources and Data Sources
 
@@ -188,6 +188,11 @@ Use the navigation to the left to read about the available resources and data so
 
 More detailed examples can be found in the [Power Platform Terraform Quickstarts](https://github.com/microsoft/power-platform-terraform-quickstarts) repo.  This repo contains a number of examples for using the Power Platform provider to manage environments and other resources within Power Platform along with Azure and Entra.
 
+## Releases
+
+A full list of released versions of the Power Platform Terraform Provider can be found [here](https://github.com/microsoft/terraform-provider-power-platform/releases).  Starting from v3.0.0, a summary of the changes to the provider in each release are documented the [CHANGELOG.md file in the GitHub repository](https://github.com/microsoft/terraform-provider-power-platform/blob/main/CHANGELOG.md). This provider follows Semantic Versioning for releases. The provider version is incremented based on the type of changes included in the release.
+
+
 ## Contributing
 
 Contributions to this provider are always welcome! Please see the [Contribution Guidelines](https://github.com/microsoft/terraform-provider-power-platform/)