MachineInventory [elemental.cattle.io/v1beta1]

MachineInventory is the long-lived identity object for a physical host. It is created by elemental-register after a host boots the seed ISO, and it survives reprovisioning — BaremetalMachine only borrows it for the lifetime of one Kubernetes node.

The bare-metal provider reads two parts of this resource:

  • metadata.name — must appear in a MachineInventoryPool.spec.inventoryNames entry for the host to be allocatable.
  • spec.observedNetwork — an Alauda-fork-only field captured during registration; the provider replays it as cloud-init network-config v2 on every reprovision, so the host comes back with the same interface/bond/VLAN/IP layout as when it was first inventoried.

The provider also writes metadata.annotations (baremetal.alauda.io/owner-*, baremetal.alauda.io/plan.type) and updates status.plan / status.conditions during clean/reprovision.

Type
object

Specification

PropertyTypeDescription
apiVersionstring

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

kindstring

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadataObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

specobject
statusobject

.spec

Type
object
PropertyTypeDescription
ipAddressClaimsobject

IPAddressClaims is a map of IPAddressClaim associated to this machine. The map key is the ipAddressPool.name.

ipAddressPoolsobject

IPAddressPools is a map of IPAddressPool objects associated to this machine.

machineHashstring

MachineHash the hash of the identifier used by the host to identify to the operator. This is used when the host authenticates without TPM. Both the authentication method and the identifier used to derive the hash depend upon the MachineRegistration spec.config.elemental.registration.auth value.

networkobject

NetworkConfig is the final NetworkConfig.

observedNetworkobject

ObservedNetwork is a live-ISO-side snapshot of the host's actual network configuration uploaded by elemental-register during initial registration (Alauda fork). It is informational only and is intentionally kept separate from Network (the target/template network). Consumers such as baremetal providers can read this to know what the host looked like before install-time network reconfiguration.

tpmHashstring

TPMHash the hash of the TPM EK public key. This is used if you are using TPM2 to identify nodes. You can obtain the TPM by running rancherd get-tpm-hash on the node. Or nodes can report their TPM hash by using the MachineRegister.

.spec.ipAddressClaims

Description
IPAddressClaims is a map of IPAddressClaim associated to this machine. The map key is the ipAddressPool.name.
Type
object

.spec.ipAddressPools

Description
IPAddressPools is a map of IPAddressPool objects associated to this machine.
Type
object

.spec.network

Description
NetworkConfig is the final NetworkConfig.
Type
object
PropertyTypeDescription
config

Config contains the network config template (nmc, nmstate, or nmconnections formats)

configuratorstring

Configurator

ipAddressesobject

IPAddresses contains a map of claimed IPAddresses

.spec.network.ipAddresses

Description
IPAddresses contains a map of claimed IPAddresses
Type
object

.spec.observedNetwork

Description
ObservedNetwork is a live-ISO-side snapshot of the host's actual network configuration uploaded by elemental-register during initial registration (Alauda fork). It is informational only and is intentionally kept separate from Network (the target/template network). Consumers such as baremetal providers can read this to know what the host looked like before install-time network reconfiguration.
Type
object
PropertyTypeDescription
dnsServersarray

DNSServers observed (typically from /etc/resolv.conf).

interfacesarray

Interfaces observed on the host.

routesarray

Routes observed in the host's routing table.

searchDomainsarray

SearchDomains observed.

.spec.observedNetwork.dnsServers

Description
DNSServers observed (typically from /etc/resolv.conf).
Type
array

.spec.observedNetwork.dnsServers[]

Type
string

.spec.observedNetwork.interfaces

Description
Interfaces observed on the host.
Type
array

.spec.observedNetwork.interfaces[]

Description
ObservedInterface describes a single network interface on the host.
Type
object
Required
name
PropertyTypeDescription
addressesarray

Addresses assigned to the interface, in CIDR form (e.g. 10.0.0.5/24, fe80::1/64). Both IPv4 and IPv6 may appear.

macstring

MAC is the hardware address.

mtuinteger

MTU in bytes.

namestring

Name is the OS-level interface name (e.g. eth0, ens3).

.spec.observedNetwork.interfaces[].addresses

Description
Addresses assigned to the interface, in CIDR form (e.g. 10.0.0.5/24, fe80::1/64). Both IPv4 and IPv6 may appear.
Type
array

.spec.observedNetwork.interfaces[].addresses[]

Type
string

.spec.observedNetwork.routes

Description
Routes observed in the host's routing table.
Type
array

.spec.observedNetwork.routes[]

Description
ObservedRoute describes a single routing table entry.
Type
object
Required
destination
PropertyTypeDescription
destinationstring

Destination CIDR, or the literal string "default" for the default route.

gatewaystring

Gateway is the next-hop IP, if any.

interfacestring

