Scaffold terraform-provider-vault-secrets-arrstack

Configure the arrstack Vault secrets engine (backend config + roles) from
terraform-vault, matching the schema declared in terraform-vault #127.

- Add terraform-plugin-framework provider (local name arrstack) authenticating
  to Vault/OpenBao via address + token (VAULT_ADDR/VAULT_TOKEN fallback).
- Add arrstack_secret_backend resource: mounts the engine and writes <mount>/config.
- Add arrstack_secret_backend_role resource: manages <mount>/roles/<name>.
- Add Vault client, conversions, unit tests, Makefile, woodpecker CI + tag
  release to artifactapi terraform-unkin, examples, and README.

internal/provider/client.go

@@ -0,0 +1,130 @@
+package provider
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	vault "github.com/hashicorp/vault/api"
+)
+
+// vaultClient wraps the Vault/OpenBao API client with the operations this
+// provider needs to manage the arrstack secrets engine.
+type vaultClient struct {
+	api *vault.Client
+}
+
+func newVaultClient(address, token string) (*vaultClient, error) {
+	cfg := vault.DefaultConfig()
+	if cfg.Error != nil {
+		return nil, cfg.Error
+	}
+	if address != "" {
+		cfg.Address = address
+	}
+	c, err := vault.NewClient(cfg)
+	if err != nil {
+		return nil, err
+	}
+	if token != "" {
+		c.SetToken(token)
+	}
+	return &vaultClient{api: c}, nil
+}
+
+// mountConfig holds the tunable options applied when enabling the engine.
+type mountConfig struct {
+	DefaultLeaseTTL string
+	MaxLeaseTTL     string
+}
+
+// enableMount mounts the secrets engine of the given plugin type at path.
+func (c *vaultClient) enableMount(ctx context.Context, path, pluginType, description string, cfg mountConfig) error {
+	input := &vault.MountInput{
+		Type:        pluginType,
+		Description: description,
+		Config: vault.MountConfigInput{
+			DefaultLeaseTTL: cfg.DefaultLeaseTTL,
+			MaxLeaseTTL:     cfg.MaxLeaseTTL,
+		},
+	}
+	return c.api.Sys().MountWithContext(ctx, path, input)
+}
+
+// tuneMount updates tunable options of an existing mount (e.g. description).
+func (c *vaultClient) tuneMount(ctx context.Context, path, description string, cfg mountConfig) error {
+	input := vault.MountConfigInput{
+		Description:     &description,
+		DefaultLeaseTTL: cfg.DefaultLeaseTTL,
+		MaxLeaseTTL:     cfg.MaxLeaseTTL,
+	}
+	return c.api.Sys().TuneMountWithContext(ctx, path, input)
+}
+
+// mountInfo returns the mount at the given path, or nil if it does not exist.
+func (c *vaultClient) mountInfo(ctx context.Context, path string) (*vault.MountOutput, error) {
+	mounts, err := c.api.Sys().ListMountsWithContext(ctx)
+	if err != nil {
+		return nil, err
+	}
+	key := strings.TrimRight(path, "/") + "/"
+	if m, ok := mounts[key]; ok {
+		return m, nil
+	}
+	return nil, nil
+}
+
+// disableMount unmounts the secrets engine at path.
+func (c *vaultClient) disableMount(ctx context.Context, path string) error {
+	return c.api.Sys().UnmountWithContext(ctx, path)
+}
+
+// write writes data to an arbitrary path under the backend mount.
+func (c *vaultClient) write(ctx context.Context, path string, data map[string]interface{}) error {
+	_, err := c.api.Logical().WriteWithContext(ctx, path, data)
+	return err
+}
+
+// read reads an arbitrary path under the backend mount, returning nil if absent.
+func (c *vaultClient) read(ctx context.Context, path string) (map[string]interface{}, error) {
+	secret, err := c.api.Logical().ReadWithContext(ctx, path)
+	if err != nil {
+		return nil, err
+	}
+	if secret == nil {
+		return nil, nil
+	}
+	return secret.Data, nil
+}
+
+// delete removes an arbitrary path under the backend mount.
+func (c *vaultClient) delete(ctx context.Context, path string) error {
+	_, err := c.api.Logical().DeleteWithContext(ctx, path)
+	return err
+}
+
+func configPath(backend string) string {
+	return fmt.Sprintf("%s/config", strings.TrimRight(backend, "/"))
+}
+
+func rolePath(backend, name string) string {
+	return fmt.Sprintf("%s/roles/%s", strings.TrimRight(backend, "/"), name)
+}
+
+// isMountAlreadyExists reports whether the error is Vault's "path is already in
+// use" response, so callers can surface a friendlier message.
+func isMountAlreadyExists(err error) bool {
+	if err == nil {
+		return false
+	}
+	var respErr *vault.ResponseError
+	if errors.As(err, &respErr) {
+		for _, e := range respErr.Errors {
+			if strings.Contains(e, "path is already in use") {
+				return true
+			}
+		}
+	}
+	return false
+}

