Skip to content

Commit 871625a

Browse files
tyrazieldleehr
tyraziel
and
dleehr
authored
Updated Documentation for advanced depends_on clauses for aap_job and aap_workflow_job. Updated make target for generatedocs. (#88)
* Updated Documentation for advanced depends_on clauses for aap_job and aap_workflow_job. Updated make target for generatedocs. --------- Co-authored-by: Dan Leehr <[email protected]>
1 parent 3c3745d commit 871625a

File tree

7 files changed

+191
-0
lines changed

7 files changed

+191
-0
lines changed

‎Makefile

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@ generatedocs: ## Format example Terraform configurations and generate plugin doc
3535
@echo "==> Formatting examples and generating docs..."
3636
terraform fmt -recursive ./examples/
3737
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate
38+
@echo
39+
@echo "****************************************************************************"
40+
@echo "********* ** ** ** ** ** ** NOTICE ** ** ** ** ** ** *********"
41+
@echo "****************************************************************************"
42+
@echo "* *"
43+
@echo "* If documentation updates were made, please validate them by going to *"
44+
@echo "* https://registry.terraform.io/tools/doc-preview?product_intent=terraform *"
45+
@echo "* and verify how they look. *"
46+
@echo "* *"
47+
@echo "****************************************************************************"
3848

3949
.PHONY: help
4050
help: ## Show this help message

‎docs/index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,12 @@ data "aap_job_template" "demo_job_template" {
7373
resource "aap_job" "my_job" {
7474
inventory_id = aap_inventory.my_inventory.id
7575
job_template_id = aap_job_template.demo_job_template.id
76+
77+
# This resource creation needs to wait for the host and group to be created in the inventory
78+
depends_on = [
79+
aap_host.my_host,
80+
aap_group.my_group
81+
]
7682
}
7783
```
7884
<!-- schema generated by tfplugindocs -->

‎docs/resources/job.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,42 @@ output "job_xyz" {
121121
```
122122

123123

124+
## Ensuring Jobs Launch on Hosts created and Inventories updated in the same configuration
125+
126+
### Advanced Usage - `depends_on` in `aap_job` `resource` for `aap_host` `resource` creation
127+
-> **Note** if you have HCL that creates an `aap_host` `resource` in an already existing `aap_inventory`, you will have to add a `depends_on` clause in the `aap_job` `resource` block of the `aap_job` that needs that `aap_host` to exist in the `aap_inventory` used for the `aap_job` creation.
128+
129+
If you do not use the depends_on clause as illustrated below you may run into a race condition where the job will attempt to launch before the inventory is updated with the host required.
130+
131+
### Example HCL for this scenario:
132+
133+
```terraform
134+
data "aap_inventory" "inventory" {
135+
name = "Demo Inventory"
136+
organization_name = "Default"
137+
}
138+
139+
resource "aap_host" "host" {
140+
inventory_id = data.aap_inventory.inventory.id
141+
name = "127.0.0.1"
142+
}
143+
144+
data "aap_job_template" "job_template" {
145+
name = "Demo Job Template"
146+
organization_name = "Default"
147+
}
148+
149+
resource "aap_job" "job" {
150+
job_template_id = data.aap_job_template.job_template.id
151+
inventory_id = data.aap_inventory.inventory.id
152+
153+
# Force creation of this resource to wait for the aap_host.host resource to be created
154+
depends_on = [
155+
aap_host.host
156+
]
157+
}
158+
```
159+
124160
<!-- schema generated by tfplugindocs -->
125161
## Schema
126162

‎docs/resources/workflow_job.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ A workflow job is launched only when the resource is first created or when the r
1414

1515
This resource always creates a new workflow job in AAP. A destroy will not delete a workflow job created by this resource, it will only remove the resource from the state.
1616

17+
-> **Note** To pass an inventory to an aap_workflow_job resource, the underlying workflow job template *must* have been configured to prompt for the inventory on launch.
18+
19+
!> **Warning** If an AAP Workflow Job launched by this resource is deleted from AAP, the resource will be removed from the state and a new workflow job will be created to replace it.
20+
1721

1822
## Example Usage
1923

@@ -98,6 +102,42 @@ output "job_xyz" {
98102
```
99103

100104

105+
## Ensuring Workflow Jobs Launch on Hosts created and Inventories updated in the same configuration
106+
107+
### Advanced Usage - `depends_on` in `aap_workflow_job` `resource` for `aap_host` `resource` creation
108+
-> **Note** if you have HCL that creates an `aap_host` `resource` in an already existing `aap_inventory`, you will have to add a `depends_on` clause in the `aap_workflow_job` `resource` block of the `aap_workflow_job` that needs that `aap_host` to exist in the `aap_inventory` used for the `aap_workflow_job` creation.
109+
110+
If you do not use the depends_on clause as illustrated below you may run into a race condition where the workflow job will attempt to launch before the inventory is updated with the host required.
111+
112+
### Example HCL for this scenario:
113+
114+
```terraform
115+
data "aap_inventory" "inventory" {
116+
name = "Demo Inventory"
117+
organization_name = "Default"
118+
}
119+
120+
resource "aap_host" "host" {
121+
inventory_id = data.aap_inventory.inventory.id
122+
name = "127.0.0.1"
123+
}
124+
125+
data "aap_workflow_job_template" "workflow_job_template" {
126+
name = "Demo Workflow Job Template"
127+
organization_name = "Default"
128+
}
129+
130+
resource "aap_workflow_job" "workflow_job" {
131+
workflow_job_template_id = data.aap_workflow_job_template.workflow_job_template.id
132+
inventory_id = data.aap_inventory.inventory.id
133+
134+
# Force creation of this resource to wait for the aap_host.host resource to be created
135+
depends_on = [
136+
aap_host.host
137+
]
138+
}
139+
```
140+
101141
<!-- schema generated by tfplugindocs -->
102142
## Schema
103143

‎examples/provider/provider.tf

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,4 +58,10 @@ data "aap_job_template" "demo_job_template" {
5858
resource "aap_job" "my_job" {
5959
inventory_id = aap_inventory.my_inventory.id
6060
job_template_id = aap_job_template.demo_job_template.id
61+
62+
# This resource creation needs to wait for the host and group to be created in the inventory
63+
depends_on = [
64+
aap_host.my_host,
65+
aap_group.my_group
66+
]
6167
}

‎templates/resources/job.md.tmpl

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,40 @@ description: |-
1818
{{ tffile .ExampleFile }}
1919
{{ end }}
2020

21+
## Ensuring Jobs Launch on Hosts created and Inventories updated in the same configuration
22+
23+
### Advanced Usage - `depends_on` in `aap_job` `resource` for `aap_host` `resource` creation
24+
-> **Note** if you have HCL that creates an `aap_host` `resource` in an already existing `aap_inventory`, you will have to add a `depends_on` clause in the `aap_job` `resource` block of the `aap_job` that needs that `aap_host` to exist in the `aap_inventory` used for the `aap_job` creation.
25+
26+
If you do not use the depends_on clause as illustrated below you may run into a race condition where the job will attempt to launch before the inventory is updated with the host required.
27+
28+
### Example HCL for this scenario:
29+
30+
```terraform
31+
data "aap_inventory" "inventory" {
32+
name = "Demo Inventory"
33+
organization_name = "Default"
34+
}
35+
36+
resource "aap_host" "host" {
37+
inventory_id = data.aap_inventory.inventory.id
38+
name = "127.0.0.1"
39+
}
40+
41+
data "aap_job_template" "job_template" {
42+
name = "Demo Job Template"
43+
organization_name = "Default"
44+
}
45+
46+
resource "aap_job" "job" {
47+
job_template_id = data.aap_job_template.job_template.id
48+
inventory_id = data.aap_inventory.inventory.id
49+
50+
# Force creation of this resource to wait for the aap_host.host resource to be created
51+
depends_on = [
52+
aap_host.host
53+
]
54+
}
55+
```
56+
2157
{{ .SchemaMarkdown | trimspace }}

‎templates/resources/workflow_job.md.tmpl

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
page_title: "{{ .Name }} {{ .Type }} - {{ .ProviderName }}"
3+
description: |-
4+
{{ .Description | plainmarkdown | trimspace | prefixlines " " }}
5+
---
6+
7+
# {{ .Name }} ({{ .Type }})
8+
9+
{{ .Description | trimspace }}
10+
11+
-> **Note** To pass an inventory to an aap_workflow_job resource, the underlying workflow job template *must* have been configured to prompt for the inventory on launch.
12+
13+
!> **Warning** If an AAP Workflow Job launched by this resource is deleted from AAP, the resource will be removed from the state and a new workflow job will be created to replace it.
14+
15+
{{ if .HasExample }}
16+
## Example Usage
17+
18+
{{ tffile .ExampleFile }}
19+
{{ end }}
20+
21+
## Ensuring Workflow Jobs Launch on Hosts created and Inventories updated in the same configuration
22+
23+
### Advanced Usage - `depends_on` in `aap_workflow_job` `resource` for `aap_host` `resource` creation
24+
-> **Note** if you have HCL that creates an `aap_host` `resource` in an already existing `aap_inventory`, you will have to add a `depends_on` clause in the `aap_workflow_job` `resource` block of the `aap_workflow_job` that needs that `aap_host` to exist in the `aap_inventory` used for the `aap_workflow_job` creation.
25+
26+
If you do not use the depends_on clause as illustrated below you may run into a race condition where the workflow job will attempt to launch before the inventory is updated with the host required.
27+
28+
### Example HCL for this scenario:
29+
30+
```terraform
31+
data "aap_inventory" "inventory" {
32+
name = "Demo Inventory"
33+
organization_name = "Default"
34+
}
35+
36+
resource "aap_host" "host" {
37+
inventory_id = data.aap_inventory.inventory.id
38+
name = "127.0.0.1"
39+
}
40+
41+
data "aap_workflow_job_template" "workflow_job_template" {
42+
name = "Demo Workflow Job Template"
43+
organization_name = "Default"
44+
}
45+
46+
resource "aap_workflow_job" "workflow_job" {
47+
workflow_job_template_id = data.aap_workflow_job_template.workflow_job_template.id
48+
inventory_id = data.aap_inventory.inventory.id
49+
50+
# Force creation of this resource to wait for the aap_host.host resource to be created
51+
depends_on = [
52+
aap_host.host
53+
]
54+
}
55+
```
56+
57+
{{ .SchemaMarkdown | trimspace }}

0 commit comments

Comments
 (0)