Skip to main content

Kosko 3.0 Released

· 4 min read

Kosko 3.0 has been released a few weeks ago. There are many improvements and some breaking changes in this version.

Refined Error Report​

In the previous version, when you run kosko generate or kosko validate command, only the first error is reported. Error messages are cramped and there is a lot of useless information.

error - data/spec/replicas must be integer, data/spec must be null, data/spec must match exactly one schema in oneOf (path: "/home/tommy/Projects/kosko-old/examples/getting-started/components/nginx.js", index: [0], kind: "apps/v1/Deployment", name: "nginx")
ValidationError: data/spec/replicas must be integer, data/spec must be null, data/spec must match exactly one schema in oneOf
- path: "/home/tommy/Projects/kosko-old/examples/getting-started/components/nginx.js"
- index: [0]
- kind: "apps/v1/Deployment"
- name: "nginx"
    at Object.validate (.../node_modules/.pnpm/@kubernetes-models+validate@2.0.1/node_modules/@kubernetes-models/validate/dist/validate.js:9:21)
    at IoK8sApiAppsV1Deployment.validate (.../node_modules/.pnpm/@kubernetes-models+base@2.0.1/node_modules/@kubernetes-models/base/dist/model.js:44:20)
    at resolve (.../packages/generate/dist/resolve.js:63:29)
    at resolve (.../packages/generate/dist/resolve.js:50:34)
    at generate (.../packages/generate/dist/generate.js:39:56)
    at async generateHandler (.../packages/cli/dist/commands/generate/index.js:69:20)
    at async Object.handler (.../packages/cli/dist/commands/generate/index.js:108:24)

In Kosko 3.0 and kubernetes-models 4.0, you can get all errors in a single run. This means you don't need to modify your code and rerun kosko generate command anymore.

Furthermore, error messages become cleaner and more human-readable now. They are grouped by component paths, and error stacks are only displayed for non-validation errors.

components/mysql.js - 1 error

  ✖ ResolveError: Validation error
    Index: [0]
    Kind: apps/v1/Deployment
    Name: mysql

      /spec/template/spec/containers/0/env/0/value must be string

components/nginx.js - 1 error

  ✖ ResolveError: Validation error
    Index: [0]
    Kind: apps/v1/Deployment
    Name: nginx

      /spec/replicas must be integer
      /spec/template/spec/containers/0/ports/0/containerPort must be integer

error - Generate failed (Total 2 errors)

If you want to stop immediately whenever an error occurred, run kosko generate with --bail option.

kosko generate --bail

Or enable bail option in kosko.toml.

kosko.toml
bail: true

Improved Nullable Type Error​

Besides Kosko, kubernetes-models was also updated to provide better error information for nullable types.

Let's say we have a nullable type as below.

interface IPod {
  spec?: IPodSpec;
}

When a value in spec is invalid, it throws a validation error like this.

data/spec must have required property 'containers',
data/spec must be null,
data/spec must match exactly one schema in oneOf

Only the first line in this error message is helpful. Other lines are very confusing and might make developers think they should set spec as null. Such error messages are removed in this version.

data/spec must have required property 'containers'

ESM Loader Support​

ESM loaders are finally supported in Kosko 3.0. You can use ESM loaders by adding loaders option to kosko.toml.

kosko.toml
loaders = ["ts-node/esm"]

Or running kosko generate with --loader option.

kosko generate --loader ts-node/esm

See ECMAScript modules for more information about how to use TypeScript ESM loader.

Faster Kustomize Build​

In @kosko/kustomize 0.2, when you call loadKustomize function without kustomize CLI installed on your computer. loadKustomize will always try to call kustomize first then kubectl kustomize, which is slow if your components contain a lot of loadKustomize calls.

In @kosko/kustomize 1.0, successful kustomize CLI invocations are cached, so loadKustomize doesn't have to retry kustomize CLI every time.

Iterable Support​

Kosko 3.0 supports the iterable protocol. You can use Set, Map, or generator functions in components now.

// Set
export default new Set([new Deployment(), new Service()]);

// Generator function
function* gen() {
  yield new Deployment();
  yield new Service();
}

See Iterable and Async Iterable for more info.

Breaking Changes​

  • Drop support for Node.js 12. The minimum supported Node.js version is 14.18.0 now.

  • @kosko/generate - All errors thrown in generate and resolve functions are wrapped in GenerateError or ResolveError for better access to context.

  • @kosko/generate - ValidationError is renamed as ResolveError.

  • @kosko/generate - Multiple errors are wrapped in AggregateError.

  • @kosko/generate - ResolveError.message no longer contains context information. You can access context from stack or direct access properties in the error value.

  • @kosko/generate - fast-glob is replaced with a homemade glob function based on micromatch. The behavior will be slightly different. Please submit an issue if you encounter any unexpected problems.

  • @kosko/yaml - Value type in Manifest has been changed from any to unknown. You might need to modify transform function to fix type errors. For example:

    // Before
    manifest.metadata.namespace = "foo";

    // After (Preferred)
    import { Pod } from "kubernetes-models/v1/Pod";

    if (Pod.is(manifest)) {
      manifest.metadata.namespace = "foo";
    }

    // After (Another way)
    import { IObjectMeta } from "@kubernetes-models/apimachinery/apis/meta/v1/ObjectMeta";
    (manifest.metadata as IObjectMeta).namespace = "foo";

  • readonly attribute is removed from the return types of many packages.

Changelog​