Foreman Terraform Provider

Terraform provider to interact with Foreman and, partly, Katello.

Use the provider from the official Terraform registry: registry.terraform.io/providers/terraform-coop/foreman.

This is a fork of the project previously developed, owned, and maintained by the SRE - Orchestration pod at Wayfair.

This repository uses mkdocs for documentation and Go modules for dependency management. Dependencies are tracked as part of the repository.

Example use-cases of this provider are included in this repository under ./examples. See the examples for more information.

Changes in 0.6.x

Starting with v0.6.0 some (breaking) changes require an update of Terraform manifests.

• The host build argument was removed (0.6.0) and is replaced by set_build_flag. (0.6.1)
  • The reason behind this change is complex and was thoroughly discussed in #125
  • Using the argument does one thing: it tells Foreman to set the build flag for a host. It defaults to false, setting it to true causes the host to be re-installed on next boot (network-based installation).
• The method argument is re-introduced as provision_method. It can be either build (network-based) or image (image-based).
  • Both options require different additional arguments, e.g the image to be used. See examples/host/.
• The host name argument was considered for deprecation (0.6.0).
  • The name attribute has issues based on the "append_domain_name" setting in Foreman. It causes "inconsistent plan" errors when you give it a shortname as value, Terraform receives an FQDN back, and the name attribute is then used in variables in other places in your Terraform manifests.
  • As an alternative, the shortname argument can be used instead. It is meant for the hostname without the domain part. If you use name as input argument, shortname will be filled by the provider automatically.
  • To get the host's FQDN from the provider, use the read-only attribute fqdn. (0.6.1)
  • Use shortname and fqdn as variables in your manifests! Example: other_server = foreman_host.other_server.fqdn. This will prevent you from running into inconsistent plans.

Requirements

• Terraform >= 0.12.x
• Golang >= 1.13

Follow the setup instructions provided on the install sections of their respective websites. Windows environments should have a *nix-style terminal emulator installed such as Cygwin to be compatible with the makefile.

Foreman Requirements

The following tools might be useful to control power of bare-metal hosts through proxy in your setup:

• Foreman BMC Plugin
• ipmitool

Foreman Smart proxies will need to be provisioned with the Foreman BMC plugin and have the ipmitool installed.

In case you are still using an older version of Foreman with disabled organizations and locations (< 1.21), you need to disable organizations and locations in the provider by setting organization_id and location_id to a value < 0.

Provider / Repository Setup

After installing and configuring the toolchain listed in the Requirements section:

1. Clone the repository with ssh:

   $ go get -u github.com:terraform-coop/terraform-provider-foreman

2. Enter the root directory of the project and install the provider:

   $ export CGO_ENABLED=0
   $ go build -trimpath -ldflags '-s -w'

   NOTE: See the Third-party Plugins section on Terraform's website over here

3. Initialize Terraform and verify the provider is recognized by terraform:

   $ cd ./examples/verify_provider
   $ terraform init
   $ terraform --version

   You should see the foreman provider in the output like in the listing below. Other providers may be listed if you have already configured Terraform. Your version info may be different depending on the version of Terraform you installed as part of the Requirements.

   Terraform v0.12.15
   + provider.foreman (unversioned)
   

   NOTE: Some builds of Terraform will require subdirectories underneath terraform.d/plugins organized by operating system and architecture. If this is the case, create the directory (if it doesn't exist) and then place the plugin within that directory. If your terraform init failed with the following message Provider "foreman" not available for installation, then this is likely the case. Read the error message and create the correct subdirectory. For 64 bit Windows, this will be terraform.d/plugins/windows_amd64. So in step 2, confirm the provider binary is located at terraform.d/plugins/windows_amd64/terraform-provider-foreman.exe and then try step 3 again.

Documentation

The rendered documentation is available at terraform-coop.github.io/terraform-provider-foreman.

This repository uses mkdocs for documentation. Follow the installation instructions on mkdocs to get started or use the auto-generated documentation available on the Github Pages for this project.

The mkdocs configuration and associated markdown is auto-generated for the provider using the autodoc package from the utility repository. The autodoc tool uses text templates defined in templates and the schema definitions in the provider to generate all the necessary mkdocs files and resources. The autodoc command is located in cmd/autodoc/main.go.

To generate and view the entire repository and in-depth provider documentation:

$> go build -v -o autodoc $(go list ./cmd/autodoc)
$> mkdir -p docs/{data-sources,resources}
$> ./autodoc
$> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

The documentation can then be viewed by accessing localhost in your favorite browser or viewport.

Logging

NOTE: When developing, it may be useful to setup terraform logging. A full list of Terraform environment variables can be found here. At minimum, it is advised to set the log level to DEBUG like so:

MacOS / Linux

$ export TF_LOG=DEBUG

Windows

> $env:TF_LOG = "DEBUG"

The provider is set to log to the file terraform-provider-foreman.log with all Foreman provider specific log messages sent to this file. When the provider is executed, it will create the provider log file in the current working directory (if it does not exist). If the log file already exists, then the logs are appended to the existing file. In the case the provider cannot create/open the desired log file, the provider defaults to sending log messages to stderr.

The provider uses a level-based logging module that extends the golang stdlib log package. When the log level is set to a verbosity threshold, only log messages of that verbosity and higher are sent to the output file.

From most verbose to least verbose:

Log Level	Description
DEBUG	Intermediate calculations, values. Useful when debugging.
TRACE	Function enter/exit notifications
INFO	Notifications - not related to suspicious behavior or errors
WARNING	Suspcious or error behavior, but the system was able to recover or default/degrade gracefully
ERROR	Behavior that causes the program execution to stop
NONE	Do not log any output

The provider's log level defaults to INFO, meaning INFO, WARNING, and ERROR messages are committed to the log file, DEBUG and TRACE are ignored. The log level can be overridden by either setting the provider_loglevel attribute in the provider block of the Terraform module, or by setting the environment variable FOREMAN_PROVIDER_LOGLEVEL. If both values are set, provider_loglevel takes precedence. You can also override the Foreman provider's log file using the FOREMAN_PROVIDER_LOGFILE environment variable. A value of - preserves the stdlib log behavior and outputs to the stdlog stream.

Ex:

Terraform module

provider "foreman" {
  ...
  provider_loglevel = "DEBUG"
  provider_logfile  = "terraform-provider-foreman.log"
  ...
}

MacOS / Linux

$> export FOREMAN_PROVIDER_LOGLEVEL="DEBUG"
$> export FOREMAN_PROVIDER_LOGFILE="terraform-provider-foreman.log"

Windows

> $env:FOREMAN_PROVIDER_LOGLEVEL = "DEBUG"
> $env:FOREMAN_PROVIDER_LOGFILE = "terraform-provider-foreman.log"