-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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 #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>- Loading branch information
Showing
10 changed files
with
590 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| // Copyright 2016-2022, Pulumi Corporation. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| // A small library for creating consistent and documented environmental variable accesses. | ||
| // | ||
| // Public environmental variables should be declared as a module level variable. | ||
|
|
||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
|
|
||
| "github.com/spf13/cobra" | ||
|
|
||
| "github.com/pulumi/pulumi/sdk/v3/go/common/diag" | ||
| "github.com/pulumi/pulumi/sdk/v3/go/common/env" | ||
| "github.com/pulumi/pulumi/sdk/v3/go/common/util/cmdutil" | ||
| declared "github.com/pulumi/pulumi/sdk/v3/go/common/util/env" | ||
| "github.com/pulumi/pulumi/sdk/v3/go/common/util/result" | ||
| ) | ||
|
|
||
| func newEnvCmd() *cobra.Command { | ||
| return &cobra.Command{ | ||
| Use: "env", | ||
| Short: "An overview of the environmental variables used by pulumi", | ||
| Args: cmdutil.NoArgs, | ||
| // Since most variables won't be included here, we hide the command. We will | ||
| // unhide once most existing variables are using the new env var framework and | ||
| // show up here. | ||
| Hidden: !env.Experimental.Value(), | ||
| Run: cmdutil.RunResultFunc(func(cmd *cobra.Command, args []string) result.Result { | ||
| table := cmdutil.Table{ | ||
| Headers: []string{"Variable", "Description", "Value"}, | ||
| } | ||
| var foundError bool | ||
| for _, v := range declared.Variables() { | ||
| foundError = foundError || emitEnvVarDiag(v) | ||
| table.Rows = append(table.Rows, cmdutil.TableRow{ | ||
| Columns: []string{v.Name(), v.Description, v.Value.String()}, | ||
| }) | ||
| } | ||
| cmdutil.PrintTable(table) | ||
| if foundError { | ||
| return result.Error("Invalid environmental variables found") | ||
| } | ||
| return nil | ||
| }), | ||
| } | ||
| } | ||
|
|
||
| func emitEnvVarDiag(val declared.Var) bool { | ||
| err := val.Value.Validate() | ||
| if err.Error != nil { | ||
| cmdutil.Diag().Errorf(&diag.Diag{ | ||
| Message: fmt.Sprintf("%s: %v", val.Name(), err.Error), | ||
| }) | ||
| } | ||
| if err.Warning != nil { | ||
| cmdutil.Diag().Warningf(&diag.Diag{ | ||
| Message: fmt.Sprintf("%s: %v", val.Name(), err.Warning), | ||
| }) | ||
| } | ||
| return err.Error != nil | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| // Copyright 2016-2022, Pulumi Corporation. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| // A small library for creating consistent and documented environmental variable accesses. | ||
| // | ||
| // Public environmental variables should be declared as a module level variable. | ||
|
|
||
| package env | ||
|
|
||
| import "github.com/pulumi/pulumi/sdk/v3/go/common/util/env" | ||
|
|
||
| // Re-export some types and functions from the env library. | ||
|
|
||
| type Env = env.Env | ||
|
|
||
| type MapStore = env.MapStore | ||
|
|
||
| func NewEnv(s env.Store) env.Env { return env.NewEnv(s) } | ||
|
|
||
| // Global is the environment defined by environmental variables. | ||
| func Global() env.Env { | ||
| return env.NewEnv(env.Global) | ||
| } | ||
|
|
||
| // That Pulumi is running in experimental mode. | ||
| // | ||
| // This is our standard gate for an existing feature that's not quite ready to be stable | ||
| // and publicly consumed. | ||
| var Experimental = env.Bool("EXPERIMENTAL", "Enable experimental options and commands") | ||
|
|
||
| var SkipUpdateCheck = env.Bool("SKIP_UPDATE_CHECK", "Disable checking for a new version of pulumi") | ||
|
|
||
| var Dev = env.Bool("DEV", "Enable features for hacking on pulumi itself") | ||
|
|
||
| var IgnoreAmbientPlugins = env.Bool("IGNORE_AMBIENT_PLUGINS", | ||
| "Discover additional plugins by examining the $PATH") |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.