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, ContainerdNamespace, CopyRequest, CopyResponse, CpuInfo, CpuInfoResponse,
118    CpuInfoResult, DiskStat, DiskStatsResponse, DiskStatsResult, DiskUsageInfo, DiskUsageRequest,
119    DiskUsageResponse, DmesgRequest, DmesgResponse, EtcdAlarmDisarmResponse, EtcdAlarmListResponse,
120    EtcdAlarmType, EtcdDefragmentResponse, EtcdForfeitLeadershipRequest,
121    EtcdForfeitLeadershipResponse, EtcdLeaveClusterRequest, EtcdLeaveClusterResponse, EtcdMember,
122    EtcdMemberAlarm, EtcdMemberListRequest, EtcdMemberListResponse, EtcdMemberStatus,
123    EtcdRemoveMemberByIdRequest, EtcdRemoveMemberByIdResponse, EtcdStatusResponse, FileInfo,
124    FileType, GenerateClientConfigurationRequest, GenerateClientConfigurationResponse,
125    GenerateClientConfigurationResult, ImageInfo, ImageListRequest, ImagePullRequest,
126    ImagePullResponse, ImagePullResult, KubeconfigResponse, L4ProtoFilter, ListRequest,
127    ListResponse, LoadAvgResponse, LoadAvgResult, LogsRequest, LogsResponse, MemoryResponse,
128    MemoryResult, MountStat, MountsResponse, MountsResult, NetDevStat, NetstatFilter,
129    NetstatRequest, NetstatResponse, NetstatResult, NetworkDeviceStatsResponse,
130    NetworkDeviceStatsResult, PacketCaptureRequest, PacketCaptureResponse, ProcessInfo,
131    ProcessesResponse, ProcessesResult, ReadRequest, ReadResponse, ResetPartitionSpec,
132    ResetRequest, ResetResponse, ResetResult, RollbackResponse, RollbackResult,
133    ServiceRestartRequest, ServiceRestartResponse, ServiceStartRequest, ServiceStartResponse,
134    ServiceStopRequest, ServiceStopResponse, UpgradeRebootMode, UpgradeRequest, UpgradeResponse,
135    UpgradeResult, WipeMode,
136};
137pub use runtime::{
138    BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitState, CustomRetryPolicy,
139    DefaultRetryPolicy, ExponentialBackoff, FixedBackoff, InterceptorMetrics, LinearBackoff,
140    LogLevel, LoggingConfig, LoggingInterceptor, NoBackoff, NoRetryPolicy, RequestLogger,
141    RequestSpan, RetryConfig, RetryConfigBuilder, RetryPolicy,
142};
talos_api_rs/lib.rs

talos_api_rs/
lib.rs
