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 generating registry from source. The command line tool can also be used as a GitHub Action.

Check k6 Extension Registry Concept for information on design considerations.

Example registry source

- module: github.com/grafana/xk6-dashboard
  description: Web-based metrics dashboard for k6
  outputs:
    - dashboard
  tier: official
  categories:
    - reporting
    - observability

- module: github.com/grafana/xk6-sql
  description: Load test SQL Servers
  imports:
    - k6/x/sql
  tier: official
  products: ["cloud", "oss"]
  categories:
    - data

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

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

- module: gitlab.com/szkiba/xk6-banner
  description: Print ASCII art banner from k6 test
  imports:
    - k6/x/banner
  categories:
    - misc

Example registry

Registry generated from the source above.

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.

Inputs

name	reqired	default	description
in	yes		input file name
out	no	stdout	output file name
api	no		output directory 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
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.

The api parameter can be used to specify a directory into which the outputs are written. The registry.json file is placed in the root directory. The extension.json file and the badge.svg file are placed in a directory with the same name as the go module path of the extension (if the lint parameter is true).

Outputs

name	description
changed	true if the output has changed compared to ref, otherwise false

Example usage

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

CLI

k6registry

k6 extension registry generator

Synopsis

Command line k6 extension registry generator.

The source of the extension registry contains only the most important properties of the extensions. The rest of the properties are collected by k6registry using the API of the extensions' git repository managers.

The source of the extension registry is read from the YAML (or JSON) format file specified as command line argument. If it is missing, the source is read from the standard input.

Repository metadata is collected using the API of the extensions' git repository managers. Currently only the GitHub API is supported.

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

The --api flag can be used to specify a directory to which the outputs will be written. The registry.json file is placed in the root directory. The extension.json file and the badge.svg file (if the --lint flag is used) are placed in a directory with the same name as the extension's go module path.

k6registry [flags] [source-file]

Flags

  -o, --out string   write output to file instead of stdout
      --api string   write outputs to directory instead of stdout
  -q, --quiet        no output, only validation
      --loose        skip JSON schema validation
      --lint         enable built-in linter
  -c, --compact      compact instead of pretty-printed output
  -V, --version      print version
  -h, --help         help for k6registry

API in the filesystem

By using the --api flag, files are created with relative paths in a base directory with a kind of REST API logic:

• in the module directory, a directory with the same name as the path of the extension module
  • badge.svg badge generated based on the compliance grade
  • extension.json extension data in a separate file
• the subdirectories of the base directory contain subsets of the registry broken down according to different properties (tier, product, category, grade)

docs/example-api
├── registry.json
├── registry.schema.json
├── category
│   ├── authentication.json
│   ├── browser.json
│   ├── data.json
│   ├── kubernetes.json
│   ├── messaging.json
│   ├── misc.json
│   ├── observability.json
│   ├── protocol.json
│   └── reporting.json
├── grade
│   ├── A.json
│   ├── B.json
│   ├── C.json
│   ├── D.json
│   ├── E.json
│   ├── F.json
│   └── passing
│       ├── A.json
│       ├── B.json
│       ├── C.json
│       ├── D.json
│       ├── E.json
│       └── F.json
├── module
│   ├── github.com
│   │   ├── grafana
│   │   │   ├── xk6-dashboard
│   │   │   │   ├── badge.svg
│   │   │   │   └── extension.json
│   │   │   ├── xk6-disruptor
│   │   │   │   ├── badge.svg
│   │   │   │   └── extension.json
│   │   │   └── xk6-sql
│   │   │       ├── badge.svg
│   │   │       └── extension.json
│   │   └── szkiba
│   │       └── xk6-faker
│   │           ├── badge.svg
│   │           └── extension.json
│   ├── gitlab.com
│   │   └── szkiba
│   │       └── xk6-banner
│   │           ├── badge.svg
│   │           └── extension.json
│   └── go.k6.io
│       └── k6
│           └── extension.json
├── product
│   ├── cloud.json
│   └── oss.json
└── tier
    ├── community.json
    └── official.json

The primary purpose of the --api flag is to support a custom k6 extension registry instance.

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 Category
• type Compliance
• type Extension
• type Grade
• type Product
• type Registry
• type Repository
• type Tier

Variables

var (
	// Categories contains possible values for Category
	Categories = []Category{
		CategoryAuthentication,
		CategoryBrowser,
		CategoryData,
		CategoryKubernetes,
		CategoryMessaging,
		CategoryMisc,
		CategoryObservability,
		CategoryProtocol,
		CategoryReporting,
	}

	// Products contains possible values for Product
	Products = []Product{ProductCloud, ProductOSS}

	// Grades contains possible values for Grade
	Grades = []Grade{GradeA, GradeB, GradeC, GradeD, GradeE, GradeF}

	// Tiers contains possible values for Tier
	Tiers = []Tier{TierOfficial, TierPartner, TierCommunity}
)

