[][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:

This example is not tested
#[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:

  1. 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, the namespace parameter is required and taken by the function itself, while other optional parameters like field_selector are fields of the api::core::v1::ListNamespacedPodOptional struct. An instance of this struct is taken as the last parameter of Pod::list_namespaced_pod. This struct impls Default so that you can just pass in Default::default() if you don't want to specify values for any of the optional parameters.

  2. 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 this http::Request using any HTTP client library you want to use. It does not matter whether you use a synchronous client like reqwest, or an asynchronous client like hyper, or a mock client that returns bytes read from a test file.

  3. For each API operation function, there is a corresponding response type. For Pod::list_namespaced_pod this is api::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 of ListNamespacedPodResponse is Ok(api::core::v1::PodList)

  4. The response types impl the Response trait, which contains a single Response::try_from_parts function. This function takes an http::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 get Ok(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.

  5. The API operation function also returns another value next to the http::Request. This value is a function that takes an http::StatusCode and returns a ResponseBody<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 an append_slice() function to append slices to this internal buffer, and a parse() 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. The ResponseBody::parse function is only a wrapper around the underlying Response::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 the ResponseBody value and call ListNamespacedPodResponse::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 match expr with the given test expression and arms. The match arms can be annotated with the other conditional compilation macros in this crate so that they're only emitted if the predicate is true.

k8s_if_1_8

This macro evaluates to its contents if the v1_8 feature is enabled, otherwise it evaluates to nothing.

k8s_if_1_9

This macro evaluates to its contents if the v1_9 feature is enabled, otherwise it evaluates to nothing.

k8s_if_1_10

This macro evaluates to its contents if the v1_10 feature is enabled, otherwise it evaluates to nothing.

k8s_if_1_11

This macro evaluates to its contents if the v1_11 feature is enabled, otherwise it evaluates to nothing.

k8s_if_1_12

This macro evaluates to its contents if the v1_12 feature is enabled, otherwise it evaluates to nothing.

k8s_if_1_13

This macro evaluates to its contents if the v1_13 feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_8

This macro evaluates to its contents if the v1_8 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_9

This macro evaluates to its contents if the v1_9 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_10

This macro evaluates to its contents if the v1_10 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_11

This macro evaluates to its contents if the v1_11 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_12

This macro evaluates to its contents if the v1_12 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_ge_1_13

This macro evaluates to its contents if the v1_13 or higher feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_8

This macro evaluates to its contents if the v1_8 or lower feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_9

This macro evaluates to its contents if the v1_9 or lower feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_10

This macro evaluates to its contents if the v1_10 or lower feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_11

This macro evaluates to its contents if the v1_11 or lower feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_12

This macro evaluates to its contents if the v1_12 or lower feature is enabled, otherwise it evaluates to nothing.

k8s_if_le_1_13

This macro evaluates to its contents if the v1_13 or lower feature is enabled, otherwise it evaluates to nothing.

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 <GetAPIVersionsResponse as Response>::try_from_parts to parse the HTTP response body of get_api_versions

GetAdmissionregistrationAPIGroupResponse

Use <GetAdmissionregistrationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_admissionregistration_api_group

GetAdmissionregistrationV1alpha1APIResourcesResponse

Use <GetAdmissionregistrationV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_admissionregistration_v1alpha1_api_resources

GetAdmissionregistrationV1beta1APIResourcesResponse

Use <GetAdmissionregistrationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_admissionregistration_v1beta1_api_resources

GetApiextensionsAPIGroupResponse

Use <GetApiextensionsAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_apiextensions_api_group

GetApiextensionsV1beta1APIResourcesResponse

Use <GetApiextensionsV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apiextensions_v1beta1_api_resources

GetApiregistrationAPIGroupResponse

Use <GetApiregistrationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_apiregistration_api_group

GetApiregistrationV1APIResourcesResponse

Use <GetApiregistrationV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apiregistration_v1_api_resources

GetApiregistrationV1beta1APIResourcesResponse

Use <GetApiregistrationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apiregistration_v1beta1_api_resources

GetAppsAPIGroupResponse

Use <GetAppsAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_apps_api_group

GetAppsV1APIResourcesResponse

Use <GetAppsV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apps_v1_api_resources

GetAppsV1beta1APIResourcesResponse

Use <GetAppsV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apps_v1beta1_api_resources

GetAppsV1beta2APIResourcesResponse

Use <GetAppsV1beta2APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_apps_v1beta2_api_resources

GetAuditregistrationAPIGroupResponse

Use <GetAuditregistrationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_auditregistration_api_group

GetAuditregistrationV1alpha1APIResourcesResponse

Use <GetAuditregistrationV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_auditregistration_v1alpha1_api_resources

GetAuthenticationAPIGroupResponse

Use <GetAuthenticationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_authentication_api_group

GetAuthenticationV1APIResourcesResponse

Use <GetAuthenticationV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_authentication_v1_api_resources

GetAuthenticationV1beta1APIResourcesResponse

Use <GetAuthenticationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_authentication_v1beta1_api_resources

GetAuthorizationAPIGroupResponse

Use <GetAuthorizationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_authorization_api_group

GetAuthorizationV1APIResourcesResponse

Use <GetAuthorizationV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_authorization_v1_api_resources

GetAuthorizationV1beta1APIResourcesResponse

Use <GetAuthorizationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_authorization_v1beta1_api_resources

GetAutoscalingAPIGroupResponse

Use <GetAutoscalingAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_autoscaling_api_group

GetAutoscalingV1APIResourcesResponse

Use <GetAutoscalingV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_autoscaling_v1_api_resources

GetAutoscalingV2beta1APIResourcesResponse

Use <GetAutoscalingV2beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_autoscaling_v2beta1_api_resources

GetAutoscalingV2beta2APIResourcesResponse

Use <GetAutoscalingV2beta2APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_autoscaling_v2beta2_api_resources

GetBatchAPIGroupResponse

Use <GetBatchAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_batch_api_group

GetBatchV1APIResourcesResponse

Use <GetBatchV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_batch_v1_api_resources

GetBatchV1beta1APIResourcesResponse

Use <GetBatchV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_batch_v1beta1_api_resources

GetBatchV2alpha1APIResourcesResponse

Use <GetBatchV2alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_batch_v2alpha1_api_resources

GetCertificatesAPIGroupResponse

Use <GetCertificatesAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_certificates_api_group

GetCertificatesV1beta1APIResourcesResponse

Use <GetCertificatesV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_certificates_v1beta1_api_resources

GetCodeVersionResponse

Use <GetCodeVersionResponse as Response>::try_from_parts to parse the HTTP response body of get_code_version

GetCoordinationAPIGroupResponse

Use <GetCoordinationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_coordination_api_group

GetCoordinationV1beta1APIResourcesResponse

Use <GetCoordinationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_coordination_v1beta1_api_resources

GetCoreAPIVersionsResponse

Use <GetCoreAPIVersionsResponse as Response>::try_from_parts to parse the HTTP response body of get_core_api_versions

GetCoreV1APIResourcesResponse

Use <GetCoreV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_core_v1_api_resources

GetEventsAPIGroupResponse

Use <GetEventsAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_events_api_group

GetEventsV1beta1APIResourcesResponse

Use <GetEventsV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_events_v1beta1_api_resources

GetExtensionsAPIGroupResponse

Use <GetExtensionsAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_extensions_api_group

GetExtensionsV1beta1APIResourcesResponse

Use <GetExtensionsV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_extensions_v1beta1_api_resources

GetNetworkingAPIGroupResponse

Use <GetNetworkingAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_networking_api_group

GetNetworkingV1APIResourcesResponse

Use <GetNetworkingV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_networking_v1_api_resources

GetPolicyAPIGroupResponse

Use <GetPolicyAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_policy_api_group

GetPolicyV1beta1APIResourcesResponse

Use <GetPolicyV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_policy_v1beta1_api_resources

GetRbacAuthorizationAPIGroupResponse

Use <GetRbacAuthorizationAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_rbac_authorization_api_group

GetRbacAuthorizationV1APIResourcesResponse

Use <GetRbacAuthorizationV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_rbac_authorization_v1_api_resources

GetRbacAuthorizationV1alpha1APIResourcesResponse

Use <GetRbacAuthorizationV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_rbac_authorization_v1alpha1_api_resources

GetRbacAuthorizationV1beta1APIResourcesResponse

Use <GetRbacAuthorizationV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_rbac_authorization_v1beta1_api_resources

GetSchedulingAPIGroupResponse

Use <GetSchedulingAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_scheduling_api_group

GetSchedulingV1alpha1APIResourcesResponse

Use <GetSchedulingV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_scheduling_v1alpha1_api_resources

GetSchedulingV1beta1APIResourcesResponse

Use <GetSchedulingV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_scheduling_v1beta1_api_resources

GetSettingsAPIGroupResponse

Use <GetSettingsAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_settings_api_group

GetSettingsV1alpha1APIResourcesResponse

Use <GetSettingsV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_settings_v1alpha1_api_resources

GetStorageAPIGroupResponse

Use <GetStorageAPIGroupResponse as Response>::try_from_parts to parse the HTTP response body of get_storage_api_group

GetStorageV1APIResourcesResponse

Use <GetStorageV1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_storage_v1_api_resources

GetStorageV1alpha1APIResourcesResponse

Use <GetStorageV1alpha1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_storage_v1alpha1_api_resources

GetStorageV1beta1APIResourcesResponse

Use <GetStorageV1beta1APIResourcesResponse as Response>::try_from_parts to parse the HTTP response body of get_storage_v1beta1_api_resources

LogFileHandlerResponse

Use <LogFileHandlerResponse as Response>::try_from_parts to parse the HTTP response body of log_file_handler

LogFileListHandlerResponse

Use <LogFileListHandlerResponse as Response>::try_from_parts to parse the HTTP response body of log_file_list_handler

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.

Functions

api_version

Extracts the API version of the given resource value.

get_admissionregistration_api_group

get information of a group

get_admissionregistration_v1alpha1_api_resources

get available resources

get_admissionregistration_v1beta1_api_resources

get available resources

get_api_versions

get available API versions

get_apiextensions_api_group

get information of a group

get_apiextensions_v1beta1_api_resources

get available resources

get_apiregistration_api_group

get information of a group

get_apiregistration_v1_api_resources

get available resources

get_apiregistration_v1beta1_api_resources

get available resources

get_apps_api_group

get information of a group

get_apps_v1_api_resources

get available resources

get_apps_v1beta1_api_resources

get available resources

get_apps_v1beta2_api_resources

get available resources

get_auditregistration_api_group

get information of a group

get_auditregistration_v1alpha1_api_resources

get available resources

get_authentication_api_group

get information of a group

get_authentication_v1_api_resources

get available resources

get_authentication_v1beta1_api_resources

get available resources

get_authorization_api_group

get information of a group

get_authorization_v1_api_resources

get available resources

get_authorization_v1beta1_api_resources

get available resources

get_autoscaling_api_group

get information of a group

get_autoscaling_v1_api_resources

get available resources

get_autoscaling_v2beta1_api_resources

get available resources

get_autoscaling_v2beta2_api_resources

get available resources

get_batch_api_group

get information of a group

get_batch_v1_api_resources

get available resources

get_batch_v1beta1_api_resources

get available resources

get_batch_v2alpha1_api_resources

get available resources

get_certificates_api_group

get information of a group

get_certificates_v1beta1_api_resources

get available resources

get_code_version

get the code version

get_coordination_api_group

get information of a group

get_coordination_v1beta1_api_resources

get available resources

get_core_api_versions

get available API versions

get_core_v1_api_resources

get available resources

get_events_api_group

get information of a group

get_events_v1beta1_api_resources

get available resources

get_extensions_api_group

get information of a group

get_extensions_v1beta1_api_resources

get available resources

get_networking_api_group

get information of a group

get_networking_v1_api_resources

get available resources

get_policy_api_group

get information of a group

get_policy_v1beta1_api_resources

get available resources

get_rbac_authorization_api_group

get information of a group

get_rbac_authorization_v1_api_resources

get available resources

get_rbac_authorization_v1alpha1_api_resources

get available resources

get_rbac_authorization_v1beta1_api_resources

get available resources

get_scheduling_api_group

get information of a group

get_scheduling_v1alpha1_api_resources

get available resources

get_scheduling_v1beta1_api_resources

get available resources

get_settings_api_group

get information of a group

get_settings_v1alpha1_api_resources

get available resources

get_storage_api_group

get information of a group

get_storage_v1_api_resources

get available resources

get_storage_v1alpha1_api_resources

get available resources

get_storage_v1beta1_api_resources

get available resources

group

Extracts the group of the given resource value.

kind

Extracts the kind of the given resource value.

log_file_handler

Use the returned crate::ResponseBody<LogFileHandlerResponse> constructor, or LogFileHandlerResponse directly, to parse the HTTP response.

log_file_list_handler

Use the returned crate::ResponseBody<LogFileListHandlerResponse> constructor, or LogFileListHandlerResponse directly, to parse the HTTP response.

version

Extracts the version of the given resource value.