Skytap Terraform provider reference

Contents

Configuration and credentials

provider "skytap" {
  username = "${var.skytap_username}"
  api_token = "${var.skytap_api_token}"
}

resource "skytap_environment" "env" {
  # ...
}

Data Sources

skytap_template

Retrieves information about a template A read-only copy of an environment that can be used to back up critical environments. It acts like a blueprint for new environments. To learn more, see Saving an environment as a template. . This data source provides the id and name of a template as configured in your Skytap account. This is useful to retrieve a template id via its name.

The name field can accept an exact string or a regular expression.

An error occurs if any of the following conditions is true:

  • No template can be retrieved.
  • The template does not exist.
  • More than one template matches the name and the most_recent flag is not set.

If more than one template is returned, set most_recent to true to sort the results in descending order by creation date. By default, the newest template is used.

The data source name is skytap_template and the following fields are defined:

Field Name Type Description
name string (required) A regular expression representation of the template name.
most_recent Boolean (optional) Use the most recently created template from the returned list.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The unique ID of the template.
Example Usage

Get the template:

data "skytap_template" "example" {
  name = "18.04"
  most_recent = true
}

skytap_project

Get information on a project A set of shared templates, environments, and assets. Users gain access to shared resources by becoming a member of a project. To learn more, see Sharing resources with projects. . This data source provides the id, name, summary, auto_add_role_name and show_project_members properties of a project as configured in your Skytap account. Use to obtain the project’s id via its name.

An error occurs if any of the following conditions is true:

  • No projects can be retrieved.
  • The project does not exist.
  • More than one project matches the name.
Example Usage

Get the project:

data "skytap_project" "example" {
  name = "example"
}
Argument Reference

The following arguments are supported:

Field Name Type Description
name string (required) The name of project.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the project.
summary string The summary description of the project.
auto_add_role_name string The role automatically assigned to every new user added to the project.
show_project_members Boolean Whether project members can view a list of the other project members.

Resources

skytap_environment

Provides a Skytap environment An object that comprises one or more VMs, one or more networks, plus configuration settings and metadata. You can save the exact state of an environment as a read-only template. To learn more, see Skytap Cloud quick start: Building your first environment. resource. Unlike a template, an environment can be run and be modified. When an environment is created, all of its VMs are run.

When you create an environment from a template, terraform does note enumerate the resources contained within that template, including VMs and networks. If you remove a resource (such as a VM Virtual Machine – A virtual computer or server hosted within a data center. A VM runs a full operating system and applications. Each VM has virtual resources, including CPU, RAM, file system storage, CD/DVD drive, and network interfaces. or network) from the environment, terraform does not automatically restore that resource.

Example Usage
# Create a new environment
resource "skytap_environment" "environment" {
  template_id = "123456"
  name = "Terraform Example"
  description = "Skytap terraform provider example environment."
  tags = ["example", "terraform"]
  timeouts {
    create = "20m"
    delete = "1h"
  }
}
Argument Reference

The following arguments are supported:

Field Name Type Description
template_id string (required, force new) ID of the template you want to create an environment from. If updating with a new one then the environment is recreated.
name string (required) User-defined name of the environment. Limited to 255 UTF-8 characters. Defaults to the name of the source template name if null is provided.
description string User-defined description of the environment. Limited to 1000 characters. Null permitted.
outbound_traffic Boolean (optional) Indicates whether networks in the environment can send outbound traffic.
routable Boolean (optional) Indicates whether networks within the environment can route traffic to one another.
shutdown_at_time datetime (optional) The date and time that the environment is automatically shut down. Format: yyyy/mm/dd hh:mm:ss. By default, the suspend time uses the UTC offset for the time zone defined in your user account settings.

Optionally, a different UTC offset can be supplied (for example: 2018/07/20 14:20:00 -0000). The value in the API response is converted to your time zone.