var Schema []byte

Schema contains JSON schema for registry JSON.

Types

type Category

type Category string

const CategoryAuthentication Category = "authentication"

const CategoryBrowser Category = "browser"

const CategoryData Category = "data"

const CategoryKubernetes Category = "kubernetes"

const CategoryMessaging Category = "messaging"

const CategoryMisc Category = "misc"

const CategoryObservability Category = "observability"

const CategoryProtocol Category = "protocol"

const CategoryReporting Category = "reporting"

type Compliance

type Compliance struct {
	// Compliance expressed as a grade.
	//
	// The `grade` property contains a grade (A-F) of how well the extension complies
	// with best practices.
	// The value of the `grade` can be `A`,`B`,`C`,`D`,`E`,`F` and is calculated from
	// the `level` property.
	//
	Grade Grade `json:"grade" yaml:"grade" mapstructure:"grade"`

	// Compliance expressed as a percentage.
	//
	// The `level` property contains a percentage of how well the extension complies
	// with best practices.
	// The value of the `level` can be between `0-100` and is determined by the
	// weighted and normalized sum of the scores of the compliance checks.
	//
	Level interface{} `json:"level" yaml:"level" mapstructure:"level"`
}

The result of the extension's k6 compliance checks.

type Extension

type Extension struct {
	// The categories to which the extension belongs.
	//
	// If the property is missing or empty in the registry source, the default value
	// is "misc".
	//
	// Possible values:
	//
	//   - authentication
	//   - browser
	//   - data
	//   - kubernetes
	//   - messaging
	//   - misc
	//   - observability
	//   - protocol
	//   - reporting
	//
	Categories []Category `json:"categories,omitempty" yaml:"categories,omitempty" mapstructure:"categories,omitempty"`

	// The result of the extension's k6 compliance checks.
	//
	Compliance *Compliance `json:"compliance,omitempty" yaml:"compliance,omitempty" mapstructure:"compliance,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"`

	// 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"`

	// Products in which the extension can be used.
	//
	// Some extensions are not available in all k6 products.
	// This may be for a technological or business reason, or the functionality of the
	// extension may not make sense in the given product.
	//
	// Possible values:
	//
	//   - oss: Extensions are available in k6 OSS
	//   - cloud: Extensions are available in Grafana Cloud k6
	//
	// If the property is missing or empty in the source of the registry, it means
	// that the extension is only available in the k6 OSS product.
	// In this case, the registry will be filled in accordingly during generation.
	//
	//
	Products []Product `json:"products,omitempty" yaml:"products,omitempty" mapstructure:"products,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"`

	// Maintainer of the extension.
	//
	// Possible values:
	//
	//   - official: Extensions owned, maintained, and designated by Grafana as
	// "official"
	//   - partner: Extensions written, maintained, validated, and published by
	// third-party companies against their own projects.
	//   - community: Extensions are listed on the Registry by individual maintainers,
	// groups of maintainers, or other members of the k6 community.
	//
	// 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` tier value is needed so that officially supported extensions can
	// be distinguished from them.
	//
	// If it is missing from the registry source, it will be set with the default
	// "community" value during generation.
	//
	//
	Tier Tier `json:"tier,omitempty" yaml:"tier,omitempty" mapstructure:"tier,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 Grade

type Grade string

const GradeA Grade = "A"

const GradeB Grade = "B"

const GradeC Grade = "C"

const GradeD Grade = "D"

const GradeE Grade = "E"

const GradeF Grade = "F"

const GradeG Grade = "G"

type Product

type Product string

const ProductCloud Product = "cloud"

const ProductOSS Product = "oss"

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"`

	// URL for the git clone operation.
	//
	// The clone_url property contains a (typically HTTP) URL, which is used to clone
	// the repository.
	//
	CloneURL string `json:"clone_url,omitempty" yaml:"clone_url,omitempty" mapstructure:"clone_url,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"`

	// Last modification timestamp.
	//
	// The timestamp property contains the timestamp of the last modification of the
	// repository in UNIX time format (the number of non-leap seconds that have
	// elapsed since 00:00:00 UTC on 1st January 1970).
	// Its value depends on the repository manager, in the case of GitHub it contains
	// the time of the last push operation, in the case of GitLab the time of the last
	// repository activity.
	//
	Timestamp float64 `json:"timestamp,omitempty" yaml:"timestamp,omitempty" mapstructure:"timestamp,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.

type Tier

type Tier string

const TierCommunity Tier = "community"

const TierOfficial Tier = "official"

const TierPartner Tier = "partner"