Faxter Platform Documentation

Introduction

The Faxter platform is a cloud management system that provides a unified interface to create, manage, and orchestrate cloud resources. It exposes a simple API and can be integrated into your Infrastructure-as-Code (IaC) workflows through a Terraform provider. Using Faxter, you can manage:

  • Projects: Logical groupings of resources, billing, and user permissions.
  • Servers: Virtual machines (compute instances) running in your projects.
  • Security Groups: Access control lists that regulate inbound and outbound network traffic to your servers.
  • Networks: Virtual private networks (VPC-like constructs) and their subnets.
  • Routers: Gateways that connect networks and subnets to external networks, enabling communication between resources and the internet.
  • SSH Keys: Public keys to securely access your servers.
  • Volumes: Additional block storage devices attached to servers.

This documentation will cover the conceptual overview of each resource type and how they interrelate, followed by step-by-step guidance on how to create various architectures using the Faxter Terraform provider.

Core Concepts

Projects

What are they?

A Project is the fundamental organizational unit in Faxter. It encapsulates resources, users, and billing. By creating a project, you define an isolated environment where you can spin up servers, create networks, and deploy applications without interfering with other projects.

Key points:

  • Each project has an owner.
  • Projects contain members who can access and manage resources within.
  • Projects have associated accounts that track resource usage and costs.
  • You can add and remove members to maintain appropriate access control.

When to use them:

Use a project to group related infrastructure components that correspond to a specific application, environment (e.g., development, staging, production), or business unit.

The Default Project

What is it?

The Default Project is a built-in, pre-configured project environment provided by Faxter. It is designed as a simplified starting point, ideal for quickly spinning up a server or experimenting with the platform’s capabilities without the overhead of managing networks, routers, or security groups.

Key Characteristics of the Default Project:

  • No Manual Setup Required: You do not need to create a project, define networks, or set up routers. The default project comes ready to use, minimizing time to get started.
  • Limited Resource Scope: The default project only supports essential resources:
  • Servers: Quickly launch virtual machines with minimal configuration.
  • SSH Keys: Easily manage and use SSH keys for secure access to servers.
  • No Network or Security Group Management: Since the default project does not support custom networks, routers, or security groups, you skip the complexities of configuring virtual networking and firewall rules. Your servers are placed in a basic, predefined environment.

When to Use the Default Project:

  • Rapid Prototyping: If you want to test a quick idea, deploy a throwaway development environment, or evaluate a new OS image, the default project lets you go from zero to a running server in minutes.
  • Simple Use Cases: For straightforward tasks like running a build job, testing a single application server, or hosting a quick internal demo, the default project provides enough infrastructure without extra overhead.
  • Learning and Experimentation: If you’re new to Faxter or Infrastructure-as-Code, starting with the default project helps you understand the basics of creating servers and accessing them via SSH keys before diving into more complex setups.

Servers

What are they?

A Server is a virtual machine that you can provision within a project. Servers are the compute layer where you run your applications.

Key points:

  • Can have various flavors (sizes of CPU/RAM) and images (base operating system).
  • Can be connected to one or more networks.
  • Can optionally attach volumes for persistent storage.
  • Require SSH keys or other access methods for secure administration.
  • Support cloud-init for post-boot configuration (e.g., installing software, setting up users).

When to use them:

Use servers as the building blocks of your application’s infrastructure. For instance, a web server, a database server, or a worker node in a distributed system.

Security Groups

What are they?

Security Groups act as virtual firewalls for your servers, controlling inbound and outbound traffic at the instance level.

Key points:

  • Rules define allowed protocols, ports, and source/destination CIDRs.
  • Direction (ingress/egress) determines whether traffic is entering or leaving the server.
  • Multiple servers can share a security group, making it easy to apply consistent security policies.

When to use them:

Use security groups to enforce the principle of least privilege. For example, you might: - Allow inbound HTTP (port 80) and HTTPS (port 443) traffic to a web server. - Restrict SSH access only from trusted IP ranges. - Block all other unnecessary inbound traffic.

Networks and Routers

What are they?

Networks provide isolated virtualized network segments within your project. You can create subnets and assign servers to them, ensuring secure and structured internal communication.

Routers connect these networks to each other and optionally to external networks or the public internet. They enable traffic to flow between private subnets and an external gateway for internet access.

Key points:

  • Networks provide IP addressing (subnets), allowing servers to communicate internally.
  • Routers typically connect a private network to a public network or another private network.
  • You can have multiple networks to segregate application tiers (e.g., front-end, back-end, database).

When to use them:

Use networks and routers to:

  • Create isolated environments that ensure internal traffic is not exposed to the public internet directly.
  • Segment different application tiers for better security and organization.
  • Control how and where your infrastructure accesses external resources.

SSH Keys

What are they?

