Provisioning APIs


OpenShift Container Platform 4.12

Reference guide for provisioning APIs

Red Hat OpenShift Documentation Team

Abstract

This document describes the OpenShift Container Platform provisioning API objects and their detailed specifications.

Chapter 1. Provisioning APIs

1.1. BMCEventSubscription [metal3.io/v1alpha1]

Description
BMCEventSubscription is the Schema for the fast eventing API
Type
object

1.2. BareMetalHost [metal3.io/v1alpha1]

Description
BareMetalHost is the Schema for the baremetalhosts API
Type
object

1.3. FirmwareSchema [metal3.io/v1alpha1]

Description
FirmwareSchema is the Schema for the firmwareschemas API
Type
object

1.4. HardwareData [metal3.io/v1alpha1]

Description
HardwareData is the Schema for the hardwaredata API
Type
object

1.5. HostFirmwareSettings [metal3.io/v1alpha1]

Description
HostFirmwareSettings is the Schema for the hostfirmwaresettings API
Type
object

1.6. PreprovisioningImage [metal3.io/v1alpha1]

Description
PreprovisioningImage is the Schema for the preprovisioningimages API
Type
object

1.7. Provisioning [metal3.io/v1alpha1]

Description
Provisioning contains configuration used by the Provisioning service (Ironic) to provision baremetal hosts. Provisioning is created by the OpenShift installer using admin or user provided information about the provisioning network and the NIC on the server that can be used to PXE boot it. This CR is a singleton, created by the installer and currently only consumed by the cluster-baremetal-operator to bring up and update containers in a metal3 cluster.
Type
object

Chapter 2. BMCEventSubscription [metal3.io/v1alpha1]

Description
BMCEventSubscription is the Schema for the fast eventing API
Type
object

2.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

 

status

object

 

2.1.1. .spec

Description
Type
object
PropertyTypeDescription

context

string

Arbitrary user-provided context for the event

destination

string

A webhook URL to send events to

hostName

string

A reference to a BareMetalHost

httpHeadersRef

object

A secret containing HTTP headers which should be passed along to the Destination when making a request

2.1.2. .spec.httpHeadersRef

Description
A secret containing HTTP headers which should be passed along to the Destination when making a request
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

2.1.3. .status

Description
Type
object
PropertyTypeDescription

error

string

 

subscriptionID

string

 

2.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/bmceventsubscriptions

    • GET: list objects of kind BMCEventSubscription
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions

    • DELETE: delete collection of BMCEventSubscription
    • GET: list objects of kind BMCEventSubscription
    • POST: create a BMCEventSubscription
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions/{name}

    • DELETE: delete a BMCEventSubscription
    • GET: read the specified BMCEventSubscription
    • PATCH: partially update the specified BMCEventSubscription
    • PUT: replace the specified BMCEventSubscription
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions/{name}/status

    • GET: read status of the specified BMCEventSubscription
    • PATCH: partially update status of the specified BMCEventSubscription
    • PUT: replace status of the specified BMCEventSubscription

2.2.1. /apis/metal3.io/v1alpha1/bmceventsubscriptions

Table 2.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind BMCEventSubscription
Table 2.2. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscriptionList schema

401 - Unauthorized

Empty

2.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions

Table 2.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 2.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of BMCEventSubscription
Table 2.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 2.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind BMCEventSubscription
Table 2.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 2.8. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscriptionList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a BMCEventSubscription
Table 2.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 2.10. Body parameters
ParameterTypeDescription

body

BMCEventSubscription schema

 
Table 2.11. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

201 - Created

BMCEventSubscription schema

202 - Accepted

BMCEventSubscription schema

401 - Unauthorized

Empty

2.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions/{name}

Table 2.12. Global path parameters
ParameterTypeDescription

name

string

name of the BMCEventSubscription

namespace

string

object name and auth scope, such as for teams and projects

Table 2.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a BMCEventSubscription
Table 2.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 2.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 2.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified BMCEventSubscription
Table 2.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 2.18. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified BMCEventSubscription
Table 2.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 2.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 2.21. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified BMCEventSubscription
Table 2.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 2.23. Body parameters
ParameterTypeDescription

body

BMCEventSubscription schema

 
Table 2.24. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

201 - Created

BMCEventSubscription schema

401 - Unauthorized

Empty

2.2.4. /apis/metal3.io/v1alpha1/namespaces/{namespace}/bmceventsubscriptions/{name}/status

Table 2.25. Global path parameters
ParameterTypeDescription

name

string

name of the BMCEventSubscription

namespace

string

object name and auth scope, such as for teams and projects

Table 2.26. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified BMCEventSubscription
Table 2.27. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 2.28. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified BMCEventSubscription
Table 2.29. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 2.30. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 2.31. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified BMCEventSubscription
Table 2.32. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 2.33. Body parameters
ParameterTypeDescription

body

BMCEventSubscription schema

 
Table 2.34. HTTP responses
HTTP codeReponse body

200 - OK

BMCEventSubscription schema

201 - Created

BMCEventSubscription schema

401 - Unauthorized

Empty

Chapter 3. BareMetalHost [metal3.io/v1alpha1]

Description
BareMetalHost is the Schema for the baremetalhosts API
Type
object

3.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

BareMetalHostSpec defines the desired state of BareMetalHost

status

object

BareMetalHostStatus defines the observed state of BareMetalHost

3.1.1. .spec

Description
BareMetalHostSpec defines the desired state of BareMetalHost
Type
object
Required
  • online
PropertyTypeDescription

automatedCleaningMode

string

When set to disabled, automated cleaning will be avoided during provisioning and deprovisioning.

bmc

object

How do we connect to the BMC?

bootMACAddress

string

Which MAC address will PXE boot? This is optional for some types, but required for libvirt VMs driven by vbmc.

bootMode

string

Select the method of initializing the hardware during boot. Defaults to UEFI.

consumerRef

object

ConsumerRef can be used to store information about something that is using a host. When it is not empty, the host is considered "in use".

customDeploy

object

A custom deploy procedure.

description

string

Description is a human-entered text used to help identify the host

externallyProvisioned

boolean

ExternallyProvisioned means something else is managing the image running on the host and the operator should only manage the power status and hardware inventory inspection. If the Image field is filled in, this field is ignored.

firmware

object

BIOS configuration for bare metal server

hardwareProfile

string

What is the name of the hardware profile for this host? It should only be necessary to set this when inspection cannot automatically determine the profile.

image

object

Image holds the details of the image to be provisioned.

metaData

object

MetaData holds the reference to the Secret containing host metadata (e.g. meta_data.json) which is passed to the Config Drive.

networkData

object

NetworkData holds the reference to the Secret containing network configuration (e.g content of network_data.json) which is passed to the Config Drive.

online

boolean

Should the server be online?

preprovisioningNetworkDataName

string

PreprovisioningNetworkDataName is the name of the Secret in the local namespace containing network configuration (e.g content of network_data.json) which is passed to the preprovisioning image, and to the Config Drive if not overridden by specifying NetworkData.

