mirror of https://github.com/pulumi/pulumi.git
40e0ac20c9
11362: Library for environmental variable access r=iwahbe a=iwahbe
Add a library to encapsulate environmental variable declaration, lookup and parsing.
### Usage
Variables strongly typed and declared in the module scope like so:
```go
// Automatically prefixed with PULUMI_ by default
var Experimental = env.Bool("EXPERIMENTAL", "Enable experimental options and commands")
```
Values are accessed by calling `.Value()` on the module level variable:
```go
if Experimental.Value() { // .Value() returns a bool here
// do the new exiting thing
} else {
// do the well tested thing
}
```
Environmental variables can be predicated on other boolean type variables:
```go
var NewThingParam = env.String("NEW_THING", "pass this to the new thing",
env.Needs(Expiremental))
```
Predicated variables will only show up as set if there predicate is `true`:
```go
if v := NewThingParam.Value(); v != "" {
do_thing(v)
} else {
// do the well tested thing
}
```
The above `if` check is equivalent to
```go
if v = os.Getenv("PULUMI_NEW_THING"); v != "" && cmduilt.IsTruthy(os.Getenv("PULUMI_EXPERIMENTAL"))
```
This makes marking and unmarking a variable as experimental a 1 line change.
---
All declared variables can then be iterated on for documentation with `env.Variables()`. This is how we can use this lib to build documentation for our environmental variables.
### Assumptions
#### Immutability
The library assumes that environmental variables are inherited from the environment. Values are captured during program startup, changes to the environment are not observed. We are not resilient to environmental variables changing out from under us, so this complies with current usage. This assumption can be changed without breaking the API.
#### Known values
The library assumes that the names of environmental variables are known at compile time. If the variable to be looked up is derived from user input, a different mechanism should be used.
### Adoption
Adopting this system over our pulumi/pkg codebase will take a while. My plan is to merge in this PR without moving over our existing env vars from `os.Getenv`. We can then gradually move over existing env vars piecemeal in subsequent PRs. Any new env vars added will use the new system.
Prerequisite for https://github.com/pulumi/pulumi/issues/10747.
### Other Options - Viper
Viper looks like an excellent config retrieval package, but doesn't support at-site documentation. It also has less type safety then I would prefer as a top level api. If it would be helpful, we could switch the underlying mechanism from `os.Lookup` to `viper.Get*` without changing the API this library exposes. I don't think viper is necessary right now, but adopting this library doesn't preclude viper.
Co-authored-by: Ian Wahbe <ian@wahbe.com>
|
||
|---|---|---|
| .. | ||
| analyzer.go | ||
| analyzer_plugin.go | ||
| check.go | ||
| config_source.go | ||
| context.go | ||
| doc.go | ||
| host.go | ||
| host_server.go | ||
| langruntime.go | ||
| langruntime_plugin.go | ||
| plugin.go | ||
| plugin_test.go | ||
| provider.go | ||
| provider_plugin.go | ||
| provider_plugin_test.go | ||
| provider_server.go | ||
| provider_test.go | ||
| provider_unimplemented.go | ||
| rpc.go | ||
| rpc_rapid_test.go | ||
| rpc_test.go | ||