k6dist

README

k6dist

k6 distro builder

k6dist is a CLI tool and a GitHub Action that allows you to build k6 distributions with extensions.

k6dist https://registry.k6.io/tier/official.json

The extensions to be embedded can be specified with an extension registry. The location of the extension registry can be specified with HTTP(S) URL or filesystem path.

k6dist builds k6 for the specified platforms with the extensions listed in the registry. After that, it also creates archive files corresponding to the platform (.zip for Windows, otherwise .tar.gz format).

In addition to the executable, the readme and the license file can be included in the archive.

A release notes file is also prepared, in which the extensions are listed with their current and previous versions and their description. The content of the release notes file can be customized, using a go template file.

Install

Precompiled binaries can be downloaded and installed from the Releases page.

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

go install github.com/grafana/k6dist/cmd/k6dist@latest

GitHub Action

grafana/k6dist is a GitHub Action that enables the building of k6 distibutions with extensions.

The extensions to be embedded can be specified with an extension registry. The location of the extension registry can be specified with HTTP(S) URL or filesystem path.

Inputs

See the CLI Flags section for the default values ​​for these parameters.

name	reqired	description
args	yes	extension registry location (URL or file path)
distro_name	no	distro name
distro_version	no	distro version
platform	no	list of target platforms
executable	no	executable file name template
archive	no	archive file name template
docker	no	generated Dockerfile name template
docker_template	no	template for the generated Dockerfile
notes	no	generated release notes file name template
notes_template	no	template for the generated release notes
notes_latest	no	latest release notes file for change detection
readme	no	readme file to be added to the archive
license	no	license file to be added to the archive
verbose	no	enable verbose logging
quiet	no	disable normal logging

The change can be indicated by comparing the generated release notes to the latest release notes. The location of the latest release notes path can be passed in the notes_latest action parameter. The changed output variable will be true or false depending on whether the release has changed or not compared to the latest release notes. If the release has not changed, the build step is skipped.

Outputs

name	description
changed	true if the release has changed compared to notes_latest, otherwise false
version	the distro release version

Example usage

- name: Build k6 distro
  uses: grafana/k6dist@v0.1.0
  with:
    args: "https://registry.k6.io/product/cloud.json"
    notes_latest: "latest-release-notes.md"

CLI

k6dist

k6 distro builder

Synopsis

Build k6 distribution with extensions.

k6dist enables building k6 distributions with extensions. The extensions to be embedded can be specified with an extension registry. The location of the registry can be specified with http(s) URL or filesystem path.

The location of the registry can be specified as a command line argument. If omitted, the URL of the registry subset containing the official k6 extensions is the default.

Each flag has a meaningful default value.

k6dist builds k6 for the specified platforms with the extensions listed in the registry. After that, it also creates archive files corresponding to the platform (.zip for Windows, otherwise .tar.gz format).

In addition to the executable, the readme and the license file can be included in the archive. Their names are detected, but can also be specified using the --readme and --license flags.

The locations of executables and archives can be specified with the go template expression using the --executable and --archive flags.

A release notes file is also prepared, in which the extensions are listed with their current and previous versions and their description. The release notes file can be customized, using the --notes-template flag you can specify a go template file to generate the release notes.

k6dist [flags] [registry-location]

Flags

      --distro-name string       distro name (default detect)
      --distro-version string    distro version (default generated)
      --platform strings         target platforms (default [linux/amd64,darwin/amd64,windows/amd64])
      --executable string        executable file name (default "dist/{{.Name}}_{{.OS}}_{{.Arch}}/k6{{.ExeExt}}")
      --archive string           archive file name (default "dist/{{.Name}}_{{.Version}}_{{.OS}}_{{.Arch}}{{.ZipExt}}")
      --docker string            generated Dockerfile name (default Dockerfile next to the exe)
      --docker-template string   template for the generated Dockerfile (default embedded)
      --notes string             generated release notes file name (default "dist/{{.Name}}_{{.Version}}.md")
      --notes-template string    template for the generated release notes (default embedded)
      --notes-latest string      latest release notes file for change detection
      --readme string            readme file to be added to the archive (default detect)
      --license string           license file to be added to the archive (default detect)
      --single-target            build only for the current runtime platform
  -v, --verbose                  enable verbose logging
  -q, --quiet                    disable normal logging
  -V, --version                  print version
  -h, --help                     help for k6dist

