config

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: GPL-3.0, LGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package config handles parsing and validation of sind cluster configuration.

Index

Constants

View Source 
const (
	DefaultClusterName = "default"
	DefaultCPUs        = 1
	DefaultMemory      = "512m"
	DefaultTmpSize     = "256m"
)

Default resource values for cluster nodes.

View Source 
const (
	MinUID = 1000
	MaxUID = math.MaxInt32
)

ID range of cluster users and groups. The IDs below MinUID belong to the system accounts of the node image (slurm, munge, sshd, ...).

View Source 
const JWTAuthType = "auth/jwt"

JWTAuthType is the authentication plugin of the tokens slurmrestd takes, which sind adds to AuthAltTypes for a cluster with a managed api node.

View Source 
const MaxAccountingClusterName = 40

MaxAccountingClusterName is the longest cluster name a cluster with a managed db node may have: slurmdbd names the cluster's MariaDB tables <cluster>_<table>, and their names may have at most 64 characters, so Slurm limits ClusterName to 40.

View Source 
const MinMemory = 6 << 20

MinMemory is the smallest memory limit Docker accepts, in bytes.

View Source 
const ReservedClusterName = "ssh"

ReservedClusterName cannot name a cluster: its config volume, <realm>-ssh-config, would be the realm's SSH volume (see mesh.Manager.SSHVolumeName), which sind delete cluster would then try to remove as the cluster's.

View Source 
const RootAccount = "root"

RootAccount is the account at the top of every cluster's account tree. slurmctld creates it, with an association for root, when it registers the cluster with slurmdbd.

Variables

View Source 
var DefaultImage = "ghcr.io/gsi-hpc/sind-node:latest"

DefaultImage is the node image of nodes that set none. Release builds set it with -ldflags "-X" to the image the image workflow publishes for their release, ghcr.io/gsi-hpc/sind-node:vX.Y.Z (.goreleaser.yaml), so a release keeps the node image it was built with. Other builds use latest, the newest Slurm release line.

View Source 
var LimitKeys = []string{
	"Comment", "DefaultQOS", "Description", "Fairshare", "Flags",
	"GrpJobs", "GrpJobsAccrue", "GrpSubmitJobs", "GrpTRES", "GrpTRESMins", "GrpTRESRunMins", "GrpWall",
	"MaxJobs", "MaxJobsAccrue", "MaxSubmitJobs", "MaxTRES", "MaxTRESMins", "MaxTRESMinsPerJob", "MaxTRESPerJob",
	"MaxTRESPerNode", "MaxTRESRunMins", "MaxWall", "MaxWallDurationPerJob",
	"MinPrioThresh", "Organization", "Priority", "QOS", "QosLevel", "Shares",
}

LimitKeys are the sacctmgr add account options an account's limits may set, matched case-insensitively: the account's description, organization and flags, and the limits and settings of its association. sacctmgr also takes any prefix of an option name, so a deny list could not keep limits off the options sind sets itself (name, parent and cluster): A, Acct, N, C or Pa would reach them. Where would make sacctmgr add account loop forever.

View Source 
var ReservedIDs = []int{65534, 65535}

ReservedIDs are the IDs in the range that no cluster user or group may have: 65534, the overflow user and group nobody that the image has, and 65535, the 16-bit -1 that some tools read as no ID.

Functions

func CheckCPUs added in v0.11.0 

func CheckCPUs(field string, n int) error

CheckCPUs reports whether n is a valid CPU limit: zero stands for the default, and a negative number is invalid. field names the value in the error.

func CheckCapabilities added in v0.10.0 

func CheckCapabilities(field string, caps []string) error

CheckCapabilities reports the first name in caps that is not a recognized Linux capability; field names the setting in the error, e.g. "capAdd".

func CheckDevices added in v0.10.0 

func CheckDevices(devices []string) error

CheckDevices reports the first device whose host path is not absolute. A device is HOST_PATH[:CONTAINER_PATH[:PERMISSIONS]].

func CheckGroupName added in v0.11.0 

func CheckGroupName(name string) error

CheckGroupName reports whether name may be used as the name of a cluster group.

func CheckMemory added in v0.11.0 

func CheckMemory(field, s string) error

CheckMemory reports whether s is a valid memory limit (see MemoryMB); empty stands for the default. field names the value in the error.

func CheckName added in v0.10.0 

func CheckName(kind, name string) error

CheckName reports whether name may be used as a cluster or realm name; kind ("cluster" or "realm") names it in the error.