raid

object

RAID configuration for bare metal server

rootDeviceHints

object

Provide guidance about how to choose the device for the image being provisioned.

taints

array

Taints is the full, authoritative list of taints to apply to the corresponding Machine. This list will overwrite any modifications made to the Machine on an ongoing basis.

taints[]

object

The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint.

userData

object

UserData holds the reference to the Secret containing the user data to be passed to the host before it boots.

3.1.2. .spec.bmc

Description
How do we connect to the BMC?
Type
object
Required
  • address
  • credentialsName
PropertyTypeDescription

address

string

Address holds the URL for accessing the controller on the network.

credentialsName

string

The name of the secret containing the BMC credentials (requires keys "username" and "password").

disableCertificateVerification

boolean

DisableCertificateVerification disables verification of server certificates when using HTTPS to connect to the BMC. This is required when the server certificate is self-signed, but is insecure because it allows a man-in-the-middle to intercept the connection.

3.1.3. .spec.consumerRef

Description
ConsumerRef can be used to store information about something that is using a host. When it is not empty, the host is considered "in use".
Type
object
PropertyTypeDescription

apiVersion

string

API version of the referent.

fieldPath

string

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. TODO: this design is not final and this field is subject to change in the future.

kind

string

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

name

string

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

namespace

string

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

resourceVersion

string

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

uid

string

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

3.1.4. .spec.customDeploy

Description
A custom deploy procedure.
Type
object
Required
  • method
PropertyTypeDescription

method

string

Custom deploy method name. This name is specific to the deploy ramdisk used. If you don’t have a custom deploy ramdisk, you shouldn’t use CustomDeploy.

3.1.5. .spec.firmware

Description
BIOS configuration for bare metal server
Type
object
PropertyTypeDescription

simultaneousMultithreadingEnabled

boolean

Allows a single physical processor core to appear as several logical processors. This supports following options: true, false.

sriovEnabled

boolean

SR-IOV support enables a hypervisor to create virtual instances of a PCI-express device, potentially increasing performance. This supports following options: true, false.

virtualizationEnabled

boolean

Supports the virtualization of platform hardware. This supports following options: true, false.

3.1.6. .spec.image

Description
Image holds the details of the image to be provisioned.
Type
object
Required
  • url
PropertyTypeDescription

checksum

string

Checksum is the checksum for the image.

checksumType

string

ChecksumType is the checksum algorithm for the image. e.g md5, sha256, sha512

format

string

DiskFormat contains the format of the image (raw, qcow2, …​). Needs to be set to raw for raw images streaming. Note live-iso means an iso referenced by the url will be live-booted and not deployed to disk, and in this case the checksum options are not required and if specified will be ignored.

url

string

URL is a location of an image to deploy.

3.1.7. .spec.metaData

Description
MetaData holds the reference to the Secret containing host metadata (e.g. meta_data.json) which is passed to the Config Drive.
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

3.1.8. .spec.networkData

Description
NetworkData holds the reference to the Secret containing network configuration (e.g content of network_data.json) which is passed to the Config Drive.
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

3.1.9. .spec.raid

Description
RAID configuration for bare metal server
Type
object
PropertyTypeDescription

hardwareRAIDVolumes

``

The list of logical disks for hardware RAID, if rootDeviceHints isn’t used, first volume is root volume. You can set the value of this field to [] to clear all the hardware RAID configurations.

softwareRAIDVolumes

``

The list of logical disks for software RAID, if rootDeviceHints isn’t used, first volume is root volume. If HardwareRAIDVolumes is set this item will be invalid. The number of created Software RAID devices must be 1 or 2. If there is only one Software RAID device, it has to be a RAID-1. If there are two, the first one has to be a RAID-1, while the RAID level for the second one can be 0, 1, or 1+0. As the first RAID device will be the deployment device, enforcing a RAID-1 reduces the risk of ending up with a non-booting node in case of a disk failure. Software RAID will always be deleted.

3.1.10. .spec.rootDeviceHints

Description
Provide guidance about how to choose the device for the image being provisioned.
Type
object
PropertyTypeDescription

deviceName

string

A Linux device name like "/dev/vda". The hint must match the actual value exactly.

hctl

string

A SCSI bus address like 0:0:0:0. The hint must match the actual value exactly.

minSizeGigabytes

integer

The minimum size of the device in Gigabytes.

model

string

A vendor-specific device identifier. The hint can be a substring of the actual value.

rotational

boolean

True if the device should use spinning media, false otherwise.

serialNumber

string

Device serial number. The hint must match the actual value exactly.

vendor

string

The name of the vendor or manufacturer of the device. The hint can be a substring of the actual value.

wwn

string

Unique storage identifier. The hint must match the actual value exactly.

wwnVendorExtension

string

Unique vendor storage identifier. The hint must match the actual value exactly.

wwnWithExtension

string

Unique storage identifier with the vendor extension appended. The hint must match the actual value exactly.

3.1.11. .spec.taints

Description
Taints is the full, authoritative list of taints to apply to the corresponding Machine. This list will overwrite any modifications made to the Machine on an ongoing basis.
Type
array

3.1.12. .spec.taints[]

Description
The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint.
Type
object
Required
  • effect
  • key
PropertyTypeDescription

effect

string

Required. The effect of the taint on pods that do not tolerate the taint. Valid effects are NoSchedule, PreferNoSchedule and NoExecute.

key

string

Required. The taint key to be applied to a node.

timeAdded

string

TimeAdded represents the time at which the taint was added. It is only written for NoExecute taints.

value

string

The taint value corresponding to the taint key.

3.1.13. .spec.userData

Description
UserData holds the reference to the Secret containing the user data to be passed to the host before it boots.
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

3.1.14. .status

Description
BareMetalHostStatus defines the observed state of BareMetalHost
Type
object
Required
  • errorCount
  • errorMessage
  • hardwareProfile
  • operationalStatus
  • poweredOn
  • provisioning
PropertyTypeDescription

errorCount

integer

ErrorCount records how many times the host has encoutered an error since the last successful operation

errorMessage

string

the last error message reported by the provisioning subsystem

errorType

string

ErrorType indicates the type of failure encountered when the OperationalStatus is OperationalStatusError

goodCredentials

object

the last credentials we were able to validate as working

hardware

object

The hardware discovered to exist on the host.

hardwareProfile

string

The name of the profile matching the hardware details.

lastUpdated

string

LastUpdated identifies when this status was last observed.

operationHistory

object

OperationHistory holds information about operations performed on this host.

operationalStatus

string

OperationalStatus holds the status of the host

poweredOn

boolean

indicator for whether or not the host is powered on

provisioning

object

Information tracked by the provisioner.

triedCredentials

object

the last credentials we sent to the provisioning backend

3.1.15. .status.goodCredentials

Description
the last credentials we were able to validate as working
Type
object
PropertyTypeDescription

credentials

object

SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace

credentialsVersion

string

 

3.1.16. .status.goodCredentials.credentials

Description
SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

3.1.17. .status.hardware

Description
The hardware discovered to exist on the host.
Type
object
PropertyTypeDescription

cpu

object

CPU describes one processor on the host.

firmware

object

Firmware describes the firmware on the host.

hostname

string

 

nics

array

 

nics[]

object

NIC describes one network interface on the host.

ramMebibytes

integer

 

storage

array

 

storage[]

object

Storage describes one storage device (disk, SSD, etc.) on the host.

systemVendor

object

HardwareSystemVendor stores details about the whole hardware system.

3.1.18. .status.hardware.cpu

Description
CPU describes one processor on the host.
Type
object
PropertyTypeDescription

arch

string

 

clockMegahertz

number

ClockSpeed is a clock speed in MHz

count

integer

 

flags

array (string)

 

model

string

 

3.1.19. .status.hardware.firmware

Description
Firmware describes the firmware on the host.
Type
object
PropertyTypeDescription

bios

object

The BIOS for this firmware

3.1.20. .status.hardware.firmware.bios

Description
The BIOS for this firmware
Type
object
PropertyTypeDescription

date

string

The release/build date for this BIOS

vendor

string

The vendor name for this BIOS

version

string

The version of the BIOS

3.1.21. .status.hardware.nics

Description
Type
array

3.1.22. .status.hardware.nics[]

Description
NIC describes one network interface on the host.
Type
object
PropertyTypeDescription

ip

string

The IP address of the interface. This will be an IPv4 or IPv6 address if one is present. If both IPv4 and IPv6 addresses are present in a dual-stack environment, two nics will be output, one with each IP.

mac

string

The device MAC address

model

string

The vendor and product IDs of the NIC, e.g. "0x8086 0x1572"

name

string

The name of the network interface, e.g. "en0"

pxe

boolean

Whether the NIC is PXE Bootable

speedGbps

integer

The speed of the device in Gigabits per second

vlanId

integer

The untagged VLAN ID

vlans

array

The VLANs available

vlans[]

object

VLAN represents the name and ID of a VLAN

3.1.23. .status.hardware.nics[].vlans

Description
The VLANs available
Type
array

3.1.24. .status.hardware.nics[].vlans[]

Description
VLAN represents the name and ID of a VLAN
Type
object
PropertyTypeDescription

id

integer

VLANID is a 12-bit 802.1Q VLAN identifier

name

string

 

3.1.25. .status.hardware.storage

Description
Type
array

3.1.26. .status.hardware.storage[]

Description
Storage describes one storage device (disk, SSD, etc.) on the host.
Type
object
PropertyTypeDescription

hctl

string

The SCSI location of the device

model

string

Hardware model

name

string

The Linux device name of the disk, e.g. "/dev/sda". Note that this may not be stable across reboots.

rotational

boolean

Whether this disk represents rotational storage. This field is not recommended for usage, please prefer using 'Type' field instead, this field will be deprecated eventually.

serialNumber

string

The serial number of the device

sizeBytes

integer

The size of the disk in Bytes

type

string

Device type, one of: HDD, SSD, NVME.

vendor

string

The name of the vendor of the device

wwn

string

The WWN of the device

wwnVendorExtension

string

The WWN Vendor extension of the device

wwnWithExtension

string

The WWN with the extension

3.1.27. .status.hardware.systemVendor

Description
HardwareSystemVendor stores details about the whole hardware system.
Type
object
PropertyTypeDescription

manufacturer

string

 

productName

string

 

serialNumber

string

 

3.1.28. .status.operationHistory

Description
OperationHistory holds information about operations performed on this host.
Type
object
PropertyTypeDescription

deprovision

object

OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.

inspect

object

OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.

provision

object

OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.

register

object

OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.

3.1.29. .status.operationHistory.deprovision

Description
OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.
Type
object
PropertyTypeDescription

end

``

 

start

``

 

3.1.30. .status.operationHistory.inspect

Description
OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.
Type
object
PropertyTypeDescription

end

``

 

start

``

 

3.1.31. .status.operationHistory.provision

Description
OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.
Type
object
PropertyTypeDescription

end

``

 

start

``

 

3.1.32. .status.operationHistory.register

Description
OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics.
Type
object
PropertyTypeDescription

end

``

 

start

``

 

3.1.33. .status.provisioning

Description
Information tracked by the provisioner.
Type
object
Required
  • ID
  • state
PropertyTypeDescription

ID

string

The machine’s UUID from the underlying provisioning tool

bootMode

string

BootMode indicates the boot mode used to provision the node

customDeploy

object

Custom deploy procedure applied to the host.

firmware

object

The Bios set by the user

image

object

Image holds the details of the last image successfully provisioned to the host.

raid

object

The Raid set by the user

rootDeviceHints

object

The RootDevicehints set by the user

state

string

An indiciator for what the provisioner is doing with the host.

3.1.34. .status.provisioning.customDeploy

Description
Custom deploy procedure applied to the host.
Type
object
Required
  • method
PropertyTypeDescription

method

string

Custom deploy method name. This name is specific to the deploy ramdisk used. If you don’t have a custom deploy ramdisk, you shouldn’t use CustomDeploy.

3.1.35. .status.provisioning.firmware

Description
The Bios set by the user
Type
object
PropertyTypeDescription

simultaneousMultithreadingEnabled

boolean

Allows a single physical processor core to appear as several logical processors. This supports following options: true, false.

sriovEnabled

boolean

SR-IOV support enables a hypervisor to create virtual instances of a PCI-express device, potentially increasing performance. This supports following options: true, false.

virtualizationEnabled

boolean

Supports the virtualization of platform hardware. This supports following options: true, false.

3.1.36. .status.provisioning.image

Description
Image holds the details of the last image successfully provisioned to the host.
Type
object
Required
  • url
PropertyTypeDescription

checksum

string

Checksum is the checksum for the image.

checksumType

string

ChecksumType is the checksum algorithm for the image. e.g md5, sha256, sha512

format

string

DiskFormat contains the format of the image (raw, qcow2, …​). Needs to be set to raw for raw images streaming. Note live-iso means an iso referenced by the url will be live-booted and not deployed to disk, and in this case the checksum options are not required and if specified will be ignored.

url

string

URL is a location of an image to deploy.

3.1.37. .status.provisioning.raid

Description
The Raid set by the user
Type
object
PropertyTypeDescription

hardwareRAIDVolumes

``

The list of logical disks for hardware RAID, if rootDeviceHints isn’t used, first volume is root volume. You can set the value of this field to [] to clear all the hardware RAID configurations.

softwareRAIDVolumes

``

The list of logical disks for software RAID, if rootDeviceHints isn’t used, first volume is root volume. If HardwareRAIDVolumes is set this item will be invalid. The number of created Software RAID devices must be 1 or 2. If there is only one Software RAID device, it has to be a RAID-1. If there are two, the first one has to be a RAID-1, while the RAID level for the second one can be 0, 1, or 1+0. As the first RAID device will be the deployment device, enforcing a RAID-1 reduces the risk of ending up with a non-booting node in case of a disk failure. Software RAID will always be deleted.