SSH Keys are used to securely authenticate to your servers. By associating a public key with a server, you ensure that only those with the corresponding private key can gain shell access.

Key points:

  • Simplifies secure, passwordless login.
  • Recommended best practice over password-based authentication.
  • Can be managed at the project level and applied to multiple servers.

When to use them:

Use SSH keys whenever you need administrative access to servers. Instead of relying on passwords, keys offer more security and convenience, particularly in automated setups.

Volumes

What are they?

Volumes are detachable block storage devices that can be attached to servers. This is analogous to adding a virtual hard drive to a machine.

Key points:

  • Persistent data storage beyond the server’s lifecycle.
  • Useful for databases, file storage, and any stateful components.
  • Can be detached and reattached to other servers, allowing flexible data management.

When to use them:

Use volumes when you need durable storage that persists independently of the server’s lifecycle. For example, use a volume for database storage so that data is not lost if the server terminates.

How They Tie Together

A typical infrastructure might look like this:

  • Project: Defines the scope of all your resources and user access.
  • Network and Router: Create a private network and a router to allow controlled internet access. For instance:
  • public-network connected via a router to external internet.
  • private-network for back-end servers that do not need direct public access.
  • Security Groups: Applied to servers to restrict who can access them. For example:
  • A web security group allowing inbound HTTP/HTTPS.
  • A database security group allowing inbound traffic only from the web server’s security group.
  • Servers: Provision servers in the desired network. For example:
  • A web-server in the public network with a security group allowing HTTP/HTTPS.
  • A db-server in the private network with a security group that only allows MySQL traffic from the web-server.
  • SSH Keys: Provide secure administrative access to these servers without passwords.
  • Volumes: Attach additional storage volumes to the db-server to hold database data that persists even if you replace the server.

Using the Faxter Terraform Provider

Getting Started

Prerequisites:

  • Terraform installed locally.
  • Faxter Terreform provider installed locally: Faxter Terraform provider
  • A valid API token for Faxter.

Example provider block:

terraform {
  required_providers {
    faxter = {
      source = "local/faxter/faxter"
      version = "0.1"
    }
  }
}

provider "faxter" {
  token    = "YOUR_TOKEN_HERE"
}

Example Using the Default Project

terraform {
  required_providers {
    faxter = {
      source = "local/faxter/faxter"
      version = "0.1"
    }
  }
}

provider "faxter" {
  token    = "YOUR_TOKEN_HERE"
}

resource "faxter_ssh_key" "mykey" {
  project    = "default"
  name       = "quick-ssh-key"
  public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."
}

resource "faxter_server" "quick_server" {
  project   = "default"
  name      = "test-server"
  key_name  = faxter_ssh_key.mykey.name
  flavor    = "copper"
  image     = "Ubuntu2204"
}

In this example, you simply provide an SSH key and spin up a server in the default project. No need to configure a project, networks, or security groups. This simplicity makes the default project an excellent choice for developers or testers who need something quick and easy. Once you’re comfortable and ready to scale up, you can move on to fully managed projects with networks, routers, and security groups for more controlled and secure deployments.

Creating a Project

resource "faxter_project" "my_project" {
  name = "my-cool-project"
}

This creates an isolated environment where all subsequent resources reside. Note that you have to fund the project before you can create any additional resources.

Defining Networks and Routers

Network:

resource "faxter_network" "private_net" {
  project     = faxter_project.my_project.name
  name        = "my-private-network"
  subnets {
    name = "subnet1"
    cidr = "192.168.10.0/24"
  }
}

Router:

resource "faxter_router" "my_router" {
  project          = faxter_project.my_project.name
  name             = "my-router"
  connect_external = true
  subnets          = [faxter_network.private_net.subnets[0].name]
}

This sets up internal networking and a router connecting your private network to an external gateway.

Security Groups

resource "faxter_security_group" "web_sg" {
  project = faxter_project.my_project.name
  name    = "web-access"

  rules {
    protocol          = "tcp"
    port_range_min    = 80
    port_range_max    = 80
    direction         = "ingress"
    remote_ip_prefix  = "0.0.0.0/0"
  }
  rules {
    protocol          = "tcp"
    port_range_min    = 443
    port_range_max    = 443
    direction         = "ingress"
    remote_ip_prefix  = "0.0.0.0/0"
  }
}

This creates a security group that allows HTTP and HTTPS traffic from the internet to servers that attach this SG.

SSH Keys

resource "faxter_ssh_key" "my_ssh_key" {
  project    = faxter_project.my_project.name
  name       = "my-terraform-key"
  public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..."
}

Now, servers associated with my_terraform_key can be accessed using the corresponding private key.

Servers

Create a server:

