Skip to main content

Kosko 4.1: Beyond Type Safe

· 4 min read

Today, I'm excited to announce the release of Kosko 4.1. This release is a significant milestone for Kosko.

Plugin System

The first major feature is the plugin system introduced in Kosko 4.0. It allows you to modify manifests, or run extra validations. Currently there are two official plugins, and we are going to introduce them in this post.

Set Metadata

The first one is @kosko/plugin-set-metadata. This plugin can modify namespace, name, labels and annotations of manifests. For example, you can set a namespace for all manifests.

name = "@kosko/plugin-set-metadata"
config.namespace.value = "dev"

You can check here for more details.


The other one is @kosko/plugin-lint. Prior to Kosko 4, Kosko only validates manifests against Kubernetes OpenAPI schema, which only contains data types, formats, required fields, etc. However, it's not enough to find all potential issues in manifests.

@kosko/plugin-lint can run extra validations on manifests. For example:

You can enable the recommended rules by setting the following configuration.

name = "@kosko/plugin-lint"
config.extends = ["@kosko/plugin-lint/presets/recommended"]

Please check here for more details. More lint rules will be added in the future. Feel free to open an issue if you have any ideas.

Streamlined Error Report

Error report was hugely improved in Kosko 3.0. However, it might be too verbose sometimes. In Kosko 4.1, error report system was redesigned to be more streamlined.

Manifest information such as API version, kind, namespace, name, and index were previously displayed in multiple lines. Now, they are displayed in a single line.

components/nginx.ts - apps/v1/Deployment dev/nginx [0]

✖ /spec/replicas must be integer

✖ no-missing-namespace: Namespace "dev" does not exist or is not allowed.

components/nginx.ts - v1/Service nginx [1]

✖ unique-service-port-name: Service contains multiple ports with the same name "http"

error - Found 3 errors in total
error - Generate failed

The other improvement is the new warning severity. This severity is used for issues that are not critical, but should be fixed. When a warning is found, the error report will display a warning message, but the manifest generation will still be successful.

In the following example, missing readiness probe is displayed as a warning.

components/nginx.ts - apps/v1/Deployment nginx [0]

⚠ require-probe: Container "nginx" must define a readiness probe.

warn - Found 1 warning in total
info - Components are valid

Breaking Changes

Minimum Node.js Version

Support for Node.js 14 was dropped. The minimum supported Node.js version is now 18.

Kosko CLI

kosko init command was removed from the CLI because it's only used at the first time. Now, you can use the new create-kosko package to create a new project.

npm create kosko@latest example



This section only applies to users who use @kosko/generate programmatically. You can safely ignore this section if you only use the CLI.

Error handling was hugely changed in @kosko/generate 5.0. To support the new error report system, a new type Issue ws introduced. This type is used in Manifest.issues, providing more information about issues of manifests.

However, this means errors are no longer thrown when a validation error occurs. You can enable the previous behavior by setting throwOnError to true.

Another change about the error handling is that Ajv errors are automatically transformed into issues. Now you can access Ajv errors in Manifest.issues. You can disable this behavior by setting keepAjvErrors to true.

Next, the component property was replaced by metadata property in ResolveError class. The metadata property was added to Manifest type as well. This property contains API version, kind, namespace, and name of a manifest.

Lastly, path and index properties were replaced by the position property in Manifest, ResolveErrorOptions, and ResolveError type.



This section only applies to users who use the @kosko/aggregate-error package. You can safely ignore this section if you only use the CLI.

This package was removed because AggregateError is now built-in in Node.js 15.0.0 and later. If you are using @kosko/aggregate-error package, please remove it from your dependencies and just use the global AggregateError class.



This section only applies to users who use the @kosko/require package. It's a low-level package, so you probably don't use it at all.

The resolve function is renamed to resolvePath because the introduction of the new resolveModule function. The resolvePath function only supports path resolution, while the resolveModule function supports both path and module resolution.