diff --git a/README.md b/README.md index 35022cba..f135db7d 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This module is used for creating IAM Roles via the ALKS API. * With an `IAMAdmin|LabAdmin` role, you can create roles and attach policies, but you can't create other infrastructure. * Works with [Terraform](https://www.terraform.io/) version `0.10.0` or newer. -## Installation +## Terraform version < 0.13 Installation * Download and install [Terraform](https://www.terraform.io/intro/getting-started/install.html) @@ -28,6 +28,38 @@ curl -L https://github.com/Cox-Automotive/terraform-provider-alks/releases/downl * 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 Terraform 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 -L https://github.com/Cox-Automotive/terraform-provider-alks/releases/download/1.4.3/terraform-provider-alks-darwin-amd64.tar.gz | tar zxv +``` + +* 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.4.3/_` and put the binary into the `_/` directory. + * Note: This `_` 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). + ## Usage ### Authentication @@ -138,15 +170,15 @@ resource "alks_iamrole" "test_role" { } ``` -Value | Type | Forces New | Value Type | Description ---------------------------------- | -------- | ---------- | ---------- | ----------- -`name` | Required | yes | string | The name of the IAM role to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. Role names are not distinguished by case. -`type` | Required | yes | string | The role type to use. [Available Roles](https://gist.github.com/brianantonelli/5769deff6fd8f3ff30e40b844f0b1fb4) -`include_default_policies` | Required | yes | bool | Whether or not the default managed policies should be attached to the role. -`role_added_to_ip` | Computed | n/a | bool | Indicates whether or not an instance profile role was created. -`arn` | Computed | n/a | string | Provides the ARN of the role that was created. -`ip_arn` | Computed | n/a | string | If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. -`enable_alks_access` | Optional | yes | bool | If true, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. +| Value | Type | Forces New | Value Type | Description | +| -------------------------- | -------- | ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Required | yes | string | The name of the IAM role to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. Role names are not distinguished by case. | +| `type` | Required | yes | string | The role type to use. [Available Roles](https://gist.github.com/brianantonelli/5769deff6fd8f3ff30e40b844f0b1fb4) | +| `include_default_policies` | Required | yes | bool | Whether or not the default managed policies should be attached to the role. | +| `role_added_to_ip` | Computed | n/a | bool | Indicates whether or not an instance profile role was created. | +| `arn` | Computed | n/a | string | Provides the ARN of the role that was created. | +| `ip_arn` | Computed | n/a | string | If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. | +| `enable_alks_access` | Optional | yes | bool | If true, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. | #### `alks_iamtrustrole` @@ -160,15 +192,15 @@ resource "alks_iamtrustrole" "test_trust_role" { } ``` -Value | Type | Forces New | Value Type | Description ---------------------------------- | -------- | ---------- | ---------- | ----------- -`name` | Required | yes | string | The name of the IAM role to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. Role names are not distinguished by case. -`type` | Required | yes | string | The role type to use `Cross Account` or `Inner Account`. -`trust_arn` | Required | yes | string | account role arn to trust. -`role_added_to_ip` | Computed | n/a | bool | Indicates whether or not an instance profile role was created. -`arn` | Computed | n/a | string | Provides the ARN of the role that was created. -`ip_arn` | Computed | n/a | string | If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. -`enable_alks_access` | Optional | yes | bool | If `true`, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. +| Value | Type | Forces New | Value Type | Description | +| -------------------- | -------- | ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | Required | yes | string | The name of the IAM role to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. Role names are not distinguished by case. | +| `type` | Required | yes | string | The role type to use `Cross Account` or `Inner Account`. | +| `trust_arn` | Required | yes | string | account role arn to trust. | +| `role_added_to_ip` | Computed | n/a | bool | Indicates whether or not an instance profile role was created. | +| `arn` | Computed | n/a | string | Provides the ARN of the role that was created. | +| `ip_arn` | Computed | n/a | string | If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. | +| `enable_alks_access` | Optional | yes | bool | If `true`, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. | ### `alks_ltk` @@ -178,12 +210,12 @@ resource "alks_ltk" "test_ltk_user" { } ``` -Value | Type | Forces New | Value Type | Description ---------------------------------- | -------- | ---------- | ---------- | ----------- -`iam_username` | Required | yes | string | The name of the IAM user to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. User names are not distinguished by case. -`iam_user_arn` | Computed | n/a | string | The ARN associated with the LTK user. -`access_key` | Computed | n/a | string | Generated access key for the LTK user. Note: This is saved in the state file, so please be aware of this. -`secret_key` | Computed | n/a | string | Generated secret key for the LTK user. Note: This is saved in the state file, so please be aware of this. +| Value | Type | Forces New | Value Type | Description | +| -------------- | -------- | ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `iam_username` | Required | yes | string | The name of the IAM user to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. User names are not distinguished by case. | +| `iam_user_arn` | Computed | n/a | string | The ARN associated with the LTK user. | +| `access_key` | Computed | n/a | string | Generated access key for the LTK user. Note: This is saved in the state file, so please be aware of this. | +| `secret_key` | Computed | n/a | string | Generated secret key for the LTK user. Note: This is saved in the state file, so please be aware of this. | ## Example diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..96a41998 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,122 @@ +# ALKS Terraform Provider + +The ALKS Terraform Provider is used to interact with several resources supported by ALKS. The provider needs to be configured with the proper credentials before it can be used. + +Use the navigation to the left to read about the available resources. + +## Example Usage + +```hcl +# Configure the ALKS Terraform Provider +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" +} + +# Create an ALKS IAM role +resource "alks_iamrole" "test_role" { + name = "My_Test_Role" + type = "Amazon EC2" + include_default_policies = false + enable_alks_access = false +} +``` + +## Authentication + +The ALKS Terraform Provider offers a flexible means of providing credentials for authentication. The following methods are supported, in this order, and explained below: + +### Static credentials + +!> **Warning:** Hard-coding credentials into any Terraform configuration is not recommended, and risks secret leakage should this file ever be committed to a public version control system. + +Static credentials can be provided via an `access_key`, `secret_key` and `token` in-line in the ALKS provider block. This method is generally not recommended, since the credentials could accidentally be committed or shared. + +```hcl +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" + access_key = "accesskey" + secret_key = "secretkey" + token = "sessiontoken" +} +``` + +### Environment variables +You can provide your credentials via the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables. If you need to pass multiple AWS credentials (when using a combination of Roles, like PowerUser and IAMAdmin) you can use the ALKS_ prefix in place of AWS_ (ex: ALKS_ACCESS_KEY_ID) as these are prioritized over the AWS_ prefixed environment varaibles for the provider. + +Terraform file: +```hcl +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" +} +``` + +Terminal: +```hcl +$ alks sessions open -i +$ export AWS_ACCESS_KEY_ID="accesskey" +$ export AWS_SECRET_ACCESS_KEY="secretkey" +$ export AWS_SESSION_TOKEN="sessiontoken" +$ terraform plan +``` + +### Shared credentials/configuration file +You can use an AWS credentials file to specify your credentials. The default location is `$HOME/.aws/credentials` on Linux and OSX, or `"%USERPROFILE%\.aws\credentials"` for Windows users. If we fail to detect credentials inline, or in the environment, Terraform will check this location last. You can optionally specify a different location in the configuration via the `shared_credentials_file` attribute, or via the environment with the `AWS_SHARED_CREDENTIALS_FILE` variable. This method also supports a profile configuration and matching `AWS_PROFILE` environment variable. + +```hcl +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" + shared_credentials_file = "/Users/my_user/.aws/credentials" + profile = "foo" +} +``` + +### Machine Identities +You can use a role created with ALKS with the `enable_alks_access` flag set to `true` to authenticate requests against ALKS. + +In order to do this, ALKS must be called from within AWS using STS credentials from an instance profile associated with the role with `enable_alks_access` set. This also works from Lambda functions in the same way. + +The STS credentials are used and provided in the same way that the AWS CLI uses the credentials, so there is nothing special you have to do to use Machine Identities. + +Your ALKS provider block can look just like this: + +```hcl +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" +} +``` + +Since Machine Identities work with Instance Profile Metadata directly, it can be helpful to assume another role or cross account trust. For example: + +```hcl +provider "alks" { + url = "https://alks.foo.com/rest" + version = "~> 1.4.3" + assume_role { + role_arn = "arn:aws:iam::112233445566:role/acct-managed/JenkinsPRODAccountTrust" + } +} +``` + +## 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: + +* `url` - (Required) The URL to your ALKS server. Also read from ENV.ALKS_URL +* `access_key` - (Optional) The access key from a valid STS session. Also read from ENV.ALKS_ACCESS_KEY_ID and ENV.AWS_ACCESS_KEY_ID. +* `secret_key` - (Optional) The secret key from a valid STS session. Also read from ENV.ALKS_SECRET_ACCESS_KEY and ENV.AWS_SECRET_ACCESS_KEY. +* `token` - (Optional) The session token from a valid STS session. Also read from ENV.ALKS_SESSION_TOKEN and ENV.AWS_SESSION_TOKEN. +* `shared_credentials_file` - (Optional) The the path to the shared credentials file. Also read from ENV.AWS_SHARED_CREDENTIALS_FILE. +* `profile` - (Optional) This is the AWS profile name as set in the shared credentials file. Also read from ENV.AWS_PROFILE. +* `assume_role` - (Optional) This is the role information to assume before making calling ALKS. This feature works the same as the assume_role feature of the AWS Terraform Provider. + * `role_arn` - (Required) The Role ARN to assume for calling the ALKS API. + * `session_name` - (Optional) The session name to provide to AWS when creating STS credentials. Please see the AWS SDK documentation for more information. + * `external_id` - (Optional) The external identifier to provide to AWS when creating STS credentials. Please see the AWS SDK documentation for more information. + * `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). \ No newline at end of file diff --git a/docs/resources/alks_iamrole.md b/docs/resources/alks_iamrole.md new file mode 100644 index 00000000..295e6c21 --- /dev/null +++ b/docs/resources/alks_iamrole.md @@ -0,0 +1,26 @@ +# Resource: alks_iamrole + +Creates an custom ALKS IAM role for usage in an AWS account. + +## Example Usage + +### ALKS IAM Role Creation +```hcl +resource "alks_iamrole" "test_role" { + name = "My_Test_Role" + type = "Amazon EC2" + include_default_policies = false + enable_alks_access = false +} +``` + +## Argument Reference + +The following arguments are supported: +* `name` - (Required) The name of the ALKS IAM role which will be reflected in AWS and the ALKS UI. +* `type` - (Required) The role type to use. To see a list of available roles, [call this endpoint](https://pages.ghe.coxautoinc.com/ETS-CloudAutomation/ALKS-Documentation/#/aws-role-type-rest-service/getAllAwsRoleTypesUsingGET). +* `include_default_policies` - (Required) Whether or not the default manages policies should be attached to the role. +* `role_added_to_ip` - (Computed) Indicates whether or not an instance profile role was created. +* `arn` - (Computed) Provides the ARN of the role that was created. +* `ip_arn` - (Computed) If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. +* `enable_alks_access` - (Optional) If `true`, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. Note: This enables **machine identity** capability. \ No newline at end of file diff --git a/docs/resources/alks_iamtrustrole.md b/docs/resources/alks_iamtrustrole.md new file mode 100644 index 00000000..13ed1771 --- /dev/null +++ b/docs/resources/alks_iamtrustrole.md @@ -0,0 +1,28 @@ +# Resource: alks_iamtrustrole + +Creates an IAM trust role on AWS. + +## Example Usage + + +### ALKS IAM Role Creation +```hcl +resource "alks_iamtrustrole" "test_trust_role" { + name = "My_Cross_Test_Role" + type = "Cross Account" + # type = "Inner Account" + trust_arn = "arn:aws:iam::123456789123:role/acct-managed/TestTrustRole" + enable_alks_access = false +} +``` + +## Argument Reference + +The following arguments are supported: +* `name` - (Required) The name of the IAM role to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. Role names are not distinguished by case. +* `type` - (Required) The role type to use `Cross Account` or `Inner Account`. +* `trust_arn` - (Required) Account role ARN to trust. +* `role_added_to_ip` - (Computed) Indicates whether or not an instance profile role was created. +* `arn` - (Computed) Provides the ARN of the role that was created. +* `ip_arn` - (Computed) If `role_added_to_ip` was `true` this will provide the ARN of the instance profile role. +* `enable_alks_access` - (Optional) If `true`, allows ALKS calls to be made by instance profiles or Lambda functions making use of this role. Note: This enables **machine identity** capability. \ No newline at end of file diff --git a/docs/resources/alks_ltk.md b/docs/resources/alks_ltk.md new file mode 100644 index 00000000..4d469b27 --- /dev/null +++ b/docs/resources/alks_ltk.md @@ -0,0 +1,27 @@ +# Resource: alks_ltk + +Creates a long term key user role in AWS. + +## Example Usage + +### ALKS IAM Role Creation +```hcl +resource "alks_ltk" "test_ltk_user" { + iam_username = "My_LTK_User_Name" +} +``` + +## Argument Reference + +The following arguments are supported: +* `iam_username` - (Required) The name of the IAM user to create. This parameter allows a string of characters consisting of upper and lowercase alphanumeric characters with no spaces. You can also include any of the following characters: =,.@-. User names are not distinguished by case. +* `iam_user_arn` - (Computed) The ARN associated with the LTK user. +* `access_key` - (Computed) Generated access key for the LTK user. Note: This is saved in the state file, so please be aware of this. +* `secret_key` - (Computed) Generated secret key for the LTK user. Note: This is saved in the state file, so please be aware of this. + +## Import + +AWS IAM users can be imported using their user name, eg: +``` +$ terraform import alks_ltk.my_ltk_resource MY_EXISTING_LTK_USER +``` \ No newline at end of file