talos_api_rs/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! # talos-api-rs
4//!
5//! A typed, async, idiomatic Rust client for the [Talos Linux](https://www.talos.dev/) gRPC API.
6//!
7//! ## Features
8//!
9//! - **40+ APIs** — Machine, etcd, system, files, diagnostics
10//! - **Async-first** — Built on `tokio` and `tonic`
11//! - **Strongly typed** — No stringly-typed API calls
12//! - **Production-ready** — Retries, circuit breakers, connection pooling
13//! - **Observable** — Prometheus metrics, OpenTelemetry tracing
14//! - **mTLS support** — ED25519 certificates (Talos default)
15//!
16//! ## Quick Start
17//!
18//! ```rust,ignore
19//! use talos_api_rs::{TalosClient, TalosClientConfig};
20//!
21//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
22//! // Connect with mTLS
23//! let config = TalosClientConfig::builder("https://10.0.0.1:50000")
24//!     .ca_cert("/path/to/ca.crt")
25//!     .client_cert("/path/to/client.crt")
26//!     .client_key("/path/to/client.key")
27//!     .build();
28//!
29//! let client = TalosClient::new(config).await?;
30//!
31//! // Get kubeconfig from cluster
32//! let kubeconfig = client.kubeconfig().await?;
33//! println!("Got kubeconfig for cluster");
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! ## Module Overview
39//!
40//! - [`client`] — Core client and connection management
41//! - [`config`] — Configuration file parsing (talosctl config)
42//! - [`resources`] — Typed API request/response wrappers
43//! - [`runtime`] — Resilience (retry, circuit breaker) and observability
44//! - [`error`] — Error types
45//! - [`api`] — Generated protobuf types (low-level)
46//! - [`testkit`] — Testing utilities
47//!
48//! ## Production Features
49//!
50//! ### Retry Policies
51//!
52//! ```rust
53//! use talos_api_rs::runtime::{RetryConfig, ExponentialBackoff};
54//! use std::time::Duration;
55//!
56//! let retry = RetryConfig::builder()
57//!     .max_retries(3)
58//!     .backoff(ExponentialBackoff::new(Duration::from_millis(100)))
59//!     .build();
60//! ```
61//!
62//! ### Circuit Breaker
63//!
64//! ```rust
65//! use talos_api_rs::runtime::{CircuitBreaker, CircuitBreakerConfig};
66//! use std::time::Duration;
67//!
68//! let cb = CircuitBreaker::new(
69//!     CircuitBreakerConfig::new()
70//!         .with_failure_threshold(5)
71//!         .with_reset_timeout(Duration::from_secs(30))
72//! );
73//! ```
74//!
75//! ### Prometheus Metrics
76//!
77//! ```rust
78//! use talos_api_rs::runtime::{MetricsCollector, MetricsConfig};
79//!
80//! let metrics = MetricsCollector::new(
81//!     MetricsConfig::builder()
82//!         .namespace("talos")
83//!         .build()
84//! );
85//!
86//! // Export Prometheus format
87//! let output = metrics.to_prometheus_text();
88//! ```
89//!
90//! ## Disclaimer
91//!
92//! This project is **NOT** affiliated with Sidero Labs or Talos Linux.
93//! Provided AS-IS, without warranty of any kind.
94
95#![cfg_attr(docsrs, feature(doc_cfg))]
96
97pub mod api;
98pub mod client;
99pub mod config;
100pub mod error;
101pub mod resources;
102pub mod runtime;
103pub mod testkit;
104
105pub use client::{
106    ConnectionPool, ConnectionPoolConfig, EndpointHealth, HealthStatus, LoadBalancer, NodeTarget,
107    TalosClient, TalosClientConfig, TalosClientConfigBuilder, NODE_METADATA_KEY,
108};
109pub use config::{
110    TalosConfig, TalosContext, ENV_TALOSCONFIG, ENV_TALOS_CONTEXT, ENV_TALOS_ENDPOINTS,
111    ENV_TALOS_NODES,
112};
113pub use error::TalosError;
114pub use resources::{
115    ApplyConfigurationRequest, ApplyConfigurationResponse, ApplyConfigurationResult, ApplyMode,
116    BootstrapRequest, BootstrapResponse, BootstrapResult, ConnectionRecord, ConnectionState,
117    ContainerDriver, CopyRequest, CopyResponse, CpuInfo, CpuInfoResponse, CpuInfoResult, DiskStat,
118    DiskStatsResponse, DiskStatsResult, DiskUsageInfo, DiskUsageRequest, DiskUsageResponse,
119    DmesgRequest, DmesgResponse, EtcdAlarmDisarmResponse, EtcdAlarmListResponse, EtcdAlarmType,
120    EtcdDefragmentResponse, EtcdForfeitLeadershipRequest, EtcdForfeitLeadershipResponse,
121    EtcdLeaveClusterRequest, EtcdLeaveClusterResponse, EtcdMember, EtcdMemberAlarm,
122    EtcdMemberListRequest, EtcdMemberListResponse, EtcdMemberStatus, EtcdRemoveMemberByIdRequest,
123    EtcdRemoveMemberByIdResponse, EtcdStatusResponse, FileInfo, FileType,
124    GenerateClientConfigurationRequest, GenerateClientConfigurationResponse,
125    GenerateClientConfigurationResult, KubeconfigResponse, L4ProtoFilter, ListRequest,
126    ListResponse, LoadAvgResponse, LoadAvgResult, LogsRequest, LogsResponse, MemoryResponse,
127    MemoryResult, MountStat, MountsResponse, MountsResult, NetDevStat, NetstatFilter,
128    NetstatRequest, NetstatResponse, NetstatResult, NetworkDeviceStatsResponse,
129    NetworkDeviceStatsResult, PacketCaptureRequest, PacketCaptureResponse, ProcessInfo,
130    ProcessesResponse, ProcessesResult, ReadRequest, ReadResponse, ResetPartitionSpec,
131    ResetRequest, ResetResponse, ResetResult, RollbackResponse, RollbackResult,
132    ServiceRestartRequest, ServiceRestartResponse, ServiceStartRequest, ServiceStartResponse,
133    ServiceStopRequest, ServiceStopResponse, UpgradeRebootMode, UpgradeRequest, UpgradeResponse,
134    UpgradeResult, WipeMode,
135};
136pub use runtime::{
137    BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitState, CustomRetryPolicy,
138    DefaultRetryPolicy, ExponentialBackoff, FixedBackoff, InterceptorMetrics, LinearBackoff,
139    LogLevel, LoggingConfig, LoggingInterceptor, NoBackoff, NoRetryPolicy, RequestLogger,
140    RequestSpan, RetryConfig, RetryConfigBuilder, RetryPolicy,
141};
talos_api_rs/lib.rs

talos_api_rs/
lib.rs
