Skip to content

Commit 3f68793

Browse files
maximiliankolbmaximiliankolb
committed
Add docs for foreman_opentofu
Refs https://github.com/ATIX-AG/foreman_opentofu/
1 parent 627d79c commit 3f68793

12 files changed

Lines changed: 335 additions & 0 deletions

‎guides/common/assembly_provision-hosts-through-opentofu.adoc‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
:compute-resource-id: opentofu
4+
:compute-resource-name: OpenTofu
5+
:parent-context: {context}
6+
:context: opentofu-provisioning
7+
:opentofu-provisioning:
8+
9+
include::modules/con_provision-hosts-through-opentofu.adoc[]
10+
11+
include::modules/ref_supported-opentofu-targets.adoc[leveloffset=+1]
12+
13+
include::modules/proc_install-the-opentofu-plugin.adoc[leveloffset=+1]
14+
15+
:compute-resource-target-id: hetzner-cloud
16+
:compute-resource-target-name: Hetzner Cloud
17+
:hetzner-cloud:
18+
include::modules/proc_connect-project-to-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
19+
20+
// TODO: Somehow broken to add OpenTofu-based compute resource to Foreman via CLI
21+
// include::modules/proc_connect-project-to-opentofu-target-by-using-cli.adoc[leveloffset=+1]
22+
23+
include::modules/proc_create-a-predefined-configuration-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
24+
25+
// TODO: Document procedure via Hammer CLI
26+
// include::modules/proc_create-a-predefined-configuration-for-hosts-on-opentofu-target-by-using-cli.adoc[leveloffset=+1]
27+
28+
include::modules/proc_define-an-image-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
29+
30+
// TODO: Document procedure via Hammer CLI
31+
// include::modules/proc_define-an-image-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
32+
33+
include::modules/proc_provision-a-host-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
34+
35+
// TODO: Document procedure via Hammer CLI
36+
// include::modules/proc_provision-a-host-on-opentofu-target-by-using-cli.adoc[leveloffset=+1]
37+
38+
include::modules/proc_delete-a-host-on-compute-resource-target.adoc[leveloffset=+1]
39+
40+
:!compute-resource-target-id:
41+
:!compute-resource-target-name:
42+
:!hetzner-cloud:
43+
44+
:compute-resource-target-id: nutanix
45+
:compute-resource-target-name: Nutanix
46+
:nutanix:
47+
include::modules/proc_connect-project-to-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
48+
49+
// TODO: Somehow broken to add OpenTofu-based compute resource to Foreman via CLI
50+
// include::modules/proc_connect-project-to-opentofu-target-by-using-cli.adoc[leveloffset=+1]
51+
52+
include::modules/proc_create-a-predefined-configuration-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
53+
54+
// TODO: Document procedure via Hammer CLI
55+
// include::modules/proc_create-a-predefined-configuration-for-hosts-on-opentofu-target-by-using-cli.adoc[leveloffset=+1]
56+
57+
include::modules/proc_define-an-image-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
58+
59+
// TODO: Document procedure via Hammer CLI
60+
// include::modules/proc_define-an-image-for-hosts-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
61+
62+
include::modules/proc_provision-a-host-on-opentofu-target-by-using-web-ui.adoc[leveloffset=+1]
63+
64+
// TODO: Document procedure via Hammer CLI
65+
// include::modules/proc_provision-a-host-on-opentofu-target-by-using-cli.adoc[leveloffset=+1]
66+
67+
include::modules/proc_delete-a-host-on-compute-resource-target.adoc[leveloffset=+1]
68+
69+
:!compute-resource-target-id:
70+
:!compute-resource-target-name:
71+
:!nutanix:
72+
73+
[appendix]
74+
include::modules/ref_opentofu-settings.adoc[leveloffset=+1]
75+
76+
:!compute-resource-id:
77+
:!compute-resource-name:
78+
:!opentofu-provisioning:
79+
:context: {parent-context}
80+
:!parent-context:

