1# API serialization compatibility tests
2
3This directory tree contains serialized API objects in json, yaml, and protobuf formats.
4
5## Populating data for each release
6
7After every v1.x.0 release, snapshot compatibility data.
8
9For example, to capture compatibility data for `v1.20.0`:
10
11```sh
12export VERSION=v1.20.0
13git checkout ${VERSION}
14cp -fr staging/src/k8s.io/api/testdata/{HEAD,${VERSION}}
15git checkout -b ${VERSION}-api-testdata master
16git add .
17git commit -m "Add ${VERSION} API testdata"
18```
19
20## Current version
21
22The `HEAD` subdirectory contains serialized API objects generated from the current commit:
23
24```
25HEAD/
26 <group>.<version>.<kind>.[json|yaml|pb]
27```
28
29To run serialization tests just for the current version:
30
31```sh
32go test k8s.io/api -run //HEAD
33```
34
35All three formats of a given group/version/kind are expected to decode successfully to identical objects,
36and to round-trip back to serialized form with identical bytes.
37Adding new fields or API types *is* expected to modify these fixtures. To regenerate them, run:
38
39```sh
40UPDATE_COMPATIBILITY_FIXTURE_DATA=true go test k8s.io/api -run //HEAD
41```
42
43## Previous versions
44
45The vX.Y.Z subdirectories contain serialized API objects from previous releases:
46
47```
48vX.Y.Z/
49 <group>.<version>.<kind>.[json|yaml|pb]
50```
51
52All three formats of a given group/version/kind are expected to decode successfully to identical objects,
53and to round-trip back to serialized form with identical bytes.
54Adding new fields to existing API types is *not* expected to require modifications to these fixtures.
55This requires making optional scalar and struct fields pointers so that protobuf serialization omits them when not present.
56
57To run serialization tests just for a previous version, like `v1.14.0`:
58
59```sh
60go test k8s.io/api -run //v1.14.0
61```
62
63To run serialization tests for a particular group/version/kind, like `apps/v1` `Deployment`:
64```sh
65go test k8s.io/api -run /apps.v1.Deployment/
66```
67
68Failures to decode, to round-trip identical bytes, or to decode identical objects from json/yaml/protobuf,
69will output detailed errors about the differences encountered. Detailed errors about protobuf differences
70requires `protoc` to be available on your `$PATH`.
71
72In exceptional cases, new non-pointer fields were added to existing API types that serialized zero values,
73resulting in additional fields being output when round-tripping data from previous releases, and failing round-trip tests.
74
75To resolve this, a `<group>.<version>.<kind>_after_roundtrip.[json|yaml|pb]` file containing the
76expected data after roundtripping can be placed beside the serialized data file from a previous release.
77
78These `after_roundtrip` files are generated by running the failing round-trip tests with `UPDATE_COMPATIBILITY_FIXTURE_DATA=true` set.
79The detailed diff from the test failure should be included in the commit message, along with a reference
80to the change that caused the failure. Updates to these files is exceptional, and requires extremely close review
81to ensure we are not breaking backwards compatibility with serialized data from previous releases.
82
83To see the diff between the original JSON/YAML data and the `...after_roundtrip...` files:
84
85```sh
86cd staging/src/k8s.io/api/testdata/v1.14.0/
87diff -u admission.k8s.io.v1beta1.AdmissionReview.json admission.k8s.io.v1beta1.AdmissionReview.after_roundtrip.json
88diff -u admission.k8s.io.v1beta1.AdmissionReview.yaml admission.k8s.io.v1beta1.AdmissionReview.after_roundtrip.yaml
89```
90
91> ```diff
92> --- admission.k8s.io.v1beta1.AdmissionReview.json 2019-06-02 20:21:03.000000000 -0400
93> +++ admission.k8s.io.v1beta1.AdmissionReview.after_roundtrip.json 2019-06-02 20:21:03.000000000 -0400
94> @@ -31,7 +31,8 @@
95> },
96> "object": {"apiVersion":"example.com/v1","kind":"CustomType","spec":{"replicas":1},"status":{"available":1}},
97> "oldObject": {"apiVersion":"example.com/v1","kind":"CustomType","spec":{"replicas":1},"status":{"available":1}},
98> - "dryRun": true
99> + "dryRun": true,
100> + "options": null
101> },
102> "response": {
103> "uid": "爟¼ªov鈶",
104> ```
105
106> ```diff
107> --- admission.k8s.io.v1beta1.AdmissionReview.yaml 2019-06-02 20:21:03.000000000 -0400
108> +++ admission.k8s.io.v1beta1.AdmissionReview.after_roundtrip.yaml 2019-06-02 20:21:03.000000000 -0400
109> @@ -23,6 +23,7 @@
110> status:
111> available: 1
112> operation: 祈¡ıŵDz廔ȇ{sŊƏp饏姥呄鐊
113> + options: null
114> resource:
115> group: "5"
116> resource: "7"
117> ```
118
119To see the diff between the original proto data and the `...after_roundtrip...` file, you must have `protoc` available,
120and strip off the leading four-byte kubernetes protobuf header to get standard protobuf that can be decoded:
121
122```sh
123cd staging/src/k8s.io/api/testdata/v1.14.0/
124diff -u \
125 <(tail -c +5 admission.k8s.io.v1beta1.AdmissionReview.pb | protoc --decode_raw) \
126 <(tail -c +5 admission.k8s.io.v1beta1.AdmissionReview.after_roundtrip.pb | protoc --decode_raw)
127```
128
129> ```diff
130> --- /dev/fd/63 2019-06-03 11:56:12.000000000 -0400
131> +++ /dev/fd/62 2019-06-03 11:56:12.000000000 -0400
132> @@ -37,6 +37,8 @@
133> 1: "{\"apiVersion\":\"example.com/v1\",\"kind\":\"CustomType\",\"spec\":{\"replicas\":1},\"status\":{\"available\":1}}"
134> }
135> 11: 1
136> + 12: ""
137> + 15: ""
138> }
139> 2 {
140> 1: "\347\210\237\302\274\302\252ov\351\210\266"
141> ```
View as plain text