internal/provider/conversions.go

@@ -0,0 +1,66 @@
+package provider
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// toStringSlice coerces the list shapes Vault returns (a JSON array decodes to
+// []interface{}) into a []string. A nil or non-list value yields an empty slice.
+func toStringSlice(v interface{}) []string {
+	switch xs := v.(type) {
+	case []string:
+		return xs
+	case []interface{}:
+		out := make([]string, 0, len(xs))
+		for _, x := range xs {
+			if s, ok := x.(string); ok {
+				out = append(out, s)
+			}
+		}
+		return out
+	default:
+		return []string{}
+	}
+}
+
+// toInt64 coerces the numeric shapes Vault returns (json.Number, float64, int)
+// into an int64.
+func toInt64(v interface{}) (int64, bool) {
+	switch n := v.(type) {
+	case json.Number:
+		i, err := n.Int64()
+		if err != nil {
+			f, ferr := n.Float64()
+			if ferr != nil {
+				return 0, false
+			}
+			return int64(f), true
+		}
+		return i, true
+	case float64:
+		return int64(n), true
+	case int64:
+		return n, true
+	case int:
+		return int64(n), true
+	default:
+		return 0, false
+	}
+}
+
+// splitBackendName splits an import ID of the form "<backend>/<marker>/<name>"
+// (e.g. "arrstack/roles/all") into its backend and name parts.
+func splitBackendName(id, marker string) (backend, name string, ok bool) {
+	sep := "/" + marker + "/"
+	idx := strings.LastIndex(id, sep)
+	if idx <= 0 {
+		return "", "", false
+	}
+	backend = id[:idx]
+	name = id[idx+len(sep):]
+	if backend == "" || name == "" {
+		return "", "", false
+	}
+	return backend, name, true
+}

internal/provider/conversions_test.go

@@ -0,0 +1,69 @@
+package provider
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestToInt64(t *testing.T) {
+	cases := []struct {
+		in   interface{}
+		want int64
+		ok   bool
+	}{
+		{json.Number("42"), 42, true},
+		{json.Number("3.0"), 3, true},
+		{float64(7), 7, true},
+		{int(9), 9, true},
+		{int64(11), 11, true},
+		{"nope", 0, false},
+		{nil, 0, false},
+	}
+	for _, c := range cases {
+		got, ok := toInt64(c.in)
+		if ok != c.ok || got != c.want {
+			t.Errorf("toInt64(%v) = (%d,%v), want (%d,%v)", c.in, got, ok, c.want, c.ok)
+		}
+	}
+}
+
+func TestToStringSlice(t *testing.T) {
+	cases := []struct {
+		name string
+		in   interface{}
+		want []string
+	}{
+		{"nil", nil, []string{}},
+		{"string-slice", []string{"sonarr", "radarr"}, []string{"sonarr", "radarr"}},
+		{"iface-slice", []interface{}{"sonarr", "radarr", "prowlarr"}, []string{"sonarr", "radarr", "prowlarr"}},
+		{"mixed", []interface{}{"sonarr", 3, "prowlarr"}, []string{"sonarr", "prowlarr"}},
+		{"wrong-type", "notalist", []string{}},
+	}
+	for _, c := range cases {
+		got := toStringSlice(c.in)
+		if strings.Join(got, ",") != strings.Join(c.want, ",") {
+			t.Errorf("%s: toStringSlice(%v) = %v, want %v", c.name, c.in, got, c.want)
+		}
+	}
+}
+
+func TestSplitBackendName(t *testing.T) {
+	cases := []struct {
+		id, marker, backend, name string
+		ok                        bool
+	}{
+		{"arrstack/roles/all", "roles", "arrstack", "all", true},
+		{"team/arrstack/roles/sonarr", "roles", "team/arrstack", "sonarr", true},
+		{"arrstack/roles/", "roles", "", "", false},
+		{"/roles/all", "roles", "", "", false},
+		{"nomarker", "roles", "", "", false},
+	}
+	for _, c := range cases {
+		b, n, ok := splitBackendName(c.id, c.marker)
+		if ok != c.ok || b != c.backend || n != c.name {
+			t.Errorf("splitBackendName(%q,%q) = (%q,%q,%v), want (%q,%q,%v)",
+				c.id, c.marker, b, n, ok, c.backend, c.name, c.ok)
+		}
+	}
+}

