Infrastructure Abstraction Layer

Cycle's Infrastructure Abstraction Layer (IAL) enables developers to extend the Cycle platform into infrastructure beyond what Cycle natively supports. This infrastructure can range from another cloud provider to on-premises setups within data centers or office buildings. With sufficient RAM and disk, it is even possible to manage IoT devices.

By expanding the Cycle platform, organizations gain the infrastructure and devops benefits enabled by Cycle but with more flexibility in terms of deployments.

Prerequisite

While Cycle aims to utilize any commodity infrastructure with an internet connection, there are a few important requirements to be aware of:

Hardware Requirements (Compute Servers):

• Minimum of 4GB RAM
• An x86 processor

• Minimum of 45GB of disk space, though 100GB+ is recommended for general purpose deployments.

CycleOS will attempt to allocate 35GB of disk space for its base volume. This base volume is used to store:

• CycleOS logs (~150Mb)
• CycleOS updates (~100Mb)
• Container Images
• Storage for any files written outside of persistent volumes.
• The base volume can be increased after the server is online.
• While not required, an SSD or NVME disk is highly recommended.

Network Requirements (Compute Servers):

• A 20Mbps+ public internet connection.
• A minimum of 1 static IPv4 address.
  • The Compute server (host) will utilize one ip address itself. Every load balancer instance will consume its own IP addresses. If this server was going to host 4 load balancers, for different environments, it would need a total of 5 static ips.
• IPv6 support is highly recommended, but not required. Cycle can be configured to use IPv4-only, IPv6-only, or dual stack.

Software Requirements (Compute Servers):

• IPXE / PXE support

  • CycleOS is a read-only operating system built specifically for running containers. The OS is very lightweight / barebones to limit attack surface and legacy code.
  • CycleOS is never written to disk, and lives purely in RAM. Every time a server is rebooted, a fresh version of CycleOS is pulled. This process enables the Cycle platform to mitigate security risks while also ensuring the entire software stack stays modernized.
  • For example, CycleOS ships with a modern mainline kernel that is automatically maintained by the Cycle team.
  • Cycle has both an IPXE ISO and an IPXE EFI image to pull CycleOS.

• Metadata or DHCP support

  • When a server with CycleOS boots it utilizes a 'node-setup' container, maintained by Cycle, to configure basic networking and storage configurations. This node-setup container must be able to learn, from an outside source, how to configure the network for the desired machines. As of now, there is no way to manually configure static IP interfaces within Cycle.

Software Requirements (Integration):

• The ability to build and publicly serve a highly-available API.

  • Cycle's IAL is built around the idea of extending Cycle's internal infrastructure provisioning system with custom APIs. Cycle maintains a git repository of the required spec definitions and endpoints needed for IAL support.
  • The git repository can be found here: https://github.com/cycleplatform/integrations

Setup and Integration

Before continuing with setup and integration, it's critical to first read, understand, and be able to satisfy the requirements above. Assuming the requirements can be met, we can begin configuring IAL.

Context around the IAL API

Before diving into the infrastructure setup, we must first build the IAL integration. When complete, Cycle will utilize this API to:

1. Discover which locations / regions it can deploy servers to.
2. Which servers / server models are available in each respective location
3. Configure a location, per hub, on first server provision
4. Provision / decommission a server
5. Check the status of a provisioning server
6. Reboot a server
7. Request / release an IP address

Building the IAL API

As mentioned above, this API will need to be publicly accessible from the Cycle platform. Additionally, the IAL API follows the same JSON specification as Cycle's primary API.

As of June 21st, 2022, a full integration requires the following endpoints. It is recommended that you develop your integration in the order of the calls listed below as many endpoints require existing data / resources before they can be utilized.

Code Considerations

All requests, from Cycle into an IAL integration, will exist within a 'RequestWrapper' which contains two to-level fields: 'auth' and 'request':

• The Auth object contains a number of optional fields which can be set depending on the requirements of the underlying integration. Cycle will populate all auth credentials specified on the platform's side.
• The Request object, from a Golang perspective, is a raw JSON message that will need to be decoded on successful authorization.

All responses back to the platform must follow the JSON API spec utilized for Cycle's primary API.

With this spec, all responses must be wrapped in a Response object containing top-level data and error fields.

In the IAL type definitions, fields follow two naming conventions:

• Fields ending in "Id": These are user-specified and unique.
  • Example: ServerId is an identifier set by the IAL integration to represent a server on the IAL side (not in Cycle).
• Fields ending in "ID": These are generated by Cycle and used to refer to specific objects after they've been created.

Additionally, many IAL request objects contain a Cycle field. This field should be considered meta information and can be used on the IAL client side to associate objects with Cycle-generated identifiers if helpful.

Connecting an IAL Integration

After implementing the API endpoints, the IAL client API must be hosted on a publicly accessible server for Cycle to access. The URL for this server must:

• Be publicly resolvable
• Be open to all IP traffic (with future restriction options planned)

To connect Cycle to the API:

1. Log in to Cycle's portal.
2. Navigate to Infrastructure, then Providers, and click “Add a Provider.”
3. In the modal that appears, select Custom / Abstraction and insert the base URL where Cycle can access the IAL endpoints.
4. Click Add to create the integration.

Once added, a new tile will appear for the integration.

1. Click Verify to begin the validation process. Cycle will then verify the API endpoints and authorization credentials.
2. Upon successful verification, Cycle will call /v1/infrastructure/provider/locations and /v1/infrastructure/provider/server-models to retrieve the available regions and server models that can be deployed.
3. Cycle will automatically synchronize with the provider/locations and provider/server-models endpoints every six hours to stay updated on availability.

Provisioning a Server

Once an IAL integration is verified and the locations and server models are synced, infrastructure provisioning can begin using Cycle's standard API calls and portal.

The provisioning process works as follows:

1. A request for a new server is initiated.
2. Cycle calls the /v1/infrastructure/server/provision endpoint, passing the following information:
   • Desired server model
   • Hostname for the server
   • Location for the server
   • Any other relevant details
3. After a short delay, Cycle will begin calling /v1/infrastructure/server/provision-check every 5-10 seconds to check the provisioning status.
4. Upon successful provisioning, the /v1/infrastructure/server/provision-check endpoint must return a ProvisionServerStatus response object, which includes:
   • Confirmation of successful provisioning
   • Authentication details required for the server to pull CycleOS during its boot process

Without these authentication credentials, the server will not be able to retrieve CycleOS.

After this point, all functionality within Cycle should work normally, provided that all IAL endpoints have been properly developed and return the correct responses upon success.

Booting a Server

After a successful provision, the server will begin using iPXE (via either an ISO or EFI executable) to pull CycleOS.

The process works as follows:

1. iPXE will attempt to pull CycleOS.
   • If the proper authentication credentials were not specified via a successful provision from the provision-check endpoint, this request will result in a "Permission Denied" error.
2. Once iPXE successfully pulls CycleOS:
   • The operating system will use DHCP or a metadata service to self-configure networking.
   • A "best guess" strategy will be applied to configure storage within the server.

Important Notes: