ALKS Provider for Terraform

This module is used for creating IAM Roles via the ALKS API.

Pre-Requisites

• An ALKS Admin or IAMAdmin STS assume-role session is needed. PowerUser access is not sufficient to create IAM roles.
  • This tool is best suited for users with an Admin role
  • With an IAMAdmin|LabAdmin role, you can create roles and attach policies, but you can't create other infrastructure.
• Works with Terraform version 0.10.0 or newer.

Installation

• Download and install Terraform

• Download ALKS Provider binary for your platform from Releases

curl -L https://github.com/Cox-Automotive/terraform-provider-alks/releases/download/1.0.0/terraform-provider-alks-darwin-amd64.tar.gz | tar zxv

• 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.

Usage

Authentication

The ALKS provider offers a flexible means of providing authentication credentials for creating roles. The following methods are supported, in this order, and explained below:

Static Credentials

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.

provider "alks" {
    url        = "https://alks.foo.com/rest"
    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.

provider "alks" {
    url     = "https://alks.foo.com/rest"
}

$ 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 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.

provider "alks" {
    url                     = "https://alks.foo.com/rest"
    shared_credentials_file = "/Users/brianantonelli/.aws/credentials"
    profile                 = "foo"
}

Provider Configuration

Provider Options:

• 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.

Resource Configuration

alks_iamrole

resource "alks_iamrole" "test_role" {
    name                     = "My_Test_Role"
    type                     = "Amazon EC2"
    include_default_policies = false
}

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
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.

alks_iamtrustrole

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"
}

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.

Example

See this example for a basic Terraform script which:

1. Creates an AWS provider and ALKS provider
2. Creates an IAM Role via the ALKS provider
3. Attaches a policy to the created role using the AWS 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.

Building from Source

To build the ALKS provider, install Go (version 1.8+ is required).

Set up a GOPATH and add $GOPATH/bin to your $PATH.

Clone this repository into $GOPATH/src/github.com/Cox-Automotive/terraform-provider-alks. All the necessary dependencies are either vendored or automatically installed (using Godep), so type make build test. This will compile the code and then run the tests. If this exits with exit status 0, then everything is working! Check your examples directory for an example Terraform script and the generated binary.

cd "$GOPATH/src/github.com/Cox-Automotive/terraform-provider-alks"
make built test

If you add any additional depedencies to the project you'll need to run godep save to update Godeps.json and /vendor.