Skip to content

fix: support YAML 1.1 parsing in Kubernetes manifests by replacing js-yaml with yaml #2548

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+63 −26
Open

fix: support YAML 1.1 parsing in Kubernetes manifests by replacing js-yaml with yaml #2548

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
80cbb7a
chore: replace js-yaml with yaml for YAML 1.1 compliance
Tanmayshi Jul 8, 2025
edd426d
chore: address reviewer feedback
Tanmayshi Jul 8, 2025
06d5731
chore: address reviewer feedback 2
Tanmayshi Jul 8, 2025
dddce79
chore: address reviewer feedback 3
Tanmayshi Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 2 additions & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,22 +55,21 @@
"author": "Kubernetes Authors",
"license": "Apache-2.0",
"dependencies": {
"@types/js-yaml": "^4.0.1",
"@types/node": "^24.0.0",
"@types/node-fetch": "^2.6.9",
"@types/stream-buffers": "^3.0.3",
"form-data": "^4.0.0",
"hpagent": "^1.2.0",
"isomorphic-ws": "^5.0.0",
"js-yaml": "^4.1.0",
"jsonpath-plus": "^10.3.0",
"node-fetch": "^2.6.9",
"openid-client": "^6.1.3",
"rfc4648": "^1.3.0",
"socks-proxy-agent": "^8.0.4",
"stream-buffers": "^3.0.2",
"tar-fs": "^3.0.9",
"ws": "^8.18.2"
"ws": "^8.18.2",
"yaml": "^2.8.0"
},
"devDependencies": {
"@eslint/js": "^9.18.0",
Expand Down
37 changes: 18 additions & 19 deletions src/yaml.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,48 +1,47 @@
import yaml from 'js-yaml';
import yaml from 'yaml';
import { getSerializationType } from './util.js';
import { KubernetesObject } from './types.js';
import { ObjectSerializer } from './serializer.js';

/**
* Load a Kubernetes object from YAML.
* Load a single Kubernetes object from YAML.
* @param data - The YAML string to load.
* @param opts - Optional YAML load options.
* @param opts - Optional YAML parse options.
* @returns The deserialized Kubernetes object.
*/
export function loadYaml<T>(data: string, opts?: yaml.LoadOptions): T {
const yml = yaml.load(data, opts) as any as KubernetesObject;
export function loadYaml<T>(data: string, opts?: yaml.ParseOptions): T {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yaml.parse accepts options of type ParseOptions & DocumentOptions & SchemaOptions & ToJSOptions. Let's the user have access to all the options, not only ParseOptions ones (especially the version one, which is in the DocumentOptions)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Updated the type to ParseOptions & DocumentOptions so version: '1.1' and similar options work correctly now. Let me know if more should be added.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cannot be sure some users won't have an interest on using options from the other ones, I would set all of them: ParseOptions & DocumentOptions & SchemaOptions & ToJSOptions

const yml = yaml.parse(data, { version: '1.1', ...opts }) as any as KubernetesObject;
if (!yml) {
throw new Error('Failed to load YAML');
throw new Error('Failed to load yaml');
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please undo this change.

}
const type = getSerializationType(yml.apiVersion, yml.kind);

return ObjectSerializer.deserialize(yml, type) as T;
}

/**
* Load all Kubernetes objects from YAML.
* Load all Kubernetes objects from a multi-document YAML string.
* @param data - The YAML string to load.
* @param opts - Optional YAML load options.
* @param opts - Optional YAML parse options.
* @returns An array of deserialized Kubernetes objects.
*/
export function loadAllYaml(data: string, opts?: yaml.LoadOptions): any[] {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think users may still want to pass options to the parser

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we may need to define our own types for the options passed to loadYaml(), loadAllYaml(), and dumpYaml(). These are part of the public API, and changing the underlying YAML library like this changes the actual options that are supported.

const ymls = yaml.loadAll(data, undefined, opts);
return ymls.map((yml) => {
const obj = yml as KubernetesObject;
export function loadAllYaml(data: string, opts?: yaml.ParseOptions): KubernetesObject[] {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

type of opts would be ParseOptions & DocumentOptions & SchemaOptions here

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i do it

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we want to change the type of the return value, as it will be a breaking change for user (and is what makes the tests fail)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not. We should try to keep backwards compatibility as much as possible.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We initially used KubernetesObject[] for better type safety and IntelliSense — especially when accessing standard fields like apiVersion, kind, or metadata.

But you're right — changing it from any[] would be a breaking change for users. So we’ve reverted back to any[] to preserve backward compatibility.

const ymls = yaml.parseAllDocuments(data, { version: '1.1', ...opts });
return ymls.map((doc) => {
const obj = doc.toJSON() as KubernetesObject;
const type = getSerializationType(obj.apiVersion, obj.kind);
return ObjectSerializer.deserialize(yml, type);
return ObjectSerializer.deserialize(obj, type);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you don't rename things and make unrelated changes, the diff stays smaller and easier to review. It also makes git blame easier to use too.

});
}

/**
* Dump a Kubernetes object to YAML.
* Dump a Kubernetes object to a YAML string.
* @param object - The Kubernetes object to dump.
* @param opts - Optional YAML dump options.
* @returns The YAML string representation of the serialized Kubernetes object.
* @param opts - Optional YAML stringify options.
* @returns The YAML string representation of the serialized object.
*/
export function dumpYaml(object: any, opts?: yaml.DumpOptions): string {
export function dumpYaml(object: any, opts?: yaml.ToStringOptions): string {
const kubeObject = object as KubernetesObject;
const type = getSerializationType(kubeObject.apiVersion, kubeObject.kind);
const serialized = ObjectSerializer.serialize(kubeObject, type);
return yaml.dump(serialized, opts);
return yaml.stringify(serialized, opts);
}
66 changes: 53 additions & 13 deletions src/yaml_test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { describe, it } from 'node:test';
import { deepEqual, deepStrictEqual, strictEqual } from 'node:assert';
import { V1CustomResourceDefinition, V1Namespace } from './api.js';
import { V1CustomResourceDefinition, V1Namespace, V1Pod } from './api.js';
import { dumpYaml, loadAllYaml, loadYaml } from './yaml.js';

describe('yaml', () => {
Expand Down Expand Up @@ -84,22 +84,27 @@ spec:
const objects = loadAllYaml(yaml);

strictEqual(objects.length, 3);
strictEqual(objects[0].kind, 'Namespace');
strictEqual(objects[1].kind, 'Pod');
strictEqual(objects[0].metadata.name, 'some-namespace');
strictEqual(objects[1].metadata.name, 'some-pod');
strictEqual(objects[1].metadata.namespace, 'some-ns');
strictEqual(objects[2].apiVersion, 'apiextensions.k8s.io/v1');
strictEqual(objects[2].kind, 'CustomResourceDefinition');
strictEqual(objects[2].metadata!.name, 'my-crd.example.com');
// Assert specific types for each object
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fact that an existing test broke implies to me that this may be a subtly breaking change.

Copy link
Author

@Tanmayshi Tanmayshi Jul 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tests themselves were not failing — the issue was purely related to TypeScript type-checking. TypeScript was warning that some properties might be undefined or missing. I've addressed those issues, and CI is now passing

If you'd prefer a more strictly type-safe solution, please let me knowd.

const ns = objects[0] as V1Namespace;
const pod = objects[1] as V1Pod;
const crd = objects[2] as V1CustomResourceDefinition;

strictEqual(ns.kind, 'Namespace');
strictEqual(pod.kind, 'Pod');
strictEqual(ns.metadata!.name, 'some-namespace');
strictEqual(pod.metadata!.name, 'some-pod');
strictEqual(pod.metadata!.namespace, 'some-ns');

strictEqual(crd.apiVersion, 'apiextensions.k8s.io/v1');
strictEqual(crd.kind, 'CustomResourceDefinition');
strictEqual(crd.metadata!.name, 'my-crd.example.com');
strictEqual(
objects[2].spec.versions[0]!.schema!.openAPIV3Schema!.properties!['foobar']
.x_kubernetes_int_or_string,
crd.spec.versions[0]!.schema!.openAPIV3Schema!.properties!['foobar'].x_kubernetes_int_or_string,
true,
);
strictEqual(
objects[2].spec.versions[0]!.schema!.openAPIV3Schema!.properties!['foobar'][
'x-kubernetes-int-or-string'
crd.spec.versions[0]!.schema!.openAPIV3Schema!.properties!['foobar'][
'x-kubernetes-int-or-string' // This access is still on the parsed object before type mapping, hence `undefined` is correct
],
undefined,
);
Expand Down Expand Up @@ -154,4 +159,39 @@ spec:
// not using strict equality as types are not matching
deepEqual(actual, expected);
});

it('should parse octal-like strings as numbers (YAML 1.1 style)', () => {
const yaml = `
defaultMode: 0644
fileMode: 0755
`;
const result = loadYaml<{
defaultMode: number;
fileMode: number;
}>(yaml);

// 0644 (octal) = 420 decimal, 0755 = 493
strictEqual(result.defaultMode, 420);
strictEqual(result.fileMode, 493);
});

it('should parse boolean-like strings as booleans (YAML 1.1 style)', () => {
const yaml = `
enableFeature: yes
debugMode: ON
maintenance: no
safeMode: off
`;
const result = loadYaml<{
enableFeature: boolean;
debugMode: boolean;
maintenance: boolean;
safeMode: boolean;
}>(yaml);

strictEqual(result.enableFeature, true);
strictEqual(result.debugMode, true);
strictEqual(result.maintenance, false);
strictEqual(result.safeMode, false);
});
});