[−][src]Crate k8s_openapi
Bindings for the Kubernetes client API, generated from the OpenAPI spec.
Each supported version of Kubernetes is represented by a feature name (like v1_9
). Only one such feature can be enabled at a time.
These docs have been generated with the v1_13
feature enabled. To see docs for one of the other supported versions, please generate the docs locally with cargo doc --features 'v1_<>'
If you're writing a library crate that supports multiple versions of Kubernetes (eg >= v1.9), it's recommended that your crate does not
enable the corresponding feature directly (eg k8s-openapi = { features = ["v1_9"] }
). Instead, let the application crate that uses your library
enable the feature corresponding to the version of Kubernetes that it supports. This ensures that the entire crate graph can use a common set
of types from this crate.
For things that differ between versions, such as the fully-qualified paths of imports, use the k8s_*
macros to emit different code
depending on which feature eventually gets enabled. See the docs of the macros, and the k8s-openapi-tests
directory in the repository,
for more details.
Similarly, if your crate does not support some versions of Kubernetes (eg <= 1.10), you can put something like this at the top of your crate root:
#[macro_use] extern crate k8s_openapi; k8s_if_le_1_10! { compile_error!("This crate requires v1_11 or higher feature to be enabled in the k8s-openapi crate."); }
Examples
Resources
This example creates an instance of api::core::v1::PodSpec
with no other properties set, and pretty-prints it.
use k8s_openapi::api::core::v1 as api; fn main() { let pod_spec: api::PodSpec = Default::default(); println!("{:#?}", pod_spec); }
Client API
This example executes the api::core::v1::Pod::list_namespaced_pod
API operation to list all pods inside a namespace.
It demonstrates the common patterns implemented by all API operation functions in this crate:
-
The API function has required parameters and optional parameters. All optional parameters are taken as a single struct with optional fields.
Specifically for the
api::core::v1::Pod::list_namespaced_pod
operation, thenamespace
parameter is required and taken by the function itself, while other optional parameters likefield_selector
are fields of theapi::core::v1::ListNamespacedPodOptional
struct. An instance of this struct is taken as the last parameter ofPod::list_namespaced_pod
. This struct implsDefault
so that you can just pass inDefault::default()
if you don't want to specify values for any of the optional parameters. -
The function returns an
http::Request
value with the URL path, query string, and request body filled out according to the parameters given to the function. The function does not execute this request. You can execute thishttp::Request
using any HTTP client library you want to use. It does not matter whether you use a synchronous client likereqwest
, or an asynchronous client likehyper
, or a mock client that returns bytes read from a test file. -
For each API operation function, there is a corresponding response type. For
Pod::list_namespaced_pod
this isapi::core::v1::ListNamespacedPodResponse
. This is an enum with variants for each of the possible HTTP status codes that the operation can return, and contains the data that the API server would return corresponding to that status code. For example, the list-namespaced-pod operation returns a pod list with HTTP 200 OK, so one of the variants ofListNamespacedPodResponse
isOk(
api::core::v1::PodList
)
-
The response types impl the
Response
trait, which contains a singleResponse::try_from_parts
function. This function takes anhttp::StatusCode
and a&u8
byte buffer, and tries to parse the byte buffer as the response type. For example, if you executed the request and received an HTTP 200 OK response with some bytes, you could call<ListNamespacedPodResponse as Response>::try_from_parts(status_code, buf)
and expect to getOk(ListNamespacedPodResponse::Ok(pod_list))
from it.Once again, this design ensures that the crate is not tied to a specific HTTP client library or interface. It does not matter how you execute the HTTP request, nor whether your library is synchronous or asynchronous, since every HTTP client library gives you a way to get the HTTP response status code and the bytes of the response body.
-
The API operation function also returns another value next to the
http::Request
. This value is a function that takes anhttp::StatusCode
and returns aResponseBody
<ListNamespacedPodResponse>
. As mentioned above,Response::try_from_parts
requires you to maintain a byte buffer for the response body.ResponseBody
is a helper that maintains such a buffer internally. It provides anappend_slice()
function to append slices to this internal buffer, and aparse()
function to parse the buffer as the expected type (ListNamespacedPodResponse
in this case).It is not necessary to use the
ResponseBody
returned by the API operation function to parse the response. TheResponseBody::parse
function is only a wrapper around the underlyingResponse::try_from_parts
function, and handles growing and shrinking its inner buffer as necessary. It also helps ensure that the response body is parsed as the correct type for the operation,ListNamespacedPodResponse
in this case, and not some other type. However, you can instead use your own byte buffer instead of theResponseBody
value and callListNamespacedPodResponse::try_from_parts
yourself.
Also see the get_single_value
and get_multiple_values
functions in the k8s-openapi-tests/
directory in the repository for an example of how to use
a synchronous client with this style of API.
// Re-export of the http crate since it's used in the public API use k8s_openapi::http; use k8s_openapi::api::core::v1 as api; // Assume `execute` is some function that takes an `http::Request` and // executes it synchronously or asynchronously to get a response. This is // provided by your HTTP client library. // // Note that the `http::Request` values returned by API operation functions // only have a URL path, query string and request body filled out. That is, // they do *not* have a URL host. So the real `execute` implementation // would first mutate the URL of the request to an absolute URL with // the API server's authority, add authorization headers, etc before // actually executing it. fn execute(req: http::Request<Vec<u8>>) -> Response { unimplemented!(); } fn main() -> Result<(), Box<dyn std::error::Error>> { // Create a `http::Request` to list all the pods in the // "kube-system" namespace. let (request, response_body) = api::Pod::list_namespaced_pod("kube-system", Default::default())?; // Execute the request and get a response. // If this is an asynchronous operation, you would await // or otherwise yield to the event loop here. let response = execute(request); // Got a status code from executing the request. let status_code: http::StatusCode = response.status_code(); // Construct the `ResponseBody<ListNamespacedPodResponse>` using the // constructor returned by the API function. let mut response_body = response_body(status_code); // Buffer used for each read from the HTTP response. let mut buf = Box::new([0u8; 4096]); let pod_list = loop { // Read some bytes from the HTTP response into the buffer. // If this is an asynchronous operation, you would await or // yield to the event loop here. let read = response.read_into(&mut *buf)?; // `buf` now contains some data read from the response. Append it // to the `ResponseBody` and try to parse it into // the response type. response_body.append_slice(&buf[..read]); let response = response_body.parse(); match response { // Successful response (HTTP 200 and parsed successfully) Ok(api::ListNamespacedPodResponse::Ok(pod_list)) => break pod_list, // Some unexpected response // (not HTTP 200, but still parsed successfully) Ok(other) => return Err(format!( "expected Ok but got {} {:?}", status_code, other).into()), // Need more response data. // Read more bytes from the response into the `ResponseBody` Err(k8s_openapi::ResponseError::NeedMoreData) => continue, // Some other error, like the response body being // malformed JSON or invalid UTF-8. Err(err) => return Err(format!( "error: {} {:?}", status_code, err).into()), } }; for pod in pod_list.items { println!("{:#?}", pod); } Ok(()) }
Re-exports
pub use chrono; |
pub use http; |
pub use serde_json; |
Modules
api | |
apiextensions_apiserver | |
apimachinery | |
kube_aggregator |
Macros
k8s_match | A macro that emits a |
k8s_if_1_8 | This macro evaluates to its contents if the |
k8s_if_1_9 | This macro evaluates to its contents if the |
k8s_if_1_10 | This macro evaluates to its contents if the |
k8s_if_1_11 | This macro evaluates to its contents if the |
k8s_if_1_12 | This macro evaluates to its contents if the |
k8s_if_1_13 | This macro evaluates to its contents if the |
k8s_if_ge_1_8 | This macro evaluates to its contents if the |
k8s_if_ge_1_9 | This macro evaluates to its contents if the |
k8s_if_ge_1_10 | This macro evaluates to its contents if the |
k8s_if_ge_1_11 | This macro evaluates to its contents if the |
k8s_if_ge_1_12 | This macro evaluates to its contents if the |
k8s_if_ge_1_13 | This macro evaluates to its contents if the |
k8s_if_le_1_8 | This macro evaluates to its contents if the |
k8s_if_le_1_9 | This macro evaluates to its contents if the |
k8s_if_le_1_10 | This macro evaluates to its contents if the |
k8s_if_le_1_11 | This macro evaluates to its contents if the |
k8s_if_le_1_12 | This macro evaluates to its contents if the |
k8s_if_le_1_13 | This macro evaluates to its contents if the |
Structs
ByteString | A wrapper around a list of bytes. |
ResponseBody | This struct provides an easy way to parse a byte buffer into a Kubernetes API function's response. |
Enums
GetAPIVersionsResponse | Use |
GetAdmissionregistrationAPIGroupResponse | Use |
GetAdmissionregistrationV1alpha1APIResourcesResponse | Use |
GetAdmissionregistrationV1beta1APIResourcesResponse | Use |
GetApiextensionsAPIGroupResponse | Use |
GetApiextensionsV1beta1APIResourcesResponse | Use |
GetApiregistrationAPIGroupResponse | Use |
GetApiregistrationV1APIResourcesResponse | Use |
GetApiregistrationV1beta1APIResourcesResponse | Use |
GetAppsAPIGroupResponse | Use |
GetAppsV1APIResourcesResponse | Use |
GetAppsV1beta1APIResourcesResponse | Use |
GetAppsV1beta2APIResourcesResponse | Use |
GetAuditregistrationAPIGroupResponse | Use |
GetAuditregistrationV1alpha1APIResourcesResponse | Use |
GetAuthenticationAPIGroupResponse | Use |
GetAuthenticationV1APIResourcesResponse | Use |
GetAuthenticationV1beta1APIResourcesResponse | Use |
GetAuthorizationAPIGroupResponse | Use |
GetAuthorizationV1APIResourcesResponse | Use |
GetAuthorizationV1beta1APIResourcesResponse | Use |
GetAutoscalingAPIGroupResponse | Use |
GetAutoscalingV1APIResourcesResponse | Use |
GetAutoscalingV2beta1APIResourcesResponse | Use |
GetAutoscalingV2beta2APIResourcesResponse | Use |
GetBatchAPIGroupResponse | Use |
GetBatchV1APIResourcesResponse | Use |
GetBatchV1beta1APIResourcesResponse | Use |
GetBatchV2alpha1APIResourcesResponse | Use |
GetCertificatesAPIGroupResponse | Use |
GetCertificatesV1beta1APIResourcesResponse | Use |
GetCodeVersionResponse | Use |
GetCoordinationAPIGroupResponse | Use |
GetCoordinationV1beta1APIResourcesResponse | Use |
GetCoreAPIVersionsResponse | Use |
GetCoreV1APIResourcesResponse | Use |
GetEventsAPIGroupResponse | Use |
GetEventsV1beta1APIResourcesResponse | Use |
GetExtensionsAPIGroupResponse | Use |
GetExtensionsV1beta1APIResourcesResponse | Use |
GetNetworkingAPIGroupResponse | Use |
GetNetworkingV1APIResourcesResponse | Use |
GetPolicyAPIGroupResponse | Use |
GetPolicyV1beta1APIResourcesResponse | Use |
GetRbacAuthorizationAPIGroupResponse | Use |
GetRbacAuthorizationV1APIResourcesResponse | Use |
GetRbacAuthorizationV1alpha1APIResourcesResponse | Use |
GetRbacAuthorizationV1beta1APIResourcesResponse | Use |
GetSchedulingAPIGroupResponse | Use |
GetSchedulingV1alpha1APIResourcesResponse | Use |
GetSchedulingV1beta1APIResourcesResponse | Use |
GetSettingsAPIGroupResponse | Use |
GetSettingsV1alpha1APIResourcesResponse | Use |
GetStorageAPIGroupResponse | Use |
GetStorageV1APIResourcesResponse | Use |
GetStorageV1alpha1APIResourcesResponse | Use |
GetStorageV1beta1APIResourcesResponse | Use |
LogFileHandlerResponse | Use |
LogFileListHandlerResponse | Use |
RequestError | The type of errors returned by the Kubernetes API functions that prepare the HTTP request. |
ResponseError | The type of errors from parsing an HTTP response as one of the Kubernetes API functions' response types. |
Traits
Metadata | A trait applied to all Kubernetes resources that have metadata. |
Resource | A trait applied to all Kubernetes resources. |
Response | A trait implemented by all response types corresponding to Kubernetes API functions. |