From 120368ed65a8b8e8a35a24f4158b1d6a7278688c Mon Sep 17 00:00:00 2001 From: Patrick Cowland Date: Tue, 15 Oct 2024 15:26:37 +0100 Subject: [PATCH 1/3] Add HCL generation advice header --- docs/exporting-configuration/README.md | 9 ++ .../pingone-plan-errors.md | 83 +++++++++++++++++++ internal/connector/common/common_utils.go | 32 +++++++ internal/connector/exportable.go | 3 + .../templates/hcl_import_header.template | 23 +++++ 5 files changed, 150 insertions(+) create mode 100644 docs/exporting-configuration/README.md create mode 100644 docs/exporting-configuration/pingone-plan-errors.md create mode 100644 internal/connector/templates/hcl_import_header.template diff --git a/docs/exporting-configuration/README.md b/docs/exporting-configuration/README.md new file mode 100644 index 00000000..07970158 --- /dev/null +++ b/docs/exporting-configuration/README.md @@ -0,0 +1,9 @@ +# Ping CLI - Exporting Platform Configuration + +## Resolving Terraform Plan Errors + +The following documents describe the actions that must be taken, per provider, to resolve `terraform plan` errors following configuration generation. + +- [PingOne Terraform Provider](./pingone-plan-errors.md) + +If you encounter an error that is not documented, please [raise a new issue](https://github.com/pingidentity/pingcli/issues/new?title=Undocumented%20Config%20Generation%20Error). \ No newline at end of file diff --git a/docs/exporting-configuration/pingone-plan-errors.md b/docs/exporting-configuration/pingone-plan-errors.md new file mode 100644 index 00000000..76783ce6 --- /dev/null +++ b/docs/exporting-configuration/pingone-plan-errors.md @@ -0,0 +1,83 @@ +# Ping CLI - Exporting Platform Configuration - PingOne Plan Errors + +The following sections describe the actions that must be taken, per resource, to resolve `terraform plan` errors following configuration generation. + +If you encounter an error that is not documented, please [raise a new issue](https://github.com/pingidentity/pingcli/issues/new?title=Undocumented%20PingOne%20Config%20Generation%20Error). + +## Resource: pingone_application + +### Attribute saml_options.type value must be one of: ["WEB_APP" "CUSTOM_APP"], got: "TEMPLATE_APP" + +**Cause**: Template applications are not supported in the PingOne provider version used to run `terraform plan`. + +**Resolution**: Upgrade the PingOne Terraform provider version. Further details can be found at https://github.com/pingidentity/terraform-provider-pingone/issues/841 + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/application#nestedatt--saml_options) + +## Resource: pingone_branding_theme + +### 2 attributes specified when one (and only one) of [background_color.<.background_color,background_color.<.use_default_background,background_color.<.background_image] is required + +**Cause**: Due to a [Terraform configuration generation limitation](https://developer.hashicorp.com/terraform/language/import/generating-configuration#conflicting-resource-arguments), conflicting parameters are included in the generated HCL. + +**Resolution**: Manual modification is required to ensure only one of `background_color`, `use_default_background` or `background_image` is defined. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/branding_theme#schema) + +## Resource: pingone_certificate + +### one of `pem_file,pkcs7_file_base64` must be specified + +**Cause**: Certificates are not exported from PingOne to maintain tenant security. + +**Resolution**: Manual modification is required to set either `pem_file` or `pkcs7_file_base64` in the generated HCL. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/certificate#schema) + +## Resource: pingone_forms_recaptcha_v2 + +### Must set a configuration value for the secret_key attribute as the provider has marked it as required + +**Cause**: The reCaptcha v2 secret key is not exported from PingOne to maintain tenant security. + +**Resolution**: Manual modification is required to set `secret_key` in the generated HCL. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/forms_recaptcha_v2#schema) + +## Resource: pingone_mfa_application_push_credential + +### No attribute specified when one (and only one) of [apns.<.fcm,apns.<.apns,apns.<.hms] is required + +**Cause**: Push credential values are not exported from PingOne to maintain tenant security. + +**Resolution**: Manual modification is required to set one of `apns`, `fcm`, or `hms` in the generated HCL. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/mfa_application_push_credential#schema) + +## Resource: pingone_notification_settings_email + +### Must set a configuration value for the password attribute as the provider has marked it as required. + +**Cause**: Passwords for email servers are not exported from PingOne to maintain tenant security. + +**Resolution**: Manual modification is required to set the `password` field in the generated HCL. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/notification_settings_email#schema) + +## Resource: pingone_phone_delivery_settings + +### The argument provider_custom.authentication.password is required because provider_custom.authentication.method is configured as: "BASIC" + +**Cause**: Password fields are not exported from PingOne to maintain tenant security. + +**Resolution**: Manual modification is required to set the `provider_custom.authentication.password` value in the generated HCL. + +**Documentation**: +- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingone/latest/docs/resources/phone_delivery_settings#password) + diff --git a/internal/connector/common/common_utils.go b/internal/connector/common/common_utils.go index fd8e4c90..8b8ab0e3 100644 --- a/internal/connector/common/common_utils.go +++ b/internal/connector/common/common_utils.go @@ -5,6 +5,7 @@ import ( "os" "path/filepath" "text/template" + "time" "github.com/pingidentity/pingcli/internal/connector" "github.com/pingidentity/pingcli/internal/customtypes" @@ -51,6 +52,11 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp } defer outputFile.Close() + err = writeHeader(format, outputFile) + if err != nil { + return fmt.Errorf("failed to write header to file %q. err: %s", outputFilePath, err.Error()) + } + for _, importBlock := range *importBlocks { // Sanitize import block "to". Make lowercase, remove special chars, convert space to underscore importBlock.Sanitize() @@ -68,3 +74,29 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp } return nil } + +func writeHeader(format string, outputFile *os.File) error { + // Parse the HCL header + hclImportHeaderTemplate, err := template.New("HCLImportHeader").Parse(connector.HCLImportHeaderTemplate) + if err != nil { + return fmt.Errorf("failed to parse HCL import header template. err: %s", err.Error()) + } + + header := struct { + DateTime string + }{ + DateTime: time.Now().Format(time.RFC1123), + } + + switch format { + case customtypes.ENUM_EXPORT_FORMAT_HCL: + err := hclImportHeaderTemplate.Execute(outputFile, header) + if err != nil { + return err + } + default: + return fmt.Errorf("unrecognized export format %q. Must be one of: %s", format, customtypes.ExportFormatValidValues()) + } + + return nil +} diff --git a/internal/connector/exportable.go b/internal/connector/exportable.go index 4e4dba00..cdfa7006 100644 --- a/internal/connector/exportable.go +++ b/internal/connector/exportable.go @@ -9,6 +9,9 @@ import ( //go:embed templates/hcl_import_block.template var HCLImportBlockTemplate string +//go:embed templates/hcl_import_header.template +var HCLImportHeaderTemplate string + // A connector that allows exporting configuration type Exportable interface { Export(format, outputDir string, overwriteExport bool) error diff --git a/internal/connector/templates/hcl_import_header.template b/internal/connector/templates/hcl_import_header.template new file mode 100644 index 00000000..e6470e38 --- /dev/null +++ b/internal/connector/templates/hcl_import_header.template @@ -0,0 +1,23 @@ +####################################################################################################################### +# +# Generated by Ping CLI: {{.DateTime}} +# https://github.com/pingidentity/pingcli +# +# Using the Terraform import blocks generated in this file, Terraform HCL can be generated and resource +# configuration can be imported to Terraform state using Terraform's out-of-the-box import features. +# +# Use of the Terraform import blocks requires Terraform `v1.5.0` and later. +# +# For more information on the Terraform import block feature, visit +# https://developer.hashicorp.com/terraform/language/import +# +# To generate Terraform configuration, run `terraform plan` with the `-generate-config-out` flag. For example: +# `terraform plan -generate-config-out=generated_resources.tf` +# +# There are limitations in the generation process that may result in errors being shown on `terraform plan`. +# +# For more information on the manual steps required to resolve the errors, visit +# https://github.com/pingidentity/pingcli/blob/main/docs/exporting-configuration/README.md +# +####################################################################################################################### + From f4f74fc570f3f7a39c12a8ff605872962190b0b3 Mon Sep 17 00:00:00 2001 From: Patrick Cowland Date: Tue, 15 Oct 2024 18:26:07 +0100 Subject: [PATCH 2/3] update to align with test scripts --- internal/connector/common/common_utils.go | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/internal/connector/common/common_utils.go b/internal/connector/common/common_utils.go index 8b8ab0e3..924d1aa2 100644 --- a/internal/connector/common/common_utils.go +++ b/internal/connector/common/common_utils.go @@ -52,9 +52,9 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp } defer outputFile.Close() - err = writeHeader(format, outputFile) + err = writeHeader(format, outputFilePath, outputFile) if err != nil { - return fmt.Errorf("failed to write header to file %q. err: %s", outputFilePath, err.Error()) + return err } for _, importBlock := range *importBlocks { @@ -65,7 +65,7 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp case customtypes.ENUM_EXPORT_FORMAT_HCL: err := hclImportBlockTemplate.Execute(outputFile, importBlock) if err != nil { - return fmt.Errorf("failed to write import block template to file %q. err: %s", outputFilePath, err.Error()) + return fmt.Errorf("failed to write import template to file %q. err: %s", outputFilePath, err.Error()) } default: return fmt.Errorf("unrecognized export format %q. Must be one of: %s", format, customtypes.ExportFormatValidValues()) @@ -75,7 +75,7 @@ func WriteFiles(exportableResources []connector.ExportableResource, format, outp return nil } -func writeHeader(format string, outputFile *os.File) error { +func writeHeader(format, outputFilePath string, outputFile *os.File) error { // Parse the HCL header hclImportHeaderTemplate, err := template.New("HCLImportHeader").Parse(connector.HCLImportHeaderTemplate) if err != nil { @@ -92,7 +92,7 @@ func writeHeader(format string, outputFile *os.File) error { case customtypes.ENUM_EXPORT_FORMAT_HCL: err := hclImportHeaderTemplate.Execute(outputFile, header) if err != nil { - return err + return fmt.Errorf("failed to write import template to file %q. err: %s", outputFilePath, err.Error()) } default: return fmt.Errorf("unrecognized export format %q. Must be one of: %s", format, customtypes.ExportFormatValidValues()) From 38a953905abe4c199112cb2d612235c2fc0f03de Mon Sep 17 00:00:00 2001 From: Patrick Cowland Date: Tue, 15 Oct 2024 18:31:37 +0100 Subject: [PATCH 3/3] remove confusing backticks --- internal/connector/templates/hcl_import_header.template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/connector/templates/hcl_import_header.template b/internal/connector/templates/hcl_import_header.template index e6470e38..32ffaf9d 100644 --- a/internal/connector/templates/hcl_import_header.template +++ b/internal/connector/templates/hcl_import_header.template @@ -12,7 +12,7 @@ # https://developer.hashicorp.com/terraform/language/import # # To generate Terraform configuration, run `terraform plan` with the `-generate-config-out` flag. For example: -# `terraform plan -generate-config-out=generated_resources.tf` +# terraform plan -generate-config-out=generated_resources.tf # # There are limitations in the generation process that may result in errors being shown on `terraform plan`. #