API

Table of Contents

Top

health/health.proto

HealthCheck

Field Type Label Description
status HealthCheck.ServingStatus

HealthCheckResponse

Field Type Label Description
messages HealthCheck repeated

HealthWatchRequest

Field Type Label Description
interval_seconds int64

ReadyCheck

Field Type Label Description
status ReadyCheck.ReadyStatus

ReadyCheckResponse

Field Type Label Description
messages ReadyCheck repeated

HealthCheck.ServingStatus

Name Number Description
UNKNOWN 0
SERVING 1
NOT_SERVING 2

ReadyCheck.ReadyStatus

Name Number Description
UNKNOWN 0
READY 1
NOT_READY 2

Health

Method Name Request Type Response Type Description
Check .google.protobuf.Empty HealthCheckResponse
Watch HealthWatchRequest HealthCheckResponse stream
Ready .google.protobuf.Empty ReadyCheckResponse

Top

machine/machine.proto

ApplyConfiguration

ApplyConfigurationResponse describes the response to a configuration request.

Field Type Label Description
metadata common.Metadata

ApplyConfigurationRequest

rpc applyConfiguration ApplyConfiguration describes a request to assert a new configuration upon a node.

Field Type Label Description
data bytes

ApplyConfigurationResponse

Field Type Label Description
messages ApplyConfiguration repeated

Bootstrap

The bootstrap message containing the bootstrap status.

Field Type Label Description
metadata common.Metadata

BootstrapRequest

rpc bootstrap

BootstrapResponse

Field Type Label Description
messages Bootstrap repeated

CPUInfo

Field Type Label Description
processor uint32
vendor_id string
cpu_family string
model string
model_name string
stepping string
microcode string
cpu_mhz double
cache_size string
physical_id string
siblings uint32
core_id string
cpu_cores uint32
apic_id string
initial_apic_id string
fpu string
fpu_exception string
cpu_id_level uint32
wp string
flags string repeated
bugs string repeated
bogo_mips double
cl_flush_size uint32
cache_alignment uint32
address_sizes string
power_management string

CPUInfoResponse

Field Type Label Description
messages CPUsInfo repeated

CPUStat

Field Type Label Description
user double
nice double
system double
idle double
iowait double
irq double
soft_irq double
steal double
guest double
guest_nice double

CPUsInfo

Field Type Label Description
metadata common.Metadata
cpu_info CPUInfo repeated

Container

The messages message containing the requested containers.

Field Type Label Description
metadata common.Metadata
containers ContainerInfo repeated

ContainerInfo

The messages message containing the requested containers.

Field Type Label Description
namespace string
id string
image string
pid uint32
status string
pod_id string
name string

ContainersRequest

Field Type Label Description
namespace string
driver common.ContainerDriver driver might be default "containerd" or "cri"

ContainersResponse

Field Type Label Description
messages Container repeated

CopyRequest

CopyRequest describes a request to copy data out of Talos node

Copy produces .tar.gz archive which is streamed back to the caller

Field Type Label Description
root_path string Root path to start copying data out, it might be either a file or directory

DiskStat

Field Type Label Description
name string
read_completed uint64
read_merged uint64
read_sectors uint64
read_time_ms uint64
write_completed uint64
write_merged uint64
write_sectors uint64
write_time_ms uint64
io_in_progress uint64
io_time_ms uint64
io_time_weighted_ms uint64
discard_completed uint64
discard_merged uint64
discard_sectors uint64
discard_time_ms uint64

DiskStats

Field Type Label Description
metadata common.Metadata
total DiskStat
devices DiskStat repeated

DiskStatsResponse

Field Type Label Description
messages DiskStats repeated

DiskUsageInfo

DiskUsageInfo describes a file or directory's information for du command

Field Type Label Description
metadata common.Metadata
name string Name is the name (including prefixed path) of the file or directory
size int64 Size indicates the number of bytes contained within the file
error string Error describes any error encountered while trying to read the file information.
relative_name string RelativeName is the name of the file or directory relative to the RootPath

DiskUsageRequest

DiskUsageRequest describes a request to list disk usage of directories and regular files

Field Type Label Description
recursion_depth int32 RecursionDepth indicates how many levels of subdirectories should be recursed. The default (0) indicates that no limit should be enforced.
all bool All write sizes for all files, not just directories.
threshold int64 Threshold exclude entries smaller than SIZE if positive, or entries greater than SIZE if negative.
paths string repeated DiskUsagePaths is the list of directories to calculate disk usage for.