Interface is the outgoing device name, if any.

metricinteger

Metric of the route.

.spec.observedNetwork.searchDomains

Description
SearchDomains observed.
Type
array

.spec.observedNetwork.searchDomains[]

Type
string

.status

Type
object
PropertyTypeDescription
conditionsarray

Conditions describe the state of the machine inventory object.

planobject

PlanStatus reflect the status of the plan owned by the machine inventory object.

.status.conditions

Description
Conditions describe the state of the machine inventory object.
Type
array

.status.conditions[]

Description
Condition contains details for one aspect of the current state of this API Resource.
Type
object
Required
lastTransitionTimemessagereasonstatustype
PropertyTypeDescription
lastTransitionTimestring

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

messagestring

message is a human readable message indicating details about the transition. This may be an empty string.

observedGenerationinteger

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

reasonstring

reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

statusstring

status of the condition, one of True, False, Unknown.

typestring

type of condition in CamelCase or in foo.example.com/CamelCase.

.status.plan

Description
PlanStatus reflect the status of the plan owned by the machine inventory object.
Type
object
PropertyTypeDescription
checksumstring

Checksum checksum of the created plan.

secretRefobject

PlanSecretRef a reference to the created plan secret.

statestring

State reflect state of the plan that belongs to the machine inventory.

.status.plan.secretRef

Description
PlanSecretRef a reference to the created plan secret.
Type
object
PropertyTypeDescription
apiVersionstring

API version of the referent.

fieldPathstring

If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.

kindstring

Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

namestring

Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

namespacestring

Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

resourceVersionstring

Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency

uidstring

UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids

API Endpoints

The following API endpoints are available:

  • /apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories
    • DELETE: delete collection of MachineInventory
    • GET: list objects of kind MachineInventory
    • POST: create a new MachineInventory
  • /apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories/{name}
    • DELETE: delete the specified MachineInventory
    • GET: read the specified MachineInventory
    • PATCH: partially update the specified MachineInventory
    • PUT: replace the specified MachineInventory
  • /apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories/{name}/status
    • GET: read status of the specified MachineInventory
    • PATCH: partially update status of the specified MachineInventory
    • PUT: replace status of the specified MachineInventory

/apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories

HTTP method
DELETE
Description
delete collection of MachineInventory
HTTP responses
HTTP codeResponse body
200 - OKStatus schema
401 - UnauthorizedEmpty
HTTP method
GET
Description
list objects of kind MachineInventory
HTTP responses
HTTP codeResponse body
200 - OKMachineInventoryList schema
401 - UnauthorizedEmpty
HTTP method
POST
Description
create a new MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
Body parameters
ParameterTypeDescription
bodyMachineInventory schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
201 - CreatedMachineInventory schema
202 - AcceptedMachineInventory schema
401 - UnauthorizedEmpty

/apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories/{name}

HTTP method
DELETE
Description
delete the specified MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
HTTP responses
HTTP codeResponse body
200 - OKStatus schema
202 - AcceptedStatus schema
401 - UnauthorizedEmpty
HTTP method
GET
Description
read the specified MachineInventory
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
401 - UnauthorizedEmpty
HTTP method
PATCH
Description
partially update the specified MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
401 - UnauthorizedEmpty
HTTP method
PUT
Description
replace the specified MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
Body parameters
ParameterTypeDescription
bodyMachineInventory schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
201 - CreatedMachineInventory schema
401 - UnauthorizedEmpty

/apis/elemental.cattle.io/v1beta1/namespaces/{namespace}/machineinventories/{name}/status

HTTP method
GET
Description
read status of the specified MachineInventory
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
401 - UnauthorizedEmpty
HTTP method
PATCH
Description
partially update status of the specified MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
401 - UnauthorizedEmpty
HTTP method
PUT
Description
replace status of the specified MachineInventory
Query parameters
ParameterTypeDescription
dryRunstringWhen present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed
fieldValidationstringfieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields. Valid values are: - Ignore: This will ignore any unknown fields that are silently dropped from the object, and will ignore all but the last duplicate field that the decoder encounters. This is the default behavior prior to v1.23. - Warn: This will send a warning via the standard warning response header for each unknown field that is dropped from the object, and for each duplicate field that is encountered. The request will still succeed if there are no other errors, and will only persist the last of any duplicate fields. This is the default in v1.23+ - Strict: This will fail the request with a BadRequest error if any unknown fields would be dropped from the object, or if any duplicate fields are present. The error returned from the server will contain all unknown and duplicate fields encountered.
Body parameters
ParameterTypeDescription
bodyMachineInventory schemaapplication/json formatted
HTTP responses
HTTP codeResponse body
200 - OKMachineInventory schema
201 - CreatedMachineInventory schema
401 - UnauthorizedEmpty