shutdown_on_idle integer (optional) The number of seconds an environment can be idle before it is automatically shut down. Valid range: 300 to 86400 seconds (5 minutes to 1 day).
suspend_at_time datetime (optional) The date and time that the environment is automatically suspended. Format: yyyy/mm/dd hh:mm:ss. By default, the suspend time uses the UTC offset for the time zone defined in your user account settings. Optionally, a different UTC offset can be supplied (for example: 2018/07/20 14:20:00 -0000). The value in the API response is converted to your time zone.
suspend_on_idle integer (optional) The number of seconds an environment can be idle before it is automatically suspended. Valid range: 300 to 86400 seconds (5 minutes to 1 day).
tags string (optional) A list of tagstag: A text value attached to a Skytap resource to improve search results. For more details about tags, see Organizing resources with labels and tags for the environment.
label array (optional) One or more label A text key/value pair attached to a Skytap resource to enhance usage reporting. For more details, see Using labels for in-depth usage reporting. s for the environment. The label block must include the following parameters:
Field NameTypeDescription
categorystring(required) A unique category name for the label.
valuestringThe value associated with the category.
See skytap_label_category.
user_data string (optional) Metadata associated with the environment, accessible from both the Skytap metadata service via an HTTP GET request, or via the Skytap REST API. For additional details about metadata, see Accessing the VM metadata service (and user data fields) from within the VM.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create an environment.
    updatestringThe allowed period of time to update an environment.
    deletestringThe allowed period of time to delete an environment.

Notes

  • If suspend_on_idle and suspend_at_time are both null, automatic suspend is disabled.
  • If shutdown_on_idle and shutdown_at_time are both null, automatic shut down is disabled.
  • An environment can’t be configured to use both automatic suspend and automatic shut down. Only one of the following settings can take effect: suspend_on_idle, suspend_at_time, shutdown_on_idle, or shutdown_at_time.
  • When you send a request that updates one of the four suspend or shutdown options, the other three options are automatically set to null by the REST API.
  • If multiple suspend or shut down options are sent in the same request, the suspend_type field determines which setting Skytap Cloud will honor.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the environment.

skytap_vm

Provides a Skytap VM Virtual Machine – A virtual computer or server hosted within a data center. A VM runs a full operating system and applications. Each VM has virtual resources, including CPU, RAM, file system storage, CD/DVD drive, and network interfaces. resource. The VM resource represents an image of a single virtual machine.

Notes

  • VMs exist only inside environments and templates.
  • An environment or template can have multiple VMs.
  • Each VM is a unique resource. A VM in a template will have a different ID than a VM in an environment created from that template.
  • The VM is run immediately after creation.
Example Usage
# Create a new vm
resource "skytap_vm" "vm" {
  template_id = 123
  vm_id = 456
  environment_id = 789
  name = "my vm"
  cpus = 4
  ram = 4096
  timeouts {
    create = "60m"
    delete = "2h"
  }

  os_disk_size = 40000

  disk {
    name = "my disk"
    size = 4096
  }
  disk = {
      name = "my other disk"
      size = 4096
  }

  network_interface {
    interface_type = "vmxnet3"
    network_id = "${skytap_network.my_network.id}"
    ip = "10.0.0.1"
    hostname = "myhost"

    published_service {
      name = "ssh"
      internal_port = 22
    }
  }
}

# Will work after VM resource is created
output "ssh_ip" {
  value = "${skytap_vm.vm.service_ips.ssh}"
}
output "ssh_port" {
  value = "${skytap_vm.vm.service_ports.ssh}"
}
Argument Reference

The following arguments are supported:

Field Name Type Description
environment_id string (required, force new) ID of the environment you want to add the VM to. If updating with a new one then the VM is recreated.
template_id string (required, force new) ID of the template you want to create the VM from. If updating with a new one then the VM is recreated.
vm_id string (required, force new) ID of the VM you want to create the VM from. If updating with a new one then the VM is recreated.
name string (optional, computed) User-defined name. Limited to 100 characters.

The name is truncated to 33 UTF-8 characters after saving. If no name is provided, the name of the source VM is used.

cpus integer (optional, computed) The number of CPUs allocated to this virtual machine. Valid range is 1 to max_cpus (generally, 12).
ram integer (optional, computed) The amount of RAM (in MB) allocated to this virtual machine. Valid range is 256 to max_ram (generally 131,072 MB).
os_disk_size integer (optional, computed) The size of the disk (in MB—converted to GB in the Skytap UI) that hosts the OS for this virtual machine. Maximum size is 2,096,128 MB (1.999 TB).
disk array (optional) Array of virtual disks (in MB—converted to GB in the Skytap UI) within the VM. Maximum combined size is 2,096,128 MB (1.999 TB).
Field NameTypeDescription
namestring(required) A unique name for the disk.

