Version v0.12 of the
documentation is no longer actively maintained. The site that you are
currently viewing is an archived snapshot.
For up-to-date documentation, see the
latest version.
API
Talos gRPC API reference.
Table of Contents
Top
common/common.proto
Data
DataResponse
| Field | Type | Label | Description |
|---|
| messages | Data | repeated | |
Empty
| Field | Type | Label | Description |
|---|
| metadata | Metadata | | |
EmptyResponse
| Field | Type | Label | Description |
|---|
| messages | Empty | repeated | |
Error
Common metadata message nested in all reply message types
| Field | Type | Label | Description |
|---|
| hostname | string | | hostname of the server response comes from (injected by proxy) |
| error | string | | error is set if request failed to the upstream (rest of response is undefined) |
| status | google.rpc.Status | | error as gRPC Status |
Code
| Name | Number | Description |
|---|
| FATAL | 0 | |
| LOCKED | 1 | |
ContainerDriver
| Name | Number | Description |
|---|
| CONTAINERD | 0 | |
| CRI | 1 | |
Top
inspect/inspect.proto
ControllerDependencyEdge
ControllerRuntimeDependenciesResponse
ControllerRuntimeDependency
The ControllerRuntimeDependency message contains the graph of controller-resource dependencies.
DependencyEdgeType
| Name | Number | Description |
|---|
| OUTPUT_EXCLUSIVE | 0 | |
| OUTPUT_SHARED | 3 | |
| INPUT_STRONG | 1 | |
| INPUT_WEAK | 2 | |
| INPUT_DESTROY_READY | 4 | |
InspectService
The inspect service definition.
InspectService provides auxilary API to inspect OS internals.
Top
machine/machine.proto
ApplyConfiguration
ApplyConfigurationResponse describes the response to a configuration request.
ApplyConfigurationRequest
rpc applyConfiguration
ApplyConfiguration describes a request to assert a new configuration upon a
node.
ApplyConfigurationResponse
Bootstrap
The bootstrap message containing the bootstrap status.
BootstrapRequest
rpc Bootstrap
| Field | Type | Label | Description |
|---|
| recover_etcd | bool | | Enable etcd recovery from the snapshot. |
Snapshot should be uploaded before this call via EtcdRecover RPC. |
| recover_skip_hash_check | bool | | Skip hash check on the snapshot (etcd).
Enable this when recovering from data directory copy to skip integrity check. |
BootstrapResponse
| Field | Type | Label | Description |
|---|
| messages | Bootstrap | repeated | |
CNIConfig
CPUInfo
CPUInfoResponse
| Field | Type | Label | Description |
|---|
| messages | CPUsInfo | repeated | |
CPUStat
CPUsInfo
ClusterConfig
ClusterNetworkConfig
Container
The messages message containing the requested containers.
ContainerInfo
The messages message containing the requested containers.
ContainersRequest
ContainersResponse
| Field | Type | Label | Description |
|---|
| messages | Container | repeated | |
ControlPlaneConfig
| Field | Type | Label | Description |
|---|
| endpoint | string | | |
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 |
DHCPOptionsConfig
| Field | Type | Label | Description |
|---|
| route_metric | uint32 | | |
DiskStat
DiskStats
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
EtcdForfeitLeadershipRequest
EtcdForfeitLeadershipResponse
EtcdLeaveCluster
EtcdLeaveClusterRequest
EtcdLeaveClusterResponse
EtcdMember
EtcdMember describes a single etcd member.
| Field | Type | Label | Description |
|---|
| id | uint64 | | member ID. |
| hostname | string | | human-readable name of the member. |
| peer_urls | string | repeated | the list of URLs the member exposes to clients for communication. |
| client_urls | string | repeated | the list of URLs the member exposes to the cluster for communication. |
| is_learner | bool | | learner flag |
EtcdMemberListRequest
| Field | Type | Label | Description |
|---|
| query_local | bool | | |
EtcdMemberListResponse
EtcdMembers
EtcdMembers contains the list of members registered on the host.
| Field | Type | Label | Description |
|---|
| metadata | common.Metadata | | |
| legacy_members | string | repeated | list of member hostnames. |
| members | EtcdMember | repeated | the list of etcd members registered on the node. |
EtcdRecover
EtcdRecoverResponse
EtcdRemoveMember
EtcdRemoveMemberRequest
| Field | Type | Label | Description |
|---|
| member | string | | |
EtcdRemoveMemberResponse
EtcdSnapshotRequest
Event
EventsRequest
FeaturesInfo
FeaturesInfo describes individual Talos features that can be switched on or off.
| Field | Type | Label | Description |
|---|
| rbac | bool | | RBAC is true if role-based access control is enabled. |
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 |
| uid | uint32 | | Owner uid |
| gid | uint32 | | Owner gid |
GenerateClientConfiguration
| Field | Type | Label | Description |
|---|
| metadata | common.Metadata | | |
| ca | bytes | | PEM-encoded CA certificate. |
| crt | bytes | | PEM-encoded generated client certificate. |
| key | bytes | | PEM-encoded generated client key. |
| talosconfig | bytes | | Client configuration (talosconfig) file content. |
GenerateClientConfigurationRequest
GenerateClientConfigurationResponse
GenerateConfiguration
GenerateConfiguration describes the response to a generate configuration request.
GenerateConfigurationRequest
GenerateConfigurationRequest describes a request to generate a new configuration
on a node.
GenerateConfigurationResponse
Hostname
HostnameResponse
| Field | Type | Label | Description |
|---|
| messages | Hostname | repeated | |
InstallConfig
| Field | Type | Label | Description |
|---|
| install_disk | string | | |
| install_image | string | | |
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. |
| types | ListRequest.Type | repeated | Types indicates what file type should be returned. If not indicated, all files will be returned. |
LoadAvg
LoadAvgResponse
| Field | Type | Label | Description |
|---|
| messages | LoadAvg | repeated | |
LogsRequest
rpc logs
The request message containing the process name.
MachineConfig
MemInfo
Memory
MemoryResponse
| Field | Type | Label | Description |
|---|
| messages | Memory | repeated | |
MountStat
The messages message containing the requested processes.
Mounts
The messages message containing the requested df stats.
MountsResponse
| Field | Type | Label | Description |
|---|
| messages | Mounts | repeated | |
NetDev
NetworkConfig
NetworkDeviceConfig
NetworkDeviceStats
NetworkDeviceStatsResponse
PhaseEvent
Process
ProcessInfo
ProcessesResponse
rpc processes
| Field | Type | Label | Description |
|---|
| messages | Process | repeated | |
ReadRequest
| Field | Type | Label | Description |
|---|
| path | string | | |
Reboot
rpc reboot
The reboot message containing the reboot status.
RebootResponse
| Field | Type | Label | Description |
|---|
| messages | Reboot | repeated | |
Reset
The reset message containing the restart status.
ResetPartitionSpec
rpc reset
ResetRequest
| Field | Type | Label | Description |
|---|
| graceful | bool | | Graceful indicates whether node should leave etcd before the upgrade, it also enforces etcd checks before leaving. |
| reboot | bool | | Reboot indicates whether node should reboot or halt after resetting. |
| system_partitions_to_wipe | ResetPartitionSpec | repeated | System_partitions_to_wipe lists specific system disk partitions to be reset (wiped). If system_partitions_to_wipe is empty, all the partitions are erased. |
ResetResponse
| Field | Type | Label | Description |
|---|
| messages | Reset | repeated | |
Restart
RestartEvent
| Field | Type | Label | Description |
|---|
| cmd | int64 | | |
RestartRequest
rpc restart
The request message containing the process to restart.
RestartResponse
The messages message containing the restart status.
| Field | Type | Label | Description |
|---|
| messages | Restart | repeated | |
Rollback
RollbackRequest
rpc rollback
RollbackResponse
| Field | Type | Label | Description |
|---|
| messages | Rollback | repeated | |
RouteConfig
SequenceEvent
rpc events
ServiceEvent
ServiceEvents
ServiceHealth
ServiceInfo
ServiceList
rpc servicelist
ServiceListResponse
ServiceRestart
ServiceRestartRequest
| Field | Type | Label | Description |
|---|
| id | string | | |
ServiceRestartResponse
ServiceStart
ServiceStartRequest
rpc servicestart
| Field | Type | Label | Description |
|---|
| id | string | | |
ServiceStartResponse
ServiceStateEvent
ServiceStop
ServiceStopRequest
| Field | Type | Label | Description |
|---|
| id | string | | |
ServiceStopResponse
Shutdown
rpc shutdown
The messages message containing the shutdown status.
ShutdownResponse
| Field | Type | Label | Description |
|---|
| messages | Shutdown | repeated | |
SoftIRQStat
StartRequest
| Field | Type | Label | Description |
|---|
| id | string | | |
StartResponse
| Field | Type | Label | Description |
|---|
| resp | string | | |
Stat
The messages message containing the requested stat.
Stats
The messages message containing the requested stats.
StatsRequest
The request message containing the containerd namespace.
StatsResponse
| Field | Type | Label | Description |
|---|
| messages | Stats | repeated | |
StopRequest
| Field | Type | Label | Description |
|---|
| id | string | | |
StopResponse
| Field | Type | Label | Description |
|---|
| resp | string | | |
SystemStat
SystemStatResponse
| Field | Type | Label | Description |
|---|
| messages | SystemStat | repeated | |
TaskEvent
Upgrade
UpgradeRequest
rpc upgrade
UpgradeResponse
| Field | Type | Label | Description |
|---|
| messages | Upgrade | repeated | |
Version
VersionInfo
VersionResponse
| Field | Type | Label | Description |
|---|
| messages | Version | repeated | |
ListRequest.Type
File type.
| Name | Number | Description |
|---|
| REGULAR | 0 | Regular file (not directory, symlink, etc). |
| DIRECTORY | 1 | Directory. |
| SYMLINK | 2 | Symbolic link. |
MachineConfig.MachineType
| Name | Number | Description |
|---|
| TYPE_UNKNOWN | 0 | |
| TYPE_INIT | 1 | |
| TYPE_CONTROL_PLANE | 2 | |
| TYPE_WORKER | 3 | |
| TYPE_JOIN | 3 | Alias for TYPE_WORKER. |
PhaseEvent.Action
| Name | Number | Description |
|---|
| START | 0 | |
| STOP | 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.
Snapshot can be later used to recover the cluster via Bootstrap method. |
| EtcdSnapshot | EtcdSnapshotRequest | .common.Data stream | EtcdSnapshot method creates etcd data snapshot (backup) from the local etcd instance and streams it back to the client.
This method is available only on control plane nodes (which run etcd). |
| GenerateConfiguration | GenerateConfigurationRequest | GenerateConfigurationResponse | |
| 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 | |
| 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 | |
| GenerateClientConfiguration | GenerateClientConfigurationRequest | GenerateClientConfigurationResponse | GenerateClientConfiguration generates talosctl client configuration (talosconfig). |
Top
network/network.proto
Interface
Interface represents a net.Interface
Interfaces
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
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.
Top
resource/resource.proto
Get
The GetResponse message contains the Resource returned.
GetRequest
rpc Get
GetResponse
| Field | Type | Label | Description |
|---|
| messages | Get | repeated | |
ListRequest
rpc List
The ListResponse message contains the Resource returned.
ListResponse
Resource
Spec
| Field | Type | Label | Description |
|---|
| yaml | bytes | | |
WatchRequest
rpc Watch
The WatchResponse message contains the Resource returned.
WatchResponse
EventType
| Name | Number | Description |
|---|
| CREATED | 0 | |
| UPDATED | 1 | |
| DESTROYED | 2 | |
ResourceService
The resource service definition.
ResourceService provides user-facing API for the Talos resources.
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.
SecurityService
The security service definition.
Top
storage/storage.proto
Disk
Disk represents a disk.
| Field | Type | Label | Description |
|---|
| size | uint64 | | Size indicates the disk size in bytes. |
| model | string | | Model idicates the disk model. |
| device_name | string | | DeviceName indicates the disk name (e.g. sda). |
| name | string | | Name as in /sys/block/<dev>/device/name. |
| serial | string | | Serial as in /sys/block/<dev>/device/serial. |
| modalias | string | | Modalias as in /sys/block/<dev>/device/modalias. |
| uuid | string | | Uuid as in /sys/block/<dev>/device/uuid. |
| wwid | string | | Wwid as in /sys/block/<dev>/device/wwid. |
| type | Disk.DiskType | | Type is a type of the disk: nvme, ssd, hdd, sd card. |
Disks
DisksResponse represents the response of the Disks RPC.
DisksResponse
| Field | Type | Label | Description |
|---|
| messages | Disks | repeated | |
Disk.DiskType
| Name | Number | Description |
|---|
| UNKNOWN | 0 | |
| SSD | 1 | |
| HDD | 2 | |
| NVME | 3 | |
| SD | 4 | |
StorageService
StorageService represents the storage service.
Top
time/time.proto
Time
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.
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) |