Expand and restructure config generation plan error docs

docs/exporting-configuration/README.md

@@ -2,8 +2,15 @@
 
 ## Resolving Terraform Plan Errors
 
-The following documents describe the actions that must be taken, per provider, to resolve `terraform plan` errors following configuration generation.
+When generating Terraform HCL configuration, errors on `terraform plan` are expected. Reasons for plan errors include:
 
-- [PingOne Terraform Provider](./pingone-plan-errors.md)
+- Certain field values are not retrievable from the Ping system.  This might be because values are sensitive (secret) and are not retrievable to maintain tenant security.  In these cases, manual adjustment is needed to ensure these values are defined in generated HCL.
+- Ambiguity in the retrieved configuration from the Ping system.  In these cases, the intention of the configuration cannot be accurately determined and requires manual correction.
+- Limitations with Terraform's `terraform plan --generate-config-out` command action. Limitations are described in further detail on Terraform's developer documentation, [Generating Configuration](https://developer.hashicorp.com/terraform/language/import/generating-configuration)
 
-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).
+The following documents describe the actions that must be taken, per provider, to resolve the various `terraform plan` errors following configuration generation.
+
+- [PingFederate Terraform Provider](./plan-errors/pingfederate.md)
+- [PingOne Terraform Provider](./plan-errors/pingone.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).

docs/exporting-configuration/plan-errors/pingfederate.md

@@ -0,0 +1,24 @@
+# Terraform Configuration Generation - PingFederate 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%20PingFederate%20Config%20Generation%20Error).
+
+## General (Any Resource)
+
+### Reference to undeclared resource - A managed resource "[any]" "[any]" has not been declared in the root module
+
+**Cause**: Terraform configuration has been generated with syntax errors.  This is an issue with the Terraform CLI.
+
+**Resolution**: Upgrade the Terraform CLI to the latest version available and re-generate the HCL configuration.
+
+## Resource Plan Errors
+
+- [pingfederate_certificate_ca](pingfederate_certificate_ca.md)
+- [pingfederate_data_store](pingfederate_data_store.md)
+- [pingfederate_idp_adapter](pingfederate_idp_adapter.md)
+- [pingfederate_kerberos_realm](pingfederate_kerberos_realm.md)
+- [pingfederate_oauth_access_token_manager](pingfederate_oauth_access_token_manager.md)
+- [pingfederate_oauth_client](pingfederate_oauth_client.md)
+- [pingfederate_password_credential_validator](pingfederate_password_credential_validator.md)
+- [pingfederate_pingone_connection](pingfederate_pingone_connection.md)

docs/exporting-configuration/plan-errors/pingfederate_certificate_ca.md

@@ -0,0 +1,33 @@
+# Terraform Configuration Generation - PingFederate Plan Errors (pingfederate_certificate_ca)
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingfederate/latest/docs/resources/certificate_ca#schema)
+
+## Invalid Attribute Value Length - Attribute file_data string length must be at least 1, got: 0
+
+**Cause**: The CA file data is not exported.
+
+**Resolution**: Manual modification is required to set the `file_data` field in the generated HCL.
+
+**Example**:
+
+Generated configuration:
+```hcl
+resource "pingfederate_certificate_ca" "my_awesome_certificate_ca" {
+  ca_id           = "7zz3****************5fnja"
+  crypto_provider = null
+  file_data       = ""
+}
+```
+
+After manual modification (`file_data` is defined):
+```hcl
+resource "pingfederate_certificate_ca" "my_awesome_certificate_ca" {
+  ca_id           = "7zz3****************5fnja"
+  crypto_provider = null
+  file_data       = filebase64("my_ca.pem")
+}
+```
+
+
+

docs/exporting-configuration/plan-errors/pingfederate_data_store.md