DmesgRequest

dmesg

Field Type Label Description
follow bool
tail bool

EtcdForfeitLeadership

Field Type Label Description
metadata common.Metadata
member string

EtcdForfeitLeadershipRequest

EtcdForfeitLeadershipResponse

Field Type Label Description
messages EtcdForfeitLeadership repeated

EtcdLeaveCluster

Field Type Label Description
metadata common.Metadata

EtcdLeaveClusterRequest

EtcdLeaveClusterResponse

Field Type Label Description
messages EtcdLeaveCluster repeated

EtcdMemberList

Field Type Label Description
metadata common.Metadata
members string repeated

EtcdMemberListRequest

EtcdMemberListResponse

Field Type Label Description
messages EtcdMemberList repeated

Event

Field Type Label Description
metadata common.Metadata
data google.protobuf.Any
id string

EventsRequest

Field Type Label Description
tail_events int32
tail_id string
tail_seconds int32

FileInfo

FileInfo describes a file or directory's information

Field Type Label Description
metadata common.Metadata
name string Name is the name (including prefixed path) of the file or directory
size int64 Size indicates the number of bytes contained within the file
mode uint32 Mode is the bitmap of UNIX mode/permission flags of the file
modified int64 Modified indicates the UNIX timestamp at which the file was last modified

TODO: unix timestamp or include proto's Date type | | is_dir | bool | | IsDir indicates that the file is a directory | | error | string | | Error describes any error encountered while trying to read the file information. | | link | string | | Link is filled with symlink target | | relative_name | string | | RelativeName is the name of the file or directory relative to the RootPath |

Hostname

Field Type Label Description
metadata common.Metadata
hostname string

HostnameResponse

Field Type Label Description
messages Hostname repeated

ListRequest

ListRequest describes a request to list the contents of a directory

Field Type Label Description
root string Root indicates the root directory for the list. If not indicated, '/' is presumed.
recurse bool Recurse indicates that subdirectories should be recursed.
recursion_depth int32 RecursionDepth indicates how many levels of subdirectories should be recursed. The default (0) indicates that no limit should be enforced.

LoadAvg

Field Type Label Description
metadata common.Metadata
load1 double
load5 double
load15 double

LoadAvgResponse

Field Type Label Description
messages LoadAvg repeated

LogsRequest

rpc logs The request message containing the process name.

Field Type Label Description
namespace string
id string
driver common.ContainerDriver driver might be default "containerd" or "cri"
follow bool
tail_lines int32

MemInfo

Field Type Label Description
memtotal uint64
memfree uint64
memavailable uint64
buffers uint64
cached uint64
swapcached uint64
active uint64
inactive uint64
activeanon uint64
inactiveanon uint64
activefile uint64
inactivefile uint64
unevictable uint64
mlocked uint64
swaptotal uint64
swapfree uint64
dirty uint64
writeback uint64
anonpages uint64
mapped uint64
shmem uint64
slab uint64
sreclaimable uint64
sunreclaim uint64
kernelstack uint64
pagetables uint64
nfsunstable uint64
bounce uint64
writebacktmp uint64
commitlimit uint64
committedas uint64
vmalloctotal uint64
vmallocused uint64
vmallocchunk uint64
hardwarecorrupted uint64
anonhugepages uint64
shmemhugepages uint64
shmempmdmapped uint64
cmatotal uint64
cmafree uint64
hugepagestotal uint64
hugepagesfree uint64
hugepagesrsvd uint64
hugepagessurp uint64
hugepagesize uint64
directmap4k uint64
directmap2m uint64
directmap1g uint64

Memory

Field Type Label Description
metadata common.Metadata
meminfo MemInfo

MemoryResponse

Field Type Label Description
messages Memory repeated

MountStat

The messages message containing the requested processes.

Field Type Label Description
filesystem string
size uint64
available uint64
mounted_on string

Mounts

The messages message containing the requested df stats.

Field Type Label Description
metadata common.Metadata
stats MountStat repeated

MountsResponse

Field Type Label Description
messages Mounts repeated

NetDev

Field Type Label Description
name string
rx_bytes uint64
rx_packets uint64
rx_errors uint64
rx_dropped uint64
rx_fifo uint64
rx_frame uint64
rx_compressed uint64
rx_multicast uint64
tx_bytes uint64
tx_packets uint64
tx_errors uint64
tx_dropped uint64
tx_fifo uint64
tx_collisions uint64
tx_carrier uint64
tx_compressed uint64

