Merge pull request #103 from planetscale/joem/align-token-env-vars

chore: align service token env vars with pscale cli

Author: joemiller

.github/workflows/test-extensive.yml

@@ -76,7 +76,7 @@ jobs:
           terraform_wrapper: false
       - run: make testacc
         env:
-          PLANETSCALE_SERVICE_TOKEN_NAME: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_NAME }}
+          PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
           PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
         timeout-minutes: 10
 
@@ -108,6 +108,6 @@ jobs:
           tofu_wrapper: false
       - run: make testacc
         env:
-          PLANETSCALE_SERVICE_TOKEN_NAME: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_NAME }}
+          PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
           PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
         timeout-minutes: 10

README.md

@@ -22,13 +22,13 @@ terraform {
 }
 ```
 
-You must then configure the provider to either use a service token, or an access token. Either can be configured in the provider config block, or via env vars (`PLANETSCALE_SERVICE_TOKEN_NAME` and `PLANETSCALE_SERVICE_TOKEN`, or `PLANETSCALE_ACCESS_TOKEN`):
+You must then configure the provider to either use a service token, or an access token. Either can be configured in the provider config block, or via env vars (`PLANETSCALE_SERVICE_TOKEN_ID` and `PLANETSCALE_SERVICE_TOKEN`, or `PLANETSCALE_ACCESS_TOKEN`):
 
 ```hcl
 provider "planetscale" {
   # use a service token
-  service_token_name = "..." # ID of the service token to use, e.g "8fbddg0zlq0r"
-  service_token      = "..." # Secret for the service token.
+  service_token_id = "..." # ID of the service token to use, e.g "8fbddg0zlq0r"
+  service_token    = "..." # Secret for the service token.
 
   # or use an access token
   access_token       = "..." # Secret for the access token.
@@ -48,7 +48,7 @@ Contributions should follow this workflow, or integrate with it.
 
 ### Tests
 
-You will need to set either `PLANETSCALE_ACCESS_TOKEN` or `PLANETSCALE_SERVICE_TOKEN_NAME` and `PLANETSCALE_SERVICE_TOKEN` to run acceptance tests.
+You will need to set either `PLANETSCALE_ACCESS_TOKEN` or `PLANETSCALE_SERVICE_TOKEN_ID` and `PLANETSCALE_SERVICE_TOKEN` to run acceptance tests.
 
 The org to create resources under is currently hardcoded in the tests. You may need to change this to match your own org.  Acceptance tests create real resources in your PlanetScale org.
 

docs/index.md

@@ -7,7 +7,7 @@ description: |-
   access token credentials, configured or stored in the environment variable PLANETSCALE_ACCESS_TOKENservice token credentials, configured or stored in the environment variables PLANETSCALE_SERVICE_TOKEN_NAME and PLANETSCALE_SERVICE_TOKEN
   Note that the provider is not production ready and only for early testing at this time.
   Known limitations:
-  Support for deployments, deploy queues, deploy requests and reverts is not implemented at this time. If you have a use case for it, please let us know in the repository issues.Service tokens don't immediately have read/write access on the resources they create. For now, access must be granted via the UI or via the CLI (pscale service-token add-access)
+  Support for deployments, deploy queues, deploy requests and reverts is not implemented at this time. If you have a use case for it, please let us know in the repository issues.When using service tokens (recommended), ensure the token has the create_databases organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.
 ---
 
 # planetscale Provider
@@ -21,7 +21,7 @@ Note that the provider is not production ready and only for early testing at thi
 
 Known limitations:
 - Support for deployments, deploy queues, deploy requests and reverts is not implemented at this time. If you have a use case for it, please let us know in the repository issues.
-- Service tokens don't immediately have read/write access on the resources they create. For now, access must be granted via the UI or via the CLI (`pscale service-token add-access`)
+- When using service tokens (recommended), ensure the token has the `create_databases` organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.
 
 ## Example Usage
 
@@ -47,4 +47,5 @@ provider "planetscale" {
 - `access_token` (String, Sensitive) Name of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_NAME`. Mutually exclusive with `service_token_name` and `service_token`.
 - `endpoint` (String) If set, points the API client to a different endpoint than `https:://api.planetscale.com/v1`.
 - `service_token` (String, Sensitive) Value of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN`. Mutually exclusive with `access_token`.
-- `service_token_name` (String) Name of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_NAME`. Mutually exclusive with `access_token`.
+- `service_token_id` (String) ID of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_ID`. Mutually exclusive with `access_token`.
+- `service_token_name` (String, Deprecated) Name of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_NAME`. Mutually exclusive with `access_token`. (Deprecated, use `service_token_id` instead)

docs/resources/database.md

@@ -5,15 +5,15 @@ subcategory: ""
 description: |-
   A PlanetScale database.
   Known limitations:
-  When the provider is configured with a service token, the service token needs to manually be granted permission on this database resource. This can be done in the UI or via the CLI (pscale service-token add-access).
+  When using service tokens (recommended), ensure the token has the create_databases organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.
 ---
 
 # planetscale_database (Resource)
 
 A PlanetScale database.
 
 Known limitations:
-- When the provider is configured with a service token, the service token needs to manually be granted permission on this database resource. This can be done in the UI or via the CLI (`pscale service-token add-access`).
+- When using service tokens (recommended), ensure the token has the `create_databases` organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.
 
 ## Example Usage
 

internal/provider/database_resource.go

@@ -132,7 +132,7 @@ func (r *databaseResource) Schema(ctx context.Context, req resource.SchemaReques
 		MarkdownDescription: `A PlanetScale database.
 
 Known limitations:
-- When the provider is configured with a service token, the service token needs to manually be granted permission on this database resource. This can be done in the UI or via the CLI (` + "`pscale service-token add-access`" + `).`,
+- When using service tokens (recommended), ensure the token has the ` + "`create_databases`" + ` organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.`,
 		Attributes: map[string]schema.Attribute{
 			"organization": schema.StringAttribute{
 				Description: "The organization this database belongs to.",

internal/provider/provider.go

@@ -35,7 +35,8 @@ type PlanetScaleProviderModel struct {
 
 	AccessToken types.String `tfsdk:"access_token"`
 
-	ServiceTokenName  types.String `tfsdk:"service_token_name"`
+	ServiceTokenID    types.String `tfsdk:"service_token_id"`   // new preferred field
+	ServiceTokenName  types.String `tfsdk:"service_token_name"` // deprecated
 	ServiceTokenValue types.String `tfsdk:"service_token"`
 }
 
@@ -62,7 +63,7 @@ Note that the provider is not production ready and only for early testing at thi
 
 Known limitations:
 - Support for deployments, deploy queues, deploy requests and reverts is not implemented at this time. If you have a use case for it, please let us know in the repository issues.
-- Service tokens don't immediately have read/write access on the resources they create. For now, access must be granted via the UI or via the CLI (` + "`pscale service-token add-access`" + `)`,
+- When using service tokens (recommended), ensure the token has the ` + "`create_databases`" + ` organization-level permission. This allows terraform to create new databases and automatically grants the token all other permissions on the databases created by the token.`,
 		Attributes: map[string]schema.Attribute{
 			"endpoint": schema.StringAttribute{
 				MarkdownDescription: "If set, points the API client to a different endpoint than `https:://api.planetscale.com/v1`.",
@@ -74,14 +75,25 @@ Known limitations:
 				Sensitive:           true,
 				Validators: []validator.String{
 					stringvalidator.ConflictsWith(path.MatchRoot("service_token_name")),
+					stringvalidator.ConflictsWith(path.MatchRoot("service_token_id")),
 					stringvalidator.ConflictsWith(path.MatchRoot("service_token")),
 				},
 			},
+			"service_token_id": schema.StringAttribute{
+				MarkdownDescription: "ID of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_ID`. Mutually exclusive with `access_token`.",
+				Optional:            true,
+				Validators: []validator.String{
+					stringvalidator.ConflictsWith(path.MatchRoot("access_token")),
+					stringvalidator.ConflictsWith(path.MatchRoot("service_token_name")),
+				},
+			},
 			"service_token_name": schema.StringAttribute{
-				MarkdownDescription: "Name of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_NAME`. Mutually exclusive with `access_token`.",
+				MarkdownDescription: "Name of the service token to use. Alternatively, use `PLANETSCALE_SERVICE_TOKEN_NAME`. Mutually exclusive with `access_token`. (Deprecated, use `service_token_id` instead)",
 				Optional:            true,
+				DeprecationMessage:  "Use service_token_id instead. This field will be removed in a future version.",
 				Validators: []validator.String{
 					stringvalidator.ConflictsWith(path.MatchRoot("access_token")),
+					stringvalidator.ConflictsWith(path.MatchRoot("service_token_id")),
 				},
 			},
 			"service_token": schema.StringAttribute{
@@ -128,31 +140,50 @@ func (p *PlanetScaleProvider) Configure(ctx context.Context, req provider.Config
 	}
 	var (
 		accessToken       = stringValueOrDefault(data.AccessToken, os.Getenv("PLANETSCALE_ACCESS_TOKEN"))
+		serviceTokenID    = stringValueOrDefault(data.ServiceTokenID, os.Getenv("PLANETSCALE_SERVICE_TOKEN_ID"))
 		serviceTokenName  = stringValueOrDefault(data.ServiceTokenName, os.Getenv("PLANETSCALE_SERVICE_TOKEN_NAME"))
 		serviceTokenValue = stringValueOrDefault(data.ServiceTokenValue, os.Getenv("PLANETSCALE_SERVICE_TOKEN"))
 	)
+
+	// Warn if the deprecated PLANETSCALE_SERVICE_TOKEN_NAME env var is used.
+	// Adding this to `resp.Diagnostics` ensures it will be printed during typical
+	// terraform operations, whereas logging with `tflog.Warn()` will only show if the
+	// users specifies the `TF_LOG` env var.
+	if serviceTokenName != "" && serviceTokenID == "" {
+		resp.Diagnostics.AddWarning(
+			"Deprecated Configuration",
+			"PLANETSCALE_SERVICE_TOKEN_NAME is deprecated. Please use PLANETSCALE_SERVICE_TOKEN_ID instead.",
+		)
+	}
+
+	// Use serviceTokenID if available, fall back to serviceTokenName
+	effectiveTokenID := serviceTokenID
+	if effectiveTokenID == "" {
+		effectiveTokenID = serviceTokenName
+	}
+
 	switch {
-	case accessToken != "" && serviceTokenName == "" && serviceTokenValue == "":
+	case accessToken != "" && effectiveTokenID == "" && serviceTokenValue == "":
 		tok := &oauth2.Token{AccessToken: accessToken}
 		rt = &oauth2.Transport{Base: initrt, Source: oauth2.StaticTokenSource(tok)}
-	case accessToken == "" && serviceTokenName != "" && serviceTokenValue != "":
+	case accessToken == "" && effectiveTokenID != "" && serviceTokenValue != "":
 		rt = roundTripperFunc(func(r *http.Request) (*http.Response, error) {
-			r.Header.Set("Authorization", serviceTokenName+":"+serviceTokenValue)
+			r.Header.Set("Authorization", effectiveTokenID+":"+serviceTokenValue)
 			return initrt.RoundTrip(r)
 		})
-	case accessToken == "" && serviceTokenName == "" && serviceTokenValue == "":
+	case accessToken == "" && effectiveTokenID == "" && serviceTokenValue == "":
 		resp.Diagnostics.AddError("Missing PlanetScale credentials.",
 			"You must set either of:\n"+
 				"- `PLANETSCALE_ACCESS_TOKEN`\n"+
-				"- `PLANETSCALE_SERVICE_TOKEN_NAME` and `PLANETSCALE_SERVICE_TOKEN`")
-	case accessToken == "" && serviceTokenName != "" && serviceTokenValue == "",
-		accessToken == "" && serviceTokenName == "" && serviceTokenValue != "":
+				"- `PLANETSCALE_SERVICE_TOKEN_ID` and `PLANETSCALE_SERVICE_TOKEN`")
+	case accessToken == "" && effectiveTokenID != "" && serviceTokenValue == "",
+		accessToken == "" && effectiveTokenID == "" && serviceTokenValue != "":
 		resp.Diagnostics.AddError("Incomplete PlanetScale service token credentials.",
-			"Both of `PLANETSCALE_SERVICE_TOKEN_NAME` and `PLANETSCALE_SERVICE_TOKEN` must be set.")
+			"Both of `PLANETSCALE_SERVICE_TOKEN_ID` and `PLANETSCALE_SERVICE_TOKEN` must be set.")
 	default:
 		resp.Diagnostics.AddError("Ambiguous PlanetScale credentials.", "You must set only an access token or a service token, but not both:\n"+
 			"- `PLANETSCALE_ACCESS_TOKEN`\n"+
-			"- `PLANETSCALE_SERVICE_TOKEN_NAME` and `PLANETSCALE_SERVICE_TOKEN`")
+			"- `PLANETSCALE_SERVICE_TOKEN_ID` and `PLANETSCALE_SERVICE_TOKEN`")
 	}
 	if resp.Diagnostics.HasError() {
 		return

internal/provider/provider_test.go

@@ -28,14 +28,14 @@ var testAccAPIClient *planetscale.Client
 func testAccPreCheck(t *testing.T) {
 	var (
 		accessToken       = os.Getenv("PLANETSCALE_ACCESS_TOKEN")
-		serviceTokenName  = os.Getenv("PLANETSCALE_SERVICE_TOKEN_NAME")
+		serviceTokenID    = os.Getenv("PLANETSCALE_SERVICE_TOKEN_ID")
 		serviceTokenValue = os.Getenv("PLANETSCALE_SERVICE_TOKEN")
 	)
 	switch {
 	case accessToken != "":
-	case serviceTokenName != "" && serviceTokenValue != "":
+	case serviceTokenID != "" && serviceTokenValue != "":
 	default:
-		t.Fatalf("must have either PLANETSCALE_ACCESS_TOKEN or both of (PLANETSCALE_SERVICE_TOKEN_NAME, PLANETSCALE_SERVICE_TOKEN)")
+		t.Fatalf("must have either PLANETSCALE_ACCESS_TOKEN or both of (PLANETSCALE_SERVICE_TOKEN_ID, PLANETSCALE_SERVICE_TOKEN)")
 	}
 
 	// TODO: factor client creation out of the provider.go Configure() func so we can
@@ -51,11 +51,11 @@ func testAccPreCheck(t *testing.T) {
 			testAccAPIClient = planetscale.NewClient(&http.Client{Transport: rt}, nil)
 		}
 
-		serviceTokenName := os.Getenv("PLANETSCALE_SERVICE_TOKEN_NAME")
+		serviceTokenID := os.Getenv("PLANETSCALE_SERVICE_TOKEN_ID")
 		serviceTokenValue := os.Getenv("PLANETSCALE_SERVICE_TOKEN")
-		if serviceTokenName != "" && serviceTokenValue != "" {
+		if serviceTokenID != "" && serviceTokenValue != "" {
 			rt := roundTripperFunc(func(r *http.Request) (*http.Response, error) {
-				r.Header.Set("Authorization", serviceTokenName+":"+serviceTokenValue)
+				r.Header.Set("Authorization", serviceTokenID+":"+serviceTokenValue)
 				return http.DefaultTransport.RoundTrip(r)
 			})
 			testAccAPIClient = planetscale.NewClient(&http.Client{Transport: rt}, nil)