@@ -0,0 +1,46 @@
+# Terraform Configuration Generation - PingFederate Plan Errors (pingfederate_data_store)
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingfederate/latest/docs/resources/data_store#nestedatt--ldap_data_store)
+
+## Invalid attribute configuration - 'password' and 'user_dn' must be set together
+
+**Cause**: The data store password is not exported from PingFederate to maintain tenant security.
+
+**Resolution**: Manual modification is required to set the `ldap_data_store.password` field in the generated HCL.
+
+**Example**:
+
+Generated configuration:
+```hcl
+resource "pingfederate_data_store" "my_ldap_data_store" {
+  # ... other configuration parameters
+
+  ldap_data_store = {
+    # ... other configuration parameters
+
+    ldap_type = "PING_DIRECTORY"
+    name      = "PingDirectory LDAP Data Store"
+    password  = null # sensitive
+    user_dn   = "cn=administrator"
+  }
+}
+```
+
+After manual modification (`ldap_data_store.password` is defined):
+```hcl
+resource "pingfederate_data_store" "my_ldap_data_store" {
+  # ... other configuration parameters
+
+  ldap_data_store = {
+    # ... other configuration parameters
+
+    ldap_type = "PING_DIRECTORY"
+    name      = "PingDirectory LDAP Data Store"
+    password  = var.pingdirectory_ldap_data_store
+    user_dn   = "cn=administrator"
+  }
+}
+```
+
+

docs/exporting-configuration/plan-errors/pingfederate_idp_adapter.md

@@ -0,0 +1,78 @@
+# Terraform Configuration Generation - PingFederate Plan Errors (pingfederate_idp_adapter)
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingfederate/latest/docs/resources/idp_adapter#schema)
+
+## Missing Configuration for Required Attribute - Must set a configuration value for the configuration.sensitive_fields[Value({"name":"API Key","value":<null>})].value attribute as the provider has marked it as required.
+
+**Cause**: The DaVinci adapter's API key is not exported from PingFederate to maintain tenant security.
+
+**Resolution**: Manual modification is required to set the `configuration.sensitive_fields` field to include an object with `name`=`API Key`, and `value` is the API key, in the generated HCL.
+
+**Example**:
+
+Generated configuration:
+```hcl
+resource "pingfederate_idp_adapter" "my_davinci_adapter" {
+  # ... other configuration parameters
+
+  adapter_id = "myDaVinciAdapter"
+
+  configuration = {
+    # ... other configuration parameters
+
+    fields = [
+       # ... other configuration parameters
+
+      {
+        name  = "API Request Timeout"
+        value = jsonencode(5000)
+      },
+      {
+        name  = "Additional Properties Attribute"
+        value = "additionalProperties"
+      },
+    ]
+    sensitive_fields = [
+      {
+        name  = "API Key"
+        value = null # sensitive
+      },
+    ]
+  }
+}
+```
+
+After manual modification (The DaVinci API key is defined):
+```hcl
+resource "pingfederate_idp_adapter" "my_davinci_adapter" {
+  # ... other configuration parameters
+
+  adapter_id = "myDaVinciAdapter"
+
+  configuration = {
+    # ... other configuration parameters
+
+    fields = [
+       # ... other configuration parameters
+
+      {
+        name  = "API Request Timeout"
+        value = jsonencode(5000)
+      },
+      {
+        name  = "Additional Properties Attribute"
+        value = "additionalProperties"
+      },
+    ]
+    sensitive_fields = [
+      {
+        name  = "API Key"
+        value = var.my_davinci_adapter_api_key
+      },
+    ]
+  }
+}
+```
+
+

docs/exporting-configuration/plan-errors/pingfederate_kerberos_realm.md

@@ -0,0 +1,37 @@
+# Terraform Configuration Generation - PingFederate Plan Errors (pingfederate_kerberos_realm)
+
+**Documentation**:
+- [Terraform Registry](https://registry.terraform.io/providers/pingidentity/pingfederate/latest/docs/resources/kerberos_realm#schema)
+
+## Invalid attribute configuration - kerberos_password is required when connection_type is set to "DIRECT".
+
+**Cause**: The Kerberos password is not exported from PingFederate to maintain tenant security.
+
+**Resolution**: Manual modification is required to set the `kerberos_password` field in the generated HCL.
+
+**Example**:
+
+Generated configuration:
+```hcl
+resource "pingfederate_kerberos_realm" "my_kerberos_realm" {
+  # ... other configuration parameters
+
+  connection_type                         = "DIRECT"
+  kerberos_password                       = null # sensitive
+  kerberos_realm_name                     = "My Kerberos Realm"
+  kerberos_username                       = "myKerberos"
+}
+```
+
+After manual modification (`kerberos_password` is defined):
+```hcl
+resource "pingfederate_kerberos_realm" "my_kerberos_realm" {
+  # ... other configuration parameters
+
+  connection_type                         = "DIRECT"
+  kerberos_password                       = var.my_kerberos_realm_password
+  kerberos_realm_name                     = "My Kerberos Realm"
+  kerberos_username                       = "myKerberos"
+}
+```
+