Terraform

Overview

Volterra terraform is a docker container that contains the quickstart tool and the terraform provider. The quickstart tool is a combination of script and templates using which, you can perform activities such as site deployment and removal. The Volterra terraform provider is used to expose Volterra Services public objects as terraform resources. The provider is responsible for interacting with Volterra objects in the backend.

Note: The Volterra terraform provider is not yet publicly available. Therefore, it is made available through the Volterra terraform container docker.io/volterraio/volt-terraform. The terraform provider binary is available in the following path in the container:
/root/.terraform.d/plugins/terraform-provider-volterra


Volterra Quickstart Tool

Installation

Download the latest quickstart tool:

docker pull volterraio/volt-terraform

Extract the quickstart deployment script to your local folder:

docker run --rm -v $(pwd):/opt/bin:rw docker.io/volterraio/volt-terraform:latest cp /deploy-terraform.sh /opt/bin

Usage

Syntax:

./deploy-terraform.sh <subcommand> [options]

Note: Use the script or the subcommand with the -h or --help option for more information. For example, use $ ./deploy-terraform.sh -h to obtain information on available subcommands.

Subcommands

The following table shows the list of subcommands:

Subcommand Description
apply Creates a node or modifies an existing node.
destroy Deletes a node.
Plan Performs terraform plan activity.
refresh Performs terraform refresh activity.
Validate Performs resource validation.
list-templates Displays all available terraform templates.
exec Executes other commands such as az, aws, etc.
output Displays the output of terraform output command.

To know more options of each subcommand, invoke the help by executing the following command.

./deploy-terraform.sh <subcommand> -h|--help

Options for Subcommands

Option Expansion Description
-p --provider Specifies name of cloud provider such as AWS or Azure.
-tn --template-name Specifies name of terraform template.
-i --input-file Specifies input variables file for terraform.
-as --aws-secret-access-key Specifies AWS secret access key.
-ak --aws-acess-key-id Specifies AWS access key.
-ast --aws-session-token Specifies session token provided by AWS.
-r --region aws Specifies AWS region.
-n --volterra-cluster-name Specifies the cluster name.
-au --azure-username Specifies the azure user.
-ac --azure-client-id Specifies azure client ID.
-azc --azure-client-secret Specifies azure client access secret.
-at --azure-tenant-id Specifies azure user tenant.
-f --force Enables the -auto-approve option for terraform command.
-d --develop Enables develop mode which mounts the local code to the container.
--container-img Enables the usage of the specified container image.
--tf-version Specifies the terraform version. Supported versions are 0.11 and 0.12. The default version is 0.11.

Examples

The following example displays a list of azure accounts in tabular format:

./deploy-terraform.sh exec az account list --output table

The following example displays the caller identity of the associated AWS account:

./deploy-terraform.sh exec aws sts get-caller-identity

The following example displays the deployment details:

./deploy-terraform.sh output -n <name of deployment>

Volterra Terraform Provider

Volterra terraform provider can used to configure Volterra infrastructure objects using Volterra API's.


Authenticating to Volterra

Volterra terraform provider supports authenticating to Volterra using API Credential P12 file. Learn more on how to generate api certificate.


Configure Volterra Provider

Example Usage

# Configure Volterra Provider
provider "volterra" {
  api_p12_file     = "/path/to/api_credential.p12"
  url              = "<tenant_name>.console.ves.volterra.io/api"
}

# Create a namespace
resource "volterra_namespace" "devops" {
  name     = "example-devops"
}

Argument Reference

The following arguments are supported

  • api_p12_file - API credential p12 file path. Either apip12file or (apicert and apikey) must be given
  • api_cert - API certificate file path.
  • api_key - API certificate private key file path
  • url - Tenant API url file path (Required)
  • timeout - Volterra api call timeout, by default its 10 seconds

When using api_p12_file, password for the p12 file must be passed as the environment variable VES_P12_PASSWORD.


Configuring Volterra Resources

