Document tokio dependency

[AndreKR]

Current and expected behavior

Currently the README says:

Installation
Select a version of kube along with the generated k8s-openapi types corresponding for your cluster version:

[dependencies]
kube = { version = "0.69.0", features = ["runtime", "derive"] }
k8s-openapi = { version = "0.14.0", features = ["v1_22"] }

But these don't seem to be enough. To be able to run code from the examples I also had to add

tokio = { version = "1.14.0", features = ["macros"] }

It seems to work but my choice of runtime, version and features was pretty much arbitrary.

Possible solution

No response

Additional context

No response

Environment

Documentation bug

Configuration and features

No response

Affected crates

No response

Would you like to work on fixing this bug?

maybe

[kazk]

To be able to run code from the examples I also had to add

What was the error? Note that examples depends on more crates and features.

https://github.com/kube-rs/kube-rs/blob/47fcf10ca68f07e52aa0dac400b4e55b368760ee/examples/Cargo.toml#L41

So, if you had copied a code out from there, you need to add any dependencies yourself.

macros feature in your example:

tokio = { version = "1.14.0", features = ["macros"] }

is necessary for #[tokio::main].

This is not necessary to use kube itself.

[nightkr]

I think there is some merit to calling this out explicitly, since tokio is currently the only async runtime we support.

[kazk]

Good point. I probably misunderstood the original issue.

[AndreKR]

This is not necessary to use kube itself.

@kazk From the examples/pod_api.rs example I had copied this code:

let client = Client::try_default().await?;
let pods: Api<Pod> = Api::default_namespaced(client);
let pod = pods.get("test").await?;

Because of the .await I was assuming that calling it in an async manner is the only supported way, so I need #[tokio::main]. If there is a way to call it in a synchronous manner I would be absolutely fine with that as well.

[kazk]

Sorry, I'm probably just confusing you.
You do need tokio to use kube (kube depends on it). But the macros feature is not necessary to use kube. It's only necessary if you want to use #[tokio::main] to mark an async function to be executed by the runtime.

[AndreKR]

Sorry, I'm probably just confusing you.

A bit. :)

pods.get() is async, can I call it without using #[tokio::main]?

(I remember something about block_on() but I also remember that was discouraged because then I wouldn't have a "reactor" or something like that.)

[kazk]

You need to set up a runtime to call an async function in (using kube or not), and kube only supports Tokio, so you need to add #[tokio::main] or use tokio::runtime::Builder if you're executing them.
My point is that macros feature is not a requirement. For example, a library crate can depend on kube, or apps can use runtime::Builder instead.

---

I think we should call out Tokio dependency and improve our docs, but I don't think it's necessary to, or should, include it in the top Cargo.toml code block on the README.

For example, hyper doesn't mention tokio at first for minimal setup:

They add it on creating an example server guide before they show a code block with #[tokio::main]:

[nightkr]

You can use tokio::Runtime::block_on, but not futures::block_on (at least not without doing a bunch of extra setup to make sure that you still have a tokio runtime in scope).

#[tokio::main]
async fn main() {
  ...
}

is basically syntax sugar for:

fn main() {
  tokio::runtime::Runtime::new().unwrap().block_on(async {
    ..
  });
}

[clux]

If you want to see details on this you can look at tokio's runtime docs. But TL;DR: #[tokio::main] is the normal pattern for running futures at the top level. It is generally what you want when using async rust, and generally want to do it with tokio.

As a side-note, there's not been a lot of contest on the executor side recently, async-std basically stopped making releases for like a year, so not sure we need to elaborate on it a lot.

I am writing a couple of lines on this in kube-rs/website#13 as it makes sense to recommend a runtime for a controller. Not sure we need it in the main README. Here's what I am considering going with:

cutout from pr above

kube = { version = "0.69.1", features = ["runtime", "client", "derive"] }
k8s-openapi = { version = "0.14.0", features = ["v1_22"]}
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The `k8s-openapi` dependency is not always necessary, but we will be using [Pod] as our controlled [[object]], so we will need it here.

The `tokio` runtime dependency is necessary to use async rust features, and is the supported way to use futures created by kube.

!!! warning "Alternate async runtimes"

    We depend on `tokio` for its `time`, `signal` and `sync` features, and while it is in theory possible to swap out a runtime, you would be sacrificing the most actively supported and most advanced runtime available. Avoid going down this alternate path unless you have a good reason.

[AndreKR]

is basically syntax sugar for:

fn main() {
  tokio::runtime::Runtime::new().unwrap().block_on(async {
    ..
  });
}

This is gold because as it turns out in a #[tokio::main] you can't use other libraries that use tokio/block_on() themselves.

[clux]

Runtime documented in the application part of the controller guide now: https://kube.rs/controllers/application/#main-dependencies