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 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.