Virtual Machine Specs
Katapult provides a powerful way of creating blueprints to describe exactly how you want new virtual machines to be deployed. We call these Virtual Machine Specs. They are, currently, XML documents which contain all the configuration required to create ,install and start a new virtual machine. Once you have created the build spec, you can simply send the XML off to the API and it will be created.
What follows describes the build spec and how you can use it. You don't have to provide everything shown here. You will be provided with useful validation errors if you submit an invalid or partial spec document.
<VirtualMachineSpec>
<!---
These options are used to define the location of the virtual machine.
A data center or zone must be provided. Only one option.
-->
<DataCenter by="id|name|permalink" />
<Zone by="id|permalink" />
<!---
These options allow you to choose the hostname for the virtual machine.
You can specify your own name or ask for a randomly generated name from
our hostname generator.
-->
<Hostname>
<Hostname>custom-name</Hostname>
<Hostname type="random" />
</Hostname>
<!---
This options allow you to choose the name for the virtual machine as shown
in the Katapult Console.
-->
<Name />
<!---
This option allows you to choose a description for the virtual machine.
-->
<Description />
<!---
This option allows you to choose which virtual machine group to assign this
new virtual machine to.
-->
<Group by="id|name" />
<!---
This option allows you to specify tags to assign to the new virtual machine.
-->
<Tags>
<Tag />
</Tags>
<!---
These options define the resources that will be provided for the
virtual machine. Memory and CPUCores can only be used by organization
that permit flexible resources.
A package or flexible resources must be provided.
-->
<Resources>
<Package by="id|permalink" />
<Memory />
<CPUCores />
</Resources>
<!---
This is the template that your main system disk will be built from.
You do not need to choose one of these.
The version is optional, if not specified the latest stable version
of the template will be used.
The options will vary depending on the template. You can specify
as many options as is required.
-->
<DiskTemplate>
<DiskTemplate by="id|permalink" />
<Version />
<Option key="something" />
<Option key="something_else" />
</DiskTemplate>
<!---
This option allows you to specify an ISO that should be attached to the
virtual machine on creation. The ID of the ISO should be provided.
-->
<ISO />
<!---
These are the system disks that will be created for your virtual machine.
If you don't specify any system disks, your initial system disk will be
determined based on the package selected under Resources. If you didn't
use a package, no system disks will be created.
-->
<SystemDisks>
<Disk>
<Name />
<Size />
<Speed />
<FileSystemType />
<IOProfile by="id|permalink" />
<BackupPolicy>
<Retention />
<Schedule>
<Interval />
<Frequency />
<Time />
</Schedule>
</BackupPolicy>
</Disk>
</SystemDisks>
<!---
These are shared disks that you wish to be attached to your new virtual
machine.
-->
<SharedDisks>
<Disk by="id" />
</SharedDisks>
<!---
These options allow you to specify any backup policies that you wish to be
created.
-->
<BackupPolicies>
<BackupPolicy>
<Retention />
<Schedule>
<Interval />
<Frequency />
<Time />
</Schedule>
</BackupPolicy>
</BackupPolicies>
<!---
These are the network interfaces that will be attached to your virtual machine.
You must specify at least one network interface if you want any network
connectivity.
You can choose to attach your interface to a public network (Network) or a
virtual network within your organization.
The speed profile determines the throughput that you can achieve using your
network interface. This can be left blank to use the default.
IP address allocations allow you to allocate new or existing IPs to this
virtual machine.
-->
<NetworkInterfaces>
<NetworkInterface>
<Network by="id|permalink|data_center|data_center:permalink" />
<VirtualNetwork by="id" />
<SpeedProfile by="id|permalink" />w
<!---
To allocate a new IP address to this network interface, you can add a
new allocation for the appropriate version.
The subnet is used if you know which subnet you wish to allocate from.
This may not always be possible if there are no addresses available
in the selected range.
-->
<IPAddressAllocation type="new">
<Version>4|6</Version>
<Subnet by="id|address" />
</IPAddressAllocation>
<!---
To allocate an existing IP address to this network interface, you can
add an existing allocation.
-->
<IPAddressAllocation type="existing">
<IPAddress by="id|address" />
</IPAddressAllocation>
</NetworkInterface>
</NetworkInterfaces>
<!---
These are security groups that are assigned directly to this virtual machine.
-->
<SecurityGroups>
<SecurityGroup by="id" />
</SecurityGroups>
<!---
These options allow you to define how SSH access is managed for this virtual
machine.
This is optional. If you leave this out of the spec, then all authorized keys
management will be disabled for this virtual machine.
If you wish to enable continuous management of SSH keys (the process by which
Katapult will attempt to keep your authorized_keys file up to date), you can
do so by enabling it. If not specified, continuous management will not be
enabled.
-->
<AuthorizedKeys continuous_management="yes|no">
<!---
This users section allows you to list which users SSH keys should be added
to this virtual machine. You can specify that all users should be added or
provide a list. Any user specified must already belong to the organization.
-->
<Users all="yes" />
<Users>
<User by="id|email_address" />
</User>
<!---
This SSH keys section allows you to list which organization-level SSH keys
should be added to this virtual machine. You can specify that all keys should
added or provide a list.
-->
<SSHKeys all="yes" />
<SSHKeys>
<SSHKey by="id" />
</SSHKeys>
</AuthorizedKeys>
</VirtualMachineSpec>
An example
This is an example of a build spec containing data.
<VirtualMachineSpec>
<!--- Create the virtual machine in the us-west-1 DC -->
<DataCenter by="permlink">us-west-1</DataCenter>
<!--- Use a random hostname -->
<Hostname>
<Hostname type="random" />
</Hostname>
<!--- Assign to the 'Web Servers' group -->
<Group by="name">Web Servers</Group>
<!--- Assign a few tags -->
<Tags>
<Tag>web-server</Tag>
<Tag>firewall:http</Tag>
</Tags>
<!--- Specify the package to use -->
<Resources>
<Package by="permalink">ROCK-3</Package>
</Resources>
<!--- Use the latest version of the Ubuntu 20.04 template -->
<DiskTemplate>
<DiskTemplate by="permalink">universal/ubuntu-20-04</DiskTemplate>
</DiskTemplate>
<!--- Add a 100GB system disk -->
<SystemDisks>
<Disk>
<Name>System Disk</Name>
<Size>100</Size>
</Disk>
</SystemDisks>
<!--- Configure backups to happen every day at 13:00 -->
<BackupPolicies>
<BackupPolicy>
<Retention>7</Retention>
<Schedule>
<Interval>daily</Interval>
<Frequency>1</Interval>
<Time>13</Time>
</Schedule>
</BackupPolicy>
</BackupPolicies>
<!--- Attach to the default network in the DC and attach new IPs-->
<NetworkInterfaces>
<NetworkInterface>
<Network by="data_center:permalink">us-west-1</Network>
<IPAddressAllocation type="new">
<Version>4</Version>
</IPAddressAllocation>
<IPAddressAllocation type="new">
<Version>6</Version>
</IPAddressAllocation>
</NetworkInterface>
</NetworkInterfaces>
<!--- Add all user & org-level SSH keys to this new VM -->
<AuthorizedKeys>
<Users all="yes" />
<SSHKeys all="yes" />
</AuthorizedKeys>
</VirtualMachineSpec>