add readme

ldap-ou-create/README.md

@@ -0,0 +1,91 @@
+# About ldap-ou-create
+
+This module will create the initial LDAP OU object in eBOCAS, provided credentials and the provider exists (it checks for this).
+The [ldap-provider](https://github.e.it.census.gov/terraform/support/tree/master/providers/terraform-provider-ldap) binary is expected to be in your `$PATH`.
+This has to be done before creating any roles with `aws-iam-role` and LDAP creation enabled.
+
+There are some quirks to the `ldap-provider` (we use [this](https://github.com/Pryz/terraform-provider-ldap) one), where if any
+details change in the DN or the DN cannot be constructed due to missing data, a *tcp connection closed* message occurs.
+
+Because of this quirk, this is a two-step apply.  The first step creates the IAM role and creates an LDIF file in
+`setup/{role-name}.ldif`.  It uses the presence of this file to create the LDAP object in the second step.  Example:
+
+1. Step 1, creates null resource
+```console
+% terraform apply -target=module.ou
+```
+
+2. Step 2, creates ldap object
+```console
+% terraform apply -target=module.ou
+```
+
+# Usage
+
+```hcl
+module "ou" {
+  source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//ldap-ou-create"
+
+  enable_ldap_creation       = true
+  ldap_user                  = "cn=myuser,ou=Application,o=U.S. Census Bureau,c=US"
+  ldap_password              = "password1234$$"
+
+  # optional
+  # account_id               = "123456789012"
+  ldap_host                  = "ldap.e.tco.census.gov"
+  ldap_port                  = 389
+}
+```
+
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+| <a name="provider_external"></a> [external](#provider\_external) | n/a |
+| <a name="provider_ldap"></a> [ldap](#provider\_ldap) | n/a |
+| <a name="provider_null"></a> [null](#provider\_null) | n/a |
+| <a name="provider_template"></a> [template](#provider\_template) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [ldap_object.ou](https://registry.terraform.io/providers/hashicorp/ldap/latest/docs/resources/object) | resource |
+| [null_resource.ou_ldif](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [aws_arn.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/arn) | data source |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [aws_iam_policy_document.ec2_assume](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_region.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/region) | data source |
+| [external_external.ldap_provider_bin](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/external) | data source |
+| [template_file.ou](https://registry.terraform.io/providers/hashicorp/template/latest/docs/data-sources/file) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_account_alias"></a> [account\_alias](#input\_account\_alias) | AWS Account Alias | `string` | `""` | no |
+| <a name="input_account_id"></a> [account\_id](#input\_account\_id) | AWS Account ID (default will pull from current user) | `string` | `""` | no |
+| <a name="input_component_tags"></a> [component\_tags](#input\_component\_tags) | Additional tags for Components (role, policy) | `map(map(string))` | <pre>{<br>  "policy": {},<br>  "role": {}<br>}</pre> | no |
+| <a name="input_enable_ldap_creation"></a> [enable\_ldap\_creation](#input\_enable\_ldap\_creation) | Flag to enable/disable LDAP object creation for role group (for SAML only). Also requires LDAP credentials. | `bool` | `false` | no |
+| <a name="input_ldap_host"></a> [ldap\_host](#input\_ldap\_host) | LDAP Hostname (default is for eBOCAS) | `string` | `"ldap.e.tco.census.gov"` | no |
+| <a name="input_ldap_password"></a> [ldap\_password](#input\_ldap\_password) | LDAP password for ldap\_user for writing data into eDirectory or Active Directory | `string` | `""` | no |
+| <a name="input_ldap_port"></a> [ldap\_port](#input\_ldap\_port) | LDAP port (default is 389 but also using STARTTLS) | `number` | `389` | no |
+| <a name="input_ldap_user"></a> [ldap\_user](#input\_ldap\_user) | LDAP user for writing data into eDirectory or Active Directory | `string` | `""` | no |
+| <a name="input_override_prefixes"></a> [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component (efs, s3, ebs, kms, role, policy, security-group). This should be used primarily for common infrastructure things | `map(string)` | `{}` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | AWS Tags to apply to appropriate resources (S3, KMS).  Do not include safeguard tags here, use the data\_safeguard field for such things. | `map(string)` | `{}` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_role_arn"></a> [role\_arn](#output\_role\_arn) | Created role ARN |
+| <a name="output_role_name"></a> [role\_name](#output\_role\_name) | Created role name |