added pre docs

docs/index.md

@@ -228,6 +228,52 @@ resource "grafana_oncall_escalation" "example_notify_step" {
 
 ### Managing Cloud Provider
 
+Before using the cloud provider, you need to create an access policy token on the Grafana Cloud Portal. This token is used to authenticate the provider to Grafana's Cloud Provider API.
+[These docs](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/authorize-services/#create-an-access-policy-for-a-stack) will guide you on how to create 
+an access policy. The required permissions, or scopes, are `integration-management:read`, `integration-management:write` and `stacks:read`.
+
+Also, by default the Access Policies UI will not show those scopes, to find name you need to use the `Add Scope` textbox, as shown in the following image:
+
+<img src="https://grafana.com/media/docs/grafana-cloud/aws/cloud-provider-terraform-access-policy-creation.png" width="700"/>
+
+1. Use the `Add Scope` textbox (1) to search for the permissions you need to add to the access policy.
+1. Make sure that you configure the three required scopes. Once done, you'll see the selected scopes as in (2).
+
+Having created an Access Policy, you can now create a token that will be used to authenticate the provider to the Cloud Provider API. You can do so just after creating the access policy, following
+the in-screen instructions, of following [this guide](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/authorize-services/#create-one-or-more-access-policy-tokens).
+
+Having created the token, we can find the correct Cloud Provider API hostname by running the following script, that requires `curl` and [`jq`](https://jqlang.github.io/jq/) installed:
+
+```bash
+curl -sH "Authorization: Bearer token" "https://grafana.com/api/instances" | \
+  jq '[.items[]|{stackName: .slug, clusterName:.clusterSlug, cloudProviderAPIURL: "https://cloud-provider-api-\(.clusterSlug).grafana.net"}]'
+```
+
+This script will return a list of all the Grafana Cloud stacks you own, with the Cloud Provider API hostname for each one. Choose the correct hostname for the stack you want to manage.
+For example, in the following response, the correct hostname for the `herokublogpost` stack is `https://cloud-provider-api-prod-us-central-0.grafana.net`.
+
+```
+[
+  {
+    "stackName": "herokublogpost",
+    "clusterName": "prod-us-central-0",
+    "cloudProviderAPIURL": "https://cloud-provider-api-prod-us-central-0.grafana.net"
+  }
+]
+```
+
+Once you have the token and Cloud Provider API hostanme, you can configure the provider as follows:
+
+```hcl
+provider "grafana" {
+  // ...
+  cloud_provider_url = "https://cloud-provider-api-url.com"
+  cloud_provider_access_token = "token"
+}
+```
+
+The following are examples on how the *Account* and *Scrape Job* resources can be configured:
+
 ```terraform
 data "grafana_cloud_stack" "test" {
   slug = "gcloudstacktest"

templates/index.md.tmpl

@@ -34,6 +34,52 @@ The changelog for this provider can be found here: <https://github.com/grafana/t
 
 ### Managing Cloud Provider
 
+Before using the cloud provider, you need to create an access policy token on the Grafana Cloud Portal. This token is used to authenticate the provider to Grafana's Cloud Provider API.
+[These docs](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/authorize-services/#create-an-access-policy-for-a-stack) will guide you on how to create 
+an access policy. The required permissions, or scopes, are `integration-management:read`, `integration-management:write` and `stacks:read`.
+
+Also, by default the Access Policies UI will not show those scopes, to find name you need to use the `Add Scope` textbox, as shown in the following image:
+
+<img src="https://grafana.com/media/docs/grafana-cloud/aws/cloud-provider-terraform-access-policy-creation.png" width="700"/>
+
+1. Use the `Add Scope` textbox (1) to search for the permissions you need to add to the access policy.
+1. Make sure that you configure the three required scopes. Once done, you'll see the selected scopes as in (2).
+
+Having created an Access Policy, you can now create a token that will be used to authenticate the provider to the Cloud Provider API. You can do so just after creating the access policy, following
+the in-screen instructions, of following [this guide](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/authorize-services/#create-one-or-more-access-policy-tokens).
+
+Having created the token, we can find the correct Cloud Provider API hostname by running the following script, that requires `curl` and [`jq`](https://jqlang.github.io/jq/) installed:
+
+```bash
+curl -sH "Authorization: Bearer token" "https://grafana.com/api/instances" | \
+  jq '[.items[]|{stackName: .slug, clusterName:.clusterSlug, cloudProviderAPIURL: "https://cloud-provider-api-\(.clusterSlug).grafana.net"}]'
+```
+
+This script will return a list of all the Grafana Cloud stacks you own, with the Cloud Provider API hostname for each one. Choose the correct hostname for the stack you want to manage.
+For example, in the following response, the correct hostname for the `herokublogpost` stack is `https://cloud-provider-api-prod-us-central-0.grafana.net`.
+
+```
+[
+  {
+    "stackName": "herokublogpost",
+    "clusterName": "prod-us-central-0",
+    "cloudProviderAPIURL": "https://cloud-provider-api-prod-us-central-0.grafana.net"
+  }
+]
+```
+
+Once you have the token and Cloud Provider API hostanme, you can configure the provider as follows:
+
+```hcl
+provider "grafana" {
+  // ...
+  cloud_provider_url = "https://cloud-provider-api-url.com"
+  cloud_provider_access_token = "token"
+}
+```
+
+The following are examples on how the *Account* and *Scrape Job* resources can be configured:
+
 {{ tffile "examples/resources/grafana_cloud_provider_aws_account/resource.tf" }}
 
 {{ tffile "examples/resources/grafana_cloud_provider_aws_cloudwatch_scrape_job/resource.tf" }}