‎guides/common/modules/con_provision-hosts-through-opentofu.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="provisioning-hosts-through-{compute-resource-id}"]
4+
= Provision hosts through {compute-resource-name}
5+
6+
[role="_abstract"]
7+
{Project} can interact with multiple clouds and virtualization solutions through {compute-resource-name}.
8+
You can create hosts and control their power management states through {Project}.
9+
10+
{Project} uses {compute-resource-name} to act as a unified interface to provision and manage hosts on several clouds and virtualization platforms.
11+
After an initial setup, you can create hosts on different compute resource providers with the same workflow.
12+
13+
// TODO: Rework docs based on this overview.
14+
// Admin: Enables OpenTofu plugin; something that you do once
15+
// "Manager": Sets up a specific compute resource target, for example, Hetzner; recurring action for each hypervisor/cloud
16+
// User: a) Customizes the provisioning workflow by creating a host group and b) Deploys hosts
17+
18+
Enable {compute-resource-name}-based host provisioning::
19+
. Install the {compute-resource-name} plugin on your {ProjectServer}.
20+
. Connect {Project} to a supported compute resource target.
21+
. Define an image from your compute resource target in {Project}.
22+
. Create a compute profile to bundle hardware settings.
23+
24+
Customize {compute-resource-name}-based host provisioning::
25+
. Depending on your use case, create additional compute profiles.
26+
. Create a host group as blue print to standardize host deployments.
27+
28+
Provision hosts::
29+
. Select a host group.
30+
. Customize settings to your needs.
31+
. Provision a host.

‎guides/common/modules/proc_connect-project-to-opentofu-target-by-using-web-ui.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="connect-{project-context}-to-{compute-resource-target-id}-by-using-web-ui"]
4+
= Connect {Project} to {compute-resource-target-name} by using {ProjectWebUI}
5+
6+
[role="_abstract"]
7+
You can use {Project} with the {compute-resource-name} plugin to provision, manage, and decommission hosts on {compute-resource-target-name}.
8+
9+
ifdef::hetzner-cloud[]
10+
.Prerequisites
11+
* You have an API token for your {compute-resource-target-name} account.
12+
You can create the token on the Hetzner Console web interface.
13+
endif::[]
14+
15+
.Procedure
16+
. In the {ProjectWebUI}, navigate to *Infrastructure* > *Compute Resources*.
17+
. Click *Create Compute Resource*.
18+
. In the *Name* field, enter a name for the compute resource, for example, `{compute-resource-target-name}`.
19+
+
20+
Append the name of your {compute-resource-target-name} account if you plan to use multiple accounts simultaneously.
21+
. From the *Provider* list, select *{compute-resource-name}*.
22+
. Optional: In the *Description* field, enter a description for your compute resource.
23+
. From the *{compute-resource-name} Provider* menu, select `{compute-resource-target-name}`.
24+
. From the *{compute-resource-name} Template* menu, select `{compute-resource-target-name} provision default`.
25+
// TODO: Yes really
26+
ifdef::hetzner-cloud[]
27+
. In the *URL* and *Username* fields, enter any arbitrary characters.
28+
+
29+
{Project} ignores them.
30+
. In the *Password* field, enter your {compute-resource-target-name} token.
31+
endif::[]
32+
// TODO: Add steps per target to setup compute resource in Foreman
33+
. Check *Enable caching* to cache API calls to {compute-resource-target-name} about clusters, network, or storage lists on {Project} for 60 minutes.
34+
+
35+
{Team} recommends to enable caching to improve performance.
36+
. Click *Submit*.
37+
38+
// TODO: Obsolete after restructuring? Too many?
39+
.Next steps
40+
* Create a compute profile to bundle hardware settings.
41+
* Define an image from your compute resource provider in {Project} to perform image-based host provisioning.
42+
* Create a host group to bundle all settings in a blue print in {Project} for reproducible host deployments.