resource "faxter_server" "web_server" {
  project   = faxter_project.my_project.name
  name      = "web1"
  key_name  = faxter_ssh_key.my_ssh_key.name
  flavor    = "copper"
  image     = "Ubuntu2204"
  networks  = [faxter_network.private_net.name]

  // Attach the web security group
  security_groups = [faxter_security_group.web_sg.name]

  // Optionally load cloud-init from a file
  cloud_init = file("${path.module}/cloud_init.yaml")
}

This provisions a server in the my-private-network subnet with web-access security group and sets up cloud-init to configure the server on first boot.

Volumes

resource "faxter_volume" "db_volume" {
  project = faxter_project.my_project.name
  name    = "db-data"
  storage    = 100 // Size in GB
}

Attach the volume to a server (if supported by the provider): Check if the provider supports attaching volumes at creation or via another resource. Typically, you might specify volumes during server creation or update.

Example: A Two-Tier Web Application

Goal: Create a simple web application architecture with a front-end web server and a back-end database server in separate networks.

Design:

  • Projects: my-app-project
  • Networks:
    • public_net for the web tier, router connected to external internet.
    • private_net for the database tier, isolated and only accessible from the web tier.
  • Security Groups:
    • web_sg: Allow inbound HTTP/HTTPS.
    • db_sg: Allow inbound MySQL (port 3306) only from the web_sg members.
  • Servers:
    • web_server in public_net with web_sg.
    • db_server in private_net with db_sg, attached to a db_volume.
  • SSH Key: One SSH key for administrative access.

Terraform Configuration Sketch:

# Provider and project
provider "faxter" {
  token    = "YOUR_TOKEN"
}

# Networks and router
resource "faxter_network" "private_net" {
  project     = "my-app-project"
  name        = "private-network"
  subnets {
    name = "subnet1"
    cidr = "10.0.2.0/24"
  }
}

resource "faxter_router" "app_router" {
  project          = "my-app-project"
  name             = "app-router"
  connect_external = true
  subnets          = [
    faxter_network.private_net.subnets[0].name
  ]
}

# Security groups
resource "faxter_security_group" "web_sg" {
  project = "my-app-project"
  name    = "web-sg"

  rules {
    protocol         = "tcp"
    port_range_min   = 80
    port_range_max   = 80
    direction        = "ingress"
    remote_ip_prefix = "0.0.0.0/0"
  }

  rules {
    protocol         = "tcp"
    port_range_min   = 443
    port_range_max   = 443
    direction        = "ingress"
    remote_ip_prefix = "0.0.0.0/0"
  }
}

resource "faxter_security_group" "db_sg" {
  project = "my-app-project"
  name    = "db-sg"

  rules {
    protocol         = "tcp"
    port_range_min   = 3306
    port_range_max   = 3306
    direction        = "ingress"
    remote_group_id  = faxter_security_group.web_sg.name
  }
}

# SSH Key
resource "faxter_ssh_key" "mykey" {
  project    = "my-app-project"
  name       = "my-app-key"
  public_key = "ssh-rsa AAAA..."
}

# Servers
resource "faxter_server" "web_server" {
  project   = "my-app-project"
  name      = "web1"
  key_name  = faxter_ssh_key.mykey.name
  flavor    = "copper"
  image     = "Ubuntu2204"
  networks  = [faxter_network.public_net.name]
  security_groups = [faxter_security_group.web_sg.name]
}

resource "faxter_volume" "db_volume" {
  project = "my-app-project"
  name    = "db-storage"
  size    = 50
}

resource "faxter_server" "db_server" {
  project   = "my-app-project"
  name      = "db1"
  key_name  = faxter_ssh_key.mykey.name
  flavor    = "copper"
  image     = "Ubuntu2204"
  networks  = [faxter_network.private_net.name]
  security_groups = [faxter_security_group.db_sg.name]
  volumes   = [faxter_volume.db_volume.name]
}

Result:

  • A web_server accessible from the internet on HTTP/HTTPS.
  • A db_server only accessible from the web_server via the private network and db_sg.
  • A persistent volume for database storage.

Assignment: Add a cloud-init file to install a webserver and mysql on the respective servers

Scaling Out and Advanced Designs

With the building blocks introduced above, you can create more complex topologies:

  • Load Balancers: Deploy multiple web_server instances and connect them to a load balancer (future Faxter resources).
  • Multi-tier Applications: Add separate networks and security groups for caching layers, message queues, etc.
  • High Availability: Run multiple servers in different projects or regions (if the API supports regions or fault domains).
  • Automated Provisioning: Combine Terraform configurations with CI/CD pipelines to version-control and automate your entire infrastructure lifecycle.

Conclusion

The Faxter platform, along with its Terraform provider, enables you to model, provision, and maintain your cloud infrastructure using declarative configurations. By understanding the concepts of projects, servers, networks, routers, security groups, and other resources, you can build secure, scalable, and maintainable systems.

As your application grows, you can easily evolve your infrastructure by adding more resources, refining your network topology, updating security policies, and scaling out to meet your performance and reliability requirements.