Home

Welcome to the terraform-provider-foreman wiki!

Completeness

As summarized in discussion #139 "Completeness", the current state of the provider plugin supports the following Foreman/Katello APIs:

API resource	available	status
foreman common_parameters	x	production-ready
foreman compute_attributes	x	production-ready
foreman compute_profiles	x	new feature (PR #134)
foreman compute resources	x
foreman domains	x	production-ready
foreman hostgroups	x	production-ready
foreman hosts	x	production-ready
foreman http_proxies	x
foreman images	x	fixed recently (PR #133)
foreman interfaces	x	production-ready (please note issue #126)
foreman job_templates	x	not yet released (PR #138)
foreman locations
foreman media	x	production-ready
foreman models	x	production-ready
foreman operatingsystems	x	production-ready
foreman os_default_templates	x
foreman paramters	x	production-ready
foreman provision templates	x	production-ready
foreman ptables	x	production-ready
foreman puppetclasses	x
foreman realms
foreman settings	x	new feature (PR #120)
foreman smart_proxies	x
foreman subnets	x	production-ready
foreman tasks
foreman template_inputs	x	not yet released (PR #138)
foreman template_kinds	x	production-ready
foreman usergroups	x
foreman users	x
katello content_credentials	x
katello content views		issue #140
katello errata
katello host_collections
katello lifecycle environments		issue #141
katello packages
katello products	x	latest fix not yet released (PR #142)
katello repositories	x	latest fix not yet released (PR #143)
katello subscriptions
katello sync_plans	x	latest fix not yet released (PR #143)

Note: "production-ready" means that we used this kind of Terraform resources very often in a production environment

Development

The development of the Terraform provider plugin is based on the Terraform SDKv2 framework. You should familiarize yourself with the Terraform plugin development workflow and how Terraform uses plugins during runtime: developer.hashicorp.com/terraform/plugin.

Basically, you write a binary that provides a gRPC interface for the Terraform binary. During a Terraform run (e.g. terraform apply), the plugin binary is executed and the provider supplies Terraform with its functionality. In this case the Foreman and Katello API wrapping.

After cloning, you'll find the following directory structure:

.
├── autodoc
├── cmd                     <-- autodoc related code
│   └── autodoc
├── CONTRIBUTING.md
├── docs                    <-- auto-generated mkdocs output (from code)
│   ├── data-sources
│   │   └── foreman_*.md
│   ├── index.md
│   └── resources
│       └── foreman_*.md
├── examples                <-- Terraform manifests (*.tf) with tested use-cases
│   ├── architecture            for each resource
│   │   └── main.tf
│   ├── *
│   └── verify_provider     <-- special case, see README
│       ├── main.tf
│       └── tfoverriderc
├── foreman                 <-- main provider plugin code
│   ├── api                 <-- Foreman HTTP API wrapper code
│   │   ├── ...
│   │   ├── client.go       <-- HTTP client used in all calls
│   │   ├── client_test.go
│   │   ├── ...
│   │   ├── core.go
│   │   ├── core_test.go
│   │   └── *.go
│   ├── config.go
│   ├── data_source_foreman_*.go       <-- all data source implementations of Foreman/Katello objects
│   ├── data_source_foreman_*_test.go
│   ├── foreman_api_test.go
│   ├── provider.go                    <-- provider meta code
│   ├── resource_foreman_*.go          <-- all resource implementations of Foreman/Katello objects
│   ├── resource_foreman_*_test.go
│   ├── ...
│   ├── resource_helper.go
│   ├── testdata            <-- JSON files with testdata for API mocking
│   │   ├── 1.11
│   │   ├── 1.20
│   │   ├── 3.1.2
│   │   └── 3.6
├── go.mod
├── go.sum
├── LICENSE
├── main.go                 <-- main entry point for the plugin binary
├── mkdocs.yml
├── README.md
├── templates
│   ├── ...
└── terraform-provider-foreman.log

The most important folders are

• foreman with its Terraform definitions (resources and data sources) and
• foreman/api which holds the HTTP API wrapper code.

In between these two "layers", conversions of the objects are handled via Go structs and conversion functions. Especially the handling of Terraform states (ResourceData) is very important, because they reflect the input from the user's manifests.

The Foreman API is a basic REST API and documented at apidocs.theforeman.org/foreman/ and apidocs.theforeman.org/katello/. The API has some inconsistencies which require special care in the API wrapper. This is mostly noticeable between Foreman and Katello, because Katello as a plugin for Foreman was written by a different team and therefore follows a different implementation strategy.