Files
llmgw/terraform-provider-llmgw/internal/provider/resource_model.go
T
Ilker ManapandClaude Opus 5.5 11b5d44702 A Terraform provider for llmgw: models, quotas and guard attachments through the admin API
terraform-provider-llmgw/ is a module of its own, built on
terraform-plugin-framework, so the gateway does not carry its dependencies.
llmgw_model is a model added at runtime: scaling, class, owner and adapters
change in place, anything else replaces it; the definition is kept as
written rather than as the catalog filled it in. llmgw_quota and
llmgw_guard_attachment keep the scope as written beside the ID it resolved
to, and import by that ID. Data sources llmgw_models and llmgw_nodes.

The client lists every endpoint it calls and refuses any other; a test
checks each, and every field it sends and reads, against
docs/admin-api.openapi.json, so a change to the admin API that breaks the
provider fails here. Acceptance tests run Terraform against an admin API in
memory when TF_ACC is set. CI vets and tests the module.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-05 00:04:35 +02:00

425 lines
19 KiB
Go

package provider
import (
"context"
"github.com/hashicorp/terraform-plugin-framework/diag"
"github.com/hashicorp/terraform-plugin-framework/resource"
"github.com/hashicorp/terraform-plugin-framework/resource/schema"
"github.com/hashicorp/terraform-plugin-framework/resource/schema/int64planmodifier"
"github.com/hashicorp/terraform-plugin-framework/resource/schema/listplanmodifier"
"github.com/hashicorp/terraform-plugin-framework/resource/schema/objectplanmodifier"
"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"
"gitea.mynodes.xyz/ilker/llmgw/terraform-provider-llmgw/internal/client"
)
// The model resource is a catalog entry added at runtime, as `llmgw ctl
// model add` adds one.
//
// What the admin API can change in place — scaling, class, owner, adapters —
// is changed in place; anything else in the definition replaces the model,
// because the API has no way to edit it and removing and adding is what an
// operator would do by hand. A replacement stops the model's replicas.
//
// The state keeps the definition as it was written rather than as the
// catalog filled it in, so a profile written without tp does not differ on
// every plan from one the catalog gave tp 1. Only what can change in place is
// read back from the cluster, where a change made from a terminal shows as a
// difference to put right. A model removed from the cluster is planned again.
type modelResource struct{ c *client.Client }
func newModelResource() resource.Resource { return &modelResource{} }
type modelResourceModel struct {
ID types.String `tfsdk:"id"`
Name types.String `tfsdk:"name"`
Source types.String `tfsdk:"source"`
Description types.String `tfsdk:"description"`
Aliases types.List `tfsdk:"aliases"`
Fallbacks types.List `tfsdk:"fallbacks"`
RoutingProfile types.String `tfsdk:"routing_profile"`
ContextLength types.Int64 `tfsdk:"context_length"`
MaxOutput types.Int64 `tfsdk:"max_output"`
Class types.String `tfsdk:"class"`
Owner types.String `tfsdk:"owner"`
OwnerID types.String `tfsdk:"owner_id"`
Capabilities *capabilitiesModel `tfsdk:"capabilities"`
External *externalModel `tfsdk:"external"`
Profiles []profileModel `tfsdk:"profiles"`
Scaling *scalingModel `tfsdk:"scaling"`
Adapters []adapterModel `tfsdk:"adapters"`
}
type capabilitiesModel struct {
Tools types.Bool `tfsdk:"tools"`
Vision types.Bool `tfsdk:"vision"`
Embeddings types.Bool `tfsdk:"embeddings"`
}
type externalModel struct {
URL types.String `tfsdk:"url"`
Model types.String `tfsdk:"model"`
APIKeyFile types.String `tfsdk:"api_key_file"`
}
type profileModel struct {
Name types.String `tfsdk:"name"`
Engine types.String `tfsdk:"engine"`
GPUClass types.String `tfsdk:"gpu_class"`
TP types.Int64 `tfsdk:"tp"`
PP types.Int64 `tfsdk:"pp"`
GPUsPerNode types.Int64 `tfsdk:"gpus_per_node"`
Nodes types.Int64 `tfsdk:"nodes"`
Args types.List `tfsdk:"args"`
Env types.Map `tfsdk:"env"`
MinMemoryGB types.Int64 `tfsdk:"min_memory_gb"`
CPUCores types.Int64 `tfsdk:"cpu_cores"`
MinDiskGB types.Int64 `tfsdk:"min_disk_gb"`
NodeSelector types.Map `tfsdk:"node_selector"`
Weight types.Float64 `tfsdk:"weight"`
Priority types.Int64 `tfsdk:"priority"`
StartupTimeout types.String `tfsdk:"startup_timeout"`
}
type scalingModel struct {
Min types.Int64 `tfsdk:"min"`
Max types.Int64 `tfsdk:"max"`
IdleTimeout types.String `tfsdk:"idle_timeout"`
}
type adapterModel struct {
Name types.String `tfsdk:"name"`
Source types.String `tfsdk:"source"`
Scale types.Float64 `tfsdk:"scale"`
}
func (r *modelResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
resp.TypeName = req.ProviderTypeName + "_model"
}
func (r *modelResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
replace := []planmodifier.String{stringplanmodifier.RequiresReplace()}
replaceInt := []planmodifier.Int64{int64planmodifier.RequiresReplace()}
replaceList := []planmodifier.List{listplanmodifier.RequiresReplace()}
replaceObject := []planmodifier.Object{objectplanmodifier.RequiresReplace()}
str := func(desc string) schema.StringAttribute {
return schema.StringAttribute{Optional: true, Description: desc}
}
num := func(desc string) schema.Int64Attribute {
return schema.Int64Attribute{Optional: true, Description: desc}
}
strMap := func(desc string) schema.MapAttribute {
return schema.MapAttribute{Optional: true, ElementType: types.StringType, Description: desc}
}
resp.Schema = schema.Schema{
Description: "A model in the catalog, added at runtime and kept in the store, as `llmgw ctl model add` adds one. " +
"Scaling, class, owner and adapters change in place; any other change replaces the model, stopping its replicas. " +
"A model declared in the control plane's configuration cannot be managed here.",
Attributes: map[string]schema.Attribute{
"id": schema.StringAttribute{Computed: true, Description: "The model's name.",
PlanModifiers: []planmodifier.String{stringplanmodifier.UseStateForUnknown()}},
"name": schema.StringAttribute{Required: true, PlanModifiers: replace,
Description: "The name clients ask for."},
"source": schema.StringAttribute{Optional: true, PlanModifiers: replace,
Description: "Where the weights are: a path on the nodes, an https URL, or a registry repository. Absent for an external model."},
"description": schema.StringAttribute{Optional: true, PlanModifiers: replace,
Description: "What the model is for."},
"aliases": schema.ListAttribute{Optional: true, ElementType: types.StringType, PlanModifiers: replaceList,
Description: "Other names it answers to."},
"fallbacks": schema.ListAttribute{Optional: true, ElementType: types.StringType, PlanModifiers: replaceList,
Description: "Models tried in order when this one cannot answer."},
"routing_profile": schema.StringAttribute{Optional: true, PlanModifiers: replace,
Description: "The routing profile, from the router's configuration."},
"context_length": schema.Int64Attribute{Optional: true, PlanModifiers: replaceInt,
Description: "The context window, in tokens."},
"max_output": schema.Int64Attribute{Optional: true, PlanModifiers: replaceInt,
Description: "The most tokens one answer may have."},
"class": schema.StringAttribute{Optional: true,
Description: "The capacity class: critical, standard or opportunistic. Absent is what the scaling implies."},
"owner": schema.StringAttribute{Optional: true,
Description: "The part of the tenancy tree the model's capacity counts against: org:NAME, team:ORG/TEAM, " +
"project:ORG/TEAM/PROJECT, or their IDs. Absent is shared."},
"owner_id": schema.StringAttribute{Computed: true,
Description: "The owner as the cluster records it, scope:ID."},
"capabilities": schema.SingleNestedAttribute{Optional: true, PlanModifiers: replaceObject,
Description: "What the model can do beyond chat.",
Attributes: map[string]schema.Attribute{
"tools": schema.BoolAttribute{Optional: true, Description: "It calls tools."},
"vision": schema.BoolAttribute{Optional: true, Description: "It reads images."},
"embeddings": schema.BoolAttribute{Optional: true, Description: "It answers /v1/embeddings."},
}},
"external": schema.SingleNestedAttribute{Optional: true, PlanModifiers: replaceObject,
Description: "A model served by a provider outside the cluster, in place of source and profiles.",
Attributes: map[string]schema.Attribute{
"url": schema.StringAttribute{Required: true, Description: "The provider's API, https://api.openai.com/v1."},
"model": schema.StringAttribute{Required: true, Description: "The provider's name for the model."},
"api_key_file": schema.StringAttribute{Optional: true, Description: "The provider's key: a file on the control plane, or an env: or vault: reference."},
}},
"profiles": schema.ListNestedAttribute{Optional: true, PlanModifiers: replaceList,
Description: "How the model runs: one profile per kind of node, tried in order. " +
"What is left out takes the catalog's default, as in server.yaml.",
NestedObject: schema.NestedAttributeObject{Attributes: map[string]schema.Attribute{
"name": str("The profile's name."),
"engine": str("vllm, sglang or llamacpp; vllm when absent."),
"gpu_class": str("The GPU class it runs on, h100-80g; absent runs on CPUs."),
"tp": num("Tensor parallelism."),
"pp": num("Pipeline parallelism."),
"gpus_per_node": num("GPUs on each node."),
"nodes": num("Nodes one replica spans."),
"args": schema.ListAttribute{Optional: true, ElementType: types.StringType, Description: "Arguments added to the engine's."},
"env": strMap("Environment for the engine."),
"min_memory_gb": num("Host memory one replica reserves, in GB."),
"cpu_cores": num("CPU cores one replica without a GPU computes on."),
"min_disk_gb": num("Free disk a node needs for the weights, in GB."),
"node_selector": strMap("Labels a node must have."),
"weight": schema.Float64Attribute{Optional: true, Description: "The share of requests this profile's replicas take."},
"priority": num("Placement order among profiles."),
"startup_timeout": str("How long a replica may take to start, 20m when absent."),
}},
},
"scaling": schema.SingleNestedAttribute{Optional: true,
Description: "How many replicas run. Absent is none: the model is in the catalog and not running. " +
"Changes in place.",
Attributes: map[string]schema.Attribute{
"min": schema.Int64Attribute{Optional: true, Computed: true, Description: "Replicas kept running; 0 is on demand."},
"max": schema.Int64Attribute{Optional: true, Computed: true, Description: "The most replicas; min when absent."},
"idle_timeout": schema.StringAttribute{Optional: true, Computed: true,
Description: "How long an on-demand model may go unasked-for before it is stopped, 30m; the cluster's default when absent."},
}},
"adapters": schema.ListNestedAttribute{Optional: true,
Description: "LoRA adapters it serves, each a name clients ask for. Changes in place; each new file is checked first.",
NestedObject: schema.NestedAttributeObject{Attributes: map[string]schema.Attribute{
"name": schema.StringAttribute{Required: true, Description: "The name clients ask for."},
"source": schema.StringAttribute{Required: true, Description: "Where the adapter's file is."},
"scale": schema.Float64Attribute{Optional: true, Description: "How strongly it applies, 1 when absent."},
}},
},
},
}
}
func (r *modelResource) Configure(_ context.Context, req resource.ConfigureRequest, _ *resource.ConfigureResponse) {
if c, ok := clientFrom(req.ProviderData); ok {
r.c = c
}
}
// definition is the model to add, from a plan. The owner is left out: it is
// set afterwards through its own endpoint, which resolves a path to an ID.
func definition(ctx context.Context, p modelResourceModel, diags *diag.Diagnostics) client.Model {
m := client.Model{
Name: p.Name.ValueString(), Source: p.Source.ValueString(), Description: p.Description.ValueString(),
Aliases: listOf(ctx, p.Aliases, diags), Fallbacks: listOf(ctx, p.Fallbacks, diags),
RoutingProfile: p.RoutingProfile.ValueString(), ContextLength: p.ContextLength.ValueInt64(),
MaxOutput: p.MaxOutput.ValueInt64(), Class: p.Class.ValueString(),
Adapters: adapters(p.Adapters),
}
if c := p.Capabilities; c != nil {
m.Capabilities = &client.Capabilities{Tools: c.Tools.ValueBool(), Vision: c.Vision.ValueBool(), Embeddings: c.Embeddings.ValueBool()}
}
if e := p.External; e != nil {
m.External = &client.External{URL: e.URL.ValueString(), Model: e.Model.ValueString(), APIKeyFile: e.APIKeyFile.ValueString()}
}
for _, pr := range p.Profiles {
m.Profiles = append(m.Profiles, client.Profile{
Name: pr.Name.ValueString(), Engine: pr.Engine.ValueString(), GPUClass: pr.GPUClass.ValueString(),
TP: pr.TP.ValueInt64(), PP: pr.PP.ValueInt64(), GPUsPerNode: pr.GPUsPerNode.ValueInt64(), Nodes: pr.Nodes.ValueInt64(),
Args: listOf(ctx, pr.Args, diags), Env: mapOf(ctx, pr.Env, diags),
MinMemoryGB: pr.MinMemoryGB.ValueInt64(), CPUCores: pr.CPUCores.ValueInt64(), MinDiskGB: pr.MinDiskGB.ValueInt64(),
NodeSelector: mapOf(ctx, pr.NodeSelector, diags), Weight: pr.Weight.ValueFloat64(), Priority: pr.Priority.ValueInt64(),
StartupTimeout: duration(pr.StartupTimeout, "startup_timeout", diags),
})
}
m.Scaling = client.Scaling(scaleRequest(p.Scaling, diags))
return m
}
func adapters(in []adapterModel) []client.Adapter {
var out []client.Adapter
for _, a := range in {
out = append(out, client.Adapter{Name: a.Name.ValueString(), Source: a.Source.ValueString(), Scale: a.Scale.ValueFloat64()})
}
return out
}
// scaleRequest is the scaling a plan asks for. What is unknown is left for
// the cluster to fill in: a max not written follows min.
func scaleRequest(s *scalingModel, diags *diag.Diagnostics) client.ScaleRequest {
if s == nil {
return client.ScaleRequest{}
}
return client.ScaleRequest{Min: s.Min.ValueInt64(), Max: s.Max.ValueInt64(),
IdleTimeout: duration(s.IdleTimeout, "scaling.idle_timeout", diags)}
}
// refresh takes what can change in place from the cluster's copy. adopt is
// set when reading: a scaling block the configuration left out is taken
// from the cluster when the cluster has one, so a model scaled from a
// terminal shows the difference.
func refresh(m client.Model, st *modelResourceModel, adopt bool) {
st.ID = types.StringValue(m.Name)
switch {
case st.Scaling != nil:
st.Scaling.Min = types.Int64Value(m.Scaling.Min)
st.Scaling.Max = types.Int64Value(m.Scaling.Max)
st.Scaling.IdleTimeout = keepDuration(st.Scaling.IdleTimeout, m.Scaling.IdleTimeout)
case adopt && m.Scaling != (client.Scaling{}):
st.Scaling = &scalingModel{Min: types.Int64Value(m.Scaling.Min), Max: types.Int64Value(m.Scaling.Max),
IdleTimeout: types.StringValue(m.Scaling.IdleTimeout.String())}
}
st.Class = strOrNull(m.Class)
if m.Owner != st.OwnerID.ValueString() {
st.Owner = strOrNull(m.Owner)
}
st.OwnerID = strOrNull(m.Owner)
switch {
case len(m.Adapters) > 0:
st.Adapters = nil
for _, a := range m.Adapters {
st.Adapters = append(st.Adapters, adapterModel{Name: types.StringValue(a.Name),
Source: types.StringValue(a.Source), Scale: floatOrNull(a.Scale)})
}
case st.Adapters != nil:
st.Adapters = []adapterModel{}
}
}
func (r *modelResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
var plan modelResourceModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
if resp.Diagnostics.HasError() {
return
}
m := definition(ctx, plan, &resp.Diagnostics)
if resp.Diagnostics.HasError() {
return
}
name := m.Name
if err := r.c.AddModel(ctx, m); err != nil {
resp.Diagnostics.AddError("Adding the model "+name, err.Error())
return
}
plan.OwnerID = types.StringNull()
if owner := plan.Owner.ValueString(); owner != "" {
id, err := r.c.SetOwner(ctx, name, owner)
if err != nil {
// Taken out again rather than left half made: Terraform would
// not know it exists, and the next apply would fail on the name.
_ = r.c.RemoveModel(ctx, name)
resp.Diagnostics.AddError("Setting the owner of "+name, err.Error())
return
}
plan.OwnerID = strOrNull(id)
}
got, err := r.c.Model(ctx, name)
if err != nil {
resp.Diagnostics.AddError("Reading the model "+name+" back", err.Error())
return
}
refresh(got, &plan, false)
resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
}
func (r *modelResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
var st modelResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &st)...)
if resp.Diagnostics.HasError() {
return
}
m, err := r.c.Model(ctx, st.Name.ValueString())
if client.IsNotFound(err) {
resp.State.RemoveResource(ctx)
return
}
if err != nil {
resp.Diagnostics.AddError("Reading the model "+st.Name.ValueString(), err.Error())
return
}
refresh(m, &st, true)
resp.Diagnostics.Append(resp.State.Set(ctx, &st)...)
}
func (r *modelResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
var plan, st modelResourceModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
resp.Diagnostics.Append(req.State.Get(ctx, &st)...)
if resp.Diagnostics.HasError() {
return
}
name := plan.Name.ValueString()
want, had := scaleRequest(plan.Scaling, &resp.Diagnostics), scaleRequest(st.Scaling, &resp.Diagnostics)
if resp.Diagnostics.HasError() {
return
}
if want != had || (plan.Scaling == nil) != (st.Scaling == nil) {
if err := r.c.Scale(ctx, name, want); err != nil {
resp.Diagnostics.AddError("Scaling "+name, err.Error())
return
}
}
if !plan.Class.Equal(st.Class) {
if err := r.c.SetClass(ctx, name, plan.Class.ValueString()); err != nil {
resp.Diagnostics.AddError("Setting the class of "+name, err.Error())
return
}
}
plan.OwnerID = st.OwnerID
if !plan.Owner.Equal(st.Owner) {
id, err := r.c.SetOwner(ctx, name, plan.Owner.ValueString())
if err != nil {
resp.Diagnostics.AddError("Setting the owner of "+name, err.Error())
return
}
plan.OwnerID = strOrNull(id)
}
if !sameAdapters(plan.Adapters, st.Adapters) {
if err := r.c.SetAdapters(ctx, name, adapters(plan.Adapters)); err != nil {
resp.Diagnostics.AddError("Setting the adapters of "+name, err.Error())
return
}
}
got, err := r.c.Model(ctx, name)
if err != nil {
resp.Diagnostics.AddError("Reading the model "+name+" back", err.Error())
return
}
refresh(got, &plan, false)
resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
}
func sameAdapters(a, b []adapterModel) bool {
if len(a) != len(b) {
return false
}
for i := range a {
if !a[i].Name.Equal(b[i].Name) || !a[i].Source.Equal(b[i].Source) || a[i].Scale.ValueFloat64() != b[i].Scale.ValueFloat64() {
return false
}
}
return true
}
func (r *modelResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
var st modelResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &st)...)
if resp.Diagnostics.HasError() {
return
}
name := st.Name.ValueString()
if err := r.c.RemoveModel(ctx, name); err != nil {
// The API refuses removing a model that is not there with the same
// status as one it may not remove; asking tells them apart, and one
// already gone is what deleting wanted.
if _, gerr := r.c.Model(ctx, name); client.IsNotFound(gerr) {
return
}
resp.Diagnostics.AddError("Removing the model "+name, err.Error())
}
}