infra

Documentation

Index

• Constants
• func BenchmarksDir(setupID string) (string, error)
• func Destroy(ctx context.Context, state *SetupState) error
• func ListRuns() ([]string, error)
• func RenderTemplate(p TemplateParams) (string, error)
• func RunDir(setupID string) (string, error)
• func SSHDir(setupID string) (string, error)
• func SaveTemplateArtifact(setupID, templateYAML string) (string, error)
• func StateFilePath(setupID string) (string, error)
• type BenchmarkRun
• type EngineInfo
• type InstanceInfo
• type Lock
  • func AcquireLock(setupDir string) (*Lock, error)
  • func (l *Lock) Release()
• type ProvisionParams
• type ProvisionResult
  • func Provision(ctx context.Context, p *ProvisionParams, state *SetupState) (*ProvisionResult, error)
• type ReplicaEndpoint
• type SSHInfo
• type SetupConfig
• type SetupState
  • func LoadState(setupID string) (*SetupState, error)
  • func (s *SetupState) Save() error
• type TemplateParams

Constants

const (
	StatusProvisioning = "provisioning"
	StatusInstalling   = "installing"
	StatusReady        = "ready"
	StatusBenchmarking = "benchmarking"
	StatusDestroying   = "destroying"
	StatusDestroyed    = "destroyed"
	StatusFailed       = "failed"
)

Status values for SetupState.Status. The lifecycle is:

provisioning -> installing -> ready <-> benchmarking
ready/failed -> destroying -> destroyed

Functions

func BenchmarksDir

func BenchmarksDir(setupID string) (string, error)

BenchmarksDir returns the directory holding per-run benchmark artifacts.

func Destroy

func Destroy(ctx context.Context, state *SetupState) error

Destroy deletes the run's CloudFormation stack and the local SSH key files. A stack that's already gone counts as success. Any other AWS failure is returned without marking the state destroyed, so we never report a live stack as deleted.

func ListRuns

func ListRuns() ([]string, error)

func RenderTemplate

func RenderTemplate(p TemplateParams) (string, error)

RenderTemplate returns the CloudFormation YAML for a single run: VPC, networking, security group, placement group, key pair and EC2 instances. It's deterministic, so the same inputs always produce byte-identical YAML.

func RunDir

func RunDir(setupID string) (string, error)

RunDir returns the per-setup directory (~/.dfbench/runs/<id>), creating it if needed.

func SSHDir

func SSHDir(setupID string) (string, error)

SSHDir returns ~/.dfbench/runs/<id>/ssh, created with 0700 because it holds a private key.

func SaveTemplateArtifact

func SaveTemplateArtifact(setupID, templateYAML string) (string, error)

SaveTemplateArtifact writes the rendered CloudFormation template next to the state file. It runs before any AWS call, so even a failed provision leaves an auditable record.

func StateFilePath

func StateFilePath(setupID string) (string, error)

Types

type BenchmarkRun

type BenchmarkRun struct {
	ID          string    `json:"id"`
	StartedAt   time.Time `json:"started_at"`
	CompletedAt time.Time `json:"completed_at,omitempty"`
	Status      string    `json:"status"`
	Engines     []string  `json:"engines"`
	Trials      int       `json:"trials"`
	ResultsPath string    `json:"results_path,omitempty"`
}

BenchmarkRun records a single `dfbench run` against this setup. ResultsPath is relative to the setup directory.

type EngineInfo

type EngineInfo struct {
	Name      string `json:"name"`
	Version   string `json:"version,omitempty"`
	Installed bool   `json:"installed"`
}

type InstanceInfo

type InstanceInfo struct {
	InstanceType string `json:"instance_type"`
	Arch         string `json:"arch"`
	PublicIP     string `json:"public_ip,omitempty"`
	PrivateIP    string `json:"private_ip,omitempty"`
}

type Lock

type Lock struct {
	// contains filtered or unexported fields
}

Lock is an exclusive flock on a setup directory. It prevents concurrent dfbench processes from racing on state.json and the remote instances.

func AcquireLock

func AcquireLock(setupDir string) (*Lock, error)

AcquireLock takes a non-blocking exclusive flock on <setupDir>/.lock. It fails immediately if another process holds the lock.

func (*Lock) Release

func (l *Lock) Release()

Release unlocks and closes the lock file. The file is not deleted, since that would race with a process that has opened but not yet flocked it. Safe to call multiple times.

type ProvisionParams

type ProvisionParams struct {
	Region           string
	AvailabilityZone string
	ServerArch       string
	ClientArch       string
	ServerInstance   string
	ClientInstance   string
	SSHPublicKey     string
	RunID            string

	// UbuntuVersion selects the Ubuntu release for all instances (empty
	// defaults to 22.04). Newer releases ship a newer glibc.
	UbuntuVersion string

	// Optional replication topology. Zero replicas renders the same
	// template it did before replicas were a thing.
	Replicas        int
	ReplicaInstance string
	ReplicaArch     string
}