3.1.38. .status.provisioning.rootDeviceHints

Description
The RootDevicehints set by the user
Type
object
PropertyTypeDescription

deviceName

string

A Linux device name like "/dev/vda". The hint must match the actual value exactly.

hctl

string

A SCSI bus address like 0:0:0:0. The hint must match the actual value exactly.

minSizeGigabytes

integer

The minimum size of the device in Gigabytes.

model

string

A vendor-specific device identifier. The hint can be a substring of the actual value.

rotational

boolean

True if the device should use spinning media, false otherwise.

serialNumber

string

Device serial number. The hint must match the actual value exactly.

vendor

string

The name of the vendor or manufacturer of the device. The hint can be a substring of the actual value.

wwn

string

Unique storage identifier. The hint must match the actual value exactly.

wwnVendorExtension

string

Unique vendor storage identifier. The hint must match the actual value exactly.

wwnWithExtension

string

Unique storage identifier with the vendor extension appended. The hint must match the actual value exactly.

3.1.39. .status.triedCredentials

Description
the last credentials we sent to the provisioning backend
Type
object
PropertyTypeDescription

credentials

object

SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace

credentialsVersion

string

 

3.1.40. .status.triedCredentials.credentials

Description
SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace
Type
object
PropertyTypeDescription

name

string

name is unique within a namespace to reference a secret resource.

namespace

string

namespace defines the space within which the secret name must be unique.

3.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/baremetalhosts

    • GET: list objects of kind BareMetalHost
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts

    • DELETE: delete collection of BareMetalHost
    • GET: list objects of kind BareMetalHost
    • POST: create a BareMetalHost
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}

    • DELETE: delete a BareMetalHost
    • GET: read the specified BareMetalHost
    • PATCH: partially update the specified BareMetalHost
    • PUT: replace the specified BareMetalHost
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}/status

    • GET: read status of the specified BareMetalHost
    • PATCH: partially update status of the specified BareMetalHost
    • PUT: replace status of the specified BareMetalHost

3.2.1. /apis/metal3.io/v1alpha1/baremetalhosts

Table 3.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind BareMetalHost
Table 3.2. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHostList schema

401 - Unauthorized

Empty

3.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts

Table 3.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 3.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of BareMetalHost
Table 3.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 3.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind BareMetalHost
Table 3.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 3.8. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHostList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a BareMetalHost
Table 3.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 3.10. Body parameters
ParameterTypeDescription

body

BareMetalHost schema

 
Table 3.11. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

201 - Created

BareMetalHost schema

202 - Accepted

BareMetalHost schema

401 - Unauthorized

Empty

3.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}

Table 3.12. Global path parameters
ParameterTypeDescription

name

string

name of the BareMetalHost

namespace

string

object name and auth scope, such as for teams and projects

Table 3.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a BareMetalHost
Table 3.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 3.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 3.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified BareMetalHost
Table 3.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 3.18. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified BareMetalHost
Table 3.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 3.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 3.21. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified BareMetalHost
Table 3.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 3.23. Body parameters
ParameterTypeDescription

body

BareMetalHost schema

 
Table 3.24. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

201 - Created

BareMetalHost schema

401 - Unauthorized

Empty

3.2.4. /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}/status

Table 3.25. Global path parameters
ParameterTypeDescription

name

string

name of the BareMetalHost

namespace

string

object name and auth scope, such as for teams and projects

Table 3.26. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified BareMetalHost
Table 3.27. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 3.28. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified BareMetalHost
Table 3.29. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 3.30. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 3.31. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified BareMetalHost
Table 3.32. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 3.33. Body parameters
ParameterTypeDescription

body

BareMetalHost schema

 
Table 3.34. HTTP responses
HTTP codeReponse body

200 - OK

BareMetalHost schema

201 - Created

BareMetalHost schema

401 - Unauthorized

Empty

Chapter 4. FirmwareSchema [metal3.io/v1alpha1]

Description
FirmwareSchema is the Schema for the firmwareschemas API
Type
object

4.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

FirmwareSchemaSpec defines the desired state of FirmwareSchema

4.1.1. .spec

Description
FirmwareSchemaSpec defines the desired state of FirmwareSchema
Type
object
Required
  • schema
PropertyTypeDescription

hardwareModel

string

The hardware model associated with this schema

hardwareVendor

string

The hardware vendor associated with this schema

schema

object

Map of firmware name to schema

schema{}

object

Additional data describing the firmware setting

4.1.2. .spec.schema

Description
Map of firmware name to schema
Type
object

4.1.3. .spec.schema{}

Description
Additional data describing the firmware setting
Type
object
PropertyTypeDescription

allowable_values

array (string)

The allowable value for an Enumeration type setting.

attribute_type

string

The type of setting.

lower_bound

integer

The lowest value for an Integer type setting.

max_length

integer

Maximum length for a String type setting.

min_length

integer

Minimum length for a String type setting.

read_only

boolean

Whether or not this setting is read only.

unique

boolean

Whether or not this setting’s value is unique to this node, e.g. a serial number.

upper_bound

integer

The highest value for an Integer type setting.

4.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/firmwareschemas

    • GET: list objects of kind FirmwareSchema
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/firmwareschemas

    • DELETE: delete collection of FirmwareSchema
    • GET: list objects of kind FirmwareSchema
    • POST: create a FirmwareSchema
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/firmwareschemas/{name}

    • DELETE: delete a FirmwareSchema
    • GET: read the specified FirmwareSchema
    • PATCH: partially update the specified FirmwareSchema
    • PUT: replace the specified FirmwareSchema

4.2.1. /apis/metal3.io/v1alpha1/firmwareschemas

Table 4.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind FirmwareSchema
Table 4.2. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchemaList schema

401 - Unauthorized

Empty

4.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/firmwareschemas

Table 4.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 4.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of FirmwareSchema
Table 4.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 4.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind FirmwareSchema
Table 4.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 4.8. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchemaList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a FirmwareSchema
Table 4.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 4.10. Body parameters
ParameterTypeDescription

body

FirmwareSchema schema

 
Table 4.11. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchema schema

201 - Created

FirmwareSchema schema

202 - Accepted

FirmwareSchema schema

401 - Unauthorized

Empty

4.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/firmwareschemas/{name}

Table 4.12. Global path parameters
ParameterTypeDescription

name

string

name of the FirmwareSchema

namespace

string

object name and auth scope, such as for teams and projects

Table 4.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a FirmwareSchema
Table 4.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 4.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 4.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified FirmwareSchema
Table 4.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 4.18. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchema schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified FirmwareSchema
Table 4.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 4.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 4.21. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchema schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified FirmwareSchema
Table 4.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 4.23. Body parameters
ParameterTypeDescription