NetworkDeviceStats

Field Type Label Description
metadata common.Metadata
total NetDev
devices NetDev repeated

NetworkDeviceStatsResponse

Field Type Label Description
messages NetworkDeviceStats repeated

PhaseEvent

Field Type Label Description
phase string
action PhaseEvent.Action

PlatformInfo

Field Type Label Description
name string
mode string

Process

Field Type Label Description
metadata common.Metadata
processes ProcessInfo repeated

ProcessInfo

Field Type Label Description
pid int32
ppid int32
state string
threads int32
cpu_time double
virtual_memory uint64
resident_memory uint64
command string
executable string
args string

ProcessesRequest

rpc processes

ProcessesResponse

Field Type Label Description
messages Process repeated

ReadRequest

Field Type Label Description
path string

Reboot

rpc reboot The reboot message containing the reboot status.

Field Type Label Description
metadata common.Metadata

RebootResponse

Field Type Label Description
messages Reboot repeated

Recover

The recover message containing the recover status.

Field Type Label Description
metadata common.Metadata

RecoverRequest

Field Type Label Description
source RecoverRequest.Source

RecoverResponse

Field Type Label Description
messages Recover repeated

Reset

The reset message containing the restart status.

Field Type Label Description
metadata common.Metadata

ResetRequest

rpc reset

Field Type Label Description
graceful bool
reboot bool

ResetResponse

Field Type Label Description
messages Reset repeated

Restart

Field Type Label Description
metadata common.Metadata

RestartRequest

rpc restart The request message containing the process to restart.

Field Type Label Description
namespace string
id string
driver common.ContainerDriver driver might be default "containerd" or "cri"

RestartResponse

The messages message containing the restart status.

Field Type Label Description
messages Restart repeated

Rollback

Field Type Label Description
metadata common.Metadata

RollbackRequest

rpc rollback

RollbackResponse

Field Type Label Description
messages Rollback repeated

SequenceEvent

rpc events

Field Type Label Description
sequence string
action SequenceEvent.Action
error common.Error

ServiceEvent

Field Type Label Description
msg string
state string
ts google.protobuf.Timestamp

ServiceEvents

Field Type Label Description
events ServiceEvent repeated

ServiceHealth

Field Type Label Description
unknown bool
healthy bool
last_message string
last_change google.protobuf.Timestamp

ServiceInfo

Field Type Label Description
id string
state string
events ServiceEvents
health ServiceHealth

ServiceList

rpc servicelist

Field Type Label Description
metadata common.Metadata
services ServiceInfo repeated

ServiceListResponse

Field Type Label Description
messages ServiceList repeated

ServiceRestart

Field Type Label Description
metadata common.Metadata
resp string

ServiceRestartRequest

Field Type Label Description
id string

ServiceRestartResponse

Field Type Label Description
messages ServiceRestart repeated

ServiceStart

Field Type Label Description
metadata common.Metadata
resp string

ServiceStartRequest

rpc servicestart

Field Type Label Description
id string

ServiceStartResponse

Field Type Label Description
messages ServiceStart repeated

ServiceStateEvent

Field Type Label Description
service string
action ServiceStateEvent.Action
message string

ServiceStop

Field Type Label Description
metadata common.Metadata
resp string

ServiceStopRequest

Field Type Label Description
id string

ServiceStopResponse

Field Type Label Description
messages ServiceStop repeated

Shutdown

rpc shutdown The messages message containing the shutdown status.

Field Type Label Description
metadata common.Metadata

ShutdownResponse

Field Type Label Description
messages Shutdown repeated

SoftIRQStat

Field Type Label Description
hi uint64
timer uint64
net_tx uint64
net_rx uint64
block uint64
block_io_poll uint64
tasklet uint64
sched uint64
hrtimer uint64
rcu uint64

StartRequest

Field Type Label Description
id string

StartResponse

Field Type Label Description
resp string

Stat

The messages message containing the requested stat.

Field Type Label Description
namespace string
id string
memory_usage uint64
cpu_usage uint64
pod_id string
name string

Stats

The messages message containing the requested stats.

Field Type Label Description
metadata common.Metadata
stats Stat repeated

StatsRequest

