k6registry

README

k6registry

Data model and tooling for the k6 extension registry

This repository contains the JSON schema of the k6 extension registry and the k6registry command line tool for registry processing. The command line tool can also be used as a GitHub Action.

Check k6 Extension Registry Concept for information on design considerations.

Example registry

- module: github.com/grafana/xk6-dashboard
  description: Web-based metrics dashboard for k6
  outputs:
    - dashboard
  official: true

- module: github.com/grafana/xk6-sql
  description: Load test SQL Servers
  imports:
    - k6/x/sql
  cloud: true
  official: true

- module: github.com/grafana/xk6-disruptor
  description: Inject faults to test
  imports:
    - k6/x/disruptor
  official: true

- module: github.com/szkiba/xk6-faker
  description: Generate random fake data
  imports:
    - k6/x/faker

A legacy extension registry converted to the new format is also a good example.

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/k6registry/cmd/k6registry@latest

GitHub Action

grafana/k6registry is a GitHub Action that enables k6 extension registry processing and the generation of customized JSON output for different applications. Processing is based on popular jq expressions using an embedded jq implementation.

The jq filter expression can be specified in the filter parameter.

The extension registry is read from the YAML format file specified in the in parameter.

Repository metadata is collected using the repository manager APIs. Currently only the GitHub API is supported.

The output of the processing will be written to the standard output by default. The output can be saved to a file using the out parameter.

Parameters

name	reqired	default	description
filter	no	.	jq compatible filter
in	yes		input file name
out	no	stdout	output file name
mute	no	false	no output, only validation
loose	no	false	skip JSON schema validation
lint	no	false	enable built-in linter
compact	no	false	compact instead of pretty-printed output
raw	no	false	output raw strings, not JSON texts
yaml	no	false	output YAML instead of JSON
ref	no		reference output URL for change detection

In GitHub action mode, the change can be indicated by comparing the output to a reference output. The reference output URL can be passed in the ref action parameter. The changed output variable will be true or false depending on whether the output has changed or not compared to the reference output.

Example usage

- name: Generate registry in JSON format
  uses: grafana/k6registry@v0.1.4
  with:
    in: "registry.yaml"
    out: "registry.json"
    filter: "."

CLI

k6registry

k6 extension registry processor

Synopsis

Command line k6 extension registry processor.

k6registry is a command line tool that enables k6 extension registry processing and the generation of customized JSON output for different applications. Processing is based on popular jq expressions using an embedded jq implementation.

The first argument is the jq filter expression. This is the basis for processing.

The extension registry is read from the YAML format file specified in the second argument. If it is missing, the extension registry is read from the standard input.

Repository metadata is collected using the repository manager APIs. Currently only the GitHub API is supported.

The output of the processing will be written to the standard output by default. The output can be saved to a file using the -o/--out flag.

k6registry [flags] <jq filter> [file]

Flags

  -o, --out string   write output to file instead of stdout
  -m, --mute         no output, only validation
      --loose        skip JSON schema validation
      --lint         enable built-in linter
  -c, --compact      compact instead of pretty-printed output
  -r, --raw          output raw strings, not JSON texts
  -y, --yaml         output YAML instead of JSON
  -V, --version      print version
  -h, --help         help for k6registry

Contribure

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

Documentation

Overview

Package k6registry contains the data model of the k6 extensions registry.

Index

• Variables
• type Extension
• type Registry
• type Repository

Variables

var Schema []byte

Schema contains JSON schema for registry JSON.

Types

type Extension