‎guides/common/modules/proc_create-a-predefined-configuration-for-hosts-on-opentofu-target-by-using-web-ui.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="create-a-predefined-configuration-for-hosts-on-{compute-resource-target-id}-by-using-web-ui"]
4+
= Create a predefined configuration for hosts on {compute-resource-target-name} by using {ProjectWebUI}
5+
6+
[role="_abstract"]
7+
You can add {compute-resource-target-name} hardware settings to a compute profile.
8+
When you create a host on {compute-resource-target-name} using this compute profile, these settings are automatically populated.
9+
10+
.Procedure
11+
. In the {ProjectWebUI}, navigate to *Infrastructure* > *Compute Profiles*.
12+
. Select your compute profile.
13+
. Select your {compute-resource-target-name} compute resource.
14+
ifeval::["{compute-resource-target-id}" == "hetzner-cloud"]
15+
. From the *Server Type* list, select the server type to use for provisioning.
16+
. From the *Location* list, select the geographical location of the {compute-resource-target-name} datacenter.
17+
+
18+
The list of available locations is not dynamically reduced to the locations that allow the selected server type.
19+
You must check manually if the selected server type is available within the location.
20+
If you do not select a location, {Project} automatically selects a compatible location.
21+
. Select *Backups* if you want to have backups of your hosts enabled on {compute-resource-target-name}.
22+
. Optional: From the *Storage* section, define additional Storage Volumes.
23+
. From the *Image* list, select the image to use for provisioning.
24+
. From the *Network* list, select the network to use for provisioning.
25+
+
26+
The first network-interface will receive a public IP address.
27+
Selecting a managed subnet may therefore result in an error.
28+
endif::[]
29+
ifeval::["{compute-resource-target-id}" == "nutanix"]
30+
// TODO: Add steps for Nutanix
31+
endif::[]
32+
. Click *Submit* to save the values to your compute profile.

‎guides/common/modules/proc_define-an-image-for-hosts-on-opentofu-target-by-using-web-ui.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="define-an-image-for-hosts-on-{compute-resource-target-id}-by-using-web-ui"]
4+
= Define an image for hosts on {compute-resource-target-name} by using {ProjectWebUI}
5+
6+
[role="_abstract"]
7+
Define an image that you use to provision hosts on {compute-resource-target-name} through {Project}.
8+
9+
.Procedure
10+
. In the {ProjectWebUI}, navigate to *Infrastructure* > *Compute Resources*.
11+
. Select your {compute-resource-target-name} compute resource.
12+
. Click *Create Image*.
13+
// TODO: Do we really want to say "golden image"?
14+
. In the *Name* field, enter the name of your golden image.
15+
. From the *Operating System* list, select the operating system of the image on {compute-resource-target-name}.
16+
. From the *Architecture* list, select the architecture of the image on {compute-resource-target-name}.
17+
. In the *Username* field, enter the user name of your golden image.
18+
. Select *User Data* if the host image supports user data.
19+
. In the *Password* field, enter the password of the user on your golden image.
20+
. From the *Image* list, select the image on {compute-resource-target-name}.
21+
. Click *Submit* to save the values to {Project}.

‎guides/common/modules/proc_delete-a-host-on-compute-resource-target.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="delete-a-host-on-{compute-resource-target-id}"]
4+
= Delete a host on {compute-resource-target-name}
5+
6+
[role="_abstract"]
7+
You can delete hosts running on {compute-resource-target-name} through {Project}.
8+
9+
include::snip_warning-destroy-vm-on-host-delete.adoc[]
10+
11+
ifeval::["{compute-resource-id}" == "opentofu"]
12+
.Prerequisites
13+
* Ensure that the `destroy_vm_on_host_delete` setting is enabled.
14+
15+
.Procedure
16+
. In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
17+
. Select your host.
18+
. From the actions menu, click *Delete*.
19+
. Click *Delete* to delete your host from {Project} and {compute-resource-target-name}.
20+
endif::[]
21+
22+
ifeval::["{compute-resource-id}" != "opentofu"]
23+
.Procedure
24+
. In the {ProjectWebUI}, navigate to *Infrastructure* > *Compute Resources*.
25+
. Select your {compute-resource-target-name} compute resource.
26+
. On the *Virtual Machines* tab, click *Delete* from the *Actions* menu.
27+
This deletes the host on {compute-resource-target-name} while retaining any associated hosts within {Project}.
28+
If you want to delete the orphaned host, navigate to *Hosts* > *All Hosts* and delete the host manually.
29+
endif::[]
30+
31+
.Additional resources
32+
* `destroy_vm_on_host_delete` setting