ProvisionParams are the inputs to Provision. Only the SSH public key goes to AWS; the private key never leaves the local machine.

type ProvisionResult

type ProvisionResult struct {
	ServerPublicIP  string
	ServerPrivateIP string
	ClientPublicIP  string
	ClientPrivateIP string
	Replicas        []ReplicaEndpoint
	AWSAccount      string
}

ProvisionResult holds the endpoints of the provisioned instances. Public IPs are for SSH from the operator's machine; memtier talks to the server's private IP inside the VPC.

func Provision

func Provision(ctx context.Context, p *ProvisionParams, state *SetupState) (*ProvisionResult, error)

Provision renders a CloudFormation template for the run and creates the stack. On failure CloudFormation rolls back and deletes whatever it created. The rendered template is written to disk before the first AWS call so it stays auditable even when the run fails.

type ReplicaEndpoint

type ReplicaEndpoint struct {
	PublicIP  string
	PrivateIP string
}

ReplicaEndpoint holds the IPs of a single replica instance.

type SSHInfo

type SSHInfo struct {
	PrivateKeyPath    string `json:"private_key_path"`
	PublicKeyPath     string `json:"public_key_path"`
	User              string `json:"user"`
	PublicKeyAuthLine string `json:"public_key_auth_line,omitempty"`
}

type SetupConfig

type SetupConfig struct {
	Region           string `json:"region"`
	AvailabilityZone string `json:"availability_zone,omitempty"`
	ServerInstance   string `json:"server_instance"`
	ClientInstance   string `json:"client_instance"`
	ServerArch       string `json:"server_arch"`
	ClientArch       string `json:"client_arch"`
	// UbuntuVersion records the Ubuntu release the instances launched with
	// ("22.04", "24.04", ...). Empty means the historical default.
	UbuntuVersion   string `json:"ubuntu_version,omitempty"`
	SSHUser         string `json:"ssh_user"`
	Replicas        int    `json:"replicas,omitempty"`
	ReplicaInstance string `json:"replica_instance,omitempty"`
	ReplicaArch     string `json:"replica_arch,omitempty"`
	// TuneNetwork records whether net_tune.sh was applied to the server
	// during setup (IRQ/RPS/XPS affinity for high-throughput runs).
	TuneNetwork bool `json:"tune_network,omitempty"`
	// DflyBenchRef records the dragonflydb/dragonfly git ref used to build
	// dfly_bench on the client at setup time. Empty means the historical
	// default (no dfly_bench installed / "main").
	DflyBenchRef string `json:"dfly_bench_ref,omitempty"`
}

SetupConfig is the subset of setup-time flags we persist so later commands don't need them passed again. Per-run benchmark flags aren't stored here.

type SetupState

type SetupState struct {
	ID         string         `json:"id"`
	CreatedAt  time.Time      `json:"created_at"`
	UpdatedAt  time.Time      `json:"updated_at"`
	Status     string         `json:"status"`
	Config     SetupConfig    `json:"config"`
	StackName  string         `json:"stack_name,omitempty"`
	AWSAccount string         `json:"aws_account,omitempty"`
	Server     InstanceInfo   `json:"server"`
	Client     InstanceInfo   `json:"client"`
	Replicas   []InstanceInfo `json:"replicas,omitempty"`
	SSH        SSHInfo        `json:"ssh"`
	Engines    []EngineInfo   `json:"engines,omitempty"`
	Benchmarks []BenchmarkRun `json:"benchmarks,omitempty"`
}

SetupState is the on-disk record of a provisioned benchmark environment, stored at ~/.dfbench/runs/<id>/state.json.

func LoadState

func LoadState(setupID string) (*SetupState, error)

LoadState reads a setup's state.json, migrating the legacy flat shape in memory when it sees one. The migrated form is only written back on the next Save.

func (*SetupState) Save

func (s *SetupState) Save() error

type TemplateParams

type TemplateParams struct {
	RunID            string
	ServerInstance   string
	ClientInstance   string
	ServerArch       string
	ClientArch       string
	AvailabilityZone string
	SSHPublicKey     string

	// UbuntuVersion selects the Ubuntu release for all instances, e.g.
	// "22.04" or "24.04". Empty defaults to 22.04. Newer releases ship a
	// newer glibc, which some Dragonfly builds need.
	UbuntuVersion string

	// Replicas provisions N extra instances in the same subnet, SG and
	// placement group. Zero renders the same template it did before
	// replicas were a thing.
	Replicas        int
	ReplicaInstance string
	ReplicaArch     string
}

TemplateParams are the inputs to RenderTemplate.