Disk names are truncated to 33 UTF-8 characters after saving. If a name is not provided then the name of the source VM is used.

sizeintegerThe size of the disk (in MB—converted to GB in the Skytap UI). Maximum size is 2,096,128 MB (1.999 TB).
network_interface array (optional, computed, force new) A Skytap network adapter is a virtualized network interface card (network adapter). It is logically contained in a VM and attached to a network.
Field NameTypeDescription
interface_typestring(required, force new) Type of network to which this network adapter is attached.
network_idstring(required, force new) ID of the network to which this network adapter is attached.
ipIP v4 address(required, force new) The IP address (for example, 10.1.0.37). Skytap will not assign the same IP address to multiple interfaces on the same network.
hostnamestring(required, force new) Limited to 32 characters. Valid characters are lowercase letters, numbers, and hyphens. Can't begin or end with hyphens. Can't be gw.
published_service array (optional, force new) Generally, a published service represents a binding of a port on a network interface to an IP and port that is routable and accessible from the public Internet. This mechanism is used to selectively expose ports on the guest to the public Internet.

Published services exist and are managed as aspects of network interfaces—that is, as part of the overall environment element.

Field NameTypeDescription
namestring(required, force new) A unique name for the published service.
internal_portstring(required, force new) The port that is exposed on the interface. Typically this is dictated by standard usage (e.g., port 80 for http traffic, port 22 for SSH).
label string (optional) One or more label A text key/value pair attached to a Skytap resource to enhance usage reporting. For more details, see Using labels for in-depth usage reporting. s for the VM. The label block must include the following parameters:
Field NameTypeDescription
categorystring(required) A unique category name for the label.
valuestringThe value associated with the category.
See skytap_label_category.
user_data string (optional) Metadata associated with the VM, accessible from both the Skytap metadata service via an HTTP GET request, or via the Skytap REST API. For additional details about metadata, see Accessing the VM metadata service (and user data fields) from within the VM.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create a VM.
    updatestringThe allowed period of time to update a VM.
    deletestringThe allowed period of time to delete a VM.

To change cpus or ram settings for an existing VM, you must first shut down the VM.

Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the VM.
max_cpus integer The maximum number of CPUs available to a VM.
max_ram integer The maximum amount of RAM (in MB) available to a VM.
disk array The disks attached to the VM.
Field NameTypeDescription
idstringThe ID of the disk.
typestringThe type of the disk.
controllerstringThe disk controller.
lunintegerThe Logical Unit Number of the disk.
network_interface array The network adapters attached to the VM.
Field NameTypeDescription
idstringThe ID of the network interface.
published_service array The published services attached to the VM.
Field NameTypeDescription
idstringThe ID of the published service.
external_ipstringThe external IP address of the published service.
external_portstringThe external port of the published service.
service_ips array A map of external IP addresses. The key is the name of a published service - as defined in the published_service block.
service_ports array A map of external ports. The key is the name of a published service - as defined in the published_service block.

skytap_network

Provides a Skytap network resource. Networks are not top-level elements of the Skytap API. They are elements properly contained within an environment. Operations on them are implicitly on the containing environment.

Example Usage
# Create a new network
resource "skytap_network" "network" {
  environment_id = "123456"
  name = "my network"
  domain = "domain.com"
  subnet = "1.2.3.4/16"
  gateway = "1.2.3.254"
  tunnelable = true
  timeouts {
    create = "20m"
    delete = "5m"
  }
}
Argument Reference

The following arguments are supported:

Field Name Type Description
environment_id string (required, force new) ID of the environment you want to attach the network to. If updating with a new one then the network is recreated.
name string (required) User-defined name of the network. Limited to 255 characters. UTF-8 character type.
domain string (required) Domain name for the Skytap network. Limited to 64 characters.

Valid characters are lowercase letters, numbers, and hyphens. Can't be blank, must not begin or end with a period, and must start and end with a letter or number. This field can be changed only when all virtual machines in the environment are stopped (not suspended or running).

subnet string (required) Defines the subnet address and subnet mask size in CIDR format (for example, 10.0.0.0/24). IP addresses for the VMs are assigned from this subnet and standard network services (DNS resolution, CIFS share, routes to Internet) are defined appropriately for it.

The subnet mask size must be between 16 and 30. Valid characters are lowercase letters, numbers, and hyphens. Can't be blank, must not begin or end with a period, and must start and end with a letter or number.

