Spheron Terraform

Guide on how to use the Spheron Terraform provider.

Prerequisites

Before you begin, please ensure that you have the following prerequisites installed on your machine:

• Terraform (version 0.13 or later)
• Spheron provider plugin (version 1.0.0 or later)

Installation

Spheron Terraform provider can be accessed here: Spheron Terraform Provider (opens in a new tab)

To install the Spheron provider plugin, follow these steps:

1. Open a terminal or command prompt.
2. Change the directory to your Terraform project directory.
3. Create a new file named terraform.tf in the project directory (if it doesn't exist already).
4. Open the terraform.tf file using a text editor.
5. Add the following lines to the file:

terraform {
  required_providers {
    spheron = {
      source = "spheronFdn/spheron"
      version = "1.0.0"
    }
  }
}

6. Save the file.

Configuration

To configure the Spheron provider, follow these steps:

1. Open the Terraform configuration file for your project (e.g., main.tf) using a text editor.
2. Add the following block to the configuration file:

provider "spheron" {
  token = "" // or use SPHERON_TOKEN env variable
}

Usage

To use the Spheron provider in your Terraform code, follow these steps:

1. Write your desired infrastructure code using Terraform, incorporating the Spheron provider resources and data sources.
2. Save the Terraform configuration file (e.g., main.tf).
3. Open a terminal or command prompt.
4. Change the directory to your Terraform project directory.
5. Run the following command to initialize the Terraform project and download the Spheron provider plugin:

terraform init

6. After initialization completes successfully, you can proceed with other Terraform commands such as plan, apply, etc., depending on your workflow.

Spheron Terraform Provider

terraform {
  required_providers {
    spheron = {
      source = "spheronFdn/spheron"
      version = "1.0.0"
    }
  }
}

provider "spheron" {
  token = ""
}

Schema

Optional:

• token (String) Spheron access token. If left empty, provide SPHERON_TOKEN env variable.

Resources and DataSources

Spheron instance (Resource)

resource "spheron_instance" "instance_test" {
  image         = "crccheck/hello-world"
  tag           = "latest"
  cluster_name  = "tf_test"
  region        = "any"
  machine_image = "Ventus Small"

  args     = ["arg"]
  commands = ["command"]

  ports = [
    {
      container_port = 8000
      exposed_port   = 80
    }
  ]
  env = [
    {
      key   = "k",
      value = "v"
    }
  ]

  health_check = {
    path = "/"
    port = 8000
  }
}

Schema

Required:

• cluster_name (String) The name of the cluster.
• image (String) The docker image to deploy. Currently, only public dockerhub images are supported.
• ports (Attributes List) The list of port mappings (see below for nested schema)
• region (String) Region to which to deploy the instance. (see below for available regions)
• replicas (Number) Number of instance replicas.
• storage (Number) Instance storage in GB. Value cannot exceed 1024GB
• tag (String) The tag of the docker image.

Optional:

• args (List of String) List of params for docker CMD command.
• commands (List of String) List of executables for docker CMD command.
• cpu (String) Instance CPU. Available values [0.5, 1, 2, 4, 8, 16, 32].
• env (Attributes Set) The list of environment variables. (see below for nested schema)
• env_secret (Attributes Set) The list of secret environment variables. (see below for nested schema)
• health_check (Attributes) Path and container port on which health check should be done. (see below for nested schema)
• id (String) Id of the instance.
• machine_image (String) Machine image name which should be used for deploying instance. (see below for available images)
• memory (String) Instance Memory in GB. Available values [0.5, 1, 2, 4, 8, 16, 32].
• persistent_storage (Attributes) Persistent storage that will be attached to the instance. (see below for nested schema)

Nested Schema for env

Required:

• key (String) Environment variable key.
• value (String) Environment variable value.

Nested Schema for env_secret

Required:

• key (String) Environment variable key.
• value (String) Environment variable value.

Nested Schema for ports

Required:

• container_port (Number) Container port that will be exposed.

Optional:

• exposed_port (Number) The port container port will be exposed to. Currently only possible to expose to port 80. Leave empty to map to a random value. The exposed port will be known and available for use after the deployment.

Nested Schema for health_check

Required:

• path (String) Path on which health check should be done.
• port (Number) Instance container path on which health check should be done.

Nested Schema for persistent_storage

Required:

• class (String) Storage class. Available classes are HDD, SSD, and NVMe.
• mount_point (String) Attachment point used for attaching persistent storage.
• size (Number) Persistent storage in GB. Value cannot exceed 1024GB

Spheron marketplace instance (Resource)

resource "spheron_marketplace_instance" "market_instance_test" {
  name          = "Postgres"
  machine_image = "Ventus Nano"

  env = [
    {
      key   = "POSTGRES_PASSWORD"
      value = "passSecrettt"
    },
    {
      key   = "POSTGRES_USER"
      value = "admin"
    },
    {
      key   = "POSTGRES_DB"
      value = "myDB"
    }
  ]

  region = "any"
}

Schema

Required:

• name (String) The name of the marketplace app. (see below for available marketplace apps)
• region (String) Region to which to deploy the instance. (see below for available regions)
• replicas (Number) Number of instance replicas.
• storage (Number) Instance storage in GB. Value cannot exceed 1024GB

Optional:

• cpu (String) Instance CPU. Available values [0.5, 1, 2, 4, 8, 16, 32].
• env (Attributes Set) The list of environment variables. NOTE: Some marketplace apps have required env variables that must be provided. (see below for nested schema)
• machine_image (String) Machine image name which should be used for deploying instance. (see below for available images)
• memory (String) Instance Memory in GB. Available values [0.5, 1, 2, 4, 8, 16, 32].
• persistent_storage (Attributes) Persistent storage that will be attached to the instance. (see below for nested schema)

Read-Only:

• id (String) Id or the instance.
• ports (Attributes List) The list of port mappings (see below for nested schema)

Nested Schema for env

Required:

• key (String) Environment variable key.
• value (String) Environment variable value.

Nested Schema for persistent_storage

Required:

• class (String) Storage class. Available classes are HDD, SSD, and NVMe.
• mount_point (String) Attachment point used for attaching persistent storage.
• size (Number) Persistent storage in GB. Value cannot exceed 1024GB

Nested Schema for ports

Read-Only:

• container_port (Number) Container port that will be exposed.
• exposed_port (Number) The port container port will be exposed to. The exposed port will be known and available for use after the deployment.

Available marketplace apps

Available machine images

Available regions

• us-east
• us-west
• us-central
• eu-west
• any

Spheron domain (Resource)

resource "spheron_domain" "domain_test" {
  name = "test.com"
  type = "domain"

  instance_port = spheron_instance.instance_test.ports[0].container_port
  instance_id   = spheron_instance.instance_test.id
}

Schema

Required:

• instance_id (String) The id of an instance to which to attach the domain.
• instance_port (Number) Container port of the instance to which to attach the domain.
• name (String) The domain name
• type (String) Type of the domain. Available options are domain and subdomain.

Read-Only:

• id (String) Id of the domain.
• verified (Boolean) Is verified. True means that the domain is verified and that it will start serving the content

Spheron organization (Data Source)

data "spheron_organization" "test_org" {
}

Schema

Read-Only:

• id (String) Organization identifier.
• name (String) Organization name.

Additional Resources

For more information on using Terraform and the Spheron provider, you can refer to the following resources:

Spheron Terraform Provider (opens in a new tab)

Terraform Documentation (opens in a new tab)

Remember to consult the specific documentation for the Spheron provider for any additional configuration options, features, or troubleshooting information.

Happy infrastructure provisioning with Terraform and the Spheron provider!