k6foundry

README

k6foundry

k6foundry is a CLI for building custom k6 binaries with extensions.

Prerequisites

A Go language tool chain or a properly configured.

Installation

Using go toolchain

If you have a go development environment, the installation can be done with the following command:

go install github.com/grafana/k6foundry@latest

Usage

build

The build command builds a custom k6 binary with extensions. Multiple extensions with their versions can be specified. The version of k6 can also be specified. If version is omitted, the latest version is used.

The custom binary can target an specific platform, specified as a os/arch pair. By default the platform of the k6foundry executable is used as target platform.

The following example shows the options for building a custom k6 v.0.50.0 binary with the latest version of the kubernetes extension and kafka output extension v0.7.0.

k6foundry build -v v0.50.0 -d github.com/grafana/xk6-kubernetes -d github.com/grafana/xk6-output-kafka@v0.7.0

For more examples run

k6foundry build --help

Documentation

Overview

Package k6foundry contains logic for building k6 binary

Index

• Variables
• type BuildInfo
• type Builder
  • func NewDefaultNativeBuilder() (Builder, error)
  • func NewNativeBuilder(_ context.Context, opts NativeBuilderOpts) (Builder, error)
• type GoOpts
• type Module
  • func ParseModule(modString string) (Module, error)
  • func (m Module) String() string
• type NativeBuilderOpts
• type Platform
  • func NewPlatform(os, arch string) Platform
  • func ParsePlatform(str string) (Platform, error)
  • func RuntimePlatform() Platform
  • func SupportedPlatforms() []Platform
  • func (p Platform) String() string
  • func (p Platform) Supported() bool

Variables

var (
	// Error compiling binary
	ErrCompiling = errors.New("compiling")
	// Error executing go command
	ErrExecutingGoCommand = errors.New("executing go command")
	// Go toolchacin is not installed
	ErrNoGoToolchain = errors.New("go toolchain notfound")
	// Git is not installed
	ErrNoGit = errors.New("git notfound")
	// Error resolving dependency
	ErrResolvingDependency = errors.New("resolving dependency")
	// Error initiailizing go build environment
	ErrSettingGoEnv = errors.New("setting go environment")
)

var (
	ErrInvalidDependencyFormat = errors.New("invalid dependency format") //nolint:revive
)

var ErrInvalidPlatform = errors.New("invalid platform") //nolint:revive

Types

type BuildInfo

type BuildInfo struct {
	Platform    string
	ModVersions map[string]string
}

BuildInfo describes the binary

type Builder

type Builder interface {
	// Build returns a custom k6 binary for the given version including a set of dependencies
	Build(
		ctx context.Context,
		platform Platform,
		k6Version string,
		mods []Module,
		buildOpts []string,
		out io.Writer,
	) (*BuildInfo, error)
}

Builder defines the interface for building a k6 binary

func NewDefaultNativeBuilder

func NewDefaultNativeBuilder() (Builder, error)

NewDefaultNativeBuilder creates a new native build environment with default options

func NewNativeBuilder

func NewNativeBuilder(_ context.Context, opts NativeBuilderOpts) (Builder, error)

NewNativeBuilder creates a new native build environment with the given options

type GoOpts

type GoOpts struct {
	// Environment variables passed to the build service
	// Can override variables copied from the current go environment
	Env map[string]string
	// Copy Environment variables to go build environment
	CopyGoEnv bool
	// Timeout for getting modules
	GoGetTimeout time.Duration
	// Timeout for building binary
	GOBuildTimeout time.Duration
	// Use an ephemeral cache. Ignores GoModCache and GoCache
	TmpCache bool
}

GoOpts defines the options for the go build environment

type Module

type Module struct {
	// The name (import path) of the go module. If at a version > 1,
	// it should contain semantic import version (i.e. "/v2").
	// Used with `go get`.
	Path string

	// The version of the Go module, as used with `go get`.
	Version string

	// Module replacement
	ReplacePath string

	//  Module replace version
	ReplaceVersion string
}

Module reference a go module and its version

func ParseModule

func ParseModule(modString string) (Module, error)

ParseModule parses a module from a string of the form path[@version][=replace[@version]]

func (Module) String

func (m Module) String() string

type NativeBuilderOpts

type NativeBuilderOpts struct {
	// options used for running go
	GoOpts
	// use alternative k6 repository
	K6Repo string
	// don't cleanup work environment (useful for debugging)
	SkipCleanup bool
	// redirect stdout
	Stdout io.Writer
	// redirect stderr
	Stderr io.Writer
	// set log level (INFO, WARN, ERROR)
	Logger *slog.Logger
}

NativeBuilderOpts defines the options for the Native build environment

type Platform

type Platform struct {
	OS   string
	Arch string
}

Platform defines a target OS and architecture for building a custom binary

func NewPlatform

func NewPlatform(os, arch string) Platform

NewPlatform creates a new Platform given the os and arch

func ParsePlatform

func ParsePlatform(str string) (Platform, error)

ParsePlatform parses a string of the format os/arch and returns the corresponding platform

func RuntimePlatform

func RuntimePlatform() Platform

RuntimePlatform returns the Platform of the current executable

func SupportedPlatforms

func SupportedPlatforms() []Platform

SupportedPlatforms returns a list of supported platforms

func (Platform) String

func (p Platform) String() string

String returns the platform in the format os/arch

func (Platform) Supported

func (p Platform) Supported() bool

Supported indicates is the given platform is supported