type Extension struct {
	// Cloud-enabled extension flag.
	//
	// The `true` value of the `cloud` flag indicates that the extension is also
	// available in the Grafana k6 cloud.
	//
	// The use of certain extensions is not supported in a cloud environment. There
	// may be a technological reason for this, or the extension's functionality is
	// meaningless in the cloud.
	//
	Cloud bool `json:"cloud,omitempty" yaml:"cloud,omitempty" mapstructure:"cloud,omitempty"`

	// Brief description of the extension.
	//
	Description string `json:"description" yaml:"description" mapstructure:"description"`

	// List of JavaScript import paths registered by the extension.
	//
	// Currently, paths must start with the prefix `k6/x/`.
	//
	// The extensions used by k6 scripts are automatically detected based on the
	// values specified here, therefore it is important that the values used here are
	// consistent with the values registered by the extension at runtime.
	//
	Imports []string `json:"imports,omitempty" yaml:"imports,omitempty" mapstructure:"imports,omitempty"`

	// The extension's go module path.
	//
	// This is the unique identifier of the extension.
	// More info about module paths: https://go.dev/ref/mod#module-path
	//
	// The extension has no name property, the module path or part of it can be used
	// as the extension name. For example, using the first two elements of the module
	// path after the host name, the name `grafana/xk6-dashboard` can be formed from
	// the module path `github.com/grafana/xk6-dashboard`. This is typically the
	// repository owner name and the repository name in the repository manager.
	//
	// The extension has no URL property, a URL can be created from the module path
	// that refers to the extension within the repository manager.
	//
	Module string `json:"module" yaml:"module" mapstructure:"module"`

	// Officially supported extension flag.
	//
	// The `true` value of the `official` flag indicates that the extension is
	// officially supported by Grafana.
	//
	// Extensions owned by the `grafana` GitHub organization are not officially
	// supported by Grafana by default. There are several k6 extensions owned by the
	// `grafana` GitHub organization, which were created for experimental or example
	// purposes only. The `official` flag is needed so that officially supported
	// extensions can be distinguished from them.
	//
	Official bool `json:"official,omitempty" yaml:"official,omitempty" mapstructure:"official,omitempty"`

	// List of output names registered by the extension.
	//
	// The extensions used by k6 scripts are automatically detected based on the
	// values specified here, therefore it is important that the values used here are
	// consistent with the values registered by the extension at runtime.
	//
	Outputs []string `json:"outputs,omitempty" yaml:"outputs,omitempty" mapstructure:"outputs,omitempty"`

	// Repository metadata.
	//
	// Metadata provided by the extension's git repository manager. Repository
	// metadata are not registered, they are queried at runtime using the repository
	// manager API.
	//
	Repo *Repository `json:"repo,omitempty" yaml:"repo,omitempty" mapstructure:"repo,omitempty"`
}

Properties of the registered k6 extension.

Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.

Properties that are available using the repository manager API are intentionally not registered.

The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)

type Registry

type Registry []Extension

k6 Extension Registry.

The k6 extension registry contains the most important properties of registered extensions.

type Repository

type Repository struct {
	// Archived repository flag.
	//
	// A `true` value indicates that the repository is archived, read only.
	//
	// If a repository is archived, it usually means that the owner has no intention
	// of maintaining it. Such extensions should be removed from the registry.
	//
	Archived bool `json:"archived,omitempty" yaml:"archived,omitempty" mapstructure:"archived,omitempty"`

	// Repository description.
	//
	Description string `json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`

	// The URL to the project homepage.
	//
	// If no homepage is set, the value is the same as the url property.
	//
	Homepage string `json:"homepage,omitempty" yaml:"homepage,omitempty" mapstructure:"homepage,omitempty"`

	// The SPDX ID of the extension's license.
	//
	// For more information about SPDX, visit https://spdx.org/licenses/
	//
	License string `json:"license,omitempty" yaml:"license,omitempty" mapstructure:"license,omitempty"`

	// The name of the repository.
	//
	Name string `json:"name" yaml:"name" mapstructure:"name"`

	// The owner of the repository.
	//
	Owner string `json:"owner" yaml:"owner" mapstructure:"owner"`

	// Public repository flag.
	//
	// A `true` value indicates that the repository is public, available to anyone.
	//
	Public bool `json:"public,omitempty" yaml:"public,omitempty" mapstructure:"public,omitempty"`

	// The number of stars in the extension's repository.
	//
	// The extension's popularity is indicated by how many users have starred the
	// extension's repository.
	//
	Stars int `json:"stars,omitempty" yaml:"stars,omitempty" mapstructure:"stars,omitempty"`

	// Repository topics.
	//
	// Topics make it easier to find the repository. It is recommended to set the xk6
	// topic to the extensions repository.
	//
	Topics []string `json:"topics,omitempty" yaml:"topics,omitempty" mapstructure:"topics,omitempty"`

	// URL of the repository.
	//
	// The URL is provided by the repository manager and can be displayed in a
	// browser.
	//
	Url string `json:"url" yaml:"url" mapstructure:"url"`

	// List of supported versions.
	//
	// Versions are tags whose format meets the requirements of semantic versioning.
	// Version tags often start with the letter `v`, which is not part of the semantic
	// version.
	//
	Versions []string `json:"versions,omitempty" yaml:"versions,omitempty" mapstructure:"versions,omitempty"`
}

Repository metadata.

Metadata provided by the extension's git repository manager. Repository metadata are not registered, they are queried at runtime using the repository manager API.