Docs + provider config: Deprecate cloud_api_key (#1366)

Related to #1365
We should now be using Cloud Access Policy tokens, not API keys. Let's deprecate the whole "API Key" naming to remove confusion

Author: julienduchesne

.github/workflows/cloud-acc-tests.yml

@@ -25,7 +25,7 @@ jobs:
         uses: grafana/shared-workflows/actions/get-vault-secrets@main
         with:
           repo_secrets: |
-            GRAFANA_CLOUD_API_KEY=cloud-tests:api-key
+            GRAFANA_CLOUD_ACCESS_POLICY_TOKEN=cloud-tests:api-key
             GRAFANA_CLOUD_ORG=cloud-tests:org
       - run: make testacc-cloud-api
         env:

docs/index.md

@@ -206,7 +206,8 @@ resource "grafana_oncall_escalation" "example_notify_step" {
 
 - `auth` (String, Sensitive) API token, basic auth in the `username:password` format or `anonymous` (string literal). May alternatively be set via the `GRAFANA_AUTH` environment variable.
 - `ca_cert` (String) Certificate CA bundle (file path or literal value) to use to verify the Grafana server's certificate. May alternatively be set via the `GRAFANA_CA_CERT` environment variable.
-- `cloud_api_key` (String, Sensitive) Access Policy Token (or API key) for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_API_KEY` environment variable.
+- `cloud_access_policy_token` (String, Sensitive) Access Policy Token for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_ACCESS_POLICY_TOKEN` environment variable.
+- `cloud_api_key` (String, Sensitive, Deprecated) Deprecated: Use `cloud_access_policy_token` instead.
 - `cloud_api_url` (String) Grafana Cloud's API URL. May alternatively be set via the `GRAFANA_CLOUD_API_URL` environment variable.
 - `http_headers` (Map of String, Sensitive) Optional. HTTP headers mapping keys to values used for accessing the Grafana and Grafana Cloud APIs. May alternatively be set via the `GRAFANA_HTTP_HEADERS` environment variable in JSON format.
 - `insecure_skip_verify` (Boolean) Skip TLS certificate verification. May alternatively be set via the `GRAFANA_INSECURE_SKIP_VERIFY` environment variable.
@@ -230,57 +231,16 @@ One, or many, of the following authentication settings must be set. Each authent
 ### `auth`
 
 This can be a Grafana API key, basic auth `username:password`, or a
-[Grafana API key](https://grafana.com/docs/grafana/latest/developers/http_api/create-api-tokens-for-org/).
+[Grafana Service Account token](https://grafana.com/docs/grafana/latest/developers/http_api/create-api-tokens-for-org/).
 
-### `cloud_api_key`
+### `cloud_access_policy_token`
 
 An access policy token created on the [Grafana Cloud Portal](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/create-api-key/).
 
 ### `sm_access_token`
 
-[Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/monitor-public-endpoints/)
-endpoints require a dedicated access token. You may obtain an access token with its
-[Registration API](https://github.com/grafana/synthetic-monitoring-api-go-client/blob/main/docs/API.md#registration-api).
-
-```console
-curl \
-  -X POST \
-  -H 'Content-type: application/json; charset=utf-8' \
-  -H "Authorization: Bearer $GRAFANA_CLOUD_API_KEY" \
-  -d '{"stackId": <stack-id>, "metricsInstanceId": <metrics-instance-id>, "logsInstanceId": <logs-instance-id>}' \
-  "$SM_API_URL/api/v1/register/install"
-```
-
-`GRAFANA_CLOUD_API_KEY` is an API key created on the
-[Grafana Cloud Portal](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/create-api-key/).
-It must have the `MetricsPublisher` role.
-
-`SM_API_URL` is the URL of the Synthetic Monitoring API.
-Based on the region of your Grafana Cloud stack, you need to use a different API URL.
-
-Please [see API docs](https://github.com/grafana/synthetic-monitoring-api-go-client/blob/main/docs/API.md#api-url) to find `SM_API_URL` for your region.
-
-`stackId`, `metricsInstanceId`, and `logsInstanceId` may also be obtained on
-the portal. First, you need to create a Stack by clicking "Add Stack". When it's
-created you will be taken to its landing page on the portal. Get your `stackId`
-from the URL in your browser:
-
-```
-https://grafana.com/orgs/<org-slug>/stacks/<stack-id>
-```
-
-Next, go to "Details" for Prometheus. Again, get `metricsInstanceId` from your URL:
-
-```
-https://grafana.com/orgs/<org-slug>/hosted-metrics/<metrics-instance-id>
-```
-
-Finally, go back to your stack page, and go to "Details" for Loki to get
-`logsInstanceId`.
-
-```
-https://grafana.com/orgs/<org-slug>/hosted-logs/<logs-instance-id>
-```
+[Grafana Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/monitor-public-endpoints/) uses distinct tokens for API access. 
+You can use the `grafana_synthetic_monitoring_installation` resource as shown above or you can request a new Synthetic Monitoring API key in Synthetics -> Config page.
 
 ### `oncall_access_token`
 

internal/provider/configure_clients.go

@@ -40,7 +40,7 @@ func createClients(providerConfig frameworkProviderConfig) (*common.Client, erro
 			return nil, err
 		}
 	}
-	if !providerConfig.CloudAPIKey.IsNull() {
+	if !providerConfig.CloudAccessPolicyToken.IsNull() {
 		if err := createCloudClient(c, providerConfig); err != nil {
 			return nil, err
 		}
@@ -146,7 +146,7 @@ func createCloudClient(client *common.Client, providerConfig frameworkProviderCo
 	openAPIConfig.Host = parsedURL.Host
 	openAPIConfig.Scheme = "https"
 	openAPIConfig.HTTPClient = getRetryClient(providerConfig)
-	openAPIConfig.DefaultHeader["Authorization"] = "Bearer " + providerConfig.CloudAPIKey.ValueString()
+	openAPIConfig.DefaultHeader["Authorization"] = "Bearer " + providerConfig.CloudAccessPolicyToken.ValueString()
 	httpHeaders, err := getHTTPHeadersMap(providerConfig)
 	if err != nil {
 		return err

internal/provider/framework_provider.go

@@ -32,8 +32,8 @@ type frameworkProviderConfig struct {
 
 	StoreDashboardSha256 types.Bool `tfsdk:"store_dashboard_sha256"`
 
-	CloudAPIKey types.String `tfsdk:"cloud_api_key"`
-	CloudAPIURL types.String `tfsdk:"cloud_api_url"`
+	CloudAccessPolicyToken types.String `tfsdk:"cloud_access_policy_token"`
+	CloudAPIURL            types.String `tfsdk:"cloud_api_url"`
 
 	SMAccessToken types.String `tfsdk:"sm_access_token"`
 	SMURL         types.String `tfsdk:"sm_url"`
@@ -52,7 +52,8 @@ func (c *frameworkProviderConfig) SetDefaults() error {
 	c.TLSKey = envDefaultFuncString(c.TLSKey, "GRAFANA_TLS_KEY")
 	c.TLSCert = envDefaultFuncString(c.TLSCert, "GRAFANA_TLS_CERT")
 	c.CACert = envDefaultFuncString(c.CACert, "GRAFANA_CA_CERT")
-	c.CloudAPIKey = envDefaultFuncString(c.CloudAPIKey, "GRAFANA_CLOUD_API_KEY")
+	c.CloudAccessPolicyToken = envDefaultFuncString(c.CloudAccessPolicyToken, "GRAFANA_CLOUD_ACCESS_POLICY_TOKEN")
+	c.CloudAccessPolicyToken = envDefaultFuncString(c.CloudAccessPolicyToken, "GRAFANA_CLOUD_API_KEY") // Backwards compatibility. TODO: Remove once cloud_api_key is removed
 	c.CloudAPIURL = envDefaultFuncString(c.CloudAPIURL, "GRAFANA_CLOUD_API_URL", "https://grafana.com")
 	c.SMAccessToken = envDefaultFuncString(c.SMAccessToken, "GRAFANA_SM_ACCESS_TOKEN")
 	c.SMURL = envDefaultFuncString(c.SMURL, "GRAFANA_SM_URL", "https://synthetic-monitoring-api.grafana.net")
@@ -170,10 +171,16 @@ func (p *frameworkProvider) Schema(_ context.Context, _ provider.SchemaRequest,
 				MarkdownDescription: "Set to true if you want to save only the sha256sum instead of complete dashboard model JSON in the tfstate.",
 			},
 
+			"cloud_access_policy_token": schema.StringAttribute{
+				Optional:            true,
+				Sensitive:           true,
+				MarkdownDescription: "Access Policy Token for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_ACCESS_POLICY_TOKEN` environment variable.",
+			},
 			"cloud_api_key": schema.StringAttribute{
 				Optional:            true,
 				Sensitive:           true,
-				MarkdownDescription: "Access Policy Token (or API key) for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_API_KEY` environment variable.",
+				DeprecationMessage:  "Use `cloud_access_policy_token` instead.",
+				MarkdownDescription: "Deprecated: Use `cloud_access_policy_token` instead.",
 			},
 			"cloud_api_url": schema.StringAttribute{
 				Optional:            true,

internal/provider/legacy_provider.go

@@ -222,16 +222,23 @@ func Provider(version string) *schema.Provider {
 				Description: "Skip TLS certificate verification. May alternatively be set via the `GRAFANA_INSECURE_SKIP_VERIFY` environment variable.",
 			},
 
+			"cloud_access_policy_token": {
+				Type:          schema.TypeString,
+				Optional:      true,
+				Sensitive:     true,
+				ConflictsWith: []string{"cloud_api_key"},
+				Description:   "Access Policy Token for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_ACCESS_POLICY_TOKEN` environment variable.",
+			},
 			"cloud_api_key": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				Sensitive:   true,
-				Description: "Access Policy Token (or API key) for Grafana Cloud. May alternatively be set via the `GRAFANA_CLOUD_API_KEY` environment variable.",
+				Deprecated:  "Use `cloud_access_policy_token` instead.",
+				Description: "Deprecated: Use `cloud_access_policy_token` instead.",
 			},
 			"cloud_api_url": {
 				Type:         schema.TypeString,
 				Optional:     true,
-				DefaultFunc:  schema.EnvDefaultFunc("GRAFANA_CLOUD_API_URL", "https://grafana.com"),
 				Description:  "Grafana Cloud's API URL. May alternatively be set via the `GRAFANA_CLOUD_API_URL` environment variable.",
 				ValidateFunc: validation.IsURLWithHTTPorHTTPS,
 			},
@@ -310,25 +317,28 @@ func configure(version string, p *schema.Provider) func(context.Context, *schema
 		}
 
 		cfg := frameworkProviderConfig{
-			Auth:                 stringValueOrNull(d, "auth"),
-			URL:                  stringValueOrNull(d, "url"),
-			OrgID:                int64ValueOrNull(d, "org_id"),
-			TLSKey:               stringValueOrNull(d, "tls_key"),
-			TLSCert:              stringValueOrNull(d, "tls_cert"),
-			CACert:               stringValueOrNull(d, "ca_cert"),
-			InsecureSkipVerify:   boolValueOrNull(d, "insecure_skip_verify"),
-			CloudAPIKey:          stringValueOrNull(d, "cloud_api_key"),
-			CloudAPIURL:          stringValueOrNull(d, "cloud_api_url"),
-			SMAccessToken:        stringValueOrNull(d, "sm_access_token"),
-			SMURL:                stringValueOrNull(d, "sm_url"),
-			OncallAccessToken:    stringValueOrNull(d, "oncall_access_token"),
-			OncallURL:            stringValueOrNull(d, "oncall_url"),
-			StoreDashboardSha256: boolValueOrNull(d, "store_dashboard_sha256"),
-			HTTPHeaders:          headers,
-			Retries:              int64ValueOrNull(d, "retries"),
-			RetryStatusCodes:     statusCodes,
-			RetryWait:            types.Int64Value(int64(d.Get("retry_wait").(int))),
-			UserAgent:            types.StringValue(p.UserAgent("terraform-provider-grafana", version)),
+			Auth:                   stringValueOrNull(d, "auth"),
+			URL:                    stringValueOrNull(d, "url"),
+			OrgID:                  int64ValueOrNull(d, "org_id"),
+			TLSKey:                 stringValueOrNull(d, "tls_key"),
+			TLSCert:                stringValueOrNull(d, "tls_cert"),
+			CACert:                 stringValueOrNull(d, "ca_cert"),
+			InsecureSkipVerify:     boolValueOrNull(d, "insecure_skip_verify"),
+			CloudAccessPolicyToken: stringValueOrNull(d, "cloud_access_policy_token"),
+			CloudAPIURL:            stringValueOrNull(d, "cloud_api_url"),
+			SMAccessToken:          stringValueOrNull(d, "sm_access_token"),
+			SMURL:                  stringValueOrNull(d, "sm_url"),
+			OncallAccessToken:      stringValueOrNull(d, "oncall_access_token"),
+			OncallURL:              stringValueOrNull(d, "oncall_url"),
+			StoreDashboardSha256:   boolValueOrNull(d, "store_dashboard_sha256"),
+			HTTPHeaders:            headers,
+			Retries:                int64ValueOrNull(d, "retries"),
+			RetryStatusCodes:       statusCodes,
+			RetryWait:              types.Int64Value(int64(d.Get("retry_wait").(int))),
+			UserAgent:              types.StringValue(p.UserAgent("terraform-provider-grafana", version)),
+		}
+		if cfg.CloudAccessPolicyToken.IsNull() {
+			cfg.CloudAccessPolicyToken = stringValueOrNull(d, "cloud_api_key") // TODO: Remove once `cloud_api_key` is removed
 		}
 		if err := cfg.SetDefaults(); err != nil {
 			return nil, diag.FromErr(err)

internal/provider/legacy_provider_test.go

@@ -121,7 +121,7 @@ func TestProviderConfigure(t *testing.T) {
 		{
 			name: "grafana cloud config from env",
 			env: map[string]string{
-				"GRAFANA_CLOUD_API_KEY": "testtest",
+				"GRAFANA_CLOUD_ACCESS_POLICY_TOKEN": "testtest",
 			},
 		},
 		{

internal/testutils/provider.go

@@ -136,7 +136,7 @@ func CheckCloudAPITestsEnabled(t *testing.T) {
 		t.Skip("TF_ACC_CLOUD_API must be set to a truthy value for Cloud API acceptance tests")
 	}
 
-	CheckEnvVarsSet(t, "GRAFANA_CLOUD_API_KEY", "GRAFANA_CLOUD_ORG")
+	CheckEnvVarsSet(t, "GRAFANA_CLOUD_ACCESS_POLICY_TOKEN", "GRAFANA_CLOUD_ORG")
 }
 
 // CheckCloudInstanceTestsEnabled checks if tests that run on cloud instances are enabled. This should be the first line of any test that tests Grafana Cloud Pro features

templates/index.md.tmpl

@@ -37,57 +37,16 @@ One, or many, of the following authentication settings must be set. Each authent
 ### `auth`
 
 This can be a Grafana API key, basic auth `username:password`, or a
-[Grafana API key](https://grafana.com/docs/grafana/latest/developers/http_api/create-api-tokens-for-org/).
+[Grafana Service Account token](https://grafana.com/docs/grafana/latest/developers/http_api/create-api-tokens-for-org/).
 
-### `cloud_api_key`
+### `cloud_access_policy_token`
 
 An access policy token created on the [Grafana Cloud Portal](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/create-api-key/).
 
 ### `sm_access_token`
 
-[Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/monitor-public-endpoints/)
-endpoints require a dedicated access token. You may obtain an access token with its
-[Registration API](https://github.com/grafana/synthetic-monitoring-api-go-client/blob/main/docs/API.md#registration-api).
-
-```console
-curl \
-  -X POST \
-  -H 'Content-type: application/json; charset=utf-8' \
-  -H "Authorization: Bearer $GRAFANA_CLOUD_API_KEY" \
-  -d '{"stackId": <stack-id>, "metricsInstanceId": <metrics-instance-id>, "logsInstanceId": <logs-instance-id>}' \
-  "$SM_API_URL/api/v1/register/install"
-```
-
-`GRAFANA_CLOUD_API_KEY` is an API key created on the
-[Grafana Cloud Portal](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/create-api-key/).
-It must have the `MetricsPublisher` role.
-
-`SM_API_URL` is the URL of the Synthetic Monitoring API.
-Based on the region of your Grafana Cloud stack, you need to use a different API URL.
-
-Please [see API docs](https://github.com/grafana/synthetic-monitoring-api-go-client/blob/main/docs/API.md#api-url) to find `SM_API_URL` for your region.
-
-`stackId`, `metricsInstanceId`, and `logsInstanceId` may also be obtained on
-the portal. First, you need to create a Stack by clicking "Add Stack". When it's
-created you will be taken to its landing page on the portal. Get your `stackId`
-from the URL in your browser:
-
-```
-https://grafana.com/orgs/<org-slug>/stacks/<stack-id>
-```
-
-Next, go to "Details" for Prometheus. Again, get `metricsInstanceId` from your URL:
-
-```
-https://grafana.com/orgs/<org-slug>/hosted-metrics/<metrics-instance-id>
-```
-
-Finally, go back to your stack page, and go to "Details" for Loki to get
-`logsInstanceId`.
-
-```
-https://grafana.com/orgs/<org-slug>/hosted-logs/<logs-instance-id>
-```
+[Grafana Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/monitor-public-endpoints/) uses distinct tokens for API access. 
+You can use the `grafana_synthetic_monitoring_installation` resource as shown above or you can request a new Synthetic Monitoring API key in Synthetics -> Config page.
 
 ### `oncall_access_token`