body

FirmwareSchema schema

 
Table 4.24. HTTP responses
HTTP codeReponse body

200 - OK

FirmwareSchema schema

201 - Created

FirmwareSchema schema

401 - Unauthorized

Empty

Chapter 5. HardwareData [metal3.io/v1alpha1]

Description
HardwareData is the Schema for the hardwaredata API
Type
object

5.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

HardwareDataSpec defines the desired state of HardwareData

5.1.1. .spec

Description
HardwareDataSpec defines the desired state of HardwareData
Type
object
PropertyTypeDescription

hardware

object

The hardware discovered on the host during its inspection.

5.1.2. .spec.hardware

Description
The hardware discovered on the host during its inspection.
Type
object
PropertyTypeDescription

cpu

object

CPU describes one processor on the host.

firmware

object

Firmware describes the firmware on the host.

hostname

string

 

nics

array

 

nics[]

object

NIC describes one network interface on the host.

ramMebibytes

integer

 

storage

array

 

storage[]

object

Storage describes one storage device (disk, SSD, etc.) on the host.

systemVendor

object

HardwareSystemVendor stores details about the whole hardware system.

5.1.3. .spec.hardware.cpu

Description
CPU describes one processor on the host.
Type
object
PropertyTypeDescription

arch

string

 

clockMegahertz

number

ClockSpeed is a clock speed in MHz

count

integer

 

flags

array (string)

 

model

string

 

5.1.4. .spec.hardware.firmware

Description
Firmware describes the firmware on the host.
Type
object
PropertyTypeDescription

bios

object

The BIOS for this firmware

5.1.5. .spec.hardware.firmware.bios

Description
The BIOS for this firmware
Type
object
PropertyTypeDescription

date

string

The release/build date for this BIOS

vendor

string

The vendor name for this BIOS

version

string

The version of the BIOS

5.1.6. .spec.hardware.nics

Description
Type
array

5.1.7. .spec.hardware.nics[]

Description
NIC describes one network interface on the host.
Type
object
PropertyTypeDescription

ip

string

The IP address of the interface. This will be an IPv4 or IPv6 address if one is present. If both IPv4 and IPv6 addresses are present in a dual-stack environment, two nics will be output, one with each IP.

mac

string

The device MAC address

model

string

The vendor and product IDs of the NIC, e.g. "0x8086 0x1572"

name

string

The name of the network interface, e.g. "en0"

pxe

boolean

Whether the NIC is PXE Bootable

speedGbps

integer

The speed of the device in Gigabits per second

vlanId

integer

The untagged VLAN ID

vlans

array

The VLANs available

vlans[]

object

VLAN represents the name and ID of a VLAN

5.1.8. .spec.hardware.nics[].vlans

Description
The VLANs available
Type
array

5.1.9. .spec.hardware.nics[].vlans[]

Description
VLAN represents the name and ID of a VLAN
Type
object
PropertyTypeDescription

id

integer

VLANID is a 12-bit 802.1Q VLAN identifier

name

string

 

5.1.10. .spec.hardware.storage

Description
Type
array

5.1.11. .spec.hardware.storage[]

Description
Storage describes one storage device (disk, SSD, etc.) on the host.
Type
object
PropertyTypeDescription

hctl

string

The SCSI location of the device

model

string

Hardware model

name

string

The Linux device name of the disk, e.g. "/dev/sda". Note that this may not be stable across reboots.

rotational

boolean

Whether this disk represents rotational storage. This field is not recommended for usage, please prefer using 'Type' field instead, this field will be deprecated eventually.

serialNumber

string

The serial number of the device

sizeBytes

integer

The size of the disk in Bytes

type

string

Device type, one of: HDD, SSD, NVME.

vendor

string

The name of the vendor of the device

wwn

string

The WWN of the device

wwnVendorExtension

string

The WWN Vendor extension of the device

wwnWithExtension

string

The WWN with the extension

5.1.12. .spec.hardware.systemVendor

Description
HardwareSystemVendor stores details about the whole hardware system.
Type
object
PropertyTypeDescription

manufacturer

string

 

productName

string

 

serialNumber

string

 

5.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/hardwaredata

    • GET: list objects of kind HardwareData
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/hardwaredata

    • DELETE: delete collection of HardwareData
    • GET: list objects of kind HardwareData
    • POST: create a HardwareData
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/hardwaredata/{name}

    • DELETE: delete a HardwareData
    • GET: read the specified HardwareData
    • PATCH: partially update the specified HardwareData
    • PUT: replace the specified HardwareData

5.2.1. /apis/metal3.io/v1alpha1/hardwaredata

Table 5.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind HardwareData
Table 5.2. HTTP responses
HTTP codeReponse body

200 - OK

HardwareDataList schema

401 - Unauthorized

Empty

5.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/hardwaredata

Table 5.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 5.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of HardwareData
Table 5.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 5.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind HardwareData
Table 5.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 5.8. HTTP responses
HTTP codeReponse body

200 - OK

HardwareDataList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a HardwareData
Table 5.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 5.10. Body parameters
ParameterTypeDescription

body

HardwareData schema

 
Table 5.11. HTTP responses
HTTP codeReponse body

200 - OK

HardwareData schema

201 - Created

HardwareData schema

202 - Accepted

HardwareData schema

401 - Unauthorized

Empty

5.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/hardwaredata/{name}

Table 5.12. Global path parameters
ParameterTypeDescription

name

string

name of the HardwareData

namespace

string

object name and auth scope, such as for teams and projects

Table 5.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a HardwareData
Table 5.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 5.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 5.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified HardwareData
Table 5.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 5.18. HTTP responses
HTTP codeReponse body

200 - OK

HardwareData schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified HardwareData
Table 5.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 5.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 5.21. HTTP responses
HTTP codeReponse body

200 - OK

HardwareData schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified HardwareData
Table 5.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 5.23. Body parameters
ParameterTypeDescription

body

HardwareData schema

 
Table 5.24. HTTP responses
HTTP codeReponse body

200 - OK

HardwareData schema

201 - Created

HardwareData schema

401 - Unauthorized

Empty

Chapter 6. HostFirmwareSettings [metal3.io/v1alpha1]

Description
HostFirmwareSettings is the Schema for the hostfirmwaresettings API
Type
object

6.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

HostFirmwareSettingsSpec defines the desired state of HostFirmwareSettings

status

object

HostFirmwareSettingsStatus defines the observed state of HostFirmwareSettings

6.1.1. .spec

Description
HostFirmwareSettingsSpec defines the desired state of HostFirmwareSettings
Type
object
Required
  • settings
PropertyTypeDescription

settings

integer-or-string

Settings are the desired firmware settings stored as name/value pairs.

6.1.2. .status

Description
HostFirmwareSettingsStatus defines the observed state of HostFirmwareSettings
Type
object
Required
  • settings
PropertyTypeDescription

conditions

array

Track whether settings stored in the spec are valid based on the schema

