install: cluster settings — ingress class, domain, storage, cert-manager issuer

Some modules need cluster-specific install values (ingress class, base
domain, storage class, TLS issuer). These are properties of the CLUSTER,
not per module, so set them once and every install inherits them.

- --ingress-class / --domain / --storage-class / --cluster-issuer on
  'tiny up' and 'tiny install'. Persisted as annotations on the
  tinysystems namespace (they travel with the cluster; no local dotfile).
- provision.Settings loads/saves them; module installs read them and set
  managerIngress.ingress.{enabled,className}, global.defaultDomainSuffix,
  the cert-manager.io/(cluster-)issuer ingress annotation, and
  storage.{enabled,storageClassName,size} — gated by the catalog's
  per-module requires_ingress / requires_storage flags.
- Agent install-on-the-fly inherits the same saved settings.

Zero-config on kind/minikube (no ingress class → ingress stays off,
port-forward). Verified live: flags persist to ns annotations; http-module
got a class=nginx ingress with cert-manager.io/cluster-issuer=<name>
(escaping correct); modules that don't need ingress didn't get one.

Author: Tiny Systems

cmd/commands.go

@@ -50,12 +50,13 @@ cluster or add something specific.`,
 				return err
 			}
 			brokerURL := provision.BrokerURL(ctx, cfg, flagNamespace)
+			settings := resolveSettings(ctx, cfg)
 
 			fmt.Println()
 			var release string
 			if err := step(fmt.Sprintf("module: %s %s", m.FullName, styleSubtle.Render(m.Tag)), func() error {
 				var e error
-				release, e = hc.InstallModule(ctx, m, brokerURL)
+				release, e = hc.InstallModule(ctx, m, brokerURL, settings)
 				return e
 			}); err != nil {
 				fmt.Println("  " + styleSubtle.Render("fresh cluster? run `tiny up` first to install the runtime, then retry."))

cmd/root.go

@@ -21,6 +21,13 @@ var (
 	flagNoRegister bool
 	flagPrint      bool
 	flagProject    string
+
+	// Cluster install settings — properties of the target cluster, applied to
+	// module installs and persisted as tinysystems-namespace annotations.
+	flagIngressClass  string
+	flagDomain        string
+	flagStorageClass  string
+	flagClusterIssuer string
 )
 
 const defaultNamespace = "tinysystems"
@@ -49,6 +56,11 @@ Run with no command to start the dev server (MCP endpoint + editor).`,
 	root.PersistentFlags().BoolVarP(&flagYes, "yes", "y", false, "skip the target confirmation prompt (for CI)")
 	root.PersistentFlags().BoolVar(&flagNoRegister, "no-register", false, "don't auto-add the MCP endpoint to Claude Code on serve")
 	root.PersistentFlags().StringVarP(&flagProject, "project", "p", "", "active project for this session (created if missing); scopes the MCP endpoint + editor")
+	// Cluster install settings (persisted to the namespace; set once).
+	root.PersistentFlags().StringVar(&flagIngressClass, "ingress-class", "", "ingress controller class for modules that expose HTTP (e.g. nginx)")
+	root.PersistentFlags().StringVar(&flagDomain, "domain", "", "base domain suffix for module ingress hostnames")
+	root.PersistentFlags().StringVar(&flagStorageClass, "storage-class", "", "storage class for modules that need a PVC")
+	root.PersistentFlags().StringVar(&flagClusterIssuer, "cluster-issuer", "", "cert-manager ClusterIssuer name to annotate ingresses for TLS")
 	// --print is local to bare `tiny` (the serve command): dump the client
 	// config and exit instead of serving.
 	root.Flags().BoolVar(&flagPrint, "print", false, "print the MCP client config and exit (don't serve)")

cmd/up.go

@@ -1,12 +1,14 @@
 package cmd
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"time"
 
 	"github.com/mattn/go-isatty"
 	"github.com/spf13/cobra"
+	"k8s.io/client-go/rest"
 
 	"github.com/tiny-systems/tiny/internal/catalog"
 	"github.com/tiny-systems/tiny/internal/kube"
