instance
Path Parameters
Name or ID of the instance
Query Parameters
Name or ID of the project
Request Body
Parameters of an Instance that can be reconfigured after creation.
The auto-restart policy for this instance.
This policy determines whether the instance should be automatically restarted by the control plane on failure. If this is null, any explicitly configured auto-restart policy will be unset, and the control plane will select the default policy when determining whether the instance can be automatically restarted.
Currently, the global default auto-restart policy is "best-effort", so instances with null auto-restart policies will be automatically restarted. However, in the future, the default policy may be configurable through other mechanisms, such as on a per-project basis. In that case, any configured default policy will be used if this is null.
A policy determining when an instance should be automatically restarted by the control plane.
The disk the instance is configured to boot from.
Setting a boot disk is optional but recommended to ensure predictable boot behavior. The boot disk can be set during instance creation or later if the instance is stopped. The boot disk counts against the disk attachment limit.
An instance that does not have a boot disk set will use the boot options specified in its UEFI settings, which are controlled by both the instance's UEFI firmware and the guest operating system. Boot options can change as disks are attached and detached, which may result in an instance that only boots to the EFI shell until a boot disk is set.
The CPU platform to be used for this instance. If this is null, the instance requires no particular CPU platform; when it is started the instance will have the most general CPU platform supported by the sled it is initially placed on.
A required CPU platform for an instance.
When an instance specifies a required CPU platform:
- The system may expose (to the VM) new CPU features that are only present on that platform (or on newer platforms of the same lineage that also support those features). - The instance must run on hosts that have CPUs that support all the features of the supplied platform.
That is, the instance is restricted to hosts that have the CPUs which support all features of the required platform, but in exchange the CPU features exposed by the platform are available for the guest to use. Note that this may prevent an instance from starting (if the hosts that could run it are full but there is capacity on other incompatible hosts).
If an instance does not specify a required CPU platform, then when it starts, the control plane selects a host for the instance and then supplies the guest with the "minimum" CPU platform supported by that host. This maximizes the number of hosts that can run the VM if it later needs to migrate to another host.
In all cases, the CPU features presented by a given CPU platform are a subset of what the corresponding hardware may actually support; features which cannot be used from a virtual environment or do not have full hypervisor support may be masked off. See RFD 314 for specific CPU features in a CPU platform.
The amount of RAM (in bytes) to be allocated to the instance
Byte count to express memory or storage capacity.
The number of vCPUs to be allocated to the instance
The number of CPUs in an Instance
Responses
The time at which the auto-restart cooldown period for this instance completes, permitting it to be automatically restarted again. If the instance enters the Failed state, it will not be restarted until after this time.
If this is not present, then either the instance has never been automatically restarted, or the cooldown period has already expired, allowing the instance to be restarted immediately if it fails.
true if this instance's auto-restart policy will permit the control plane to automatically restart it if it enters the Failed state.
The auto-restart policy configured for this instance, or null if no explicit policy has been configured.
This policy determines whether the instance should be automatically restarted by the control plane on failure. If this is null, the control plane will use the default policy when determining whether or not to automatically restart this instance, which may or may not allow it to be restarted. The value of the auto_restart_enabled field indicates whether the instance will be auto-restarted, based on its current policy or the default if it has no configured policy.
A policy determining when an instance should be automatically restarted by the control plane.
the ID of the disk used to boot this Instance, if a specific one is assigned.
The CPU platform for this instance. If this is null, the instance requires no particular CPU platform.
A required CPU platform for an instance.
When an instance specifies a required CPU platform:
- The system may expose (to the VM) new CPU features that are only present on that platform (or on newer platforms of the same lineage that also support those features). - The instance must run on hosts that have CPUs that support all the features of the supplied platform.
That is, the instance is restricted to hosts that have the CPUs which support all features of the required platform, but in exchange the CPU features exposed by the platform are available for the guest to use. Note that this may prevent an instance from starting (if the hosts that could run it are full but there is capacity on other incompatible hosts).
If an instance does not specify a required CPU platform, then when it starts, the control plane selects a host for the instance and then supplies the guest with the "minimum" CPU platform supported by that host. This maximizes the number of hosts that can run the VM if it later needs to migrate to another host.
In all cases, the CPU features presented by a given CPU platform are a subset of what the corresponding hardware may actually support; features which cannot be used from a virtual environment or do not have full hypervisor support may be masked off. See RFD 314 for specific CPU features in a CPU platform.
human-readable free-form text about a resource
RFC1035-compliant hostname for the Instance.
unique, immutable, system-controlled identifier for each resource
memory allocated for this Instance
Byte count to express memory or storage capacity.
unique, mutable, user-controlled identifier for each resource
Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.
number of CPUs allocated for this Instance
The number of CPUs in an Instance
id for the project containing this Instance
Running state of an Instance (primarily: booted or stopped)
This typically reflects whether it's starting, running, stopping, or stopped, but also includes states related to the Instance's lifecycle
timestamp when this resource was created
The timestamp of the most recent time this instance was automatically restarted by the control plane.
If this is not present, then this instance has not been automatically restarted.
timestamp when this resource was last modified