From 28c6e3b4e7db45bec721f77fe9eb30db3e33d632 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Tue, 13 Nov 2018 22:15:50 +0000 Subject: [PATCH 1/4] Client Environment Variables --- rfcs/0135-client-env-vars.md | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 rfcs/0135-client-env-vars.md diff --git a/rfcs/0135-client-env-vars.md b/rfcs/0135-client-env-vars.md new file mode 100644 index 0000000..47ad839 --- /dev/null +++ b/rfcs/0135-client-env-vars.md @@ -0,0 +1,91 @@ +# RFC 0135 - Clients and Environment Variables +* Comments: [#135](https://api.github.com/repos/taskcluster/taskcluster-rfcs/pulls/135) +* Proposed by: @djmitche + +# Summary + +Client libraries should not automatically read environment variables. + +## Motivation + +Some client libraries currently automatically use environment variables + * `TASKCLUSTER_CLIENT_ID` + * `TASKCLUSTER_ACCESS_TOKEN` + * `TASKCLUSTER_CERTIFICATE` + * `TASKCLUSTER_ROOT_URL` +if they are set, and if no explicit configuration is given when constructing the client. +But clients differ in their use of these variables. + +This is problematic because not all code will want to configure settings based on +environment variables, for example workers that take their configuration from +configuration files. + +This has also caused issues with testing and deploying software, where the +"hidden" context of environment variables can cause tests to pass or fail, or a +service to fail when deployed in a different context. + +Finally, we should strive for some similarity in usage of the client libraries. + +# Details + +The proposed change is that client libraries do not *automatically* look to +these four environment variables for configuration. The libraries would still have +options to explicitly "opt in" to using the environment variables, e.g., + +```go +queue := queue.NewFromEnvVars() +``` + +or + +```js +queue = new taskcluster.Queue({fromEnvVars: true}); +``` + +## Taskcluster-CLI + +The `taskcluster-cli` application is often referred to as a "shell client library". +However, environment variables are a common and accepted way of sending configuration to command-line tools, so `taskcluster-cli` will continue to use these environment variables for its configuration. + +# Current Status + +## Python + +The Python client currently accepts all four environment variables mentioned above, as well as a `rootUrl` option to the class constructor. +This was released in version 5.0.0. + +## JS + +The JS client currently accepts all four environment variables mentioned above, as well as a `rootUrl` option to the class constructor. +This was released in version 10.0.0. + +## Go + +The Go client does not read environment variables directly and does not support root URLs at all. +(That is, it is already compliant with this RFC) + +## Java + +The Java client does not read environment variables directly and does not support root URLs at all. +(That is, it is already compliant with this RFC) + +## Web + +The Web client runs in a browser, and therefore does not accept environment variables at all. +It does accept a `rootUrl` option similar to the JS client. + +# Compatibility + +This is a breaking change, necessitating a major version bump for the Python and JS clients. + +RFC 0128 adds the requirement to specify a root URL, with no default available. +Because failing to specify a root URL is a fatal error, any use of clients that are not upgraded to supply explicit configuration or use `NewFromEnvVars` will likely fail clearly in testing. +Such clear failures should ease the task of upgrading client consumers, assuming good test coverage. + +However, many consumers have already been updated to use the newest versions of these clients. +Such upgraded consumers may encounter subtle issues where a client continues to work for read-only operations, but fails (perhaps only in production) for operations requiring credentials. +Thus, the upgrade from 5.x (for Python) or 10.x (for JS) will require some caution. + +# Implementation + +TBD From 70d8332e9a4ec52fbab75a04c7d3e1a8b299bc77 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Wed, 14 Nov 2018 17:59:10 +0000 Subject: [PATCH 2/4] add standardized variables section --- rfcs/0135-client-env-vars.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/rfcs/0135-client-env-vars.md b/rfcs/0135-client-env-vars.md index 47ad839..7916250 100644 --- a/rfcs/0135-client-env-vars.md +++ b/rfcs/0135-client-env-vars.md @@ -42,6 +42,17 @@ or queue = new taskcluster.Queue({fromEnvVars: true}); ``` +## Standardized Variables + +This RFC also serves to standardize the meanings of the following environment variables. +These meanings capture the current *de facto* meanings. + + * `TASKCLUSTER_CLIENT_ID` - the `clientId` for API requests + * `TASKCLUSTER_ACCESS_TOKEN` - the corresponding `accessToken` for API requests + * `TASKCLUSTER_CERTIFICATE` - if present, a JSON-formatted temporary credential certificate. In this case, `TASKCLUSTER_CLIENT_ID` and `TASKCLUSTER_ACCESS_TOKEN` are defined as described in [the temporary credentials documentation](https://docs.taskcluster.net/docs/manual/design/apis/hawk/temporary-credentials). NOTE: users are not expected to decode this string. + * `TASKCLUSTER_ROOT_URL` - the root URL of the cluster to which API requests should be made + * `TASKCLUSTER_PROXY_URL` - if present, the root URL of a `taskcluster-proxy` instance suitable for accessing the Taskcluster deployment in which the current task is running (defined in [RFC 0128](https://github.com/taskcluster/taskcluster-rfcs/blob/master/rfcs/0128-redeployable-clients.md)) + ## Taskcluster-CLI The `taskcluster-cli` application is often referred to as a "shell client library". From 1d4b61d3bf9e4e93d65be3724b57f3cf1bd9e9d0 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Thu, 15 Nov 2018 13:38:19 +0000 Subject: [PATCH 3/4] indicate that go support for rootUrls is coming --- rfcs/0135-client-env-vars.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0135-client-env-vars.md b/rfcs/0135-client-env-vars.md index 7916250..11ad878 100644 --- a/rfcs/0135-client-env-vars.md +++ b/rfcs/0135-client-env-vars.md @@ -72,7 +72,7 @@ This was released in version 10.0.0. ## Go -The Go client does not read environment variables directly and does not support root URLs at all. +The Go client does not read environment variables directly and does not [yet](https://bugzilla.mozilla.org/show_bug.cgi?id=1428422) support root URLs at all. (That is, it is already compliant with this RFC) ## Java From fd5ae28814a0603d623454acca679eed0268a3b2 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Mon, 19 Nov 2018 17:43:35 +0000 Subject: [PATCH 4/4] add implementation link --- rfcs/0135-client-env-vars.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0135-client-env-vars.md b/rfcs/0135-client-env-vars.md index 11ad878..f45d1aa 100644 --- a/rfcs/0135-client-env-vars.md +++ b/rfcs/0135-client-env-vars.md @@ -99,4 +99,4 @@ Thus, the upgrade from 5.x (for Python) or 10.x (for JS) will require some cauti # Implementation -TBD +https://bugzilla.mozilla.org/show_bug.cgi?id=1508333