Volterra objects creation, read, update and deletion functionalities are defined as part of terraform provider resources. Internally it maps terraform lifecycle operation to Volterra’s public API operations.

Namespace

Example Usage

resource "volterra_namespace" "devops" {
  name     = "example-devops"
}

Argument reference

  • annotations - Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects (Optional)
  • description - Human readable description for the object
  • disable - A value of true will administratively disable the object
  • labels - Map of string keys and values that can be used to organize and categorize (scope and select) objects as chosen by the user. Values specified here will be used by selector expression
  • name - Name of the namespace object (Required)

Attribute Reference

  • uid or id - ID of Namespace object
  • tenant_name - Tenant name

Origin Pool

Example Usage

# create namespace
resource "volterra_namespace" "devops" {
  name     = "example-devops"
}

# create origin pool in example-devops namespace
resource "volterra_origin_pool" "example_op" {
  name      = "apache-org"
  namespace = "example-devops"
  loadbalancer_algorithm = "ROUND_ROBIN"
  origin_servers {
    choice {
      public_name {
        dns_name = "apache.org"
      }
    }
  }
  port = 80
}

Argument Reference

  • annotations - Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects (Optional)
  • description - Human readable description for the object
  • disable - A value of true will administratively disable the object
  • labels - Map of string keys and values that can be used to organize and categorize (scope and select) objects as chosen by the user. Values specified here will be used by selector expression
  • name - Name of the origin_pool object (Required)
  • namespace - This defines the workspace within which each the configuration object is to be created. Must be a DNS_LABEL format (Required)

NOTE: The following list explains only those arguments that are used in the above example:

  • origin_servers.choice.public_name.dns_name - Specify origin server with public DNS name
  • loadbalancer_algorithm - Different load balancing algorithms supported When a connection to an endpoint in an upstream cluster is required, the load balancer uses loadbalanceralgorithm to determine which host is selected. Valid values are `ROUNDROBIN,LEASTREQUEST,RINGHASHandRANDOM`
  • port - on which the service is available

HTTP Loadbalancer

Example Usage

# create namespace
resource "volterra_namespace" "devops" {
  name     = "example-devops"
}

# create origin pool in example-devops namespace
resource "volterra_origin_pool" "example_op" {
  name      = "apache-org"
  namespace = "example-devops"
  loadbalancer_algorithm = "ROUND_ROBIN"
  origin_servers {
    choice {
      public_name {
        dns_name = "apache.org"
      }
    }
  }
  port = 80
}

# create http loadbalancer in example-devops namespace
resource "volterra_http_loadbalancer" "volt_apache" {
  name = "volt-apache"
  namespace = "example-devops"
  add_location = true
  advertise_choice {
    advertise_on_public_default_vip = true
  }
  default_route_pools {
    pool_choice {
      pool {
         name = "apache-org"
         namespace = "example-devops"
         tenant = volterra_namespace.devops.tenant_name
      }
    }
  }
  domains = ["volt-apache.helloclouds.app"]
  loadbalancer_type {
    https_auto_cert {
      http_redirect = true
    }
  }
}

Argument Reference

  • annotations - Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects (Optional)
  • description - Human readable description for the object
  • disable - A value of true will administratively disable the object
  • labels - Map of string keys and values that can be used to organize and categorize (scope and select) objects as chosen by the user. Values specified here will be used by selector expression
  • name - Name of the http_loadbalancer object (Required)
  • namespace - This defines the workspace within which each the configuration object is to be created. Must be a DNS_LABEL format (Required)

NOTE: The following list explains only those arguments that are used in the above example:

  • add_location - Appends header x-volterra-location = in responses. This configuration is ignored on CE sites.
  • domains - A list of domains (host/authority header) that will be matched to loadbalancer. Wildcard hosts are supported in the suffix or prefix form
  • default_route_pools.pool_choice.pool - Select the reference pool object

    • name - name of the origin pool
    • namespace - namespace of the origin pool object
    • tenant - tenant where the namespace exists
  • loadbalancer_type.https_auto_cert.http_redirect - Enable http auto cert and http_redirect