Skip to content

Latest commit

 

History

History
429 lines (308 loc) · 34.2 KB

README.md

File metadata and controls

429 lines (308 loc) · 34.2 KB

License: GPL v3 Developed by: Cisco

Easy IMM

Table of Content

Recommended Module Versions

Module(s) Release 4.2.11-17769 Compatibility

Module API Version Provider Version Appliance Version Module Notes
organizations >=1.0.11-17769 1.0.51 Not Supported New Module to Manage Organizations/Resource Groups.
pools >=1.0.11-17769 1.0.51 Not Supported Adds IP Pool Block Level IP Configuration.
policies >=1.0.11-17769 1.0.51 Not Supported adapter_config - Add physical_nic_mode_settings; bios - M8 AMD BIOS attributes; ethernet_network - QnQ capabilities; vnics - sriov; vnic/vhba templates
profiles >=1.0.11-17769 1.0.51 Not Supported Adds Chassis/Domain Templates.

Module(s) Release 4.2.11-16711 Compatibility

Module API Version Provider Version Appliance Version Module Notes
pools >=1.0.11-16711 1.0.47 >=1.1.0-0 With IP Pools use Configuration outside IP Block.
policies >=1.0.11-16711 1.0.47 >=1.1.0-0 Anything supported by YAML Schema Outside of New Features in 17769
profiles >=1.0.11-16711 1.0.47 >=1.1.0-0 Doesn't support Chassis and Domain Templates

Updates

  • 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 . 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. See Notes for modules above.
  • 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.

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.

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:

"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 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.

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 install github.com/cloudposse/tfenv@latest

Add go/bin to PATH

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.

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'

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 :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.

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
  • Add variable intersight_secret_key with the value of

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

export intersight_api_key_id="<your-api-key>"
export intersight_secret_key="<secret-key-file-location>"

Windows

$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

export cert_mgmt_certificate_1='<cert_mgmt_certificate_file_location>'
export cert_mgmt_private_key_1='<cert_mgmt_private_key_file_location>'

Windows

$env:TF_VAR_cert_mgmt_certificate_1='<cert_mgmt_certificate_file_location>'
$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

export drive_security_authentication_password='<drive_security_authentication_password>'
export drive_security_server_ca_certificate='<drive_security_server_ca_certificate_file_location>'

Windows

$env:drive_security_authentication_password='<drive_security_authentication_password>'
$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

export cco_user='<cco_user>'
export cco_password='<cco_password>'

Windows

$env:TF_VAR_cco_user='<cco_user>'
$env:TF_VAR_cco_password='<cco_password>'

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
# 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
# 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

Name Version
terraform >=1.3.0
intersight 1.0.54
time 0.9.1
utils >= 0.1.3

Providers

Name Version
utils 0.2.6

Modules

Name Source Version
organizations terraform-cisco-modules/organizations/intersight 4.2.11-18370
pools terraform-cisco-modules/pools/intersight 4.2.11-18370
policies terraform-cisco-modules/policies/intersight 4.2.11-18370
profiles terraform-cisco-modules/profiles/intersight 4.2.11-18370

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.

Inputs