Contribure

If you want to contribute, start by reading CONTRIBUTING.md.

Documentation

Overview

Package k6dist contains k6dists's go API.

Index

• Constants
• Variables
• func Build(ctx context.Context, opts *Options) (bool, *semver.Version, error)
• type Options
• type Platform
  • func ParsePlatform(value string) (*Platform, error)
  • func (p Platform) String() string

Constants

const (
	// DefaultExecutableTemplate is a default go template for executable file path.
	DefaultExecutableTemplate = `dist/{{.Name}}_{{.OS}}_{{.Arch}}/k6{{.ExeExt}}`
	// DefaultNotesTemplate is a default go template for release notes file path.
	DefaultNotesTemplate = `dist/{{.Name}}_{{.Version}}.md`
	// DefaultArchiveTemplate is a default go template for archive file path.
	DefaultArchiveTemplate = `dist/{{.Name}}_{{.Version}}_{{.OS}}_{{.Arch}}{{.ZipExt}}`
	// DefaultRegistryURL is a default registry URL.
	DefaultRegistryURL = `https://registry.k6.io/tier/official.json`
)

Variables

var ErrInvalidPlatform = errors.New("invalid platform")

ErrInvalidPlatform thrown when platform cannot be parsed.

Functions

func Build

func Build(ctx context.Context, opts *Options) (bool, *semver.Version, error)

Build builds k6 binaries and archives based on opts parameter.

Types

type Options

type Options struct {
	// Name contains short name of the distribution.
	// Templating is not supported.
	Name string
	// Version contains distribution version.
	Version *semver.Version
	// Executable is the name of the k6 executable file to be built.
	// Templating is supported.
	// It defaults to DefaultExecutableTemplate.
	Executable string
	// Archive is the name of the archive file to be created.
	// Templating is supported.
	// It defaults to DefaultArchiveTemplate.
	Archive string
	// Readme is the name of the readme file to be added.
	// Templating is not supported.
	// No readme will be added if it is empty.
	Readme string
	// License is the name of the license file to be added.
	// Templating is not supported.
	// No license will be added if it is empty.
	License string
	// NotesTemplate is the name of the release notes (go) template file.
	// Templating is not supported in filename.
	// Default is an embedded template.
	NotesTemplate string
	// Notes is the name of the generated release notes file.
	// Templating is supported.
	// It defaults to DefaultNotesTemplate.
	Notes string
	// DockerfileTemplate is the name of the Dockerfile template.
	// Templating is not supported in filename.
	// Default is an embedded template.
	DockerfileTemplate string
	// Dockerfile is the name of the generated Dockerfile.
	// Templating is supported.
	// It defaults to Dockerfile in the same directory as the executable.
	Dockerfile string
	// NotesLatest contains the name of the latest release notes file.
	// It is used for change detection, if the release notes have not changed, no new release is made.
	// Within the release notes, an HTML comment contains the module list.
	// Change detection is done by comparing this.
	// Templating is not supported.
	NotesLatest string
	// Platforms contains the target platforms.
	// If absent, the current runtime platform will be used.
	Platforms []*Platform
	// Registry contains the location of the registry. Its value is http(s) URL or filesystem path.
	// Templating is not supported.
	// It defaults to the URL of the registry subset containing the official k6 extensions.
	Registry string
}

Options contains the optional parameters of the Build function.

type Platform

type Platform struct {
	OS   string
	Arch string
}

Platform contains a target platform (OS and architecture) for building.

func ParsePlatform

func ParsePlatform(value string) (*Platform, error)

ParsePlatform parses string representation of Platform.

func (Platform) String

func (p Platform) String() string

String returns the platform in string format.