Replace documentation with type alias

Keep the top-of-line documentation simple, but supply additional hints
as to how to configure ldap via a type alias (struct) as well as a
yardoc link to the relevant API documentation.

Author: reidmv

documentation/install.md

@@ -107,7 +107,7 @@ Example params.json Bolt parameters file (shown: Extra Large with DR):
 }
 ```
 
-Example params.json Bolt parameters file including LDAP configuration (shown: Standard):
+Example params.json Bolt parameters file (shown: Standard):
 
 ```json
 {
@@ -116,36 +116,10 @@ Example params.json Bolt parameters file including LDAP configuration (shown: St
   "console_password": "puppetlabs",
   "dns_alt_names": [ "puppet", "puppet.lab1.puppet.vm" ],
   "version": "2021.5.0",
-
-  "ldap_config": {
-    "help_link": "https://help.example.com",
-    "ssl": true,
-    "group_name_attr": "name",
-    "password": "skippy",
-    "group_rdn": null,
-    "connect_timeout": 15,
-    "user_display_name_attr": "cn",
-    "disable_ldap_matching_rule_in_chain": false,
-    "ssl_hostname_validation": true,
-    "hostname": "ldap.example.com",
-    "base_dn": "dc=example,dc=com",
-    "user_lookup_attr": "uid",
-    "port": 636,
-    "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
-    "group_lookup_attr": "cn",
-    "group_member_attr": "uniqueMember",
-    "ssl_wildcard_validation": false,
-    "user_email_attr": "mail",
-    "user_rdn": "ou=users",
-    "group_object_class": "groupOfUniqueNames",
-    "display_name": "Acme Corp Ldap server",
-    "search_nested_groups": true,
-    "start_tls": false
-  }
 }
 ```
 
-Review the [peadm::install plan](../plans/install.pp) to learn about more advanced installation options. It is possible to supply an ssh private key and git clone URL for a control-repo as part of installation, for example.
+Review the [peadm::install plan](../plans/install.pp) to learn about more advanced installation options. For example, it is possible to: supply an ssh private key and git clone URL for a control-repo as part of installation; supply the LDAP configuration data for PE; and similar complete automation tie-ins.
 
 ## Offline usage
 

plans/install.pp

@@ -16,6 +16,11 @@
 #   specified, PEAdm will attempt to download PE installation media from its
 #   standard public source. When specified, PEAdm will download directly from the
 #   URL given.
+# @param ldap_config
+#   If specified, configures PE RBAC DS with the supplied configuration hash.
+#   The parameter should be set to a valid set of connection settings as
+#   documented for the PE RBAC /ds endpoint. See:
+#   https://puppet.com/docs/pe/latest/rbac_api_v1_directory.html#put_ds-request_format
 #
 plan peadm::install (
   # Standard
@@ -38,7 +43,7 @@
   Optional[String]                  $internal_compiler_a_pool_address = undef,
   Optional[String]                  $internal_compiler_b_pool_address = undef,
   Optional[Hash]                    $pe_conf_data                     = { },
-  Optional[Hash]                    $ldap_config                      = undef,
+  Optional[Peadm::Ldap_config]      $ldap_config                      = undef,
 
   # Code Manager
   Optional[String]                  $r10k_remote              = undef,

plans/subplans/configure.pp

@@ -30,12 +30,12 @@
   Optional[Peadm::SingleTargetSpec] $replica_postgresql_host = undef,
 
   # Common Configuration
-  String           $compiler_pool_address = $primary_host.peadm::certname(),
-  Optional[String] $internal_compiler_a_pool_address = undef,
-  Optional[String] $internal_compiler_b_pool_address = undef,
-  Optional[String] $token_file = undef,
-  Optional[String] $deploy_environment = undef,
-  Optional[Hash]   $ldap_config = undef,
+  String                       $compiler_pool_address = $primary_host.peadm::certname(),
+  Optional[String]             $internal_compiler_a_pool_address = undef,
+  Optional[String]             $internal_compiler_b_pool_address = undef,
+  Optional[String]             $token_file = undef,
+  Optional[String]             $deploy_environment = undef,
+  Optional[Peadm::Ldap_config] $ldap_config = undef,
 
   # Other
   String           $stagingdir = '/tmp',

tasks/pe_ldap_config.json

@@ -2,7 +2,7 @@
   "description": "Set the ldap config in the PE console",
   "parameters": {
     "ldap_config": {
-      "type": "Hash",
+      "type": "Peadm::Ldap_config",
       "description": "The hash of options for ldap."
     },
     "pe_main": {
@@ -14,4 +14,4 @@
   "implementations": [
     {"name": "pe_ldap_config.rb"}
   ]
-}
+}

types/ldap_config.pp

@@ -0,0 +1,25 @@
+type Peadm::Ldap_config = Struct[{
+  base_dn                             => String,
+  connect_timeout                     => Integer,
+  disable_ldap_matching_rule_in_chain => Boolean,
+  display_name                        => String,
+  group_lookup_attr                   => String,
+  group_member_attr                   => String,
+  group_name_attr                     => String,
+  group_object_class                  => String,
+  Optional[group_rdn]                 => Optional[String],
+  Optional[help_link]                 => Optional[String],
+  hostname                            => String,
+  Optional[login]                     => Optional[String],
+  Optional[password]                  => Optional[String],
+  port                                => Integer,
+  search_nested_groups                => Boolean,
+  ssl                                 => Boolean,
+  ssl_hostname_validation             => Boolean,
+  ssl_wildcard_validation             => Boolean,
+  start_tls                           => Boolean,
+  user_display_name_attr              => String,
+  user_email_attr                     => String,
+  user_lookup_attr                    => String,
+  Optional[user_rdn]                  => Optional[String],
+}]