review changes 3

Signed-off-by: Mauritz Uphoff <[email protected]>

Author: h3adex

docs/ephemeral-resources/access_token.md

@@ -4,20 +4,36 @@ page_title: "stackit_access_token Ephemeral Resource - stackit"
 subcategory: ""
 description: |-
   Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. Token generation logic prioritizes environment variables first, followed by provider configuration. Access tokens generated from service account keys expire after 60 minutes.
+  ~> This ephemeral-resource is in beta and may be subject to breaking changes in the future. Use with caution. See our guide https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources for how to opt-in to use beta resources.
 ---
 
 # stackit_access_token (Ephemeral Resource)
 
 Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. Token generation logic prioritizes environment variables first, followed by provider configuration. Access tokens generated from service account keys expire after 60 minutes.
 
+~> This ephemeral-resource is in beta and may be subject to breaking changes in the future. Use with caution. See our [guide](https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources) for how to opt-in to use beta resources.
+
 ## Example Usage
 
 ```terraform
+provider "stackit" {
+  default_region           = "eu01"
+  service_account_key_path = "/path/to/sa_key.json"
+}
+
 ephemeral "stackit_access_token" "example" {}
 
+locals {
+  publicIpBody = {
+    labels = {
+      key = "value"
+    }
+  }
+}
+
 // https://registry.terraform.io/providers/Mastercard/restapi/latest/docs
 provider "restapi" {
-  uri                  = "https://iaas.api.eu01.stackit.cloud/"
+  uri                  = "https://iaas.api.stackit.cloud"
   write_returns_object = true
 
   headers = {
@@ -30,23 +46,40 @@ provider "restapi" {
   destroy_method = "DELETE"
 }
 
-resource "restapi_object" "iaas_keypair" {
-  path = "/v2/keypairs"
+resource "restapi_object" "public_ip" {
+  path = "/v2/projects/${var.project_id}/regions/${var.region}/public-ips"
 
-  data = jsonencode({
-    labels = {
-      key = "testvalue"
-    }
-    name      = "test-keypair-123"
-    publicKey = file(chomp("~/.ssh/id_rsa.pub"))
-  })
+  data = jsonencode(local.publicIpBody)
 
-  id_attribute   = "name"
+  id_attribute   = "id"
   read_method    = "GET"
   create_method  = "POST"
   update_method  = "PATCH"
   destroy_method = "DELETE"
 }
+
+// https://registry.terraform.io/providers/magodo/restful/latest/docs
+provider "restful" {
+  base_url = "https://iaas.api.stackit.cloud"
+  security = {
+    http = {
+      token = {
+        token = ephemeral.stackit_access_token.example.access_token
+      }
+    }
+  }
+}
+
+resource "restful_resource" "public_ip" {
+  path = "/v2/projects/${var.project_id}/regions/${var.region}/public-ips"
+  data = jsonencode(local.publicIpBody)
+
+  read_path     = "$(path)/$(body.id)"
+  update_path   = "$(path)/$(body.id)"
+  update_method = "PATCH"
+  delete_path   = "$(path)/$(body.id)"
+  delete_method = "DELETE"
+}
 ```
 
 <!-- schema generated by tfplugindocs -->

examples/ephemeral-resources/stackit_access_token/ephemeral-resource.tf

@@ -1,8 +1,25 @@
+provider "stackit" {
+  default_region           = "eu01"
+  service_account_key_path = "/path/to/sa_key.json"
+  enable_beta_resources    = true
+}
+
 ephemeral "stackit_access_token" "example" {}
 