@@ -73,6 +75,7 @@ func runUp(cmd *cobra.Command, _ []string) error {
 	// Resolve the authenticated broker URL now that NATS is up, and wire it
 	// into every module so durable execution works on the first run.
 	brokerURL := provision.BrokerURL(ctx, cfg, flagNamespace)
+	settings := resolveSettings(ctx, cfg)
 
 	for _, name := range coreModules {
 		nm := name
@@ -81,7 +84,7 @@ func runUp(cmd *cobra.Command, _ []string) error {
 			if err != nil {
 				return err
 			}
-			_, err = hc.InstallModule(ctx, m, brokerURL)
+			_, err = hc.InstallModule(ctx, m, brokerURL, settings)
 			return err
 		}); err != nil {
 			return err
@@ -143,3 +146,30 @@ func step(label string, fn func() error) error {
 func elapsed(start time.Time) string {
 	return time.Since(start).Round(time.Second).String()
 }
+
+// flagSettings collects the cluster-install flags passed this invocation.
+func flagSettings() provision.Settings {
+	s := provision.Settings{
+		IngressClass: flagIngressClass,
+		DomainSuffix: flagDomain,
+		StorageClass: flagStorageClass,
+	}
+	if flagClusterIssuer != "" {
+		s.Issuer = flagClusterIssuer
+		s.ClusterIssuer = true
+	}
+	return s
+}
+
+// resolveSettings returns the effective cluster settings for a module install:
+// the namespace's saved settings overlaid with any flags passed this run — and
+// persists those flags so later installs (including the agent's on-the-fly
+// ones) inherit them. Set them once with `tiny up --ingress-class … …`.
+func resolveSettings(ctx context.Context, cfg *rest.Config) provision.Settings {
+	saved, _ := provision.LoadSettings(ctx, cfg, flagNamespace)
+	fs := flagSettings()
+	if !fs.Empty() {
+		_ = provision.SaveSettings(ctx, cfg, flagNamespace, fs)
+	}
+	return saved.Merge(fs)
+}

internal/catalog/catalog.go

@@ -35,6 +35,10 @@ type Module struct {
 	// services, deployments, ingresses) for modules that manage cluster
 	// resources — http-module's port exposure, kubernetes-module's ops.
 	RequiresKubernetesAccess bool
+	// RequiresIngress / RequiresStorage tell us whether this module needs the
+	// cluster's ingress class / storage class wired at install time.
+	RequiresIngress bool
+	RequiresStorage bool
 }
 
 // apiModule mirrors the fields we consume from GET /v1/modules/{name}.
@@ -48,6 +52,10 @@ type apiModule struct {
 		Tag                      string `json:"tag"`
 		RequiresKubernetesAccess bool   `json:"requires_kubernetes_access"`
 	} `json:"latest_version"`
+	HelmInstall struct {
+		RequiresIngress bool `json:"requires_ingress"`
+		RequiresStorage bool `json:"requires_storage"`
+	} `json:"helm_install"`
 }
 
 // Resolve looks up a module by name against the public catalog. Public
@@ -118,6 +126,8 @@ func fetch(ctx context.Context, baseURL, name string) (*Module, error) {
 		Repo:                     am.LatestVersion.Repo,
 		Tag:                      am.LatestVersion.Tag,
 		RequiresKubernetesAccess: am.LatestVersion.RequiresKubernetesAccess,
+		RequiresIngress:          am.HelmInstall.RequiresIngress,
+		RequiresStorage:          am.HelmInstall.RequiresStorage,
 	}, nil
 }
 

internal/installer/installer.go

@@ -65,9 +65,12 @@ func (m *ModuleInstaller) InstallModule(ctx context.Context, moduleName, version
 		return &sdktools.InstallResult{Success: false, Error: fmt.Sprintf("helm client: %v", err)}, nil
 	}
 	broker := provision.BrokerURL(ctx, m.cfg, m.namespace)
+	// Inherit the cluster's saved install settings (ingress/storage/issuer)
+	// so an agent-installed module lands with the same config as `tiny install`.
+	settings, _ := provision.LoadSettings(ctx, m.cfg, m.namespace)
 
 	progress("install", "installing "+mod.FullName+" ("+mod.Tag+") — this can take a minute while the image pulls", "info")
-	release, err := hc.InstallModule(ctx, mod, broker)
+	release, err := hc.InstallModule(ctx, mod, broker, settings)
 	if err != nil {
 		return &sdktools.InstallResult{Success: false, Error: err.Error()}, nil
 	}

internal/provision/provision.go

@@ -190,7 +190,7 @@ func (c *Client) InstallOTEL(ctx context.Context) error {
 // release parameterised by the module's image. Returns the helm release
 // name. natsURL wires the broker so durable execution is on out of the box;
 // pass "" to leave the module in blocking-only mode.
-func (c *Client) InstallModule(ctx context.Context, m *catalog.Module, natsURL string) (string, error) {
+func (c *Client) InstallModule(ctx context.Context, m *catalog.Module, natsURL string, settings Settings) (string, error) {
 	release := SanitizeResourceName(m.FullName)
 	spec := &helmclient.ChartSpec{
 		ReleaseName:     release,
@@ -204,7 +204,7 @@ func (c *Client) InstallModule(ctx context.Context, m *catalog.Module, natsURL s
 		Force:           true,
 		Replace:         true,
 		CleanupOnFail:   true,
-		ValuesOptions:   values.Options{Values: c.moduleValues(m, release, natsURL)},
+		ValuesOptions:   values.Options{Values: c.moduleValues(m, release, natsURL, settings)},
 	}
 	if err := c.install(ctx, spec); err != nil {
 		return "", err
@@ -218,7 +218,7 @@ func (c *Client) InstallModule(ctx context.Context, m *catalog.Module, natsURL s
 // otherwise), the durable-transport env, secret resolution, and the broker
 // URL. --name is the workspace-qualified full name so the node IDs the agent
 // builds resolve to this operator.
-func (c *Client) moduleValues(m *catalog.Module, release, natsURL string) []string {
+func (c *Client) moduleValues(m *catalog.Module, release, natsURL string, settings Settings) []string {
 	v := []string{
 		"controllerManager.manager.image.repository=" + m.Repo,
 		"controllerManager.manager.image.tag=" + m.Tag,
@@ -242,9 +242,6 @@ func (c *Client) moduleValues(m *catalog.Module, release, natsURL string) []stri
 		// uses the WorkQueue stream (pod-death survival + per-edge retry).
 		"controllerManager.manager.extraEnv[1].name=TINY_NATS_TRANSPORT",
 		"controllerManager.manager.extraEnv[1].value=jetstream",
-		// Local installs don't assume an ingress controller; http servers are
-		// reachable by port-forward.
-		"managerIngress.ingress.enabled=false",
 		// Namespace-scoped secret reads so [[secret:name/key]] placeholders in
 		// node settings resolve against Kubernetes Secrets.
 		"secrets.enabled=true",
@@ -255,6 +252,40 @@ func (c *Client) moduleValues(m *catalog.Module, release, natsURL string) []stri
 	if m.RequiresKubernetesAccess {
 		v = append(v, "rbac.enableKubernetesResourceAccess=true")
 	}
+
+	// Ingress: enable only when the module exposes HTTP and the cluster has an
+	// ingress class set. Otherwise leave it off (reachable by port-forward,
+	// the default on kind/minikube).
+	if m.RequiresIngress && settings.IngressClass != "" {
+		v = append(v,
+			"managerIngress.ingress.enabled=true",
+			"managerIngress.ingress.className="+settings.IngressClass,
+		)
+		if settings.DomainSuffix != "" {
+			v = append(v, "global.defaultDomainSuffix="+settings.DomainSuffix)
+		}
+		if settings.Issuer != "" {
+			// cert-manager TLS: annotate with the (cluster-)issuer. Dots in the
+			// annotation key are escaped so helm --set treats them as key, not
+			// nesting.
+			key := "cert-manager\\.io/issuer"
+			if settings.ClusterIssuer {
+				key = "cert-manager\\.io/cluster-issuer"
+			}
+			v = append(v, "managerIngress.ingress.annotations."+key+"="+settings.Issuer)
+		}
+	} else {
+		v = append(v, "managerIngress.ingress.enabled=false")
+	}
+
+	// Storage: wire the cluster's storage class for modules that need a PVC.
+	if m.RequiresStorage && settings.StorageClass != "" {
+		v = append(v,
+			"storage.enabled=true",
+			"storage.storageClassName="+settings.StorageClass,
+			"storage.size="+settings.storageSizeOr(),
+		)
+	}
 	return v
 }
 

internal/provision/settings.go

@@ -0,0 +1,125 @@
+package provision
+
+import (
+	"context"
+	"encoding/json"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/rest"
+)
+
+// Settings are cluster-wide install values — properties of YOUR cluster, not
+// of any one module: which ingress controller, the base domain, the storage
+// class. They're persisted as annotations on the tinysystems namespace, so
+// they travel with the cluster and every module install reads them. Set them
+// once (flags on `tiny up`/`tiny install`); modules that need them pick them up.
+type Settings struct {
+	IngressClass string
+	DomainSuffix string
+	StorageClass string
+	StorageSize  string // default 1Gi when a module needs storage
+	// Issuer is the cert-manager (Cluster)Issuer name to annotate ingresses
+	// with for TLS; ClusterIssuer selects cluster-issuer vs namespace issuer.
+	Issuer        string
+	ClusterIssuer bool
+}
+
+const (
+	annIngressClass  = "tinysystems.io/ingress-class"
+	annDomainSuffix  = "tinysystems.io/domain-suffix"
+	annStorageClass  = "tinysystems.io/storage-class"
+	annStorageSize   = "tinysystems.io/storage-size"
+	annIssuer        = "tinysystems.io/issuer"
+	annClusterIssuer = "tinysystems.io/issuer-cluster-scoped"
+)
+
+func (s Settings) storageSizeOr() string {
+	if s.StorageSize == "" {
+		return "1Gi"
+	}
+	return s.StorageSize
+}
+
+// Empty reports whether no setting is present.
+func (s Settings) Empty() bool { return s == Settings{} }
+
+// Merge overlays o's non-empty fields onto s (o wins). Used to layer
+// this-invocation flags over the cluster's saved settings.
+func (s Settings) Merge(o Settings) Settings {
+	if o.IngressClass != "" {
+		s.IngressClass = o.IngressClass
+	}
+	if o.DomainSuffix != "" {
+		s.DomainSuffix = o.DomainSuffix
+	}
+	if o.StorageClass != "" {
+		s.StorageClass = o.StorageClass
+	}
+	if o.StorageSize != "" {
+		s.StorageSize = o.StorageSize
+	}
+	if o.Issuer != "" {
+		s.Issuer = o.Issuer
+		s.ClusterIssuer = o.ClusterIssuer
+	}
+	return s
+}
+
+// LoadSettings reads the saved cluster settings off the namespace annotations.
+func LoadSettings(ctx context.Context, cfg *rest.Config, namespace string) (Settings, error) {
+	cs, err := kubernetes.NewForConfig(cfg)
+	if err != nil {
+		return Settings{}, err
+	}
+	ns, err := cs.CoreV1().Namespaces().Get(ctx, namespace, metav1.GetOptions{})
+	if err != nil {
+		return Settings{}, err
+	}
+	a := ns.Annotations
+	return Settings{
+		IngressClass:  a[annIngressClass],
+		DomainSuffix:  a[annDomainSuffix],
+		StorageClass:  a[annStorageClass],
+		StorageSize:   a[annStorageSize],
+		Issuer:        a[annIssuer],
+		ClusterIssuer: a[annClusterIssuer] == "true",
+	}, nil
+}
+
+// SaveSettings persists the non-empty settings as namespace annotations
+// (a merge patch — it never clears an existing annotation).
+func SaveSettings(ctx context.Context, cfg *rest.Config, namespace string, s Settings) error {
+	ann := map[string]string{}
+	if s.IngressClass != "" {
+		ann[annIngressClass] = s.IngressClass
+	}
+	if s.DomainSuffix != "" {
+		ann[annDomainSuffix] = s.DomainSuffix
+	}
+	if s.StorageClass != "" {
+		ann[annStorageClass] = s.StorageClass
+	}
+	if s.StorageSize != "" {
+		ann[annStorageSize] = s.StorageSize
+	}
+	if s.Issuer != "" {
+		ann[annIssuer] = s.Issuer
+		if s.ClusterIssuer {
+			ann[annClusterIssuer] = "true"
+		}
+	}
+	if len(ann) == 0 {
+		return nil
+	}
+	cs, err := kubernetes.NewForConfig(cfg)
+	if err != nil {
+		return err
+	}
+	patch, _ := json.Marshal(map[string]interface{}{
+		"metadata": map[string]interface{}{"annotations": ann},
+	})
+	_, err = cs.CoreV1().Namespaces().Patch(ctx, namespace, types.MergePatchType, patch, metav1.PatchOptions{})
+	return err
+}