Merge pull request #112 from Cox-Automotive/updateDocs

Update TFP Docs

docs/data-sources/alks_keys.md

@@ -0,0 +1,27 @@
+# Data Source: alks_keys
+
+Returns credentials for a given AWS account using ALKS.
+
+## Example Usage
+
+```hcl
+data "alks_keys" "account_keys" {
+   providers: alks.my_alias
+}
+```
+
+## Argument Reference
+
+* Note: This does not take any arguments. See below.
+
+## Attribute Reference
+
+* `access_key` - Generated access key for the specified provider. If multiple providers, it takes the `provider` field. Otherwise, uses the initial provider.
+* `secret_key` - Generated secret key for the specified provider. If multiple providers, it takes the `provider` field. Otherwise, uses the initial provider.
+* `session_token` - Generated session token for the specified provider. If multiple providers, it takes the `provider` field. Otherwise, uses the initial provider.
+* `account` - The account number of the returned keys.
+* `role` - The role from the returned keys.
+
+
+## How it works 
+- Whatever your default provider credentials are, will be used. If multiple providers have been configured, then one can point the data source to return keys for specific providers using `providers` field with an explicit alias.

docs/guides/example_usage.md

@@ -0,0 +1,15 @@
+---
+page_title: "Example usage of ALKS TFP"
+---
+
+## Example
+
+See [this example](https://github.com/Cox-Automotive/terraform-provider-alks/blob/master/examples/alks.tf) for a basic Terraform script which:
+
+1. Creates an AWS provider and ALKS provider
+   - Note: There are two ALKS / AWS providers to showcase multi-provider configuration in use.
+2. Creates an IAM role via the ALKS provider
+3. Attaches a policy to the created role using the AWS provider
+4. Creates an LTK user via the ALKS provider.
+
+This example is intended to show how to combine a typical AWS Terraform script with the ALKS provider to automate the creation of IAM roles and other infrastructure.

docs/guides/local_installation.md

@@ -0,0 +1,49 @@
+---
+page_title: "Local Installation"
+---
+
+### Terraform Version < 0.13 Local Installation
+* Download and install [Terraform](https://www.terraform.io/intro/getting-started/install.html)
+
+* Download ALKS Provider binary for your platform from [Releases](https://github.com/Cox-Automotive/terraform-provider-alks/releases)
+
+For example on macOS:
+
+```
+curl https://github.com/Cox-Automotive/terraform-provider-alks/releases/download/1.5.0/terraform-provider-alks_1.5.0_darwin_amd64.zip -O -J -L | unzip
+```
+
+* Configure Terraform to use this plugin by placing the binary in `.terraform.d/plugins/` on MacOS/Linux or `terraform.d\plugins\` in your user's "Application Data" directory on Windows.
+
+* Note: If you've used a previous version of the ALKS provider and created a `.terraformrc` file in your home directory you'll want to remove it prior to updating.
+
+### Terraform Version >= 0.13 Local Installation
+* Download and install [Terraform](https://www.terraform.io/intro/getting-started/install.html)
+
+* Download ALKS Provider binary for your platform from [Releases](https://github.com/Cox-Automotive/terraform-provider-alks/releases)
+
+For example on macOS:
+
+```
+curl https://github.com/Cox-Automotive/terraform-provider-alks/releases/download/1.5.0/terraform-provider-alks_1.5.0_darwin_amd64.zip -O -J -L | unzip
+```
+
+* Go into the Terraform plugins path; `.terraform.d/plugins/` on MacOS/Linux or `terraform.d\plugins\` in your user's "Application Data" directory on Windows.
+
+* Create the following directories: `coxautoinc.com/engineering-enablement/alks/1.5.0/<OS>_<ARCH>` and put the binary into the `<OS>_<ARCH>/` directory.
+  * Note: This `<OS>_<ARCH>` will vary depending on your system. For example, 64-bit MacOS would be: `darwin_amd64` while 64-bit Windows 10 would be: `windows_amd64` 
+
+* Finally, configure Terraform.
+    * In your `versions.tf` or `main.tf` file you'll want to add the new ALKS provider as such:
+    ```
+    terraform {
+        required_version = ">= 0.13"
+        required_providers {
+        alks = {
+            source = "coxautoinc.com/engineering-enablement/alks"
+            }
+        }
+    }
+    ```
+
+* Note: If you've previously installed our provider and it is stored in your remote state, you may need to run the [`replace-provider` command](https://www.terraform.io/docs/commands/state/replace-provider.html).

docs/index.md

@@ -102,6 +102,49 @@ provider "alks" {
 }
 ```
 
+
+### Multiple Provider Configuration
+
+You can configure multiple ALKS providers to each have their own account context. 
+
+The initial provider must have credentials set in a default way (static, shared credentials file, environment variables, etc) before the second provider can determine whether your account/role combination are allowed. 
+
+The second (or so) provider can then be used to generate resources for multiple accounts in one plan / apply.
+
+Note: This only works for accounts you have access to!
+
+```tf
+# PROVIDER 1
+provider "alks" {
+  url = "https://alks.coxautoinc.com/rest"
+}
+
+# PROVIDER 2
+provider "alks" {
+  url     = "https://alks.coxautoinc.com/rest"
+  account = "<account No>"
+  role    = "<role>"
+  alias   = "second"
+}
+
+# CREATE IAM ROLE -- PROVIDER 1
+resource "alks_iamrole" "test_role" {
+  name                     = "TEST-DELETE"
+  type                     = "AWS CodeBuild"
+  include_default_policies = false
+  enable_alks_access       = true
+}
+
+# CREATE IAM ROLE -- PROVIDER 2
+resource "alks_iamrole" "test_role_nonprod" {
+  provider                 = alks.second
+  name                     = "TEST-DELETE"
+  type                     = "AWS CodeBuild"
+  include_default_policies = false
+  enable_alks_access       = true
+}
+```
+
 ## Argument Reference
 
 In addition to [generic `provider` arguments](https://www.terraform.io/docs/configuration/providers.html?_ga=2.182283811.562816692.1597670778-20010454.1565803281) (e.g. `alias` and `version`), the following arguments are supported in the AWS provider block:
@@ -119,4 +162,4 @@ In addition to [generic `provider` arguments](https://www.terraform.io/docs/conf
     * `policy` - (Optional) This specifies additional policy restrictions to apply to the resulting STS credentials beyond any existing inline or managed policies. Please see the AWS SDK documentation for more information.
 
 ---
-For more in-depth docs, please visit the [Github repository](https://github.com/Cox-Automotive/terraform-provider-alks).
+For questions, please reach out to the [ALKS team](https://github.com/orgs/Cox-Automotive/teams/cai-internal-tools).

examples/alks.tf

@@ -24,12 +24,12 @@ provider "aws" {
 # Second AWS provider, using credentials retreived from data source.
 provider "aws" {
   region = "us-east-1"
-  alias = "nonprod"
+  alias  = "nonprod"
 
   # data source alks keys
   access_key = data.alks_keys.non_prod_keys.access_key
   secret_key = data.alks_keys.non_prod_keys.secret_key
-  token = data.alks_keys.non_prod_keys.session_token
+  token      = data.alks_keys.non_prod_keys.session_token
 }
 
 # CREATE IAM ROLE -- Initial Provider
@@ -51,9 +51,9 @@ resource "alks_iamrole" "test_role_nonprod" {
 
 # ATTACH POLICY
 resource "aws_iam_role_policy" "test_policy" {
-    name     = "test_policy"
-    role     = "${alks_iamrole.test_role.name}"
-    policy   = <<EOF
+  name   = "test_policy"
+  role   = "${alks_iamrole.test_role.name}"
+  policy = <<EOF
 {
   "Version": "2012-10-17",
   "Statement": [
@@ -71,11 +71,11 @@ EOF
 
 # ATTACH MANAGED POLICY
 resource "aws_iam_role_policy_attachment" "sr-attach" {
-    role       = "${alks_iamrole.test_role.name}"
-    policy_arn = "arn:aws:iam::aws:policy/service-role/AWSElasticBeanstalkService"
+  role       = "${alks_iamrole.test_role.name}"
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSElasticBeanstalkService"
 }
 
 # CREATE LTK USER
 resource "alks_ltk" "ltk" {
-    iam_username = "TEST_LTK_USER"
+  iam_username = "TEST_LTK_USER"
 }

examples/versions.tf

@@ -1,8 +1,8 @@
 terraform {
   required_providers {
     alks = {
-      source  = "coxautoinc.com/engineering-enablement/alks"
-      version = "1.4.4"
+      source  = "Cox-Automotive/alks"
+      version = "1.5.8"
     }
     aws = {
       source = "hashicorp/aws"