The request message containing the containerd namespace.

Field Type Label Description
namespace string
driver common.ContainerDriver driver might be default "containerd" or "cri"

StatsResponse

Field Type Label Description
messages Stats repeated

StopRequest

Field Type Label Description
id string

StopResponse

Field Type Label Description
resp string

SystemStat

Field Type Label Description
metadata common.Metadata
boot_time uint64
cpu_total CPUStat
cpu CPUStat repeated
irq_total uint64
irq uint64 repeated
context_switches uint64
process_created uint64
process_running uint64
process_blocked uint64
soft_irq_total uint64
soft_irq SoftIRQStat

SystemStatResponse

Field Type Label Description
messages SystemStat repeated

TaskEvent

Field Type Label Description
task string
action TaskEvent.Action

Upgrade

Field Type Label Description
metadata common.Metadata
ack string

UpgradeRequest

rpc upgrade

Field Type Label Description
image string
preserve bool

UpgradeResponse

Field Type Label Description
messages Upgrade repeated

Version

Field Type Label Description
metadata common.Metadata
version VersionInfo
platform PlatformInfo

VersionInfo

Field Type Label Description
tag string
sha string
built string
go_version string
os string
arch string

VersionResponse

Field Type Label Description
messages Version repeated

PhaseEvent.Action

Name Number Description
START 0
STOP 1

RecoverRequest.Source

Name Number Description
ETCD 0
APISERVER 1

SequenceEvent.Action

Name Number Description
NOOP 0
START 1
STOP 2

ServiceStateEvent.Action

Name Number Description
INITIALIZED 0
PREPARING 1
WAITING 2
RUNNING 3
STOPPING 4
FINISHED 5
FAILED 6
SKIPPED 7

TaskEvent.Action

Name Number Description
START 0
STOP 1

MachineService

The machine service definition.

Method Name Request Type Response Type Description
ApplyConfiguration ApplyConfigurationRequest ApplyConfigurationResponse
Bootstrap BootstrapRequest BootstrapResponse
Containers ContainersRequest ContainersResponse
Copy CopyRequest .common.Data stream
CPUInfo .google.protobuf.Empty CPUInfoResponse
DiskStats .google.protobuf.Empty DiskStatsResponse
Dmesg DmesgRequest .common.Data stream
Events EventsRequest Event stream
EtcdMemberList EtcdMemberListRequest EtcdMemberListResponse
EtcdLeaveCluster EtcdLeaveClusterRequest EtcdLeaveClusterResponse
EtcdForfeitLeadership EtcdForfeitLeadershipRequest EtcdForfeitLeadershipResponse
Hostname .google.protobuf.Empty HostnameResponse
Kubeconfig .google.protobuf.Empty .common.Data stream
List ListRequest FileInfo stream
DiskUsage DiskUsageRequest DiskUsageInfo stream
LoadAvg .google.protobuf.Empty LoadAvgResponse
Logs LogsRequest .common.Data stream
Memory .google.protobuf.Empty MemoryResponse
Mounts .google.protobuf.Empty MountsResponse
NetworkDeviceStats .google.protobuf.Empty NetworkDeviceStatsResponse
Processes .google.protobuf.Empty ProcessesResponse
Read ReadRequest .common.Data stream
Reboot .google.protobuf.Empty RebootResponse
Restart RestartRequest RestartResponse
Rollback RollbackRequest RollbackResponse
Reset ResetRequest ResetResponse
Recover RecoverRequest RecoverResponse
ServiceList .google.protobuf.Empty ServiceListResponse
ServiceRestart ServiceRestartRequest ServiceRestartResponse
ServiceStart ServiceStartRequest ServiceStartResponse
ServiceStop ServiceStopRequest ServiceStopResponse
Shutdown .google.protobuf.Empty ShutdownResponse
Stats StatsRequest StatsResponse
SystemStat .google.protobuf.Empty SystemStatResponse
Upgrade UpgradeRequest UpgradeResponse
Version .google.protobuf.Empty VersionResponse

MaintenanceService

Method Name Request Type Response Type Description
ApplyConfiguration ApplyConfigurationRequest ApplyConfigurationResponse

Top

network/network.proto

Interface

Interface represents a net.Interface

Field Type Label Description
index uint32
mtu uint32
name string
hardwareaddr string
flags InterfaceFlags
ipaddress string repeated

Interfaces

