armada_client/lib.rs
1//! Rust client for the [Armada](https://armadaproject.io) batch-job scheduler.
2//!
3//! This crate provides an async gRPC client for submitting and monitoring batch
4//! jobs on an Armada cluster. It is built on top of [tonic] and exposes a
5//! small, ergonomic API that can be shared across async tasks without locking.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! use armada_client::k8s::io::api::core::v1::{Container, PodSpec};
11//! use armada_client::{
12//! ArmadaClient, JobRequestItemBuilder, JobSubmitRequest, StaticTokenProvider,
13//! };
14//!
15//! #[tokio::main]
16//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
17//! // 1. Connect (plaintext). Use `connect_tls` for production clusters.
18//! let client = ArmadaClient::connect(
19//! "http://localhost:50051",
20//! StaticTokenProvider::new("my-token"),
21//! )
22//! .await?;
23//!
24//! // 2. Build a job item — pod spec required before `.build()` compiles.
25//! let pod_spec = PodSpec {
26//! containers: vec![Container {
27//! name: Some("main".into()),
28//! image: Some("busybox:latest".into()),
29//! command: vec!["echo".into()],
30//! args: vec!["hello".into()],
31//! ..Default::default()
32//! }],
33//! ..Default::default()
34//! };
35//!
36//! let item = JobRequestItemBuilder::new()
37//! .namespace("default")
38//! .priority(1.0)
39//! .pod_spec(pod_spec)
40//! .build();
41//!
42//! // 3. Submit.
43//! let response = client
44//! .submit(JobSubmitRequest {
45//! queue: "my-queue".into(),
46//! job_set_id: "my-job-set".into(),
47//! job_request_items: vec![item],
48//! })
49//! .await?;
50//!
51//! for r in &response.job_response_items {
52//! println!("job_id={}", r.job_id);
53//! }
54//! Ok(())
55//! }
56//! ```
57//!
58//! # Features
59//!
60//! | Feature | How to use |
61//! |---|---|
62//! | Plaintext connection | [`ArmadaClient::connect`] |
63//! | TLS connection (system roots) | [`ArmadaClient::connect_tls`] |
64//! | TLS with custom CA / mTLS | [`ArmadaClient::connect_tls_with_config`] |
65//! | Per-call timeout | [`ArmadaClient::with_timeout`] |
66//! | Job submission | [`ArmadaClient::submit`] |
67//! | Cancel jobs by ID | [`ArmadaClient::cancel_jobs`] |
68//! | Cancel a job set | [`ArmadaClient::cancel_job_set`] |
69//! | Event streaming | [`ArmadaClient::watch`] |
70//! | Static bearer token | [`StaticTokenProvider`] |
71//! | Custom auth (OIDC, OAuth2…) | Implement [`TokenProvider`] |
72//! | Compile-time safe job builder | [`JobRequestItemBuilder`] |
73//!
74//! # Kubernetes proto types
75//!
76//! Armada job specs embed Kubernetes `PodSpec` and related types. These are
77//! generated from the upstream k8s protobufs and re-exported under the
78//! [`k8s`] module, mirroring the proto package hierarchy:
79//!
80//! ```ignore
81//! use armada_client::k8s::io::api::core::v1::{Container, PodSpec, ResourceRequirements};
82//! use armada_client::k8s::io::apimachinery::pkg::api::resource::Quantity;
83//! ```
84//!
85//! # Cloning and concurrent use
86//!
87//! [`ArmadaClient`] is `Clone`. All clones share the same underlying
88//! connection pool — cloning is cheap and the correct way to use the client
89//! across multiple tasks:
90//!
91//! ```no_run
92//! # use armada_client::{ArmadaClient, StaticTokenProvider};
93//! # async fn example() -> Result<(), armada_client::Error> {
94//! let client = ArmadaClient::connect("http://localhost:50051", StaticTokenProvider::new("tok"))
95//! .await?;
96//!
97//! let c1 = client.clone();
98//! let c2 = client.clone();
99//! tokio::join!(
100//! async move { /* use c1 */ },
101//! async move { /* use c2 */ },
102//! );
103//! # Ok(())
104//! # }
105//! ```
106
107pub mod api {
108 #![allow(
109 clippy::tabs_in_doc_comments,
110 clippy::doc_lazy_continuation,
111 clippy::doc_overindented_list_items,
112 clippy::large_enum_variant
113 )]
114 tonic::include_proto!("api");
115}
116
117// google.api types (HttpRule etc.) generated as a side-effect of compiling the
118// Armada API protos. Not part of the public API — used internally by api.rs.
119pub(crate) mod google {
120 pub mod api {
121 #![allow(
122 dead_code,
123 clippy::tabs_in_doc_comments,
124 clippy::doc_lazy_continuation,
125 clippy::doc_overindented_list_items,
126 clippy::large_enum_variant
127 )]
128 tonic::include_proto!("google.api");
129 }
130}
131
132// k8s types referenced by the api package — must mirror the proto package hierarchy
133// so that generated api.rs cross-package refs (e.g., super::k8s::io::api::core::v1::PodSpec) resolve.
134pub mod k8s {
135 #![allow(
136 clippy::tabs_in_doc_comments,
137 clippy::doc_lazy_continuation,
138 clippy::doc_overindented_list_items,
139 clippy::large_enum_variant
140 )]
141 pub mod io {
142 pub mod api {
143 pub mod core {
144 pub mod v1 {
145 tonic::include_proto!("k8s.io.api.core.v1");
146 }
147 }
148 pub mod networking {
149 pub mod v1 {
150 tonic::include_proto!("k8s.io.api.networking.v1");
151 }
152 }
153 }
154 pub mod apimachinery {
155 pub mod pkg {
156 pub mod api {
157 pub mod resource {
158 tonic::include_proto!("k8s.io.apimachinery.pkg.api.resource");
159 }
160 }
161 pub mod apis {
162 pub mod meta {
163 pub mod v1 {
164 tonic::include_proto!("k8s.io.apimachinery.pkg.apis.meta.v1");
165 }
166 }
167 }
168 pub mod runtime {
169 tonic::include_proto!("k8s.io.apimachinery.pkg.runtime");
170 }
171 pub mod util {
172 pub mod intstr {
173 tonic::include_proto!("k8s.io.apimachinery.pkg.util.intstr");
174 }
175 }
176 }
177 }
178 }
179}
180
181pub mod auth;
182pub mod builder;
183pub mod client;
184pub mod error;
185
186// Convenience re-exports for the public API surface
187pub use api::{
188 CancellationResult, EventMessage, EventStreamMessage, JobCancelRequest, JobSetCancelRequest,
189 JobSetFilter, JobState, JobSubmitRequest, JobSubmitRequestItem, JobSubmitResponse,
190};
191pub use auth::{BasicAuthProvider, StaticTokenProvider, TokenProvider};
192pub use builder::JobRequestItemBuilder;
193pub use client::ArmadaClient;
194pub use error::Error;
195pub use futures::stream::BoxStream;
196pub use prost;
197pub use tonic;