conditions[]

object

Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo’s current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions" // other fields }

lastUpdated

string

Time that the status was last updated

schema

object

FirmwareSchema is a reference to the Schema used to describe each FirmwareSetting. By default, this will be a Schema in the same Namespace as the settings but it can be overwritten in the Spec

settings

object (string)

Settings are the firmware settings stored as name/value pairs

6.1.3. .status.conditions

Description
Track whether settings stored in the spec are valid based on the schema
Type
array

6.1.4. .status.conditions[]

Description
Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo’s current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions" // other fields }
Type
object
Required
  • lastTransitionTime
  • message
  • reason
  • status
  • type
PropertyTypeDescription

lastTransitionTime

string

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.

message

string

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

observedGeneration

integer

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.

reason

string

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.

status

string

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

type

string

type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)

6.1.5. .status.schema

Description
FirmwareSchema is a reference to the Schema used to describe each FirmwareSetting. By default, this will be a Schema in the same Namespace as the settings but it can be overwritten in the Spec
Type
object
Required
  • name
  • namespace
PropertyTypeDescription

name

string

name is the reference to the schema.

namespace

string

namespace is the namespace of the where the schema is stored.

6.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/hostfirmwaresettings

    • GET: list objects of kind HostFirmwareSettings
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings

    • DELETE: delete collection of HostFirmwareSettings
    • GET: list objects of kind HostFirmwareSettings
    • POST: create HostFirmwareSettings
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings/{name}

    • DELETE: delete HostFirmwareSettings
    • GET: read the specified HostFirmwareSettings
    • PATCH: partially update the specified HostFirmwareSettings
    • PUT: replace the specified HostFirmwareSettings
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings/{name}/status

    • GET: read status of the specified HostFirmwareSettings
    • PATCH: partially update status of the specified HostFirmwareSettings
    • PUT: replace status of the specified HostFirmwareSettings

6.2.1. /apis/metal3.io/v1alpha1/hostfirmwaresettings

Table 6.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind HostFirmwareSettings
Table 6.2. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettingsList schema

401 - Unauthorized

Empty

6.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings

Table 6.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 6.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of HostFirmwareSettings
Table 6.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 6.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind HostFirmwareSettings
Table 6.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 6.8. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettingsList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create HostFirmwareSettings
Table 6.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 6.10. Body parameters
ParameterTypeDescription

body

HostFirmwareSettings schema

 
Table 6.11. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

201 - Created

HostFirmwareSettings schema

202 - Accepted

HostFirmwareSettings schema

401 - Unauthorized

Empty

6.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings/{name}

Table 6.12. Global path parameters
ParameterTypeDescription

name

string

name of the HostFirmwareSettings

namespace

string

object name and auth scope, such as for teams and projects

Table 6.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete HostFirmwareSettings
Table 6.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 6.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 6.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified HostFirmwareSettings
Table 6.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 6.18. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified HostFirmwareSettings
Table 6.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 6.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 6.21. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified HostFirmwareSettings
Table 6.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 6.23. Body parameters
ParameterTypeDescription

body

HostFirmwareSettings schema

 
Table 6.24. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

201 - Created

HostFirmwareSettings schema

401 - Unauthorized

Empty

6.2.4. /apis/metal3.io/v1alpha1/namespaces/{namespace}/hostfirmwaresettings/{name}/status

Table 6.25. Global path parameters
ParameterTypeDescription

name

string

name of the HostFirmwareSettings

namespace

string

object name and auth scope, such as for teams and projects

Table 6.26. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified HostFirmwareSettings
Table 6.27. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 6.28. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified HostFirmwareSettings
Table 6.29. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 6.30. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 6.31. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified HostFirmwareSettings
Table 6.32. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 6.33. Body parameters
ParameterTypeDescription

body

HostFirmwareSettings schema

 
Table 6.34. HTTP responses
HTTP codeReponse body

200 - OK

HostFirmwareSettings schema

201 - Created

HostFirmwareSettings schema

401 - Unauthorized

Empty

Chapter 7. PreprovisioningImage [metal3.io/v1alpha1]

Description
PreprovisioningImage is the Schema for the preprovisioningimages API
Type
object

7.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

PreprovisioningImageSpec defines the desired state of PreprovisioningImage

status

object

PreprovisioningImageStatus defines the observed state of PreprovisioningImage

7.1.1. .spec

Description
PreprovisioningImageSpec defines the desired state of PreprovisioningImage
Type
object
PropertyTypeDescription

acceptFormats

array (string)

acceptFormats is a list of acceptable image formats.

architecture

string

architecture is the processor architecture for which to build the image.

networkDataName

string

networkDataName is the name of a Secret in the local namespace that contains network data to build in to the image.

7.1.2. .status

Description
PreprovisioningImageStatus defines the observed state of PreprovisioningImage
Type
object
PropertyTypeDescription

architecture

string

architecture is the processor architecture for which the image is built

conditions

array

conditions describe the state of the built image

conditions[]

object

Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo’s current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions" // other fields }

extraKernelParams

string

extraKernelParams is a string with extra parameters to pass to the kernel when booting the image over network. Only makes sense for initrd images.

format

string

format is the type of image that is available at the download url: either iso or initrd.

imageUrl

string

imageUrl is the URL from which the built image can be downloaded.

kernelUrl

string

kernelUrl is the URL from which the kernel of the image can be downloaded. Only makes sense for initrd images.

networkData

object

networkData is a reference to the version of the Secret containing the network data used to build the image.

7.1.3. .status.conditions

Description
conditions describe the state of the built image
Type
array

7.1.4. .status.conditions[]

Description
Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo’s current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions" // other fields }
Type
object
Required
  • lastTransitionTime
  • message
  • reason
  • status
  • type
PropertyTypeDescription

lastTransitionTime

string

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.

message

string

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

observedGeneration

integer

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.

reason

string

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.

status

string

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

type

string

type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)

7.1.5. .status.networkData

Description
networkData is a reference to the version of the Secret containing the network data used to build the image.
Type
object
PropertyTypeDescription

name

string

 

version

string

 

7.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/preprovisioningimages

    • GET: list objects of kind PreprovisioningImage
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages

    • DELETE: delete collection of PreprovisioningImage
    • GET: list objects of kind PreprovisioningImage
    • POST: create a PreprovisioningImage
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages/{name}

    • DELETE: delete a PreprovisioningImage
    • GET: read the specified PreprovisioningImage
    • PATCH: partially update the specified PreprovisioningImage
    • PUT: replace the specified PreprovisioningImage
  • /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages/{name}/status

    • GET: read status of the specified PreprovisioningImage
    • PATCH: partially update status of the specified PreprovisioningImage
    • PUT: replace status of the specified PreprovisioningImage

7.2.1. /apis/metal3.io/v1alpha1/preprovisioningimages

Table 7.1. Global query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

pretty

string

If 'true', then the output is pretty printed.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

