Skip to content

v0.4.0
Compare
Choose a tag to compare
@Arnavion Arnavion released this 07 Mar 10:04
· 506 commits to master since this release
v0.4.0
269e646

  • A new Resource trait is implemented on all resource types to get their API version, group, kind and version properties. See docs for details.

    Since the API version and kind of resource types is statically associated with their Rust types, the api_version and kind fields have been removed from these types. The fields are serialized and deserialized automatically without needing to be set.

  • A new Metadata trait is implemented on all resource types that have metadata (ObjectMeta or ListMeta), and can be used to get access to this metadata.

  • Fixed string responses like ReadNamespacedPodLogResponse to return ResponseError::NeedMoreData when given an empty slice, instead of returning an empty string.

  • Fixed string responses like ReadNamespacedPodLogResponse to return as much data as possible before an invalid utf-8 sequence in the input slice. In the previous release, the parser would return Err even if there was valid utf-8 before the first invalid byte. It now only returns Err if the first byte of the slice is invalid.

  • A new ResponseBody::advance function can be used to remove bytes from the front of the ResponseBody's internal buffer. This is useful in cases like reading a pod's logs, where the parser indicates that some bytes in the beginning of the slice are invalid, and you want to skip over them and continue parsing.

There are many breaking changes in this release, as part of modifying the generated code to be easier and safer to use:

  • The crate no longer supports enabling multiple version features ('v1_8', 'v1_9', etc). One and only one version feature can be enabled.

    As before, it's recommended that only application crates enable features of this crate in their Cargo.toml, based on the version of Kubernetes they want to run against. Library crates should not enable specific features. If library crates need to emit different code based on the feature that gets enabled, they should continue to use the version detection macros (k8s_if_ge_1_8! { }, etc) around such code.

    The build script of this crate will panic and fail the build if it detects zero or more than one feature has been enabled.

  • In the previous release, every enabled version was represented by a top-level module, eg enabling the v1_8 feature granted access to the k8s_openapi::v1_8 module and the k8s_openapi::v1_8::api::core::v1::Pod type. Since only one feature can be enabled now, the contents of this corresponding module are re-exported from the crate root, and the module itself is hidden. Thus enabling the v1_8 feature allows access to v1.8's Pod type through the k8s_openapi::api::core::v1::Pod path. This means crates that support multiple versions no longer need to write code like:

    k8s_if_1_8! { use k8s_openapi::v1_8::api::core::v1 as api; }
k8s_if_1_9! { use k8s_openapi::v1_9::api::core::v1 as api; }
k8s_if_1_10! { use k8s_openapi::v1_10::api::core::v1 as api; }
...

    and can instead write:

    use k8s_openapi::api::core::v1 as api;

  • Support for v1.7 API servers has been dropped. Its API structure was very different from the later versions (upstream rearranged the OpenAPI spec in v1.8). Continuing to support it would've required crates to continue using k8s_if_1_7! { } and k8s_if_ge_1_7! { }. By dropping support for it, there is much less reason to use the version detection macros.

  • API operation functions now have shorter names in many cases. For example Pod::read_core_v1_namespaced_pod_log is now called just Pod::read_namespaced_pod_log. The thing that is stripped from the name is a combination of the API kind ("core") and the API version ("v1"). In general, this means supporting different versions of API, like supporting Deployment::list_apps_v1beta2_namespaced_deployment on v1.8 and Deployment::list_apps_v1_namespaced_deployment on v1.9+ no longer requires version detection macros, since the function is now called Deployment::list_namespaced_deployment in both cases.

  • API operations now take a single parameter for all optional parameters. This parameter implements Default such that passing in Default::default() for this parameter is equivalent to not passing any optional parameters.

    For example, the api::core::v1::Pod::list_namespaced_pod operation has one required parameter for the namespace, and the optional parameters are fields of the api::core::v1::ListNamespacedPodOptional struct which is taken as the last parameter of the function. To set one or more of these optional parameters, use struct update syntax to set those parameters and Default the rest. See the crate docs for details.

    This reduces the number of None parameters that need to be passed to all operation functions. It also means that function that differed in the number of optional parameters between Kubernetes versions no longer need version detection macros if you don't want to set any of the optional parameters. For example, Job::create_namespaced_job takes one optional parameter in v1.11 and three in v1.12. With this release, it can be called as Job::create_namespaced_job("name", &spec, Default::default()) regardless of the version.

  • ResponseBody is now generic on the response type at the type level. Previously only its append_slice_and_parse function was generic on the response type.

  • ResponseBody::append_slice_and_parse has been removed. This function gave the wrong impression that appending a slice would allow zero or one responses to be parsed from its buffer. In fact, more than one response can be parsed, say when parsing a sequence of WatchEvents and the appended slice contains more than one WatchEvent. Instead, there are now separate ResponseBody::append_slice and ResponseBody::parse functions. You should call ResponseBody::parse in a loop as long as it returns Ok(parsed_response).

  • API operation functions now return two values in a tuple. The first value is the same http::Request<Vec<u8>> that they used to return in the previous release - this is the HTTP request with the path, query string and request body filled out according to the API operation. The second value is a function with the signature fn(http::StatusCode) -> ResponseBody<ResponseType>, where ResponseType is the type that should be used to parse the response. For example, Pod::list_namespaced_pod returns (http::Request<Vec<u8>>, fn(http::StatusCode) -> ResponseBody<ListNamespacedPodResponse>).

    In previous releases, you would've needed to read the docs to know that ListNamespacedPodResponse is the type you should use to parse the response. With this change, you can use the constructor to let the type system enforce it.

  • API operations that allowed you to list or watch in the same operation are now more strongly typed. For example, in the previous release, Pod::list_core_v1_namespaced_pod's docs indicated that you should use ListCoreV1NamespacedPodResponse to parse its response. However, this function has an optional watch parameter which can be used to get a stream of WatchEvent responses instead and thus you would need to parse the response with WatchCoreV1NamespacedPodResponse instead. This WatchCoreV1NamespacedPodResponse type was the response type of the otherwise unrelated Pod::watch_core_v1_namespaced_pod operation.

    Furthermore, Kubernetes has deprecated many of these watch and watchlist operations, like Pod::watch_core_v1_namespaced_pod and Pod::watch_core_v1_namespaced_pod_list respectively, in favor of using the list operation with the watch parameter set.

    With this release, both of these issues are solved.

    The list function, like Pod::list_namespaced_pod, no longer has a watch parameter. This function always returns a list response.

    The watch function, like Pod::watch_namespaced_pod, is no longer generated from the (potentially deprecated) watch function in the OpenAPI spec. Instead, it has the same URL and parameters as the list operation. It too does not have a watch parameter, but it sets watch=true in the URL of the generated http::Request automatically. This function always returns a WatchEvent stream response.

    The watchlist function, if any, is no longer emitted. It is redundant with the watch function, since watching a single item for changes or multiple items for changes is determined by the specificity of the field_selector parameter.

Corresponding Kubernetes API server versions:

  • v1.8.15
  • v1.9.11
  • v1.10.13
  • v1.11.8
  • v1.12.6
  • v1.13.4
Assets 2
Loading