Kosko 4.1: Beyond Type Safe
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.
[[plugins]]
name = "@kosko/plugin-set-metadata"
config.namespace.value = "dev"
You can check here for more details.
Lint
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:
- Check if a resource reference exists or not. (no-missing-* rules)
- Require security context for containers. (require-security-context)
- Check if service ports are unique. (unique-service-port-name)
- Check if deployment selector matches with pod labels. (valid-pod-selector)
You can enable the recommended rules by setting the following configuration.
[[plugins]]
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
- Yarn
- pnpm
npm init kosko@latest example
yarn create kosko@latest example
pnpm create kosko@latest example
@kosko/generate
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.
@kosko/aggregate-error
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.
@kosko/require
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.