Terraform¶
The following instructions to install the needed Digital Rebar Provision integrations to support Terraform. Terraform integrations require that machines can reboot.
The Terraform system is not synchronized with Digital Rebar, this documentation is only intended to cover the provider.
Note: As of DRP v3.8 (workflows enabled), changes to bootenvs will automatically cause reboots if the DRP runner/agent is allowed to keep running. Otherwise, an IPMI plugin is required. We recommend using both Workflow and IPMI based reboots to ensure that the systems return to a consistent state.
Source Code: https://gitlab.com/rackn/terraform-provider-drp
Video Demos: * v3.8 DRP https://youtu.be/RtuZQHKmd9U * v3.2 DRP https://www.youtube.com/watch?v=6MLyUVgnVo4
License¶
The Terraform Provider for Digital Rebar Provision is APLv2 licensed. Advanced features or workflow may require capabilities that use different licenses.
Prereqs¶
Before starting this process, a Digital Rebar Provision (DRP) server is required, along with the ability to provision machines. These machines could be VMs, Packet servers or physical servers in a data center.
You must also have installed Terraform and secured the Digital Rebar Provision Terraform Provider. You can build the provider from source or retrieve a compiled version from the Github releases area, https://gitlab.com/rackn/terraform-provider-drp/releases.
Basic Operation¶
The DRP Terraform Provider uses a pair of Machine Parameters to create an inventory pool. Only machines with these parameters will be available to the provider.
The terraform/managed
parameter determines the basic inventory availability. This flag must be set to true for Terraform to find machines.
The terraform/allocated
parameter determines when machines have been assigned to a Terraform plan. When true, the machine is now being managed by Terraform. When false, the machine is available for allocation.
Using the RackN terraform-ready
stage will automatically set these two parameters.
The Terraform Provider can read additional fields when requesting inventory. In this way, users can request machines with specific characteristics.
DRP Machine Configuration¶
Note
These instructions assume that you are using the RackN extension; however, it is not required for Terraform operation.
Install the Terraform
content package from RackN. This content provides the parameters (described above) and a stage (terraform-ready
) to configure Terraform properties on machines.
Create a workflow that includes the terraform-ready
stage to set the two parameters. Once these values are set they do not have to be run again, but there is no harm in leaving the stage in place.
Before testing Terraform, it is good practice to make sure you can manually cycle machines by changing their workflow (or change stage and reboot). These changes should result in a machine provisioning cycle.
Make sure that you know your endpoint URI, user and password.
Installing The Terraform Digital Rebar Provision Provider¶
Please install Terraform on your system: https://www.terraform.io/intro/getting-started/install.html
Download (or build) the DRP Provider from https://gitlab.com/rackn/terraform-provider-drp/releases.
Initialize the plugin using terraform init
Create a Plan using the DRP Provider Resources¶
The DRP Provider exposes all the objects in Digital Rebar Project so you can script against any operation.
The critical block is the provider block which identifies the provider and login information (shown here with default values):
variable "api_url" {
default = "https://127.0.0.1:8092"
}
variable "api_user" {
default = "rocketskates"
}
variable "api_password" {
default = "r0cketsk8ts"
}
provider "drp" {
api_user = "${var.api_user}"
api_password = "${var.api_password}"
api_url = "${var.api_url}"
}
Once you have the provider block, you can name resource blocks using the normal object key values. For example, a machine resource looks like this:
resource "drp_machine" "one_random_node" {
count = 1
Workflow = "centos-7"
Description = "updated description"
Name = "greg2"
userdata = "yaml cloudinit file"
}
You can set any Machine property by naming the property with correct capitalization. You can use the Terraform syntax to create more complex models like Meta, Profiles.
Note
If you set Profiles, Params or Meta you will override other existing information in the machine! The following helpers have been defined to avoid this:
add_profiles
: allows you to add profiles to the machine without override other profiles.
There are many options to set including filters, parameters and profiles. For a full example, please look at https://gitlab.com/rackn/terraform-provider-drp/blob/master/test.tf.example
Picking Machines with a Pool¶
You can add a pool
block into the plan that will select machines based on the pool name. This is helpful if you want to partiation your machines. Pools use the terraform/pool
Param on the machines and will be assumed to be default
if omitted.
For example:
Picking Machines with Filter¶
You can add a filters
block into the plan that will select machines based on criteria. This is helpful if you want to select specific types of machines based on Param data. Filters use the API filters definition and are JSON formatted (types are guessed so numbers and bools are coerced).
For example:
You can only filter on indexed fields and defined Params. Further, you cannot search deeply into Params, only the first level value is matched.
Special Complete and Decommissioning Fields¶
The provider watches until the machine reaches the complete
or complete-no-wait
stages; however, you can customize this behavior by setting the completion_stage
to the plan.
You can override the default the decommissioning flow (set workflow or stage back to discover
) by adding decommission_workflow = "my_decom_workflow"
to the plan.
You can also override the return icon (map outline
) and color ('black') by adding decommission_icon
and decommission_color
to the plan. Machine icons are handy ways to quickly show status of a provisioning cycle.
Users can set icons using
Creating RAW Machines using Cloud IPMI plugins¶
The drp_machine
resource relies on having a pool of machines already configured; however, you can use the drp_raw_machine
resource to create machines in Digital Rebar Provision. If you are using an IPMI plugin that supports creating machines, such as Packet or Virtualbox, and set the machine-plugin
value then the plugin will create (and destroy) the associated machine in the target platform. This can be a very powerful way to build and manage clusters.
It is possible to use raw and pooled machines together by also setting the terraform/managed
and terraform/allocated
parameters when creating machines. This will allow Terraform to treat newly created machines as a pool. It's important to include chained depends_on
in the resource blocks when using this approach in a single plan.
You may also set terraform/pool
to something. The default behavior assumes default
but you can use this Param to manage multiple pools of resources. Select pools using pool
in the drp_machine
resources.
Note
Unlike the drp_machine
resource, this resource does not wait until the workflow has completed. It will return when the machine has been create API returns.
An example of the drp_raw_machine
resource with correct parameter values is
ini
resource "drp_raw_machine" "packet-machines" {
Description = "Terraform Added RAW"
Workflow = "discover"
Name = "packet_machine"
Params {
"machine-plugin" = "packet-ipmi"
"packet/plan" ="baremetal_0"
"terraform/managed" = "true"
"terraform/allocated" = "false"
"terraform/pool" = "default"
}
Running Terraform¶
Just use terraform apply
and terraform destroy
and as normal!
Note
The examples above use variables for endpoint login. The syntax for overriding these variables to set environment variables starting with export TF_VAR_my_var=
and the variable name or pass -var 'api_url=https://[ip address]:8092'
. User names and passwords should never be hard coded into plan files!
Extending the Features¶
Using the terraform/owner
parameter helps administrators track who is using which machines. You may also choose to create multiple DRP users to help track activity.
It is highly recommended that you include decommissioning steps (disk scrub, bios reset, etc) and additional burn-in to validate systems during the recovery cycle.
Using IPMI to reset machines is a safer bet than relying on the DRP runner to soft reboot systems. If you want to make sure that you have a consistent recovery process, IPMI is highly recommended.
To improve delivery time:
- Keep the machines running
- Use image based provisioning instead of netboot.
Note
If you are relying on the DRP Running workflow to start allocation and recovery, make sure that you have your tokens set to never expire!
Summary¶
Now that these steps are completed, the Digital Rebar Provision Terraform Provider will integrate like any cloud provider.