Both names become part of Docker resource names (<realm>-<cluster>-net), of DNS names (<node>.<cluster>.<realm>.sind) and of paths ($XDG_STATE_HOME/sind/<realm>), so each has to be one DNS label: lowercase ASCII letters, digits and hyphens, 1 to 63 characters, not beginning or ending with a hyphen. A "." would add a DNS label and split node arguments such as worker-0.dev in the wrong place, and "/" or ".." would leave the state directory. Uppercase letters are refused too: DNS ignores case, so Dev and dev would be two sets of containers behind the same DNS names.

The cluster name ReservedClusterName is refused as well.

func CheckSecurityOpts added in v0.11.0 

func CheckSecurityOpts(field string, opts []string) error

CheckSecurityOpts reports the first security option in opts that Docker would reject for its form: NAME=VALUE (or Docker's older NAME:VALUE) with a name in securityOptNames and a value, or no-new-privileges alone. field names the setting in the error, e.g. "securityOpt". The values are left to Docker, which checks them when it creates the container.

func CheckTmpSize added in v0.11.0 

func CheckTmpSize(field, s string) error

CheckTmpSize reports whether s is a valid size of a node's /tmp tmpfs, which sind passes to the kernel as the mount's size option; empty stands for the default. field names the value in the error.

func CheckUserName added in v0.11.0 

func CheckUserName(name string) error

CheckUserName reports whether name may be used as the name of a cluster user.

func LinePairs added in v0.11.0 

func LinePairs(line string) [][2]string

LinePairs returns the key=value pairs of one slurm.conf-style line, in order, as Slurm's parser reads them: a "#" starts a comment, a line may hold several pairs, and a value may be quoted.

func LineParameter added in v0.11.0 

func LineParameter(line, key string) (string, bool)

LineParameter returns the value one slurm.conf-style line assigns to a parameter, and whether it assigns it (see LinePairs); keys match case-insensitively, as Slurm matches them. Pairs after a key such as NodeName or PartitionName belong to that node or partition, not to the cluster, so they do not count. Of several assignments the last one wins, as in Slurm.

func ListsValue added in v0.11.0 

func ListsValue(value, item string) bool

ListsValue reports whether a comma-separated parameter value, such as LaunchParameters or AuthInfo, lists item.

func MemoryMB added in v0.11.0 

func MemoryMB(s string) (int, error)

MemoryMB parses a memory limit in Docker's size syntax (docker run --memory) and returns it in MiB, rounded down, the unit of Slurm's RealMemory. The syntax is a decimal number, optionally with a fraction, followed by an optional unit: b, k, m, g, t or p, in either case, the last five optionally followed by b or ib. All units are powers of 1024, and a number without a unit counts bytes: 512m, 2g, 2GB, 2GiB, 1.5g, 2048k and 1073741824 are valid. The limit must be at least MinMemory.

Types

type Account added in v0.11.0 

type Account struct {
	Name string `json:"name"`
	// Parent is the parent account: RootAccount, the default, or an
	// account declared before this one.
	Parent string `json:"parent,omitempty"`
	// Limits are further sacctmgr options of the account, passed as
	// key=value, e.g. GrpTRES: cpu=4 or MaxJobs: 1.
	Limits Limits `json:"limits,omitempty"`
}

Account is a Slurm account that sind creates with sacctmgr once the cluster is registered with slurmdbd.

func (*Account) UnmarshalJSON added in v0.11.0 

func (a *Account) UnmarshalJSON(data []byte) error

UnmarshalJSON supports two YAML forms:

  • bare string: "physics"
  • full object: "name: theory\n parent: physics"

type AdminLevel added in v0.11.0 

type AdminLevel string

AdminLevel is a Slurm user's administrative level. 

const (
	AdminOperator AdminLevel = "operator"
	AdminAdmin    AdminLevel = "admin"
)

Admin levels a user can have besides none, the default.

type Cluster 

type Cluster struct {
	Kind     string    `json:"kind"`
	Name     string    `json:"name,omitempty"`
	Realm    string    `json:"realm,omitempty"`
	Defaults Defaults  `json:"defaults,omitempty"`
	Storage  Storage   `json:"storage,omitempty"`
	Slurm    Slurm     `json:"slurm,omitempty"`
	Users    []User    `json:"users,omitempty"`
	Groups   []Group   `json:"groups,omitempty"`
	Accounts []Account `json:"accounts,omitempty"`
	Identity Identity  `json:"identity,omitempty"`
	Nodes    []Node    `json:"nodes,omitempty"`

	// Pull is a runtime flag (not part of the config file) that forces
	// fresh image pulls when creating containers.
	Pull bool `json:"-" yaml:"-"`
	// Wait is a runtime setting (not part of the config file): when
	// positive, how long cluster.Create waits for the nodes and Slurm to
	// become ready, counted from when the node containers have started.
	Wait time.Duration `json:"-" yaml:"-"`
}

Cluster represents a sind cluster configuration.

func Parse 

func Parse(data []byte) (*Cluster, error)

Parse parses a YAML cluster configuration and returns a Cluster.

func (*Cluster) ApplyDefaults 

func (c *Cluster) ApplyDefaults()

ApplyDefaults populates missing fields with defaults. If no nodes are defined, creates a minimal cluster (1 controller + 1 worker). Node-level fields inherit from the Defaults section, which in turn falls back to built-in defaults. Users without a uid, then groups without a gid, get the lowest free ID from MinUID up. The identity mode defaults to local.

func (*Cluster) HasBackupController added in v0.10.0 

func (c *Cluster) HasBackupController() bool

HasBackupController reports whether the controller node spec enables the backup controller.

func (*Cluster) HasManagedAPI added in v0.11.0 

func (c *Cluster) HasManagedAPI() bool

HasManagedAPI reports whether the cluster has an api node on which sind runs slurmrestd: one without managed: false, in a managed cluster. Only then does sind set up JWT authentication (jwt_hs256.key and the AuthAlt parameters in slurm.conf and slurmdbd.conf).

func (*Cluster) HasManagedDB added in v0.11.0 

func (c *Cluster) HasManagedDB() bool

HasManagedDB reports whether the cluster has a db node whose accounting services sind manages: one without managed: false, in a managed cluster. Only then does sind configure accounting (slurmdbd.conf and the accounting parameters in slurm.conf).

func (*Cluster) Managed added in v0.10.0 

func (c *Cluster) Managed() bool

Managed reports whether sind manages the cluster's Slurm configuration and daemons. managed: false on the controller node spec makes the whole cluster unmanaged: sind writes no Slurm configuration and starts no Slurm daemons on any node.

func (*Cluster) UsesAccounts added in v0.11.0 

func (c *Cluster) UsesAccounts() bool

UsesAccounts reports whether the config asks for Slurm accounts: accounts, or a user with accounts, coordinator or adminLevel.

func (*Cluster) Validate 

func (c *Cluster) Validate() error

Validate checks that the cluster configuration satisfies all constraints. It should be called after ApplyDefaults.

func (*Cluster) Warnings added in v0.11.0 

func (c *Cluster) Warnings() []string

Warnings returns what is likely a mistake in a valid config, for sind create cluster to print: account limits (Max* and Grp*) that Slurm does not enforce, as slurm.main's AccountingStorageEnforce does not include limits. sind keeps Slurm's default of no enforcement, which changes which jobs run.

type DataStorage 

type DataStorage struct {
	Type      StorageType `json:"type,omitempty"`
	HostPath  string      `json:"hostPath,omitempty"`
	MountPath string      `json:"mountPath,omitempty"`
}

DataStorage configures the shared data volume.

func (DataStorage) UsesHostPath added in v0.10.0 

func (d DataStorage) UsesHostPath() bool

UsesHostPath reports whether the data is a bind mount of HostPath rather than the cluster's Docker volume: with type hostPath, or with no type and a host path. With type volume, HostPath is ignored.

type Defaults 

type Defaults struct {
	Image       string   `json:"image,omitempty"`
	CPUs        int      `json:"cpus,omitempty"`
	Memory      string   `json:"memory,omitempty"`
	TmpSize     string   `json:"tmpSize,omitempty"`
	CapAdd      []string `json:"capAdd,omitempty"`
	CapDrop     []string `json:"capDrop,omitempty"`
	Devices     []string `json:"devices,omitempty"`
	SecurityOpt []string `json:"securityOpt,omitempty"`
}

Defaults holds default settings applied to all nodes unless overridden.

type Group added in v0.11.0 

type Group struct {
	Name string `json:"name"`
	// GID is the ID of the group. Zero assigns the lowest ID from MinUID up
	// that no user or group has (see Cluster.ApplyDefaults).
	GID int `json:"gid,omitempty"`
}

Group is a Linux group that sind creates on the nodes that get the cluster users, as a primary or supplementary group of the users.

func (*Group) UnmarshalJSON added in v0.11.0 

func (g *Group) UnmarshalJSON(data []byte) error

UnmarshalJSON supports two YAML forms:

  • bare string: "hpc"
  • full object: "name: hpc\n gid: 3000"

type Identity added in v0.11.0 

type Identity struct {
	Mode IdentityMode `json:"mode,omitempty"`
	// ControllerUsers also creates the users and groups on the controllers
	// with IdentityClientIDs, which a partition with AllowGroups needs:
	// slurmctld checks AllowGroups with local lookups.
	ControllerUsers bool `json:"controllerUsers,omitempty"`
}

Identity selects the identity mode (identity) of a cluster.

func (*Identity) UnmarshalJSON added in v0.11.0 

func (i *Identity) UnmarshalJSON(data []byte) error

UnmarshalJSON supports two YAML forms:

  • bare string: "nssSlurm" (the mode)
  • full object: "mode: clientIds\n controllerUsers: true"

func (Identity) UsesNSSSlurm added in v0.11.0 

func (i Identity) UsesNSSSlurm() bool

UsesNSSSlurm reports whether managed workers resolve users with nss_slurm.

type IdentityMode added in v0.11.0 

type IdentityMode string

IdentityMode is where a cluster's nodes look up the users, and how Slurm authenticates them. 

const (
	// IdentityLocal gives every node the Linux accounts, with munge
	// authentication. It is the default.
	IdentityLocal IdentityMode = "local"
	// IdentityNSSSlurm keeps the accounts off managed workers, which
	// resolve the job's user and groups with nss_slurm, from the job
	// credential (LaunchParameters=enable_nss_slurm), with munge
	// authentication.
	IdentityNSSSlurm IdentityMode = "nssSlurm"
	// IdentityClientIDs gives only the login node the accounts:
	// auth/slurm with AuthInfo=use_client_ids carries each user's identity
	// in their tokens to slurmctld and slurmdbd, and nss_slurm serves it on
	// managed workers. munge is off.
	IdentityClientIDs IdentityMode = "clientIds"
)

Identity modes.

func (IdentityMode) SlurmParameters added in v0.11.0 

func (m IdentityMode) SlurmParameters() []SlurmParameter

SlurmParameters returns the slurm.conf parameters an identity mode needs, in the order sind writes them: with clientIds, auth/slurm and cred/slurm with slurm.key instead of munge, and the users' identities in their tokens; with nssSlurm and clientIds, nss_slurm on the workers, served from the job credential. sind writes each parameter unless slurm.main sets it, and slurm.main's value must then list sind's.

type Limits added in v0.11.0 

type Limits map[string]string

Limits are sacctmgr options of an account, by option name. Numbers are passed in plain decimal form, as YAML 1.1 reads them before sind sees them: MaxJobs: 1 becomes MaxJobs=1, but 010 is octal and becomes 8, and 1.10 becomes 1.1. A quoted value is passed as written.

func (Limits) Keys added in v0.11.0 

func (l Limits) Keys() []string

Keys returns the option names in sorted order, the order sind passes them to sacctmgr.

func (*Limits) UnmarshalJSON added in v0.11.0 

func (l *Limits) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a map of strings and numbers.

type Node 

type Node struct {
	Role             Role     `json:"role"`
	Count            int      `json:"count,omitempty"`
	Image            string   `json:"image,omitempty"`
	CPUs             int      `json:"cpus,omitempty"`
	Memory           string   `json:"memory,omitempty"`
	TmpSize          string   `json:"tmpSize,omitempty"`
	Managed          *bool    `json:"managed,omitempty"`
	BackupController bool     `json:"backupController,omitempty"`
	CapAdd           []string `json:"capAdd,omitempty"`
	CapDrop          []string `json:"capDrop,omitempty"`
	Devices          []string `json:"devices,omitempty"`
	SecurityOpt      []string `json:"securityOpt,omitempty"`
}

Node represents a single node or node group in the cluster configuration.

func (*Node) UnmarshalJSON 

func (n *Node) UnmarshalJSON(data []byte) error

UnmarshalJSON supports three YAML forms:

  • bare string: "controller"
  • shorthand map: "worker: 3" (role: count)
  • full object: "role: worker\n count: 3\n cpus: 4"

type Role added in v0.7.0 

type Role string

Role identifies the function of a node within a cluster. 

const (
	RoleController Role = "controller"
	RoleDB         Role = "db"
	RoleSubmitter  Role = "submitter"
	RoleWorker     Role = "worker"
	// RoleAPI is the node that runs slurmrestd, Slurm's REST API daemon.
	RoleAPI Role = "api"
)

Valid node roles.

type Section added in v0.7.0 

type Section struct {
	Content   string            // string form
	Fragments map[string]string // map form
}

Section represents a Slurm config file section that can be either:

  • a string (content appended directly to the config file)
  • a map of fragment name → content (creates a .conf.d/ directory)

func (Section) FragmentNames added in v0.7.0 

func (s Section) FragmentNames() []string

FragmentNames returns the sorted keys from Fragments.

func (Section) IsEmpty added in v0.7.0 

func (s Section) IsEmpty() bool

IsEmpty returns true if the section has no content and no fragments.

func (Section) IsMap added in v0.7.0 

func (s Section) IsMap() bool

IsMap returns true if the section uses the map/fragments form.

func (Section) Lines added in v0.11.0 

func (s Section) Lines() iter.Seq[string]

Lines returns the lines of the section in the order sind writes them: the string form, then the fragments by name.

func (Section) Parameter added in v0.11.0 

func (s Section) Parameter(key string) (string, bool)

Parameter returns the value the section gives a slurm.conf-style parameter, and whether it sets it (see LineParameter). Like Slurm, it takes the last assignment, in the order of Lines.

func (Section) SetsParameter added in v0.10.0 

func (s Section) SetsParameter(key string) bool

SetsParameter reports whether the section sets a slurm.conf-style parameter (see Parameter).

func (*Section) UnmarshalJSON added in v0.7.0 

func (s *Section) UnmarshalJSON(data []byte) error

UnmarshalJSON supports two YAML/JSON forms:

  • string: "content" → Section{Content: "content"}
  • map: {"key": "content"} → Section{Fragments: {"key": "content"}}

type Slurm added in v0.7.0 

type Slurm struct {
	Main      Section `json:"main,omitempty"`
	Cgroup    Section `json:"cgroup,omitempty"`
	Gres      Section `json:"gres,omitempty"`
	Topology  Section `json:"topology,omitempty"`
	Plugstack Section `json:"plugstack,omitempty"`
	Slurmdbd  Section `json:"slurmdbd,omitempty"`
}

Slurm configures custom Slurm configuration files. Each field maps to a Slurm config file: main → slurm.conf, cgroup → cgroup.conf, gres → gres.conf, etc.

type SlurmParameter added in v0.11.0 

type SlurmParameter struct{ Key, Value string }

SlurmParameter is a slurm.conf parameter and the value sind gives it.

type Storage 

type Storage struct {
	DataStorage DataStorage `json:"dataStorage,omitempty"`
	// CVMFS mounts CVMFS read-only at /cvmfs on every node, from the cvmfs
	// Docker volume plugin or from the Docker host's /cvmfs.
	CVMFS bool `json:"cvmfs,omitempty"`
}

Storage configures cluster storage options.

type StorageType added in v0.7.0 

type StorageType string

StorageType identifies the backing mechanism for data storage. 

const (
	StorageVolume   StorageType = "volume"
	StorageHostPath StorageType = "hostPath"
)

Storage type values.

type User added in v0.11.0 

type User struct {
	Name string `json:"name"`
	// UID is the ID of the user and, without Group, of its private group.
	// Zero assigns the lowest free ID from MinUID up (see
	// Cluster.ApplyDefaults).
	UID int `json:"uid,omitempty"`
	// Group is the user's primary group, one of the cluster's groups.
	// Empty gives the user a private group of its own name, with gid = uid.
	Group string `json:"group,omitempty"`
	// Groups are the user's supplementary groups, all among the cluster's
	// groups.
	Groups []string `json:"groups,omitempty"`
	// Accounts are the Slurm accounts the user gets associations with,
	// all among the cluster's accounts. The first is the default account.
	Accounts []string `json:"accounts,omitempty"`
	// Coordinator are the accounts the user coordinates: the user may
	// manage them and their sub-accounts.
	Coordinator []string `json:"coordinator,omitempty"`
	// AdminLevel is the user's Slurm admin level, none by default.
	AdminLevel AdminLevel `json:"adminLevel,omitempty"`
}

User is a Linux user account that sind creates on the nodes of the cluster, with a home directory under /home.

func (*User) UnmarshalJSON added in v0.11.0 

func (u *User) UnmarshalJSON(data []byte) error

UnmarshalJSON supports two YAML forms:

  • bare string: "alice"
  • full object: "name: alice\n uid: 2001"

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.