HTTP method
GET
Description
list objects of kind PreprovisioningImage
Table 7.2. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImageList schema

401 - Unauthorized

Empty

7.2.2. /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages

Table 7.3. Global path parameters
ParameterTypeDescription

namespace

string

object name and auth scope, such as for teams and projects

Table 7.4. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of PreprovisioningImage
Table 7.5. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 7.6. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind PreprovisioningImage
Table 7.7. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 7.8. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImageList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a PreprovisioningImage
Table 7.9. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 7.10. Body parameters
ParameterTypeDescription

body

PreprovisioningImage schema

 
Table 7.11. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

201 - Created

PreprovisioningImage schema

202 - Accepted

PreprovisioningImage schema

401 - Unauthorized

Empty

7.2.3. /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages/{name}

Table 7.12. Global path parameters
ParameterTypeDescription

name

string

name of the PreprovisioningImage

namespace

string

object name and auth scope, such as for teams and projects

Table 7.13. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a PreprovisioningImage
Table 7.14. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 7.15. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 7.16. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified PreprovisioningImage
Table 7.17. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 7.18. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified PreprovisioningImage
Table 7.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 7.20. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 7.21. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified PreprovisioningImage
Table 7.22. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 7.23. Body parameters
ParameterTypeDescription

body

PreprovisioningImage schema

 
Table 7.24. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

201 - Created

PreprovisioningImage schema

401 - Unauthorized

Empty

7.2.4. /apis/metal3.io/v1alpha1/namespaces/{namespace}/preprovisioningimages/{name}/status

Table 7.25. Global path parameters
ParameterTypeDescription

name

string

name of the PreprovisioningImage

namespace

string

object name and auth scope, such as for teams and projects

Table 7.26. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified PreprovisioningImage
Table 7.27. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 7.28. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified PreprovisioningImage
Table 7.29. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 7.30. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 7.31. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified PreprovisioningImage
Table 7.32. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 7.33. Body parameters
ParameterTypeDescription

body

PreprovisioningImage schema

 
Table 7.34. HTTP responses
HTTP codeReponse body

200 - OK

PreprovisioningImage schema

201 - Created

PreprovisioningImage schema

401 - Unauthorized

Empty

Chapter 8. Provisioning [metal3.io/v1alpha1]

Description
Provisioning contains configuration used by the Provisioning service (Ironic) to provision baremetal hosts. Provisioning is created by the OpenShift installer using admin or user provided information about the provisioning network and the NIC on the server that can be used to PXE boot it. This CR is a singleton, created by the installer and currently only consumed by the cluster-baremetal-operator to bring up and update containers in a metal3 cluster.
Type
object

8.1. Specification

PropertyTypeDescription

apiVersion

string

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

kind

string

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

metadata

ObjectMeta

Standard object’s metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

spec

object

ProvisioningSpec defines the desired state of Provisioning

status

object

ProvisioningStatus defines the observed state of Provisioning

8.1.1. .spec

Description
ProvisioningSpec defines the desired state of Provisioning
Type
object
PropertyTypeDescription

bootIsoSource

string

BootIsoSource provides a way to set the location where the iso image to boot the nodes will be served from. By default the boot iso image is cached locally and served from the Provisioning service (Ironic) nodes using an auxiliary httpd server. If the boot iso image is already served by an httpd server, setting this option to http allows to directly provide the image from there; in this case, the network (either internal or external) where the httpd server that hosts the boot iso is needs to be accessible by the metal3 pod.

disableVirtualMediaTLS

boolean

DisableVirtualMediaTLS turns off TLS on the virtual media server, which may be required for hardware that cannot accept HTTPS links.

preProvisioningOSDownloadURLs

object

PreprovisioningOSDownloadURLs is set of CoreOS Live URLs that would be necessary to provision a worker either using virtual media or PXE.

provisioningDHCPExternal

boolean

ProvisioningDHCPExternal indicates whether the DHCP server for IP addresses in the provisioning DHCP range is present within the metal3 cluster or external to it. This field is being deprecated in favor of provisioningNetwork.

provisioningDHCPRange

string

ProvisioningDHCPRange needs to be interpreted along with ProvisioningDHCPExternal. If the value of provisioningDHCPExternal is set to False, then ProvisioningDHCPRange represents the range of IP addresses that the DHCP server running within the metal3 cluster can use while provisioning baremetal servers. If the value of ProvisioningDHCPExternal is set to True, then the value of ProvisioningDHCPRange will be ignored. When the value of ProvisioningDHCPExternal is set to False, indicating an internal DHCP server and the value of ProvisioningDHCPRange is not set, then the DHCP range is taken to be the default range which goes from .10 to .100 of the ProvisioningNetworkCIDR. This is the only value in all of the Provisioning configuration that can be changed after the installer has created the CR. This value needs to be two comma sererated IP addresses within the ProvisioningNetworkCIDR where the 1st address represents the start of the range and the 2nd address represents the last usable address in the range.

provisioningIP

string

ProvisioningIP is the IP address assigned to the provisioningInterface of the baremetal server. This IP address should be within the provisioning subnet, and outside of the DHCP range.

provisioningInterface

string

ProvisioningInterface is the name of the network interface on a baremetal server to the provisioning network. It can have values like eth1 or ens3.

provisioningMacAddresses

array (string)

ProvisioningMacAddresses is a list of mac addresses of network interfaces on a baremetal server to the provisioning network. Use this instead of ProvisioningInterface to allow interfaces of different names. If not provided it will be populated by the BMH.Spec.BootMacAddress of each master.

provisioningNetwork

string

ProvisioningNetwork provides a way to indicate the state of the underlying network configuration for the provisioning network. This field can have one of the following values - Managed- when the provisioning network is completely managed by the Baremetal IPI solution. Unmanaged- when the provsioning network is present and used but the user is responsible for managing DHCP. Virtual media provisioning is recommended but PXE is still available if required. Disabled- when the provisioning network is fully disabled. User can bring up the baremetal cluster using virtual media or assisted installation. If using metal3 for power management, BMCs must be accessible from the machine networks. User should provide two IPs on the external network that would be used for provisioning services.

provisioningNetworkCIDR

string

ProvisioningNetworkCIDR is the network on which the baremetal nodes are provisioned. The provisioningIP and the IPs in the dhcpRange all come from within this network. When using IPv6 and in a network managed by the Baremetal IPI solution this cannot be a network larger than a /64.

provisioningOSDownloadURL

string

ProvisioningOSDownloadURL is the location from which the OS Image used to boot baremetal host machines can be downloaded by the metal3 cluster.

virtualMediaViaExternalNetwork

boolean

VirtualMediaViaExternalNetwork flag when set to "true" allows for workers to boot via Virtual Media and contact metal3 over the External Network. When the flag is set to "false" (which is the default), virtual media deployments can still happen based on the configuration specified in the ProvisioningNetwork i.e when in Disabled mode, over the External Network and over Provisioning Network when in Managed mode. PXE deployments will always use the Provisioning Network and will not be affected by this flag.