Field Type Label Description
metadata common.Metadata
interfaces Interface repeated

InterfacesResponse

Field Type Label Description
messages Interfaces repeated

Route

The messages message containing a route.

Field Type Label Description
interface string Interface is the interface over which traffic to this destination should be sent
destination string Destination is the network prefix CIDR which this route provides
gateway string Gateway is the gateway address to which traffic to this destination should be sent
metric uint32 Metric is the priority of the route, where lower metrics have higher priorities
scope uint32 Scope desribes the scope of this route
source string Source is the source prefix CIDR for the route, if one is defined
family AddressFamily Family is the address family of the route. Currently, the only options are AF_INET (IPV4) and AF_INET6 (IPV6).
protocol RouteProtocol Protocol is the protocol by which this route came to be in place
flags uint32 Flags indicate any special flags on the route

Routes

Field Type Label Description
metadata common.Metadata
routes Route repeated

RoutesResponse

The messages message containing the routes.

Field Type Label Description
messages Routes repeated

AddressFamily

Name Number Description
AF_UNSPEC 0
AF_INET 2
IPV4 2
AF_INET6 10
IPV6 10

InterfaceFlags

Name Number Description
FLAG_UNKNOWN 0
FLAG_UP 1
FLAG_BROADCAST 2
FLAG_LOOPBACK 3
FLAG_POINT_TO_POINT 4
FLAG_MULTICAST 5

RouteProtocol

Name Number Description
RTPROT_UNSPEC 0
RTPROT_REDIRECT 1 Route installed by ICMP redirects
RTPROT_KERNEL 2 Route installed by kernel
RTPROT_BOOT 3 Route installed during boot
RTPROT_STATIC 4 Route installed by administrator
RTPROT_GATED 8 Route installed by gated
RTPROT_RA 9 Route installed by router advertisement
RTPROT_MRT 10 Route installed by Merit MRT
RTPROT_ZEBRA 11 Route installed by Zebra/Quagga
RTPROT_BIRD 12 Route installed by Bird
RTPROT_DNROUTED 13 Route installed by DECnet routing daemon
RTPROT_XORP 14 Route installed by XORP
RTPROT_NTK 15 Route installed by Netsukuku
RTPROT_DHCP 16 Route installed by DHCP
RTPROT_MROUTED 17 Route installed by Multicast daemon
RTPROT_BABEL 42 Route installed by Babel daemon

NetworkService

The network service definition.

Method Name Request Type Response Type Description
Routes .google.protobuf.Empty RoutesResponse
Interfaces .google.protobuf.Empty InterfacesResponse

Top

os/os.proto

OSService

The OS service definition.

Deprecated: this API is deprecated and merged into Machine API.

Method Name Request Type Response Type Description
Containers .machine.ContainersRequest .machine.ContainersResponse
Dmesg .machine.DmesgRequest .common.Data stream
Memory .google.protobuf.Empty .machine.MemoryResponse
Processes .google.protobuf.Empty .machine.ProcessesResponse
Restart .machine.RestartRequest .machine.RestartResponse
Stats .machine.StatsRequest .machine.StatsResponse

Top

security/security.proto

CertificateRequest

The request message containing the process name.

Field Type Label Description
csr bytes

CertificateResponse

The response message containing the requested logs.

Field Type Label Description
ca bytes
crt bytes

ReadFileRequest

The request message for reading a file on disk.

Field Type Label Description
path string

ReadFileResponse

The response message for reading a file on disk.

Field Type Label Description
data bytes

WriteFileRequest

The request message containing the process name.

Field Type Label Description
path string
data bytes
perm int32

WriteFileResponse

The response message containing the requested logs.

SecurityService

The security service definition.

Method Name Request Type Response Type Description
Certificate CertificateRequest CertificateResponse
ReadFile ReadFileRequest ReadFileResponse
WriteFile WriteFileRequest WriteFileResponse

Top

time/time.proto

Time

Field Type Label Description
metadata common.Metadata
server string
localtime google.protobuf.Timestamp
remotetime google.protobuf.Timestamp

TimeRequest

The response message containing the ntp server

Field Type Label Description
server string

TimeResponse

The response message containing the ntp server, time, and offset

Field Type Label Description
messages Time repeated

TimeService

The time service definition.

Method Name Request Type Response Type Description
Time .google.protobuf.Empty TimeResponse
TimeCheck TimeRequest TimeResponse

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)