README.md

SparkleFormation Vault Callback

Repo Deprecated

resolvers in the parameter callback can probabl provide this functionality for you now.

Provides a mechanism to read dynamic credentials for use with AWS Orchestration APIs from a Vault secret backend.

Also provides a method to set and store template parameters in a configured Vault instance. This is implemented by handling a custom parameter 'type'.

This is early alpha quality code

Currently supported cloud providers:

• AWS

On initial usage this will read the configured vault path to obtain temporary aws credentials and cache them locally in .sfn-vault. When the lease expires a new credential will be requested.

Usage

Make the callback available by adding it to the bundle via the project's Gemfile:

group :sfn do
  gem 'sfn-vault'
end

Vault Read

Enable

The sfn-vault callback is configured via the .sfn configuration file. First the callback must be enabled:

Configuration.new do
  callbacks do
    require ['sfn-vault']
    default ['vault_read']
  end
end

Configuration

The default read path is aws/creds/deploy and will be used without configuration but it is customizable.

Vault read configuration is controlled within the .sfn file:

Configuration.new
  credentials do
    #  Remote provider name
    provider :aws
    #  AWS credentials information can be empty
    aws_access_key_id ""
    aws_secret_access_key ""
    aws_region 'us-east-1'
    aws_bucket_region 'us-east-1'
    # read path for vault client
    vault_read_path 'awsqa/creds/auto_deploy'
  end
end

The vault read callback will look for VAULT_ADDR and VAULT_TOKEN environment variables by default, or you can set vault_addr and vault_token in the vault section of your configuration. It is generally best to set these as environment variables since the .sfn file should be checked into version control.

The following additional parameters can be adjusted by adding a vault section to your .sfn config:

Configuration.new
  vault do
    vault_addr 'http://127.0.0.1:8200'
    vault_token 'vault-access-token'
    # globally disable vault read callback
    status 'disabled'
    # customize the name of cache file
    cache_file '.sfn-vault'
    # customize vault api client retries
    retries 5
    # number of seconds to wait for iam creds to be ready
    iam_delay 15
  end
end

Vault Pseudo Parameters

Cloudformation parameters can have optional AWS-Specific Parameter Types. In a similar way this callback looks for a special parameter type named Vault::Generic::Secret and will dynamically get or set a key value from Vault. The key will be named to match the parameters name. Then the parameter type in the template is changed to 'String' which can be understood by AWS.

Generally these should be set as NoEcho parameters and a dsl helper method is provided to generate this type of named parameter.

Example usage in template:

vault_parameter!(:secret_value)

Will result in a template with the following parameter defined:

"Parameters": {
  "SecretValue": {
    "NoEcho": true,
    "Description": "Generated secret automatically stored in Vault",
    "Type": "String"
  }
}

And the value of this parameter will be stored and retrieved from a stack specific Vault key by default named like:

cubbyhole/SparkleFormation/template/SecretValue

In this example the template is named 'template', but this will be replaced with the stack name during create/update operations.

The value will be stored in vault and retrieved dynamically at stack creation time. If the sfn command is running in a CI environment, where the CI environment variable is set, then the callback will attempt to use the default generic secret backed path of secret in a stack specific location.

For local development needs or if this environment variable is undetected the vault cubbyhole is used.

The base path is also configurable by using the :pseudo_parameter_path in the sfn config. This replaces either cubbyhole or secret in the vault key used to store the parameter values. If configured this base path will override any CI environment detection and always be honored.

...
vault do
  pseudo_parameter_path "/secret/aws_secrets"
end

By default 15 character base64 strings are generated using SecureRandom. The length can be adjusted by setting :pseudo_parameter_length in the config to any integer value.

Known Issues

• Doesn't support parameters for nested stacks

• If the iam_delay for the vault read behavior is not long enough the generated credentials will not be available for use and api requests will fail. As noted in the Vault documentation this is a limitation due to the eventually consistent behavior of IAM credentials. If you need the credentials to be immediately available, it is suggested to use the STS Callback and set thestatus to disabled in the vault config section. This will disable the vault read behavior but still handles pseudo parameters.

Info

• Repository: https://github.com/webframp/sfn-vault
• IRC: Freenode @ #sparkleformation