Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/matthewoden/cfenv
Environmental helpers for cloudfoundry, parsing and returning values off VCAP_SERVICES and VCAP_APPLICATON
https://github.com/matthewoden/cfenv
Last synced: about 1 month ago
JSON representation
Environmental helpers for cloudfoundry, parsing and returning values off VCAP_SERVICES and VCAP_APPLICATON
- Host: GitHub
- URL: https://github.com/matthewoden/cfenv
- Owner: matthewoden
- License: mit
- Created: 2017-11-23T22:40:43.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2018-12-12T03:46:31.000Z (about 6 years ago)
- Last Synced: 2024-04-16T22:22:54.939Z (9 months ago)
- Language: Elixir
- Size: 28.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# CFEnv
A helper application for grabbing and parsing CloudFoundry Environment
Variables.
A small application for parsing and retrieving `VCAP_SERVICES`, and
`VCAP_APPLICATION.`
## API Preview
```elixir
> MyApp.Env.service_credentials("dynamo-db")
%{"database" => "dynamo", "accessKeyId" => "abcd", "secretAccessKey" => "defg",
"tableName" => "test-table" }
```
Or grabbing the current application name.
```elixir
iex(1)> MyApp.Env.app_name()
"test_app"
```
See [the documentation](https://hexdocs.pm/cf_env/CFEnv.html) for other api
examples.
## Migration to 1.0.0
CFEnv is no longer an application, but a process started within your application, with functions created as a macro. All functionality is present, but CFEnv.Services and CFEnv.Application have been combined. See usage instructions below, and the `CFEnv` module.
## Usage
You'll need to add cf_env as a dependancy to your mix.exs file, along with a
module for parsing json. `CFEnv` supports `Poison` and `Jason` by
default, though custom JSON adapters can be provided. See `CFEnv.Adapters.JSON` for details.
### Dependancies
```elixir
def deps do
[
{:cf_env, "~> 1.0"},
{:jason, "~> 1.1"},
# or, if you prefer poison
{:poison, "~> 3.0"}
]
end
```
Then, fetch your dependencies:
```bash
$ mix deps.get
```
You'll need to create a module that represents your service bindings.
```elixir
defmodule MyApp.Env do
use CFEnv,
otp_app: :my_app,
json_engine: Jason
...
```
Finally, add the process to your supervision tree:
```elixir
# For Elixir v1.5 and later
{MyApp.Env, [ default_bindings: %{} ]}
# For Elixir v1.4 and earlier
supervisor(MyApp.Env, [ default_bindings: %{}])
```
## Configuration
You can provide options as application config, or with runtime config. Runtime config always overrides application config.
### Application Config
```elixir
config :my_app, MyApp.Env
json_engine: Jason,
default_services: %{
"some_db" => %{
"username" => System.get_env("TEST_USER"),
"password" => System.get_env("TEST_PASSWORD")
}
}
...
```
### Runtime Config
```elixir
options = [
json_engine: Jason,
default_services: %{
"some_db" => %{
"username" => System.get_env("TEST_USER"),
"password" => System.get_env("TEST_PASSWORD")
}
}]
# explicit start
MyApp.Env.start_link(])
# supervisor start
children = [
{MyApp.Env, [options]}
]
```
## Default Services
Working with VCAP_SERVICES can be a pain. Instead, default services bindings can be passed in as a map from configuration, where each key is a string. You can provide reasonable defaults for local development this way.
```elixir
config :cf_env,
default_services:
%{ "service_name" => %{
"username" => "u5er",
"password" => "pa$$w0rd"
}
}
```
## Data Conversion
On init, `VCAP_SERVICES` and `VCAP_APPLICATION` are parsed from JSON.
And each value is transformed into a map. If an alias key is present on the
credentials, the service will be mapped to use that name instead. This is useful
for updating the bindings for an application, without having to implement a code
change, or affect other services using this binding.
Every map created this way is merged back into the provided default service map,
with parsed CF services overwriting defaults, if any.
Currently only `user-provided` services are supported.
### Conversion Example:
The following list of services:
```json
{
"user-provided": [
{
"name": "cf-env-test",
"label": "user-provided",
"tags": [],
"credentials": {
"database": "database",
"password": "passw0rd",
"url": "https://example.com/",
"username": "userid"
},
"syslog_drain_url": "http://example.com/syslog"
},
{
"name": "dynamo-db",
"label": "user-provided",
"tags": [],
"credentials": {
"alias": "alias-name",
"database": "dynamo",
"accessKeyId": "abcd",
"secretAccessKey": "defg"
"tableName": "test-table",
},
"syslog_drain_url": "http://example.com/syslog"
}
]
}
```
is reduced to the following map:
```elixir
%{
# using the name
"cf-env-test" => %{
"name" => "cf-env-test",
"label" => "user-provided",
"tags" => [],
"credentials" => %{
"database" => "database",
"password" => "passw0rd",
"url" => "https://example.com/",
"username" => "userid"
},
"syslog_drain_url" => "http://example.com/syslog"
},
# using the provided alias
"another-cf-env-test" => %{
"name" => "another-cf-env-test",
"label" => "user-provided",
"tags" => [],
"credentials" => %{
"alias" => "alias-name",
"database" => "dynamo",
"accessKeyId" => "abcd",
"secretAccessKey" => "defg"
"tableName" => "test-table",
},
"syslog_drain_url": "http://example.com/syslog"
}
}
```
## Local Development / Testing
Use the `.env` file to set up your local environment before testing.