talos/api.md at 757cc204ecc434736d584441f45d2571f2f342ef

mirror of https://github.com/siderolabs/talos.git synced 2025-10-31 00:11:36 +01:00

Andrey Smirnov dd810d0514 docs: add 0.8 docs for the upcoming release

I reverted some reference docs changes in 0.7 which are related to changes
which went only into 0.8.

Signed-off-by: Andrey Smirnov <smirnov.andrey@gmail.com>

2020-11-24 06:02:40 -08:00

59 KiB

Raw Blame History

title

title
API

health/health.proto
machine/machine.proto
network/network.proto
os/os.proto
- OSService
security/security.proto
time/time.proto
Scalar Value Types

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
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
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
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	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	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

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	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	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
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	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
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
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
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	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
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