Name Description Type Default Required
intersight_api_key_id Intersight API Key. string n/a yes
intersight_secret_key Intersight Secret Key. string "blah.txt" no
cert_mgmt_certificate_1 The Server Certificate, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_certificate_2 The Server Certificate, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_certificate_3 The Server Certificate, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_certificate_4 The Server Certificate, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_certificate_5 The Server Certificate, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_private_key_1 The Server Private Key, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_private_key_2 The Server Private Key, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_private_key_3 The Server Private Key, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_private_key_4 The Server Private Key, in PEM Format, File Location. string "blah.txt" no
cert_mgmt_private_key_5 The Server Private Key, in PEM Format, File Location. string "blah.txt" no
drive_security_current_security_key_passphrase Drive Security Current Security Key Passphrase for Manual or Remote Key Management. It must meet the following criteria:
- One Uppercase Letter
- One LowerCase Letter
- One Number
- One Special Character: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 32 Characters in Length.
string "" no
drive_security_new_security_key_passphrase Drive Security New Security Key Passphrase for Manual Key Management. It must meet the following criteria:
- One Uppercase Letter
- One LowerCase Letter
- One Number
- One Special Character: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 32 Characters in Length.
string "" no
drive_security_authentication_password Drive Security User Password. string "" no
drive_security_server_ca_certificate Drive Security Server CA Certificate, in PEM Format, File Location. string "blah.txt" no
cco_password CCO User Account Password. It must meet the following criteria:
- One Uppercase Letter
- One Lowercase Letter
- One Number
- One Special Character: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 12 and 60 Characters in Length.
string "" no
cco_user CCO User Account Email for Firmware Policies. string "cco_user" no
ipmi_encryption_key Encryption key to use for IPMI communication. It should have an even number of hexadecimal characters and not exceed 40 characters. string "" no
iscsi_boot_password Password to Assign to the iSCSI Boot Policy if doing Authentication. It can be any string that adheres to the following constraints.
- Any non-white space character
- Be between 12 and 16 Characters in Length.
string "" no
binding_parameters_password The password of the user for initial bind process with an LDAP Policy. It can be any string that adheres to the following constraints.
- Any non-white space character
- Be between 8 and 254 Characters in Length.
string "" no
local_user_password_1 Password to assign to a Local User Policy -> User.
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 127 Characters in Length.
string "" no
local_user_password_2 Password to assign to a Local User Policy -> User.
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 127 Characters in Length.
string "" no
local_user_password_3 Password to assign to a Local User Policy -> User.
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 127 Characters in Length.
string "" no
local_user_password_4 Password to assign to a Local User Policy -> User.
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 127 Characters in Length.
string "" no
local_user_password_5 Password to assign to a Local User Policy -> User.
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 127 Characters in Length.
string "" no
persistent_passphrase Secure passphrase to be applied on the Persistent Memory Modules on the server. The allowed characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: !, @, #, $, %, ^, &, *, +, _, =, -
- Be between 8 and 32 Characters in Length.
string "" no
access_community_string_1 The default SNMPv1, SNMPv2c community name or SNMPv3 username to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
access_community_string_2 The default SNMPv1, SNMPv2c community name or SNMPv3 username to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
access_community_string_3 The default SNMPv1, SNMPv2c community name or SNMPv3 username to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
access_community_string_4 The default SNMPv1, SNMPv2c community name or SNMPv3 username to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
access_community_string_5 The default SNMPv1, SNMPv2c community name or SNMPv3 username to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
snmp_auth_password_1 The SNMPv3 User Authorization password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_auth_password_2 The SNMPv3 User Authorization password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_auth_password_3 The SNMPv3 User Authorization password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_auth_password_4 The SNMPv3 User Authorization password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_auth_password_5 The SNMPv3 User Authorization password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_privacy_password_1 The SNMPv3 User Privacy password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_privacy_password_2 The SNMPv3 User Privacy password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_privacy_password_3 The SNMPv3 User Privacy password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_privacy_password_4 The SNMPv3 User Privacy password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_privacy_password_5 The SNMPv3 User Privacy password. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, @, _, *, -
- Be between 8 and 64 Characters in Length.
string "" no
snmp_trap_community_1 The SNMPv1, SNMPv2c community name to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
snmp_trap_community_2 The SNMPv1, SNMPv2c community name to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
snmp_trap_community_3 The SNMPv1, SNMPv2c community name to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
snmp_trap_community_4 The SNMPv1, SNMPv2c community name to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
snmp_trap_community_5 The SNMPv1, SNMPv2c community name to include on any trap messages sent to the SNMP host. The name can be 32 characters long. Allowed Characters are:
- Lower or Upper Case Letters
- Numbers
- Special Characters: ., =, !, &, #, $, %, +, ^, _, *, -
- Be between 8 and 32 Characters in Length.
string "" no
vmedia_password_1 Virtual Media Policy -> Mapping Target Password when authentication is enabled. Allowed Characters are:
- Any non-white space character
- Be between 6 and 255 Characters in Length.
string "" no
vmedia_password_2 Virtual Media Policy -> Mapping Target Password when authentication is enabled. Allowed Characters are:
- Any non-white space character
- Be between 6 and 255 Characters in Length.
string "" no
vmedia_password_3 Virtual Media Policy -> Mapping Target Password when authentication is enabled. Allowed Characters are:
- Any non-white space character
- Be between 6 and 255 Characters in Length.
string "" no
vmedia_password_4 Virtual Media Policy -> Mapping Target Password when authentication is enabled. Allowed Characters are:
- Any non-white space character
- Be between 6 and 255 Characters in Length.
string "" no
vmedia_password_5 Virtual Media Policy -> Mapping Target Password when authentication is enabled. Allowed Characters are:
- Any non-white space character
- Be between 6 and 255 Characters in Length.
string "" no

Outputs

Name Description
organizations Outputs from the organizations module.
policies Outputs from the policies module.
pools Outputs from the pools module.
profiles Outputs from the profiles module.

Sub Modules - Terraform Registry

If you want to see documentation on Variables for Submodules use the links below: