k6build

package module

v0.5.0 Latest Latest Go to latest Published: Dec 13, 2024 License: AGPL-3.0 Imports: 6 Imported by: 2

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/grafana/k6build

README ¶

k6build

k6build builds custom k6 binaries with extensions.

API

k6build defines an API for building custom k6 binaries.

The API returns the metadata of the custom binary, including an URL for downloading it, but does not return the binary itself.

The request for building a binary specifies the target platform (required) and the dependencies, including k6.

The dependencies specify the import path (as used in the k6 script) and the semantic version constrains.

Dependencies are mapped by a catalog to the corresponding go module that implements it. The catalog also defines the available versions.

If a dependency doesn't specify a constrains, the latest version (according to the catalog) is used.

See k6catalog for more details on defining a catalog.

The default catalog is defined at https://registry.k6.io/catalog.json

Usage scenarios

The following sections describe different usage scenarios.

kubernetes

examples/kubernetes describes how to run k6build in a kubernetes cluster and execute k6 tests in a pod using k6exec.

k6-operator

TODO: use k6-operator for running the tests using a custom image.

k6build

Build custom k6 binaries with extensions

Commands

k6build local - build custom k6 binary locally
k6build remote - build a custom k6 using a remote build server
k6build server - k6 build service
k6build store - k6build object store server

k6build local

build custom k6 binary locally

Synopsis

k6build local builder creates a custom k6 binary artifacts that satisfies certain dependencies. Requires the golang toolchain and git.

k6build local [flags]

Examples


# build k6 v0.51.0 with latest version of k6/x/kubernetes
k6build local -k v0.51.0 -d k6/x/kubernetes

platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.9.0
checksum: 7f06720503c80153816b4ef9f58571c2fce620e0447fba1bb092188ff87e322d

# build k6 v0.51.0 with k6/x/kubernetes v0.8.0 and k6/x/output-kafka v0.7.0
k6build local -k v0.51.0 \
    -d k6/x/kubernetes:v0.8.0 \
    -d k6/x/output-kafka:v0.7.0

platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.8.0
k6/x/output-kafka": v0.7.0
checksum: f4af178bb2e29862c0fc7d481076c9ba4468572903480fe9d6c999fea75f3793


# build k6 v0.50.0 with latest version of k6/x/kubernetes using a custom catalog
k6build local -k v0.50.0 -d k6/x/kubernetes \
    -c /path/to/catalog.json -q

# build k6 v0.50.0 using a custom GOPROXY
k6build local -k v0.50.0 -e GOPROXY=http://localhost:80 -q

Flags

      --allow-build-semvers      allow building versions with build metadata (e.g v0.0.0+build).
  -c, --catalog string           dependencies catalog (default "https://registry.k6.io/catalog.json")
  -g, --copy-go-env              copy go environment (default true)
  -d, --dependency stringArray   list of dependencies in form package:constrains
  -e, --env stringToString       build environment variables (default [])
  -h, --help                     help for local
  -k, --k6 string                k6 version constrains (default "*")
  -o, --output string            path to put the binary as an executable. (default "k6")
  -p, --platform string          target platform (default GOOS/GOARCH)
  -q, --quiet                    don't print artifact's details
  -f, --store-dir string         object store dir (default "/tmp/k6build/store")
  -v, --verbose                  print build process output

k6build remote

build a custom k6 using a remote build server

Synopsis

Builds custom k6 binaries using a k6build server returning the details of the binary artifact and optionally download it.

k6build remote [flags]

Examples


# build k6 v0.51.0 with k6/x/kubernetes v0.8.0 and k6/x/output-kafka v0.7.0
k6build remote -s http://localhost:8000 \
    -k v0.51.0 \
    -p linux/amd64 \
    -d k6/x/kubernetes:v0.8.0 \
    -d k6/x/output-kafka:v0.7.0

id: 62d08b13fdef171435e2c6874eaad0bb35f2f9c7
platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.9.0
k6/x/output-kafka": v0.7.0
checksum: f4af178bb2e29862c0fc7d481076c9ba4468572903480fe9d6c999fea75f3793
url: http://localhost:8000/store/62d08b13fdef171435e2c6874eaad0bb35f2f9c7/download


# build k6 v0.51 with k6/x/output-kafka v0.7.0 and download as 'build/k6'
k6build remote -s http://localhost:8000 \
    -p linux/amd64  \
    -k v0.51.0 -d k6/x/output-kafka:v0.7.0 \
    -o build/k6 -q

# check downloaded binary
build/k6 version
k6 v0.51.0 (go1.22.2, linux/amd64)
Extensions:
  github.com/grafana/xk6-output-kafka v0.7.0, xk6-kafka [output]

Flags

  -d, --dependency stringArray   list of dependencies in form package:constrains
  -h, --help                     help for remote
  -k, --k6 string                k6 version constrains (default "*")
  -o, --output string            path to download the custom binary as an executable.
                                 If not specified, the artifact is not downloaded.
  -p, --platform string          target platform (default GOOS/GOARCH)
  -q, --quiet                    don't print artifact's details
  -s, --server string            url for build server (default "http://localhost:8000")

k6build server

k6 build service

Synopsis

Starts a k6build server

The server exposes an API for building custom k6 binaries.

The API returns the metadata of the custom binary, including an URL for downloading it, but does not return the binary itself.

For example

curl http://localhost:8000/build/ -d \
'{
  "k6":"v0.50.0",
  "dependencies":[
    {
	"name":"k6/x/kubernetes",
	"constraints":">v0.8.0"
    }
  ],
  "platform":"linux/amd64"
}' | jq .

{
  "artifact": {
  "id": "5a241ba6ff643075caadbd06d5a326e5e74f6f10",
  "url": "http://localhost:9000/store/5a241ba6ff643075caadbd06d5a326e5e74f6f10/download",
  "dependencies": {
    "k6": "v0.50.0",
    "k6/x/kubernetes": "v0.10.0"
  },
  "platform": "linux/amd64",
  "checksum": "bfdf51ec9279e6d7f91df0a342d0c90ab4990ff1fb0215938505a6894edaf913"
  }
}

Note: The build server does not support CGO_ENABLE when building binaries due to this issue: https://github.com/grafana/k6build/issues/37 use --enable-cgo=true to enable CGO support

k6build server [flags]

Examples


# start the build server using a custom local catalog
k6build server -c /path/to/catalog.json

# start the build server using a custom GOPROXY
k6build server -e GOPROXY=http://localhost:80

Flags

      --allow-build-semvers   allow building versions with build metadata (e.g v0.0.0+build).
  -c, --catalog string        dependencies catalog. Can be path to a local file or an URL.
                               (default "https://registry.k6.io/catalog.json")
  -g, --copy-go-env           copy go environment (default true)
      --enable-cgo            enable CGO for building binaries.
  -e, --env stringToString    build environment variables (default [])
  -h, --help                  help for server
  -l, --log-level string      log level (default "INFO")
  -p, --port int              port server will listen (default 8000)
      --s3-endpoint string    s3 endpoint
      --s3-region string      aws region
      --store-bucket string   s3 bucket for storing binaries
      --store-url string      store server url (default "http://localhost:9000/store")
  -v, --verbose               print build process output

k6build store

k6build object store server

Synopsis

Starts a k6build objectstore server.

The object server offers a REST API for storing and downloading objects.

Objects can be retrieved by a download url returned when the object is stored.

The --download-url specifies the base URL for downloading objects. This is necessary to allow downloading the objects from different machines.

k6build store [flags]

Examples


# start the server serving an external url
k6build store --download-url http://external.url

# store object from same host
curl -x POST http://localhost:9000/store/objectID -d "object content" | jq .
{
	"Error": "",
	"Object": {
	  "ID": "objectID",
	  "Checksum": "17d3eb873fe4b1aac4f9d2505aefbb5b53b9a7f34a6aadd561be104c0e9d678b",
	  "URL": "http://external.url:9000/store/objectID/download"
	}
      }

# download object from another machine using the external url
curl http://external.url:9000/store/objectID/download

Flags

  -d, --download-url string   base url used for downloading objects.
                              If not specified http://localhost:<port>/store is used
  -h, --help                  help for store
  -l, --log-level string      log level (default "INFO")
  -p, --port int              port server will listen (default 9000)
  -c, --store-dir string      object store directory (default "/tmp/store/objectstore")

Documentation ¶

Overview ¶

Package k6build defines a service for building k6 binaries

Index ¶

Variables
func ParseLogLevel(levelString string) (slog.Level, error)
type Artifact
type BuildService
type Dependency
type Module
type WrappedError
- func AsError(e error) (*WrappedError, bool)
- func NewWrappedError(err error, reason error) *WrappedError

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrBuildFailed = errors.New("build failed") //nolint:revive

View Source

var ErrReasonUnknown = errors.New("reason unknown")

ErrReasonUnknown signals the reason for an WrappedError is unknown

Functions ¶

func ParseLogLevel ¶ added in v0.2.3

func ParseLogLevel(levelString string) (slog.Level, error)

ParseLogLevel parses the level from a string

Types ¶

type Artifact ¶

type Artifact struct {
	// Unique id. Binaries satisfying the same set of dependencies have the same ID
	ID string `json:"id,omitempty"`
	// URL to fetch the artifact's binary
	URL string `json:"url,omitempty"`
	// List of dependencies that the artifact provides
	Dependencies map[string]string `json:"dependencies,omitempty"`
	// platform
	Platform string `json:"platform,omitempty"`
	// binary checksum (sha256)
	Checksum string `json:"checksum,omitempty"`
}

Artifact defines the metadata of binary that satisfies a set of dependencies including a URL for downloading it.

func (Artifact) Print ¶ added in v0.3.1

func (a Artifact) Print() string

Print returns a string with a pretty print of the artifact

func (Artifact) PrintSummary ¶ added in v0.3.1

func (a Artifact) PrintSummary() string

PrintSummary returns a string with a pretty print of the artifact

func (Artifact) String ¶ added in v0.2.0

func (a Artifact) String() string

String returns a text serialization of the Artifact

type BuildService ¶

type BuildService interface {
	// Build returns a k6 Artifact that satisfies a set dependencies and version constrains.
	Build(ctx context.Context, platform string, k6Constrains string, deps []Dependency) (Artifact, error)
}

BuildService defines the interface for building custom k6 binaries

type Dependency ¶

type Dependency struct {
	// Name is the name of the dependency.
	Name string `json:"name,omitempty"`
	// Constraints specifies the semantic version constraints. E.g. >v0.2.0
	Constraints string `json:"constraints,omitempty"`
}

Dependency defines a dependency and its semantic version constrains

type Module ¶

type Module struct {
	// Path is the go module path
	Path string `json:"path,omitempty"`
	// Version is the go module version
	Version string `json:"version,omitempty"`
}

Module defines the mapping of a Dependency to a go module that satisfies it

type WrappedError ¶ added in v0.3.7

type WrappedError struct {
	Err    error `json:"error,omitempty"`
	Reason error `json:"reason,omitempty"`
}

WrappedError represents an error returned by the build service This custom error type facilitates extracting the reason of an error by using errors.Unwrap method. It also facilitates checking an error (or its reason) using errors.Is by comparing the error and its reason. This custom type has the following known limitations: - A nil WrappedError 'e' will not satisfy errors.Is(e, nil) - Is method will not

func AsError ¶ added in v0.3.7

func AsError(e error) (*WrappedError, bool)

AsError returns an error as an Error, if possible

func NewWrappedError ¶ added in v0.3.7

func NewWrappedError(err error, reason error) *WrappedError

NewWrappedError creates an Error from an error and a reason If the reason is nil, ErrReasonUnknown is used

func (*WrappedError) Error ¶ added in v0.3.7

func (e *WrappedError) Error() string

Error returns the Error as a string

func (*WrappedError) Is ¶ added in v0.3.7

func (e *WrappedError) Is(target error) bool

Is returns true if the target error is the same as the WrappedError or its reason It attempts several strategies: - compare error and reason to target's Error() - unwrap the error and reason and compare to target's WrappedError - unwrap target and compares to the error recursively

func (*WrappedError) MarshalJSON ¶ added in v0.3.7

func (e *WrappedError) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for the WrappedError type

func (*WrappedError) UnmarshalJSON ¶ added in v0.3.7

func (e *WrappedError) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for the WrappedError type

func (*WrappedError) Unwrap ¶ added in v0.3.7

func (e *WrappedError) Unwrap() error

Unwrap returns the underlying reason for the WrappedError

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package cmd contains build cobra command factory function.	Package cmd contains build cobra command factory function.
k6build package main implements the CLI root command for the k6build tool	package main implements the CLI root command for the k6build tool
local Package local implements the local build command	Package local implements the local build command
remote Package remote implements the client command	Package remote implements the client command
server Package server implements the build server command	Package server implements the build server command
store Package store implements the object store server command	Package store implements the object store server command
pkg
api Package api defines the interface to a build service	Package api defines the interface to a build service
builder Package builder implements a build service	Package builder implements a build service
client Package client implements a client for a build service	Package client implements a client for a build service
local Package local implements a local build service	Package local implements a local build service
server Package server implements a build server	Package server implements a build server
store Package store defines the interface of an object store service	Package store defines the interface of an object store service
store/api Package api defines the interface to a store server	Package api defines the interface to a store server
store/client Package client implements an object store service client	Package client implements an object store service client
store/downloader Package downloader implements utility functions for downloading objects from a store	Package downloader implements utility functions for downloading objects from a store
store/file Package file implements a file-backed object store	Package file implements a file-backed object store
store/s3 Package s3 implements a s3-backed object store	Package s3 implements a s3-backed object store
store/server Package server implements an object store server	Package server implements an object store server
util Package util implements utility functions	Package util implements utility functions
tools
gendoc Package main contains CLI documentation generator tool.	Package main contains CLI documentation generator tool.

README ¶

k6build

API

Usage scenarios

kubernetes

k6-operator

k6build

Commands

k6build local

Synopsis

Examples

Flags

SEE ALSO

k6build remote

Synopsis

Examples

Flags

SEE ALSO

k6build server

Synopsis

Examples

Flags

SEE ALSO

k6build store

Synopsis

Examples

Flags

SEE ALSO

Documentation ¶

Overview ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func ParseLogLevel ¶ added in v0.2.3

Types ¶

type Artifact ¶

func (Artifact) Print ¶ added in v0.3.1

func (Artifact) PrintSummary ¶ added in v0.3.1

func (Artifact) String ¶ added in v0.2.0

type BuildService ¶

type Dependency ¶

type Module ¶

type WrappedError ¶ added in v0.3.7

func AsError ¶ added in v0.3.7

func NewWrappedError ¶ added in v0.3.7

func (*WrappedError) Error ¶ added in v0.3.7

func (*WrappedError) Is ¶ added in v0.3.7

func (*WrappedError) MarshalJSON ¶ added in v0.3.7

func (*WrappedError) UnmarshalJSON ¶ added in v0.3.7

func (*WrappedError) Unwrap ¶ added in v0.3.7

Source Files ¶

Directories ¶