gateway string (optional, computed) Gateway IP address.
tunnelable Boolean (optional) If true, this network can be connected to other networks.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create a network.
    updatestringThe allowed period of time to update a network.
    deletestringThe allowed period of time to delete a network.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the network.

skytap_project

Provides a Skytap project A set of shared templates, environments, and assets. Users gain access to shared resources by becoming a member of a project. To learn more, see Sharing resources with projects. resource. Projects are an access permissions model used to share environments, templates, and assets with other users.

Example Usage
# Create a new project
resource "skytap_project" "project" {
  name = "Terraform Example"
  summary = "Skytap terraform provider example project."
  show_project_members = false
  auto_add_role_name = "participant"
  timeouts {
    create = "30s"
    delete = "10s"
  }
}
Argument Reference

The following arguments are supported:

Field Name Type Description
name string (required) User-defined project name.
summary string (optional) User-defined description of project.
auto_add_role_name string

(optional)

  • If this field is set to viewer, participant, editor, or manager, new users added to your Skytap account are automatically added to this project with the specified project role. Existing users aren’t affected by this setting.
  • If the field is set to null, new users aren’t automatically added to the project.

For additional details, see Automatically adding new users to a project.

show_project_members Boolean (optional) Determines whether projects members can view a list of other project members. The default value is false.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create a project.
    updatestringThe allowed period of time to update a project.
    deletestringThe allowed period of time to delete a project.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the project.

skytap_icnr_tunnel

Provides an ICNR Tunnel. Inter-Configuration Network Routing connects networks from different environments to a single, shared server. Without ICNR, environments are on isolated networks. For more information, see Networking between environments.

Example Usage
resource "skytap_environment" "env1" {
  template_id = "123"
  name = "env1"
  description = "This is an environment example"
}

resource "skytap_environment" "env2" {
  template_id = "%s"
  name = "%s-environment-%d"
  description = "This is an environment example"
}

resource "skytap_network" "net1" {
  environment_id = "${skytap_environment.env1.id}"
  name = "net1"
  domain = "domain.com"
  subnet = "10.0.100.0/24"
  gateway = "10.0.100.254"
  tunnelable = true
}

resource "skytap_network" "net2" {
  environment_id = "${skytap_environment.env2.id}"
  name = "net2"
  domain = "domain.com"
  subnet = "10.0.200.0/24"
  gateway = "10.0.200.254"
  tunnelable = true
}

# Create an ICNR Tunnel between both networks.
resource "skytap_icnr_tunnel" "tunnel" {
  source = "${skytap_network.net1.id}"
  target = "${skytap_network.net2.id}"
  timeouts {
    create = "4m"
    delete = "40s"
  }
}
Argument Reference

The following arguments are supported:

Field Name Type Description
source string (required, force new) Source network from where the connection was initiated. This network doesn’t need to be visible to other networks).
target string (required, force new) Target network to which the connection was made. The network must be visible to other networks.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create an ICNR tunnel.
    updatestringThe allowed period of time to update an ICNR tunnel.
    deletestringThe allowed period of time to delete an ICNR tunnel.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the tunnel.

skytap_label_category

Provides a Skytap label category resource. Label categories provide a taxonomy of the usa reporting, once the label category is define it can be use to label resources. There are restrictions for the use of labels for example:

An account can have a maximum of 100 active categories. An account can have a maximum combined total active and inactive (deleted) 200 categories. NOTE: Creating a label category fail when we reuse the name and change for label single value.

Example Usage
# Create a new label_category
resource "label_category" "env" {
  name = "environment"
  single_value = true
}
Argument Reference

The following arguments are supported:

Field Name Type Description
name string (required) User-defined label category name.
single_value Boolean (required) When true, a label can have only one value per category. When false, a label can have multiple values per category.
timeouts string (optional) The allowed duration of an operation before it is considered to have failed.

The format for timeout values is {integer}{units}, where units is one of:

  • h – hours
  • m – minutes
  • s – seconds
  • The default value for all operations is 10 minutes (10m).

    Field NameTypeDescription
    createstringThe allowed period of time to create a label category.
    updatestringThe allowed period of time to update a label category.
    deletestringThe allowed period of time to delete a label category.
Attributes Reference

The following attributes are exported:

Field Name Type Description
id string The ID of the label category.