Resource Types¶
The API supports various resource types. Some of them can be queried and updated, others can only be queried.
Each type has a set of identifying keys which correspond to the RDBMS „primary key“ concept. When updating or deleting a record you need to specify at least the primary key to ensure unambiguity.
Project¶
Projects are the foundational building block for organizing resources in the Flying Circus platform: they group together which machines belong to the same project, which users have permissions for them, what rules apply for maintenance, and more.
Bemerkung
In technical terms a project is just a thing grouping resource, hence we used to call projects „resource groups“. The API still uses the old term, and will continue to do so to ensure compatibility.
In addition to the project that your key is associated with, you can create new child projects.
The structure of a project record looks like this:
{'__type__': 'resourcegroup',
'customer_no': '',
'in_maintenance': False,
'maintenance_end': 5,
'maintenance_start': 22,
'name': 'services',
'notification_leadtime': 12,
'parent': '',
'production': True,
'technical_contacts': ['admin@flyingcircus.io'],
'timezone': 'Europe/Berlin'}]
- name
read-only, primary key, filterable
The name of the project. Needs to be a valid Linux group name.
- customer_no
readonly, filterable, default: inherited or pre-set
The customer number of the customer who is charged for resources that belong to this project.
- in_maintenance
bool, default:
False
True, if the project is in maintenance mode. This prevents alerting FC staff.
- maintenance_start
filterable, default:
22
Hour in the day when scheduled maintenance windows may start.
- maintenance_end
filterable, default:
5
Hour in the day when scheduled maintenance windows should end.
- notification_leadtime
filterable, default:
12
Number of hours that technical contacts should be informed upfront about maintenance windows.
- timezone
filterable, default:
'Europe/Berlin'
The name of a timezone that VMs should be running in and that any time specifications (like maintenance windows) should be relative to.
- parent
default:
''
Name of the parent project if this project has one.
If you create new projects, this will be set to the name of the project that your API key belongs to. Alternatively you can set the parent to any project that your API key has access to.
(Making new top-level projects does not make much sense as they would become inaccessible to your API key anyway.)
- production
filterable, default:
True
Indicates whether the services of this project are considered for production use (in contrast to testing, staging, dev, or similar non-production instances).
- technical_contacts
default:
[]
A list of strings specifying email addresses that should be notified of technical updates (monitoring, maintenance windows, …).
Service users¶
Service users are used to run your actual services - compared to running them in your login user. This gives additional security and allows more flexible workflows when cooperating with other team members.
In nested projects, service users exist on all child projects recursively.
You can query, create, update and delete service users. Their names always
start with s-
to make them distinguishable from regular users. Their names
are unique per project, so you can have multiple services users named
s-myservice
in different projects.
The structure of a service user record looks like this:
{'__type__': 'serviceuser',
'description': '',
'gid_number': 101,
'home_directory': '/srv/s-services',
'id_number': 1000,
'login_shell': '/bin/bash',
'resource_group': 'services',
'resource_groups_recursive': ['services'],
'ssh_pubkey': [],
'uid': 's-services',
'virtual_machines': []}
- uid
needs to be set on create, read-only otherwise; primary key; filterable
The Linux name of this service user. Needs to start with
s-
and be unique within each project.- resource_group
needs to be set on create, read-only otherwise; primary key
The name of the resourcegroup this service user belongs to.
- resource_groups_recursive
read-only
The flattened list of names of all projects that this service user has access to.
- description
default:
''
A descriptive text that will be displayed in the context of this service user to clarify its purpose.
- id_number
read-only
The numerical id that this user has on Linux machines.
- gid_number
read-only, default:
101
The numerical id of the primary group that this user wears on Linux machines.
- home_directory
read-only, default:
'/srv/<uid>'
The home directory that this user has on Linux machines. Historical users may deviate from that schema. The record is kept to avoid unnecessarily moving data around.
- login_shell
read-only, default:
'/bin/bash'
The service user may have a deviating login shell in special circumstances. Normally it’s just bash.
- ssh_pubkey
read-only, default:
[]
The service user can be permitted to log in via SSH (although we do not recommend this normally). To set a service users’s SSH keys, please use the self-service UI.
- virtual_machines
read-only
The names of all the virtual machines that this service user has access to.
User permissions¶
Permissions are assigned to users (human and service) on a per-project basis and control the access level that users have to login and interact with virtual machines and other services.
The available permissions are:
login
Grants the user the ability to log into virtual machines by SSH. Does not allow the user to configure or control services on the machines.
sudo-srv
Grants the user the ability to configure and control services on the machines by sudoing into service user accounts after logging in via SSH.
stats
Grants the user (read-only) access to statistical backend services like Nagios, PNP, Kibana, awstats and others.
Permission records look like this:
{'__type__': 'permission',
'permission': 'test',
'resource_group': 'services',
'uid': 's-services'}
- permission
read-only, primary key
The name of the permission that is granted.
- resource_group
read-only, primary key
The name of the project the permission is granted. Applies to child projects as long as the child resource group does not define any other permission.
- uid
read-only, primary key, filterable
The uid of the user that this permission applies to. Can apply to human and service users.
Virtual Machines¶
The API allows querying, creating, updating, and deleting the VM resources that your services need.
Creation of VMs may take a while: you can be sure that a machine is ready
to use when the needs_install
flag is set to False
.
Updates to VM propagate depending on your change. Virtual hardware changes may take a while to be applied and may even require a maintenance window.
Creation or changes to the VM’s resources may be rejected if it would exceed safety thresholds of our data centers. There are also some limits given by the API to avoid accidents.
A virtual machine record looks like this:
{'__type__': 'virtualmachine',
'classes': ['role::generic'],
'cores': 1,
'creation_date': '2015-01-02T03:04:05+00:00',
'deletion': {'deadline': '', 'stages': []},
'disk': 10,
'environment': '',
'id': 4100,
'interfaces': {'fe': {'mac': '02:00:00:02:10:04', 'networks': {}},
'srv': {'mac': '02:00:00:03:10:04',
'networks': {'192.168.0.0/24':
['192.168.0.2']}}},
'kvm_host': '',
'last_maintenance_end': '',
'location': 'rzob',
'machine': 'virtual',
'memory': 256,
'name': 'services10',
'online': True,
'production': True,
'resource_group': 'services',
'resource_group_parent': '',
'frontend_ips_v4': 0,
'frontend_ips_v6': 0,
'reverses': {},
'service_description': '',
'servicing': True,
'timezone': 'Europe/Berlin'}
- name
read-only, primary key
The name of the virtual machine. All machines within a project need to adhere to the schema
<nameofrg><serialnumber>
. You can choose how to allocate those numbers as you like.We typically use
00
for the frontend machine, the numbers01
-09
are typically for singular services like databases, mailservers, and other auxiliary things.Higher numbers typically indicate clusters of application instances, like
10
-30
being instances of your application.- resource_group
readonly, required
The name of the project this VM belongs to.
- location
readonly, required
The data center that this VM is running in. Can only (and must) be set to
'rzob'
, our only public data center at the moment.- id
read-only
A globally unique integer ID identifying this VM instance.
- service_description
default:
''
A textual description of the purpose of this VM. This will be shown in appropriate places, e.g. as MOTD when logging in to the VM.
- resource_group_parent
readonly
The name of the parent project of the project this VM belongs to.
‚timezone‘: ‚Europe/Berlin‘
- classes
default:
['role::generic', 'role::backupclient']
Those are names for the „managed components“, or „roles“ that we provide to install on your machine. You can find details about each class in the specific platform release documentation.
A few roles are not selectable by you: if your VM runs in a production project, it will always be marked as
role::backupclient
to ensure safety of your data.Generally your VM will always have the
role::generic
class applied.Removing those classes is ignored.
- environment_class
The
environment_class
is the general flavor of your VM. Possible values are:NixOS
Puppet
(Gentoo platform, obsolete)
Bemerkung
The
environment_class
must be set coherently with theenvironment
. Theenvironment_class
can not be changed without deleting the VM (and going through the recycling period) first.- environment
The environment is the rolling-release version of our platform and management code.
The available environments depend on the environments class:
NixOS
fc-22.05-production
fc-22.05-staging
fc-21.11-production
fc-21.11-staging
Outdated environments:
fc-21.05-production
fc-21.05-staging
fc-20.09-production
fc-20.09-staging
fc-19.03-production
fc-19.03-staging
fc-15.09-production
fc-15.09-staging
Puppet:
production
,staging
- cores
default:
1
The number of virtual cores assigned to the VM. A maximum of 8 cores can be assigned per VM. If you need more: contact us.
Changing the number of cores will schedule a maintenance window to reboot the VM.
- memory
default:
256
The amount of memory assigned to the VM in MiB. The minimum of 256 MiB can not be undercut. Through the API you can assign a maximum of 3072 MiB (or 3 GiB) to a single VM. If you need more: contact us.
Changing the amount of memory will schedule a maintenance window to reboot the VM.
- disk
default:
10
The amount of disk space assigned to the root disk (
/
) of your VM in GiB. The minimum of 10 GiB can not be undercut. Through the API you can assign a maximum of 1000GiB to a virtual machine.We provide auxiliary space for
/tmp
andswap
for free.Increasing the amount of disk space will perform an online resize within a few minutes.
Decreasing the amount of disk space will schedule a maintenance window to reboot the VM.
- rbd_pool
default:
rbd.hdd
Set the storage pool for the VM. Possible values are:
rbd.hdd
for HDD backed storage, andrbd.ssd
for SSD backed storage.
Bemerkung
This value can only be set when the VM is created, and cannot be changed later.
- online
default: True
Indicates if the VM should be running (True) or not (False).
Setting
online
toFalse
will properly shutdown the VM, if possible. If the shutdown fails, the VM will be killed.- interfaces
readonly
A hierarchy of VLANs, the assigned IP networks (4 and 6) and the associated IP addresses for the VM.
srv
indicates the server-to-server communication channel. Those machines will only be assigned private IPv4 addresses but public IPv6 addresses.fe
indicates public internet traffic.- reverses:
readonly
A list of IP addresses and registered reverse DNS names. We can set those for you if you contact us.
- frontend_ips_v4
default:
0
The number of public IPv4 addresses to allocate for this VM. Increasing this number will cause more addresses to be allocated. Decreasing this number will not remove IP addresses at this time. Contact us if you want to reduce this number.
Bemerkung
Public IPv4 addresses are a scarce resource. Most virtual machines do not require one. Typically you need only 1 per project, maybe 2 or 3 under certain conditions. In the case of excessive use we may reduce the number of IPs available to your VM.
The number of public IPv4 addresses is limited to 3 per machine.
If you have a special case that justifies using more IPv4 addresses, please talk to us and we will be happy to work on a solution with you.
- frontend_ips_v6
default:
0
The number of public IPv6 addresses to allocate for this VM. Increasing this number will cause more addresses to be allocated. Decreasing this number will not remove IP addresses at this time. Contact us if you want to reduce this number.
The API limits you to 100 public IPv6 addresses per virtual machine.
- machine
readonly
Indicates that this is a virtual machine. In the future we may provide access to physical machines which would have similar records but display
physical
instead ofvirtual
in this place.- kvm_host
readonly
The hostname of the machine running your VM. Given for informative purposes. Sometimes having two VMs run on the same host may give significantly different networking results.
- production
readonly
Reflects the setting of this VM’s
production
flag - see above.- servicing
readonly, default:
True
Reflects whether this VM is assumed to be doing purposeful things at the moment. During maintenance this may be set to
False
and may be used by our infrastructure to temporarily do things to this VM that would not be appropriate if it was busy.- last_maintenance_end
readonly
The date and time when the VM was last in maintenance mode, ISO 6801 formatted with time zone. This can be useful to correlate with monitoring results. For instance you could ignore monitoring errors for a certain time after the maintenance ended to avoid notifications.
- creation_date
Date and time when the VM has been created, ISO 6801 formatted with time zone.
- deletion
readonly, default:
{'deadline': '', 'stages': []}
Reflects the deletion state of this VM. Reflects the deadline and the stages of the deletion that have been reached already.
Deleting a virtual machine¶
If you delete a VM without any options it will be marked for deletion by the end of the current month. After that it will not be accounted for any longer and will be shut down, and unconfigured. The data will be deleted over a period of about 1 month – which grants you some time to notice if you accidentally deleted the wrong VM. The VM’s record will be shown in queries until a few days after its deadline.
Additionally you can pass the field deadline
with an ISO date:
>>> server.apply([
... {'__type__': 'virtualmachine',
... '__action__': 'delete',
... 'deadline': '2020-01-01',
... 'name': 'services10'}])
Bemerkung
Deletions must be scheduled in the future. The earliest possible day is always „tomorrow“. Our timezone is Europe/Berlin for this.
To cancel a pending VM deletion you can simply update the VM without giving any additional data:
>>> server.apply([{'__type__': 'virtualmachine', 'name': 'services10'}])
Maintenance¶
The API allows querying maintenance windows and activities that have been scheduled for your services. Maintenance windows can not be changed through the API.
General parameters for maintenance windows can be configured on the corresponding project object.
A maintenance record looks like this:
{'__type__': 'maintenance',
'active': True,
'activities': [{'comment': 'test',
'duration': 0,
'ended': False,
'estimated': 100,
'reference_id': '',
'result': '',
'starts': '2011-07-02T20:00:00+00:00'}],
'announced': False,
'comment': '',
'ends': '2011-07-03T03:00:00+00:00',
'machine': 'kyle10',
'starts': '2011-07-02T20:00:00+00:00'}
Times are given in UTC.
Consumptions¶
The API allows querying consumptions. Consumptions are used to account for things that you as a customer use or „consume“ on our platform. At the end of a month, those consumptions are reviewed and turned into invoice items.
Consumptions can be queried during a month to see the ongoing view of your traffic, virtual machines, contracts, and more. Consumptions are also historic data and remain available even if you delete a project, a VM, or pass your resources over to a different customer.
Access to consumptions is granted based on the customer of the resource group that your API key is registered for.
A consumption record looks like this:
{'__type__': 'consumption',
'customer_no': '12345',
'parameters': {'traffic': 12345678104378L},
'period': '2015-01-01',
'type': 'traffic',
'type_id': 'myrg'}
The content of type_id
depends on the type. For example: traffic is
accounted per project. Virtual machines are accounted per virtual
machine. Parameters vary per type as well.
Invoices¶
The API allows querying invoices. Invoices are generated on a monthly basis for each customer based on the corresponding consumptions.
Invoices are send out by email in PDF format automatically and can be retrieved in an automatic fashion from the API. However, due to the complexities of international taxes, we only show pre-tax information through the API.
An invoice record looks like this:
{'__type__': 'invoice',
'consumption_end': '2012-01-31',
'consumption_start': '2012-01-01',
'customer_no': '12345',
'items': [{'description': 'test item',
'price': '10.0000',
'product': 'PRODUCT1234'}],
'status': 'pending',
'total': '10.0000'}