‎guides/common/modules/proc_install-the-opentofu-plugin.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="install-the-{compute-resource-id}-plugin"]
4+
= Install the {compute-resource-name} plugin
5+
6+
[role="_abstract"]
7+
Install the {compute-resource-name} plugin on your {ProjectServer} to provision and manage hosts through {compute-resource-name}.
8+
9+
.Procedure
10+
* On your {ProjectServer}, install the {compute-resource-name} plugin:
11+
+
12+
[options="nowrap", subs="+quotes,verbatim,attributes"]
13+
----
14+
# {foreman-installer} --enable-foreman-plugin-opentofu
15+
----
16+
17+
.Verification
18+
. In the {ProjectWebUI}, navigate to *Administer* > *About*.
19+
. On the *Plugins* tab, verify the installation of the {compute-resource-name} plugin.
20+
21+
.Next steps
22+
* Connect {Project} to a {compute-resource-name}-based compute resource.
23+
For more information, see xref:supported-opentofu-targets[].

‎guides/common/modules/proc_provision-a-host-on-opentofu-target-by-using-web-ui.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="provision-a-host-on-{compute-resource-target-id}-by-using-web-ui"]
4+
= Provision a host on {compute-resource-target-name} by using {ProjectWebUI}
5+
6+
[role="_abstract"]
7+
You can use {Project} to provision a host on {compute-resource-target-name}.
8+
9+
.Procedure
10+
. In the {ProjectWebUI}, navigate to *Hosts* > *Create Host*.
11+
+
12+
include::snip_steps-create-a-host-tab-host.adoc[]
13+
. From the *Deploy on* list, select the {compute-resource-target-name} compute resource.
14+
. From the *Compute Profile* list, select a compute profile to automatically populate virtual machine settings.
15+
ifdef::katello,orcharhino,satellite[]
16+
. From the *Lifecycle Environment* list, select the environment.
17+
endif::[]
18+
+
19+
include::snip_steps-create-a-host-tab-interfaces.adoc[]
20+
. On the *Operating System* tab, confirm that all fields automatically contain values.
21+
. Click *Resolve* next to *Provisioning templates* to confirm that the host can identify its provisioning templates.
22+
. Click the *Virtual Machine* tab and confirm that these settings are populated with details from the host group and compute profile.
23+
ifdef::hetzner-cloud[. From the *Server Type* List, select the server type on {compute-resource-target-name}.]
24+
ifdef::hetzner-cloud[. From the *Location* List, select the geographical location of the host on {compute-resource-target-name}.]
25+
// TODO: Add steps for Nutanix
26+
ifdef::katello,orcharhino,satellite[]
27+
+
28+
include::snip_step-parameter-ak.adoc[]
29+
endif::[]
30+
. Click *Submit* to provision a host.
31+
32+
.Additional resources
33+
* {ManagingHostsDocURL}Working_with_Host_Groups_managing-hosts[Working with host groups in _{ManagingHostsDocTitle}_]

‎guides/common/modules/ref_opentofu-settings.adoc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="{compute-resource-id}-settings"]
4+
= {compute-resource-name} settings
5+
6+
[role="_abstract"]
7+
The {compute-resource-name} settings define how {Project} interacts with {compute-resource-name}.
8+
9+
[cols="35%,30%,35%",options="header"]
10+
|====
11+
| Setting | Default value | Description
12+
| *TfState Token Timeout* | `600` | Allowed duration in seconds for {compute-resource-name} to report back to {Project}.
13+
|====

‎guides/common/modules/ref_supported-opentofu-targets.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="supported-{compute-resource-id}-targets"]
4+
= Supported {compute-resource-name} targets
5+
6+
[role="_abstract"]
7+
{Project} integrates with several compute resource targets through {compute-resource-name}.
8+
It provides a provisioning template for each supported {compute-resource-name} target.
9+
10+
Hetzner Cloud::
11+
You can provision cloud instances on Hetzner Cloud, manage their lifecycle, and decommission them.
12+
13+
Nutanix::
14+
You can provision virtual machines on Nutanix AHV, manage their lifecycle, and decommission them.
15+
16+
oVirt/Oracle Linux Virtualization Manager/Red{nbsp}Hat Virtualization::
17+
You can provision virtual machines on oVirt, Oracle Linux Virtualization Manager, and Red{nbsp}Hat Virtualization, manage their lifecycle, and decommission them.

0 commit comments

Comments
 (0)