-// https://registry.terraform.io/providers/Mastercard/restapi/latest/docs
+locals {
+  stackit_api_base_url = "https://iaas.api.stackit.cloud"
+  public_ip_path       = "/v2/projects/${var.project_id}/regions/${var.region}/public-ips"
+
+  public_ip_payload = {
+    labels = {
+      key = "value"
+    }
+  }
+}
+
+# Docs: https://registry.terraform.io/providers/Mastercard/restapi/latest
 provider "restapi" {
-  uri                  = "https://iaas.api.eu01.stackit.cloud/"
+  uri                  = local.stackit_api_base_url
   write_returns_object = true
 
   headers = {
@@ -11,24 +28,41 @@ provider "restapi" {
   }
 
   create_method  = "POST"
-  update_method  = "PUT"
+  update_method  = "PATCH" # more likely in RESTful APIs than PUT
   destroy_method = "DELETE"
 }
 
-resource "restapi_object" "iaas_keypair" {
-  path = "/v2/keypairs"
-
-  data = jsonencode({
-    labels = {
-      key = "testvalue"
-    }
-    name      = "test-keypair-123"
-    publicKey = file(chomp("~/.ssh/id_rsa.pub"))
-  })
+resource "restapi_object" "public_ip_restapi" {
+  path = local.public_ip_path
+  data = jsonencode(local.public_ip_payload)
 
-  id_attribute   = "name"
+  id_attribute   = "id"
   read_method    = "GET"
   create_method  = "POST"
   update_method  = "PATCH"
   destroy_method = "DELETE"
 }
+
+# Docs: https://registry.terraform.io/providers/magodo/restful/latest
+provider "restful" {
+  base_url = local.stackit_api_base_url
+
+  security = {
+    http = {
+      token = {
+        token = ephemeral.stackit_access_token.example.access_token
+      }
+    }
+  }
+}
+
+resource "restful_resource" "public_ip_restful" {
+  path = local.public_ip_path
+  data = jsonencode(local.public_ip_payload)
+
+  read_path     = "$(path)/$(body.id)"
+  update_path   = "$(path)/$(body.id)"
+  update_method = "PATCH"
+  delete_path   = "$(path)/$(body.id)"
+  delete_method = "DELETE"
+}

stackit/internal/core/core.go

@@ -15,8 +15,9 @@ import (
 type ResourceType string
 
 const (
-	Resource   ResourceType = "resource"
-	Datasource ResourceType = "datasource"
+	Resource          ResourceType = "resource"
+	Datasource        ResourceType = "datasource"
+	EphemeralResource ResourceType = "ephemeral-resource"
 
 	// Separator used for concatenation of TF-internal resource ID
 	Separator = ","
@@ -31,6 +32,7 @@ type EphemeralProviderData struct {
 	ServiceAccountKey     string
 	ServiceAccountKeyPath string
 	TokenCustomEndpoint   string
+	EnableBetaResources   bool
 }
 
 type ProviderData struct {

stackit/internal/services/access_token/ephemeral_resource.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stackitcloud/stackit-sdk-go/core/config"
 	"github.com/stackitcloud/terraform-provider-stackit/stackit/internal/conversion"
 	"github.com/stackitcloud/terraform-provider-stackit/stackit/internal/core"
+	"github.com/stackitcloud/terraform-provider-stackit/stackit/internal/features"
 )
 
 var (
@@ -28,17 +29,27 @@ type accessTokenEphemeralResource struct {
 }
 
 func (e *accessTokenEphemeralResource) Configure(ctx context.Context, req ephemeral.ConfigureRequest, resp *ephemeral.ConfigureResponse) {
-	providerData, ok := conversion.ParseEphemeralProviderData(ctx, req.ProviderData, &resp.Diagnostics)
+	ephemeralProviderData, ok := conversion.ParseEphemeralProviderData(ctx, req.ProviderData, &resp.Diagnostics)
 	if !ok {
 		return
 	}
 
+	features.CheckBetaResourcesEnabled(
+		ctx,
+		&core.ProviderData{EnableBetaResources: ephemeralProviderData.EnableBetaResources},
+		&resp.Diagnostics,
+		"stackit_access_token", "ephemeral_resource",
+	)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
 	e.keyAuthConfig = config.Configuration{
-		ServiceAccountKey:     providerData.ServiceAccountKey,
-		ServiceAccountKeyPath: providerData.ServiceAccountKeyPath,
-		PrivateKeyPath:        providerData.PrivateKey,
-		PrivateKey:            providerData.PrivateKeyPath,
-		TokenCustomUrl:        providerData.TokenCustomEndpoint,
+		ServiceAccountKey:     ephemeralProviderData.ServiceAccountKey,
+		ServiceAccountKeyPath: ephemeralProviderData.ServiceAccountKeyPath,
+		PrivateKeyPath:        ephemeralProviderData.PrivateKey,
+		PrivateKey:            ephemeralProviderData.PrivateKeyPath,
+		TokenCustomUrl:        ephemeralProviderData.TokenCustomEndpoint,
 	}
 }
 
@@ -52,11 +63,11 @@ func (e *accessTokenEphemeralResource) Metadata(_ context.Context, req ephemeral
 
 func (e *accessTokenEphemeralResource) Schema(_ context.Context, _ ephemeral.SchemaRequest, resp *ephemeral.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description: "Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. " +
-			"A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. " +
-			"If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. " +
-			"Token generation logic prioritizes environment variables first, followed by provider configuration. " +
-			"Access tokens generated from service account keys expire after 60 minutes.",
+		Description: features.AddBetaDescription("Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. "+
+			"A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. "+
+			"If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. "+
+			"Token generation logic prioritizes environment variables first, followed by provider configuration. "+
+			"Access tokens generated from service account keys expire after 60 minutes.", core.EphemeralResource),
 		Attributes: map[string]schema.Attribute{
 			"access_token": schema.StringAttribute{
 				Description: "JWT access token for STACKIT API authentication.",
@@ -75,26 +86,34 @@ func (e *accessTokenEphemeralResource) Open(ctx context.Context, req ephemeral.O
 		return
 	}
 
-	rt, err := auth.KeyAuth(&e.keyAuthConfig)
+	accessToken, err := getAccessToken(&e.keyAuthConfig)
 	if err != nil {
-		core.LogAndAddError(ctx, &resp.Diagnostics, "Access token generation failed", fmt.Sprintf("Failed to initialize authentication: %v", err))
+		core.LogAndAddError(ctx, &resp.Diagnostics, "Access token generation failed", err.Error())
 		return
 	}
 
+	model.AccessToken = types.StringValue(accessToken)
+	resp.Diagnostics.Append(resp.Result.Set(ctx, model)...)
+}
+
+// getAccessToken initializes authentication using the provided config and returns an access token via the KeyFlow mechanism.
+func getAccessToken(keyAuthConfig *config.Configuration) (string, error) {
+	roundTripper, err := auth.KeyAuth(keyAuthConfig)
+	if err != nil {
+		return "", fmt.Errorf("failed to initialize authentication: %v", err)
+	}
+
 	// Type assert to access token functionality
-	client, ok := rt.(*clients.KeyFlow)
+	client, ok := roundTripper.(*clients.KeyFlow)
 	if !ok {
-		core.LogAndAddError(ctx, &resp.Diagnostics, "Access token generation failed", "Internal error: expected *clients.KeyFlow, but received a different implementation of http.RoundTripper")
-		return
+		return "", fmt.Errorf("internal error: expected *clients.KeyFlow, but received a different implementation of http.RoundTripper")
 	}
 
 	// Retrieve the access token
 	accessToken, err := client.GetAccessToken()
 	if err != nil {
-		core.LogAndAddError(ctx, &resp.Diagnostics, "Access token retrieval failed", fmt.Sprintf("Error obtaining access token: %v", err))
-		return
+		return "", fmt.Errorf("error obtaining access token: %v", err)
 	}
 
-	model.AccessToken = types.StringValue(accessToken)
-	resp.Diagnostics.Append(resp.Result.Set(ctx, model)...)
+	return accessToken, nil
 }