watchAllNamespaces

boolean

WatchAllNamespaces provides a way to explicitly allow use of this Provisioning configuration across all Namespaces. It is an optional configuration which defaults to false and in that state will be used to provision baremetal hosts in only the openshift-machine-api namespace. When set to true, this provisioning configuration would be used for baremetal hosts across all namespaces.

8.1.2. .spec.preProvisioningOSDownloadURLs

Description
PreprovisioningOSDownloadURLs is set of CoreOS Live URLs that would be necessary to provision a worker either using virtual media or PXE.
Type
object
PropertyTypeDescription

initramfsURL

string

InitramfsURL Image URL to be used for PXE deployments

isoURL

string

IsoURL Image URL to be used for Live ISO deployments

kernelURL

string

KernelURL is an Image URL to be used for PXE deployments

rootfsURL

string

RootfsURL Image URL to be used for PXE deployments

8.1.3. .status

Description
ProvisioningStatus defines the observed state of Provisioning
Type
object
PropertyTypeDescription

conditions

array

conditions is a list of conditions and their status

conditions[]

object

OperatorCondition is just the standard condition fields.

generations

array

generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction.

generations[]

object

GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made.

observedGeneration

integer

observedGeneration is the last generation change you’ve dealt with

readyReplicas

integer

readyReplicas indicates how many replicas are ready and at the desired state

version

string

version is the level this availability applies to

8.1.4. .status.conditions

Description
conditions is a list of conditions and their status
Type
array

8.1.5. .status.conditions[]

Description
OperatorCondition is just the standard condition fields.
Type
object
PropertyTypeDescription

lastTransitionTime

string

 

message

string

 

reason

string

 

status

string

 

type

string

 

8.1.6. .status.generations

Description
generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction.
Type
array

8.1.7. .status.generations[]

Description
GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made.
Type
object
PropertyTypeDescription

group

string

group is the group of the thing you’re tracking

hash

string

hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps

lastGeneration

integer

lastGeneration is the last generation of the workload controller involved

name

string

name is the name of the thing you’re tracking

namespace

string

namespace is where the thing you’re tracking is

resource

string

resource is the resource type of the thing you’re tracking

8.2. API endpoints

The following API endpoints are available:

  • /apis/metal3.io/v1alpha1/provisionings

    • DELETE: delete collection of Provisioning
    • GET: list objects of kind Provisioning
    • POST: create a Provisioning
  • /apis/metal3.io/v1alpha1/provisionings/{name}

    • DELETE: delete a Provisioning
    • GET: read the specified Provisioning
    • PATCH: partially update the specified Provisioning
    • PUT: replace the specified Provisioning
  • /apis/metal3.io/v1alpha1/provisionings/{name}/status

    • GET: read status of the specified Provisioning
    • PATCH: partially update status of the specified Provisioning
    • PUT: replace status of the specified Provisioning

8.2.1. /apis/metal3.io/v1alpha1/provisionings

Table 8.1. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete collection of Provisioning
Table 8.2. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 8.3. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
list objects of kind Provisioning
Table 8.4. Query parameters
ParameterTypeDescription

allowWatchBookmarks

boolean

allowWatchBookmarks requests watch events with type "BOOKMARK". Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server’s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored.

continue

string

The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the "next key".

This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications.

fieldSelector

string

A selector to restrict the list of returned objects by their fields. Defaults to everything.

labelSelector

string

A selector to restrict the list of returned objects by their labels. Defaults to everything.

limit

integer

limit is a maximum number of responses to return for a list call. If more items exist, the server will set the continue field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true.

The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned.

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

resourceVersionMatch

string

resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

timeoutSeconds

integer

Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity.

watch

boolean

Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion.

Table 8.5. HTTP responses
HTTP codeReponse body

200 - OK

ProvisioningList schema

401 - Unauthorized

Empty

HTTP method
POST
Description
create a Provisioning
Table 8.6. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 8.7. Body parameters
ParameterTypeDescription

body

Provisioning schema

 
Table 8.8. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

201 - Created

Provisioning schema

202 - Accepted

Provisioning schema

401 - Unauthorized

Empty

8.2.2. /apis/metal3.io/v1alpha1/provisionings/{name}

Table 8.9. Global path parameters
ParameterTypeDescription

name

string

name of the Provisioning

Table 8.10. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
DELETE
Description
delete a Provisioning
Table 8.11. Query parameters
ParameterTypeDescription

dryRun

string

When 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

gracePeriodSeconds

integer

The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately.

orphanDependents

boolean

Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object’s finalizers list. Either this field or PropagationPolicy may be set, but not both.

propagationPolicy

string

Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground.

Table 8.12. Body parameters
ParameterTypeDescription

body

DeleteOptions schema

 
Table 8.13. HTTP responses
HTTP codeReponse body

200 - OK

Status schema

202 - Accepted

Status schema

401 - Unauthorized

Empty

HTTP method
GET
Description
read the specified Provisioning
Table 8.14. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 8.15. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update the specified Provisioning
Table 8.16. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 8.17. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 8.18. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace the specified Provisioning
Table 8.19. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 8.20. Body parameters
ParameterTypeDescription

body

Provisioning schema

 
Table 8.21. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

201 - Created

Provisioning schema

401 - Unauthorized

Empty

8.2.3. /apis/metal3.io/v1alpha1/provisionings/{name}/status

Table 8.22. Global path parameters
ParameterTypeDescription

name

string

name of the Provisioning

Table 8.23. Global query parameters
ParameterTypeDescription

pretty

string

If 'true', then the output is pretty printed.

HTTP method
GET
Description
read status of the specified Provisioning
Table 8.24. Query parameters
ParameterTypeDescription

resourceVersion

string

resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details.

Defaults to unset

Table 8.25. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

401 - Unauthorized

Empty

HTTP method
PATCH
Description
partially update status of the specified Provisioning
Table 8.26. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 8.27. Body parameters
ParameterTypeDescription

body

Patch schema

 
Table 8.28. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

401 - Unauthorized

Empty

HTTP method
PUT
Description
replace status of the specified Provisioning
Table 8.29. Query parameters
ParameterTypeDescription

dryRun

string

When 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

fieldManager

string

fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint.

fieldValidation

string

fieldValidation instructs the server on how to handle objects in the request (POST/PUT/PATCH) containing unknown or duplicate fields, provided that the ServerSideFieldValidation feature gate is also enabled. 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 and is the default behavior when the ServerSideFieldValidation feature gate is disabled. - 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 when the ServerSideFieldValidation feature gate is enabled. - 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.

Table 8.30. Body parameters
ParameterTypeDescription

body

Provisioning schema

 
Table 8.31. HTTP responses
HTTP codeReponse body

200 - OK

Provisioning schema

201 - Created

Provisioning schema

401 - Unauthorized

Empty

Legal Notice

Copyright © 2024 Red Hat, Inc.

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.