internal/provider/provider.go

@@ -0,0 +1,100 @@
+package provider
+
+import (
+	"context"
+	"os"
+
+	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/provider"
+	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
+	"github.com/hashicorp/terraform-plugin-framework/resource"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+var _ provider.Provider = &arrstackProvider{}
+
+type arrstackProvider struct {
+	version string
+}
+
+type arrstackProviderModel struct {
+	Address types.String `tfsdk:"address"`
+	Token   types.String `tfsdk:"token"`
+}
+
+func New(version string) func() provider.Provider {
+	return func() provider.Provider {
+		return &arrstackProvider{version: version}
+	}
+}
+
+func (p *arrstackProvider) Metadata(_ context.Context, _ provider.MetadataRequest, resp *provider.MetadataResponse) {
+	// Source address is artifactapi.k8s.syd1.au.unkin.net/terraform-unkin/vault-secrets-arrstack,
+	// but resources are prefixed "arrstack_" (declare it in required_providers
+	// under the local name "arrstack").
+	resp.TypeName = "arrstack"
+	resp.Version = p.version
+}
+
+func (p *arrstackProvider) Schema(_ context.Context, _ provider.SchemaRequest, resp *provider.SchemaResponse) {
+	resp.Schema = schema.Schema{
+		Description: "Manage the arrstack dynamic secrets engine (config and roles) on HashiCorp Vault or OpenBao.",
+		Attributes: map[string]schema.Attribute{
+			"address": schema.StringAttribute{
+				Description: "Address of the Vault/OpenBao server. Falls back to the VAULT_ADDR environment variable.",
+				Optional:    true,
+			},
+			"token": schema.StringAttribute{
+				Description: "Token used to authenticate to Vault/OpenBao. Falls back to the VAULT_TOKEN environment variable.",
+				Optional:    true,
+				Sensitive:   true,
+			},
+		},
+	}
+}
+
+func (p *arrstackProvider) Configure(ctx context.Context, req provider.ConfigureRequest, resp *provider.ConfigureResponse) {
+	var config arrstackProviderModel
+	resp.Diagnostics.Append(req.Config.Get(ctx, &config)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	address := os.Getenv("VAULT_ADDR")
+	if !config.Address.IsNull() && config.Address.ValueString() != "" {
+		address = config.Address.ValueString()
+	}
+
+	token := os.Getenv("VAULT_TOKEN")
+	if !config.Token.IsNull() && config.Token.ValueString() != "" {
+		token = config.Token.ValueString()
+	}
+
+	if address == "" {
+		resp.Diagnostics.AddError(
+			"missing Vault address",
+			"Set the provider \"address\" attribute or the VAULT_ADDR environment variable.",
+		)
+		return
+	}
+
+	client, err := newVaultClient(address, token)
+	if err != nil {
+		resp.Diagnostics.AddError("failed to create Vault client", err.Error())
+		return
+	}
+
+	resp.DataSourceData = client
+	resp.ResourceData = client
+}
+
+func (p *arrstackProvider) Resources(_ context.Context) []func() resource.Resource {
+	return []func() resource.Resource{
+		NewSecretBackendResource,
+		NewSecretBackendRoleResource,
+	}
+}
+
+func (p *arrstackProvider) DataSources(_ context.Context) []func() datasource.DataSource {
+	return nil
+}

internal/provider/resource_secret_backend.go

@@ -0,0 +1,240 @@
+package provider
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/hashicorp/terraform-plugin-framework/path"
+	"github.com/hashicorp/terraform-plugin-framework/resource"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/int64default"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringdefault"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+var (
+	_ resource.Resource                = &secretBackendResource{}
+	_ resource.ResourceWithImportState = &secretBackendResource{}
+)
+
+const defaultPluginType = "vault-plugin-secrets-arrstack"
+
+const defaultBaseURL = "https://arrstack.unkin.net"
+
+type secretBackendResource struct {
+	client *vaultClient
+}
+
+type secretBackendModel struct {
+	Path                  types.String `tfsdk:"path"`
+	Plugin                types.String `tfsdk:"plugin"`
+	Description           types.String `tfsdk:"description"`
+	BaseURL               types.String `tfsdk:"base_url"`
+	AdminToken            types.String `tfsdk:"admin_token"`
+	CACert                types.String `tfsdk:"ca_cert"`
+	RequestTimeoutSeconds types.Int64  `tfsdk:"request_timeout_seconds"`
+}
+
+func NewSecretBackendResource() resource.Resource {
+	return &secretBackendResource{}
+}
+
+func (r *secretBackendResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
+	resp.TypeName = req.ProviderTypeName + "_secret_backend"
+}
+
+func (r *secretBackendResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
+	resp.Schema = schema.Schema{
+		Description: "Mounts the arrstack secrets engine and writes its connection config and seeded arrproxy admin token.",
+		Attributes: map[string]schema.Attribute{
+			"path": schema.StringAttribute{
+				Description: "Mount path for the arrstack secrets engine (e.g. \"arrstack\").",
+				Required:    true,
+				PlanModifiers: []planmodifier.String{
+					stringplanmodifier.RequiresReplace(),
+				},
+			},
+			"plugin": schema.StringAttribute{
+				Description: "Registered plugin name/type to mount.",
+				Optional:    true,
+				Computed:    true,
+				Default:     stringdefault.StaticString(defaultPluginType),
+				PlanModifiers: []planmodifier.String{
+					stringplanmodifier.RequiresReplace(),
+				},
+			},
+			"description": schema.StringAttribute{
+				Description: "Human-readable description of the mount.",
+				Optional:    true,
+				Computed:    true,
+				Default:     stringdefault.StaticString(""),
+			},
+			"base_url": schema.StringAttribute{
+				Description: "Base URL of the arrproxy front door (e.g. https://arrstack.unkin.net).",
+				Optional:    true,
+				Computed:    true,
+				Default:     stringdefault.StaticString(defaultBaseURL),
+			},
+			"admin_token": schema.StringAttribute{
+				Description: "arrproxy admin token the engine authenticates with. Write-only; never read back.",
+				Required:    true,
+				Sensitive:   true,
+			},
+			"ca_cert": schema.StringAttribute{
+				Description: "PEM CA certificate that signed the arrproxy server's TLS certificate (optional; omit to use the system trust store). Write-only; never read back.",
+				Optional:    true,
+				Sensitive:   true,
+			},
+			"request_timeout_seconds": schema.Int64Attribute{
+				Description: "HTTP timeout in seconds for calls from the plugin to arrproxy.",
+				Optional:    true,
+				Computed:    true,
+				Default:     int64default.StaticInt64(30),
+			},
+		},
+	}
+}
+
+func (r *secretBackendResource) Configure(_ context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
+	if req.ProviderData == nil {
+		return
+	}
+	client, ok := req.ProviderData.(*vaultClient)
+	if !ok {
+		resp.Diagnostics.AddError("unexpected provider data type", fmt.Sprintf("got %T", req.ProviderData))
+		return
+	}
+	r.client = client
+}
+
+func (r *secretBackendResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	var plan secretBackendModel
+	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	mountPath := strings.Trim(plan.Path.ValueString(), "/")
+
+	err := r.client.enableMount(ctx, mountPath, plan.Plugin.ValueString(), plan.Description.ValueString(), mountConfig{})
+	if err != nil {
+		if isMountAlreadyExists(err) {
+			resp.Diagnostics.AddError(
+				"mount path already in use",
+				fmt.Sprintf("A secrets engine is already mounted at %q. Import it or choose another path.", mountPath),
+			)
+			return
+		}
+		resp.Diagnostics.AddError("failed to enable arrstack secrets engine", err.Error())
+		return
+	}
+
+	if err := r.client.write(ctx, configPath(mountPath), r.configData(plan)); err != nil {
+		// Roll back the mount so we don't leave a half-configured engine.
+		_ = r.client.disableMount(ctx, mountPath)
+		resp.Diagnostics.AddError("failed to write arrstack config", err.Error())
+		return
+	}
+
+	plan.Path = types.StringValue(mountPath)
+	resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
+}
+
+func (r *secretBackendResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
+	var state secretBackendModel
+	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	mountPath := strings.Trim(state.Path.ValueString(), "/")
+
+	mount, err := r.client.mountInfo(ctx, mountPath)
+	if err != nil {
+		resp.Diagnostics.AddError("failed to read mount", err.Error())
+		return
+	}
+	if mount == nil {
+		resp.State.RemoveResource(ctx)
+		return
+	}
+	state.Description = types.StringValue(mount.Description)
+	if mount.Type != "" {
+		state.Plugin = types.StringValue(mount.Type)
+	}
+
+	cfg, err := r.client.read(ctx, configPath(mountPath))
+	if err != nil {
+		resp.Diagnostics.AddError("failed to read arrstack config", err.Error())
+		return
+	}
+	if cfg != nil {
+		if v, ok := cfg["base_url"].(string); ok {
+			state.BaseURL = types.StringValue(v)
+		}
+		if n, ok := toInt64(cfg["request_timeout_seconds"]); ok {
+			state.RequestTimeoutSeconds = types.Int64Value(n)
+		}
+	}
+	// admin_token and ca_cert are never returned by the backend; preserve the
+	// state values.
+
+	resp.Diagnostics.Append(resp.State.Set(ctx, state)...)
+}
+
+func (r *secretBackendResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
+	var plan, state secretBackendModel
+	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
+	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	mountPath := strings.Trim(state.Path.ValueString(), "/")
+
+	if !plan.Description.Equal(state.Description) {
+		if err := r.client.tuneMount(ctx, mountPath, plan.Description.ValueString(), mountConfig{}); err != nil {
+			resp.Diagnostics.AddError("failed to tune mount description", err.Error())
+			return
+		}
+	}
+
+	if err := r.client.write(ctx, configPath(mountPath), r.configData(plan)); err != nil {
+		resp.Diagnostics.AddError("failed to update arrstack config", err.Error())
+		return
+	}
+
+	plan.Path = types.StringValue(mountPath)
+	resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
+}
+
+func (r *secretBackendResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	var state secretBackendModel
+	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	if err := r.client.disableMount(ctx, strings.Trim(state.Path.ValueString(), "/")); err != nil {
+		resp.Diagnostics.AddError("failed to disable arrstack secrets engine", err.Error())
+		return
+	}
+}
+
+func (r *secretBackendResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
+	resource.ImportStatePassthroughID(ctx, path.Root("path"), req, resp)
+}
+
+func (r *secretBackendResource) configData(m secretBackendModel) map[string]interface{} {
+	data := map[string]interface{}{
+		"base_url":                m.BaseURL.ValueString(),
+		"admin_token":             m.AdminToken.ValueString(),
+		"request_timeout_seconds": m.RequestTimeoutSeconds.ValueInt64(),
+	}
+	if !m.CACert.IsNull() && !m.CACert.IsUnknown() {
+		data["ca_cert"] = m.CACert.ValueString()
+	}
+	return data
+}

internal/provider/resource_secret_backend_role.go

@@ -0,0 +1,230 @@
+package provider
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/path"
+	"github.com/hashicorp/terraform-plugin-framework/resource"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+var (
+	_ resource.Resource                = &secretBackendRoleResource{}
+	_ resource.ResourceWithImportState = &secretBackendRoleResource{}
+)
+
+type secretBackendRoleResource struct {
+	client *vaultClient
+}
+
+type secretBackendRoleModel struct {
+	Backend types.String `tfsdk:"backend"`
+	Name    types.String `tfsdk:"name"`
+	Apps    types.List   `tfsdk:"apps"`
+	TTL     types.Int64  `tfsdk:"ttl"`
+	MaxTTL  types.Int64  `tfsdk:"max_ttl"`
+}
+
+func NewSecretBackendRoleResource() resource.Resource {
+	return &secretBackendRoleResource{}
+}
+
+func (r *secretBackendRoleResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
+	resp.TypeName = req.ProviderTypeName + "_secret_backend_role"
+}
+
+func (r *secretBackendRoleResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
+	resp.Schema = schema.Schema{
+		Description: "Manages a role on the arrstack secrets engine that mints short-lived scoped arrproxy API keys.",
+		Attributes: map[string]schema.Attribute{
+			"backend": schema.StringAttribute{
+				Description: "Mount path of the arrstack secrets engine.",
+				Required:    true,
+				PlanModifiers: []planmodifier.String{
+					stringplanmodifier.RequiresReplace(),
+				},
+			},
+			"name": schema.StringAttribute{
+				Description: "Name of the role.",
+				Required:    true,
+				PlanModifiers: []planmodifier.String{
+					stringplanmodifier.RequiresReplace(),
+				},
+			},
+			"apps": schema.ListAttribute{
+				Description: "arr apps a generated key may access (subset of sonarr, radarr, prowlarr).",
+				ElementType: types.StringType,
+				Required:    true,
+			},
+			"ttl": schema.Int64Attribute{
+				Description: "Default lease TTL in seconds for keys generated from this role.",
+				Optional:    true,
+			},
+			"max_ttl": schema.Int64Attribute{
+				Description: "Maximum lease TTL in seconds for keys generated from this role.",
+				Optional:    true,
+			},
+		},
+	}
+}
+
+func (r *secretBackendRoleResource) Configure(_ context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
+	if req.ProviderData == nil {
+		return
+	}
+	client, ok := req.ProviderData.(*vaultClient)
+	if !ok {
+		resp.Diagnostics.AddError("unexpected provider data type", fmt.Sprintf("got %T", req.ProviderData))
+		return
+	}
+	r.client = client
+}
+
+func (r *secretBackendRoleResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	var plan secretBackendRoleModel
+	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	data, diags := roleData(ctx, plan)
+	resp.Diagnostics.Append(diags...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	if err := r.client.write(ctx, rolePath(plan.Backend.ValueString(), plan.Name.ValueString()), data); err != nil {
+		resp.Diagnostics.AddError("failed to create arrstack role", err.Error())
+		return
+	}
+	resp.Diagnostics.Append(r.readInto(ctx, &plan)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
+}
+
+func (r *secretBackendRoleResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
+	var state secretBackendRoleModel
+	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	role, err := r.client.read(ctx, rolePath(state.Backend.ValueString(), state.Name.ValueString()))
+	if err != nil {
+		resp.Diagnostics.AddError("failed to read arrstack role", err.Error())
+		return
+	}
+	if role == nil {
+		resp.State.RemoveResource(ctx)
+		return
+	}
+	resp.Diagnostics.Append(applyRoleData(&state, role)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	resp.Diagnostics.Append(resp.State.Set(ctx, state)...)
+}
+
+func (r *secretBackendRoleResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
+	var plan secretBackendRoleModel
+	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	data, diags := roleData(ctx, plan)
+	resp.Diagnostics.Append(diags...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	if err := r.client.write(ctx, rolePath(plan.Backend.ValueString(), plan.Name.ValueString()), data); err != nil {
+		resp.Diagnostics.AddError("failed to update arrstack role", err.Error())
+		return
+	}
+	resp.Diagnostics.Append(r.readInto(ctx, &plan)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
+}
+
+func (r *secretBackendRoleResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	var state secretBackendRoleModel
+	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+	if err := r.client.delete(ctx, rolePath(state.Backend.ValueString(), state.Name.ValueString())); err != nil {
+		resp.Diagnostics.AddError("failed to delete arrstack role", err.Error())
+		return
+	}
+}
+
+func (r *secretBackendRoleResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
+	backend, name, ok := splitBackendName(req.ID, "roles")
+	if !ok {
+		resp.Diagnostics.AddError(
+			"invalid import ID",
+			fmt.Sprintf("expected \"<backend>/roles/<name>\", got %q", req.ID),
+		)
+		return
+	}
+	resp.Diagnostics.Append(resp.State.SetAttribute(ctx, path.Root("backend"), backend)...)
+	resp.Diagnostics.Append(resp.State.SetAttribute(ctx, path.Root("name"), name)...)
+}
+
+func (r *secretBackendRoleResource) readInto(ctx context.Context, m *secretBackendRoleModel) diag.Diagnostics {
+	var diags diag.Diagnostics
+	role, err := r.client.read(ctx, rolePath(m.Backend.ValueString(), m.Name.ValueString()))
+	if err != nil {
+		diags.AddError("failed to read back arrstack role", err.Error())
+		return diags
+	}
+	if role == nil {
+		diags.AddError("role missing after write", "the role was not found immediately after being written")
+		return diags
+	}
+	return applyRoleData(m, role)
+}
+
+func roleData(ctx context.Context, m secretBackendRoleModel) (map[string]interface{}, diag.Diagnostics) {
+	var diags diag.Diagnostics
+	data := map[string]interface{}{}
+
+	if !m.Apps.IsNull() && !m.Apps.IsUnknown() {
+		var apps []string
+		diags.Append(m.Apps.ElementsAs(ctx, &apps, false)...)
+		data["apps"] = apps
+	}
+	if !m.TTL.IsNull() && !m.TTL.IsUnknown() {
+		data["ttl"] = m.TTL.ValueInt64()
+	}
+	if !m.MaxTTL.IsNull() && !m.MaxTTL.IsUnknown() {
+		data["max_ttl"] = m.MaxTTL.ValueInt64()
+	}
+	return data, diags
+}
+
+func applyRoleData(m *secretBackendRoleModel, role map[string]interface{}) diag.Diagnostics {
+	var diags diag.Diagnostics
+
+	apps := toStringSlice(role["apps"])
+	appList, appDiags := types.ListValueFrom(context.Background(), types.StringType, apps)
+	diags.Append(appDiags...)
+	m.Apps = appList
+
+	if n, ok := toInt64(role["ttl"]); ok && n != 0 {
+		m.TTL = types.Int64Value(n)
+	} else if m.TTL.IsUnknown() {
+		m.TTL = types.Int64Null()
+	}
+	if n, ok := toInt64(role["max_ttl"]); ok && n != 0 {
+		m.MaxTTL = types.Int64Value(n)
+	} else if m.MaxTTL.IsUnknown() {
+		m.MaxTTL = types.Int64Null()
+	}
+	return diags
+}

internal/provider/resource_secret_backend_role_test.go

@@ -0,0 +1,104 @@
+package provider
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+func listOf(t *testing.T, vals ...string) types.List {
+	t.Helper()
+	l, diags := types.ListValueFrom(context.Background(), types.StringType, vals)
+	if diags.HasError() {
+		t.Fatalf("building list: %v", diags)
+	}
+	return l
+}
+
+func TestRoleDataOmitsUnsetTTLs(t *testing.T) {
+	m := secretBackendRoleModel{
+		Apps:   listOf(t, "sonarr", "radarr", "prowlarr"),
+		TTL:    types.Int64Null(),
+		MaxTTL: types.Int64Null(),
+	}
+	data, diags := roleData(context.Background(), m)
+	if diags.HasError() {
+		t.Fatalf("roleData: %v", diags)
+	}
+	apps, ok := data["apps"].([]string)
+	if !ok || len(apps) != 3 || apps[0] != "sonarr" {
+		t.Errorf("apps = %v, want [sonarr radarr prowlarr]", data["apps"])
+	}
+	if _, ok := data["ttl"]; ok {
+		t.Errorf("ttl should be omitted when null")
+	}
+	if _, ok := data["max_ttl"]; ok {
+		t.Errorf("max_ttl should be omitted when null")
+	}
+}
+
+func TestRoleDataIncludesTTLs(t *testing.T) {
+	m := secretBackendRoleModel{
+		Apps:   listOf(t, "prowlarr"),
+		TTL:    types.Int64Value(60),
+		MaxTTL: types.Int64Value(86400),
+	}
+	data, diags := roleData(context.Background(), m)
+	if diags.HasError() {
+		t.Fatalf("roleData: %v", diags)
+	}
+	if data["ttl"] != int64(60) {
+		t.Errorf("ttl = %v, want 60", data["ttl"])
+	}
+	if data["max_ttl"] != int64(86400) {
+		t.Errorf("max_ttl = %v, want 86400", data["max_ttl"])
+	}
+}
+
+func TestApplyRoleDataMapsEngineResponse(t *testing.T) {
+	// Shape mirrors what the engine's role read returns via the Vault API.
+	role := map[string]interface{}{
+		"apps":    []interface{}{"sonarr", "radarr", "prowlarr"},
+		"ttl":     json.Number("60"),
+		"max_ttl": json.Number("86400"),
+	}
+	var m secretBackendRoleModel
+	m.TTL = types.Int64Null()
+	m.MaxTTL = types.Int64Null()
+	if diags := applyRoleData(&m, role); diags.HasError() {
+		t.Fatalf("applyRoleData: %v", diags)
+	}
+	var apps []string
+	m.Apps.ElementsAs(context.Background(), &apps, false)
+	if len(apps) != 3 || apps[2] != "prowlarr" {
+		t.Errorf("apps = %v, want [sonarr radarr prowlarr]", apps)
+	}
+	if m.TTL.ValueInt64() != 60 || m.MaxTTL.ValueInt64() != 86400 {
+		t.Errorf("ttl/max_ttl = %d/%d, want 60/86400", m.TTL.ValueInt64(), m.MaxTTL.ValueInt64())
+	}
+}
+
+func TestApplyRoleDataZeroTTLLeavesNull(t *testing.T) {
+	// The engine returns 0 for an unset TTL, which must not clobber the null
+	// model value into a spurious 0.
+	role := map[string]interface{}{
+		"apps":    []interface{}{"sonarr"},
+		"ttl":     json.Number("0"),
+		"max_ttl": json.Number("0"),
+	}
+	m := secretBackendRoleModel{
+		TTL:    types.Int64Null(),
+		MaxTTL: types.Int64Null(),
+	}
+	if diags := applyRoleData(&m, role); diags.HasError() {
+		t.Fatalf("applyRoleData: %v", diags)
+	}
+	if !m.TTL.IsNull() {
+		t.Errorf("ttl = %v, want null", m.TTL)
+	}
+	if !m.MaxTTL.IsNull() {
+		t.Errorf("max_ttl = %v, want null", m.MaxTTL)
+	}
+}

internal/provider/resource_secret_backend_test.go

@@ -0,0 +1,37 @@
+package provider
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+func TestBackendConfigData(t *testing.T) {
+	r := &secretBackendResource{}
+
+	m := secretBackendModel{
+		BaseURL:               types.StringValue("https://arrstack.example.com"),
+		AdminToken:            types.StringValue("arrsvc_secret"),
+		RequestTimeoutSeconds: types.Int64Value(15),
+		CACert:                types.StringNull(),
+	}
+	data := r.configData(m)
+	if data["base_url"] != "https://arrstack.example.com" {
+		t.Errorf("base_url = %v", data["base_url"])
+	}
+	if data["admin_token"] != "arrsvc_secret" {
+		t.Errorf("admin_token = %v", data["admin_token"])
+	}
+	if data["request_timeout_seconds"] != int64(15) {
+		t.Errorf("request_timeout_seconds = %v, want 15", data["request_timeout_seconds"])
+	}
+	if _, ok := data["ca_cert"]; ok {
+		t.Errorf("ca_cert should be omitted when null")
+	}
+
+	m.CACert = types.StringValue("-----BEGIN CERTIFICATE-----")
+	data = r.configData(m)
+	if data["ca_cert"] != "-----BEGIN CERTIFICATE-----" {
+		t.Errorf("ca_cert = %v", data["ca_cert"])
+	}
+}