-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy path.terraform-docs.yml
379 lines (257 loc) · 17.7 KB
/
.terraform-docs.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
version: '>= 0.14.0'
formatter: markdown table
content: |-
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://developer.cisco.com)
# Easy IMM
## Table of Content
* [Recommended Module Versions](#recommended-module-versions)
* [Updates](#updates)
* [Examples](#examples-for-using-the-easy-imm-terraform-modules)
* [Important Notes](#important-notes)
* [YAML Schema Notes](#yaml-schema-notes-for-auto-completion-help-and-error-validation)
* [Cloud Posse `tfenv`](#cloud-posse-tfenv)
* [Recommended Firmware](#recommended-firmware)
* [Environment Variables](#environment-variables)
* [Sensitive Variables for the Policies Module](#sensitive-variables-for-the-policies-module)
* [Execute Terraform Apply/Plan](#execute-the-terraform-applyplan)
* [Terraform Requirements](#requirements)
* [Terraform Providers](#providers)
* [Terraform Modules](#modules)
* [Terraform Inputs](#inputs)
* [Terraform Outputs](#outputs)
* [Sub Modules - Terraform Registry](#sub-modules---terraform-registry)
## Recommended Module Versions
## SaaS API Version >=1.0.11-20241204094351081
| **Module** | **Module Version** | **Provider Version** | **Appliance Version** | **Module Notes**
| :-----------: | :----------------: | :------------------: | :-------------------: | :--------------------------: |
| organizations | 4.2.11-20241204094351081 | 1.0.61 | Not Supported | New Module to Manage Organizations/Resource Groups. |
| pools | 4.2.11-20241204094351081 | 1.0.61 | Not Supported | Adds IP Pool Block Level IP Configuration. |
| policies | 4.2.11-20241204094351081 | 1.0.61 | Not Supported | * New Memory and Scrub Policies |
| profiles | 4.2.11-20241204094351081 | 1.0.61 | Not Supported | * Adds Support for Certificate Management/LDAP to Domain Profiles/Templates. |
## CVA Version >=1.1.1-1 API Version >=1.0.11-18735
| **Module** | **Module Version** | **Provider Version** | **Appliance Version** | **Module Notes**
| :-----------: | :----------------: | :------------------: | :-------------------: | :--------------------------: |
| organizations | 4.2.11-18775 | 1.0.51 | >=1.1.1-0 | New Module to Manage Organizations/Resource Groups. |
| pools | 4.2.11-16711 | 1.0.51 | >=1.1.1-0 | With IP Pools use Configuration outside IP Block. |
| policies | 4.2.11-16713 | 1.0.51 | >=1.1.1-0 | Anything supported by YAML Schema Outside of New Features in 17769 |
| profiles | 4.2.11-16712 | 1.0.51 | >=1.1.1-0 | * Adds Scrub Policies to Server Profiles/Templates. |
## PVA Version >=1.1.0-0 API Version >=1.0.11-16711
| **Module** | **Module Version** | **Provider Version** | **Appliance Version** | **Module Notes**
| :-----------: | :----------------: | :------------------: | :-------------------: | :--------------------------: |
| organizations | 4.2.11-18775 | 1.0.51 | >=1.1.0-0 | New Module to Manage Organizations/Resource Groups. |
| pools | 4.2.11-16711 | 1.0.51 | >=1.1.0-0 | With IP Pools use Configuration outside IP Block. |
| policies | 4.2.11-16713 | 1.0.51 | >=1.1.0-0 | Anything supported by YAML Schema Outside of New Features in 17769 |
| profiles | 4.2.11-16712 | 1.0.51 | >=1.1.0-0 | Doesn't support Chassis and Domain Templates |
### [<ins>Back to Top<ins>](#easy-imm)
## Updates
* 2025-01-21: Recommended releases are 4.2.11-20241204094351081 (SaaS) or 4.2.11-18775 (CVA 1.1.1-0)
* 2024-11-12: Recommended releases are 4.2.11-20241004054146475 (SaaS) or 4.2.11-18775 (CVA 1.1.1-0).
<ins>IMPORTANT NOTE</ins>: 4.2.11-20241004054146475 introduces support for multi-ethernet network group policies for Ethernet Uplink Port-Channels and Ethernet Uplink. If you are still using older module versions make sure to point to the older JSON Schema for Visual Studio Code.
For example: v4.2.11-18775 - https://github.com/terraform-cisco-modules/easy-imm/blob/39542dfc4ee2f368d42ff6a73ee4e08cb26a4c09/yaml_schema/easy-imm.json
* 2024-10-23: Recommended releases are 4.2.11-20241004054146474 or 4.2.11-16712. Adding Memory Policy. Intersight API versioning changed to include date.
* 2024-10-11: Recommended releases are 4.2.11-18775 or 4.2.11-16712. Adding Scrub Policy.
* 2024-09-13: Recommended releases are 4.2.11-18371 or 4.2.11-16712. ISSUE 287 resolved.
* 2024-09-08: Rolling back SaaS recommendation to 4.2.11-17769 since provider v1.0.54 is broken again for server templates [ISSUE 287](https://github.com/CiscoDevNet/terraform-provider-intersight/issues/287) . Version v4.2.11-18369 and v4.2.11-18370 is on hold for now until provider fixed.
* 2024-09-07: Recommended releases are 4.2.11-18369 or 4.2.11-16711. This update changes the drive security policy to match the updated API of 1.0.11-18369. Make sure to update your variables.tf, locals.tf from the eas-imm repository to get the updated sensitive variables for drive_security. The variables have also been updated to do validation using the regular expression patterns from the API.
* 2024-07-23: Recommended releases are 4.2.11-17769 or 4.2.11-16711.
* 2024-07-16: Terraform Provider 1.0.48, 1.0.49, and 1.0.50 depricated due to breaking BIOS changes and bulk_merger problems. Do not use these provider versions.
### [<ins>Back to Top<ins>](#easy-imm)
## Examples for Using the Easy IMM Terraform Modules
Examples are shown in the following directories:
* `organizations`
* `policies`
* `pools`
* `profiles`
* `recommended_firmware` - This is used to get the latest recommended firmware releases from Intersight
* `templates`
* `Wakanda` - To Show profiles using pools/policies/templates as Data Sources (Mostly)
`organizations/policies/pools/profiles/templates` Folders are the `common/default/Asgard` organizations in our lab environment.
`Wakanda` Folder is the Wakanda organization in our lab environment. It is not using the organizations module.
### [<ins>Back to Top<ins>](#easy-imm)
### IMPORTANT NOTES
Take notice of the `ezi.yaml` extension on the files. This is how the `data.utils_yaml_merge.model`, in the `main.tf`, is configured to recognize the files that should be imported with the module.
The Structure of the YAML files is very flexible. You can have all the YAML Data in a single file or you can have it in multiple individual folders like is shown in this module. The important part is that the `data.utils_yaml_merge.model` is configured to read the folders that you put the Data into.
When defining Identity reservations under a server profile, see example in `profiles` folder, note the flag in the example with `ignore_reservations`. Reservation records are ephimeral. Meaning that as soon as the reservation is assigned to a server profile, the identity reservation record is removed from the API. Thus, after you run the first plan and the identities are created, this flag should be configured to `true` or you need to remove the reservations from the `server_profiles`. Either way the reservations will only work on the first apply. Subsequent applies with the reservations defined will cause the plan/apply to fail due to the identity being consumed.
## YAML Schema Notes for auto-completion, Help, and Error Validation:
If you would like to utilize Autocomple, Help Context, and Error Validation, `(HIGHLY RECOMMENDED)` make sure the files all utilize the `.ezi.yaml` file extension.
Add the Following to `YAML: Schemas`. In Visual Studio Code: Settings > Settings > Search for `YAML: Schema`: Click edit in `settings.json`. In the `yaml.schemas` section:
```bash
"https://raw.githubusercontent.com/terraform-cisco-modules/easy-imm/main/yaml_schema/easy-imm.json": "*.ezi.yaml"
```
Soon the Schema for these YAML Files have been registered with [*SchemaStore*](https://github.com/SchemaStore/schemastore/blob/master/src/api/json/catalog.json) via utilizing this `.ezi.yaml` file extension. But until that is complete, need to still add to settings.
### Modify `global_settings.ezi.yaml` for SaaS versus CVA/PVA FQDN
`global_settings.ezi.yamls` contains variable `intersight_fqdn`.
#### Notes for the `global_settings.ezi.yamls`
* `intersight_fqdn`: SaaS will by default be `intersight.com`. Available in the event of CVA or PVA deployments.
* `tags`: Not Required, but by default the version of the script is being flagged here.
#### Note: Modules can be added or removed dependent on the use case. The primary example in this repository is consuming/showing a full environment deployment.
### [<ins>Back to Top<ins>](#easy-imm)
## [<ins>Cloud Posse `tfenv`<ins>](https://github.com/cloudposse/tfenv)
Command line utility to transform environment variables for use with Terraform. (e.g. HOSTNAME → TF_VAR_hostname)
Recently I adopted the `tfenv` runner to standardize environment variables with multiple orchestration tools. tfenv makes it so you don't need to add TF_VAR_ to the variables when you add them to the environment. But it doesn't work for windows would be the caveat.
In the export examples below, for the Linux Example, the 'TF_VAR_' is excluded because Cloud Posse tfenv is used to insert it during the run.
### Make sure you have already installed go
## [go](https://go.dev/doc/install)
```bash
go install github.com/cloudposse/tfenv@latest
```
### Add go/bin to PATH
```bash
GOPATH="$HOME/go"
PATH="$GOPATH/bin:$PATH"
```
### Aliases for `.bashrc`
Additionally to Save time on typing commands I use the following aliases by editing the `.bashrc` for my environment.
```bash
alias tfa='tfenv terraform apply main.plan'
alias tfap='tfenv terraform apply -parallelism=1 main.plan'
alias tfd='tfenv terraform destroy'
alias tff='terraform fmt'
alias tfi='terraform init'
alias tfim='tfenv terraform import'
alias tfp='tfenv terraform plan -out=main.plan'
alias tfu='terraform init -upgrade'
alias tfv='terraform validate'
```
### [<ins>Back to Top<ins>](#easy-imm)
## Recommended Firmware
In the `recommended_firmware` folder is a simple terraform setup that you can use to query Intersight for the latest recommended firmware for servers. Following is an example output:
## Creating Server Profiles from Templates or Attaching Server Profiles to Templates
If you want to create server profiles from templates use the flag `create_from_template` under the server profile in <org>:profiles:server. See examples in `./profiles`.
Do not create from template if you want to assign identity reservations to a server profile. Instead set the `attach_template` flag in the server profile. This will also attach the template to the profile but will reserve the identities to the profile prior to template attachement.
### [<ins>Back to Top<ins>](#easy-imm)
## Environment Variables
Note that all the variables in `variables.tf` are marked as sensitive. Meaning these are variables that shouldn't be exposed due to the sensitive nature of them.
Take note of the `locals.tf` that currently has the following sensitive variables defined:
* `certificate_management`
* `drive_security`
* `firmware`
* `ipmi_over_lan`
* `iscsi_boot`
* `ldap`
* `local_user`
* `persistent_memory`
* `snmp`
* `virtual_media`
The Reason to add these variables as maps of string is to allow the flexibility to add or remove iterations of these sensitive variables as needed. Sensitive Variables cannot be iterated with a `for_each` loop. Thus instead of adding these variables to the YAML schema, directly, they are added to these seperate maps to allow lookup of the variable index.
In example, if you needed to add 100 iterations of the `certificate_management` variables you can do that, and simply reference the index in the map of the iteration that will consume that instance.
### Terraform Cloud/Enterprise - Workspace Variables
- Add variable `intersight_api_key_id` with the value of <ins>your-intersight-api-key</ins>
- Add variable `intersight_secret_key` with the value of <ins>your-intersight-secret-file-content</ins>
- Add additional variables as required for the sensitive policy values
#### Add Other Variables as discussed below based on use cases.
## Sensitive Variables for the Policies Module:
Take note of the `locals.tf` that currently has all the sensitive variables mapped.
This is the default sensitive variable mappings. You can add or remove to these according to the needs of your environment.
The important point is that if you need more than is added by default you can expand the locals.tf and variables.tf to accomodate your environment.
### IMPORTANT:
ALL EXAMPLES BELOW ASSUME USING `tfenv` in LINUX
#### Linux - with tfenv
```bash
export intersight_api_key_id="<your-api-key>"
export intersight_secret_key="<secret-key-file-location>"
```
#### Windows
```powershell
$env:TF_VAR_intersight_api_key_id="<your-api-key>"
$env:TF_VAR_intersight_secret_key="<secret-key-file-location>"
```
#### To Assign any of these values for consumption you can define them as discussed below.
### Certificate Management
* `cert_mgmt_certificate`: Options are by default 1-5 for Up to 5 Certificates. Variable Should Point to the File Location of the PEM Certificate or be the value of the PEM certificate.
* `cert_mgmt_private_key`: Options are by default 1-5 for Up to 5 Private Keys. Variable Should Point to the File Location of the PEM Private Key or be the value of the PEM Private Key.
#### Linux - with tfenv
```bash
export cert_mgmt_certificate_1='<cert_mgmt_certificate_file_location>'
```
```bash
export cert_mgmt_private_key_1='<cert_mgmt_private_key_file_location>'
```
#### Windows
```powershell
$env:TF_VAR_cert_mgmt_certificate_1='<cert_mgmt_certificate_file_location>'
```
```powershell
$env:TF_VAR_cert_mgmt_private_key_1='<cert_mgmt_private_key_file_location>'
```
### Drive Security - KMIP Sensitive Variables
* `drive_security_current_security_key_passphrase`: Used by Manual and Remote Key Management, if the server has a previous passphrase configured.
* `drive_security_new_security_key_passphrase`: Used by Manual Key Management to Assign a new passphrase to the server.
* `drive_security_authentication_password`: If Authentication is supported/used by the KMIP Server, This is the User Password to Configure.
* `drive_security_server_ca_certificate`: KMIP Server CA Certificate Contents.
#### Linux - with tfenv
```bash
export drive_security_authentication_password='<drive_security_authentication_password>'
```
```bash
export drive_security_server_ca_certificate='<drive_security_server_ca_certificate_file_location>'
```
#### Windows
```powershell
$env:drive_security_authentication_password='<drive_security_authentication_password>'
```
```powershell
$env:TF_VAR_drive_security_server_ca_certificate='<drive_security_server_ca_certificate_file_location>'
```
### Firmware - CCO Credentials
* `cco_user`: If Configuring Firmware Policies, the CCO User for Firmware Downloads.
* `cco_password`: If Configuring Firmware Policies, the CCO Password for Firmware Downloads.
#### Linux - with tfenv
```bash
export cco_user='<cco_user>'
```
```bash
export cco_password='<cco_password>'
```
#### Windows
```powershell
$env:TF_VAR_cco_user='<cco_user>'
```
```powershell
$env:TF_VAR_cco_password='<cco_password>'
```
### [<ins>Back to Top<ins>](#easy-imm)
## Execute the Terraform Apply/Plan
### Terraform Cloud
When running in Terraform Cloud with VCS Integration the first Plan will need to be run from the UI but subsiqent runs should trigger automatically
### Terraform CLI
* Execute the Plan - Linux
```bash
# First time execution requires initialization. Not needed on subsequent runs.
terraform init
terraform plan -out="main.plan"
terraform apply "main.plan"
```
* Execute the Plan - Windows
```powershell
# First time execution requires initialization. Not needed on subsequent runs.
terraform.exe init
terraform.exe plan -out="main.plan"
terraform.exe apply "main.plan"
```
{{ .Requirements }}
### [<ins>Back to Top<ins>](#easy-imm)
{{ .Providers }}
### [<ins>Back to Top<ins>](#easy-imm)
{{ .Modules }}
**NOTE: When the Data is merged from the YAML files, it will run through the modules using for_each loop(s). Sensitive Variables cannot be added to a for_each loop, instead use the variables below to add sensitive values for policies.**
### [<ins>Back to Top<ins>](#easy-imm)
{{ .Inputs }}
### [<ins>Back to Top<ins>](#easy-imm)
{{ .Outputs }}
### [<ins>Back to Top<ins>](#easy-imm)
## Sub Modules - Terraform Registry
If you want to see documentation on Variables for Submodules use the links below:
#### * [<ins>Organizations<ins>](https://registry.terraform.io/modules/terraform-cisco-modules/organizations/intersight/latest)
#### * [<ins>Policies<ins>](https://registry.terraform.io/modules/terraform-cisco-modules/policies/intersight/latest)
#### * [<ins>Pools<ins>](https://registry.terraform.io/modules/terraform-cisco-modules/pools/intersight/latest)
#### * [<ins>Profiles<ins>](https://registry.terraform.io/modules/terraform-cisco-modules/profiles/intersight/latest)
### [<ins>Back to Top<ins>](#easy-imm)
output:
file: README.md
mode: replace
sort:
enabled: false
settings:
read-comments: false