Help:Toolforge/Envvars

Toolforge tools can configure envvars (environment variables) that will be available for your application when running (both webservices and jobs running in Kubernetes are supported, built with the newer build service or using one of the provided images).

The service is suitable for storing both configuration and secrets for your application, allowing workflows like having different config and secrets in your development/ci/production environments without changing a line of code. The envvar values are only available to the tool’s code and maintainers (though the names are publicly visible, e.g. in k8s-status).

Roadmap

Features that are already available

Create/update, delete and list environment variables.
Automatically inject environment variables to your application on startup (if you add or modify them, you'll have to restart your application).
Some system envvars are there (replicas user, replicas password, toolsdb user, toolsdb password, ...), all starting with TOOL_, see the config for details.

Planned features that are not available yet

Create a ticket with a feature request if you have any suggestions

Quickstart

Prerequisites

If you don't have a tool account yet, you need to create or join one. Detailed instructions are available at Help:Toolforge/Quickstart.

You should have a webservice or job running or ready to run. See Help:Toolforge/Build Service on how to build and start a webservice or job. Non-buildpack based webservices and jobs are also supported, for those see Help:Toolforge/Quickstart#Host your first tool on a tool account.

Creating a new environment variable

Once you have setup your toolforge account, you can ssh to the bastion and become your tool (using wm-lol tool as an example):

$ ssh myuser@login.toolforge.org
myuser@tools-sgebastion-10:~$ become wm-lol
tools.wm-lol@tools-sgebastion-10:~$

Now you can run toolforge envvars --help to see the available commands and syntax for each:

tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars --help
Usage: toolforge-envvars [OPTIONS] COMMAND [ARGS]...

  Toolforge command line

Options:
  -v, --verbose  Show extra verbose output. NOTE: Do no rely on the format of
                 the verbose output
  -d, --debug    show logs to debug the toolforge-envvars-* packages. For
                 extra verbose output for say build or job, see --verbose
  --version      Show the version and exit.
  --help         Show this message and exit.

Commands:
  create  Create/update an envvar.
  delete  Delete an envvar.
  list    List all your envvars.

For example, we can create a new environment variable (note that the name for the envvar has to be all caps, and has the same restriction as a sh/bash environment variables, and can't overwrite the system TOOL_* variables). There's many ways you can do it:

tools.wm-lol@tools-sgebastion-10:~$ echo "from stdin" | toolforge envvars create TEST
name    value
TEST    from stdin

tools.wm-lol@tools-sgebastion-10:~$ echo "from file" > envvar_file
tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars create TEST <envvar_file
name    value
TEST    from file

tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars create TEST "from argument"
name    value
TEST    from argument

tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars create TEST
Enter the value of your envvar (prompt is hidden, hit Ctrl+C to abort): 
name    value
TEST    from prompt

Now we have to start or restart the running webservice so it picks up the new environment variable (this example restarts a running buildservice based webservice):

tools.wm-lol@tools-sgebastion-10:~$ toolforge webservice buildservice restart

That's all! That environment variable is now available for the web service. :)

Updating an environment variable

Imagine that our api key has changed, and now we want to update it.

The process is exactly the same, the create command will update the variable if it already exists:

tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars list
name     value
API_KEY  my_api_key1


tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars create API_KEY "my_api_key2"
name     value
API_KEY  my_api_key2

Remember to restart your running webservices/jobs if you want the new value to be picked up!

tools.wm-lol@tools-sgebastion-10:~$ toolforge webservice buildservice restart

Globally set environment variables

There's a few of environment variables that will be always set for you, currently you can find the list in gitlab:repos/cloud/toolforge/toolforge-deploy/-/blob/main/components/envvars-admission/values/tools.yaml. T394408 tracks a feature request to show them in toolforge envvars list output.

All of them will start with TOOL_*, some of them are:

TOOL_TOOLFORGE_API_URL: url to the toolforge api (ex. https://api.svc.tools.eqiad1.wikimedia.cloud:30003).
TOOL_REDIS_URI: uri for the shared redis service (ex. redis://redis.svc.tools.eqiad1.wikimedia.cloud:6379).
TOOL_ELASTICSEARCH_URL: url for the elasticsearch service (ex. http://elasticsearch.svc.tools.eqiad1.wikimedia.cloud:80).
TOOL_DATA_DIR: Path to your tool's NFS mounted home directory. The $HOME envvar will not always match this path. Your application should rely on $TOOL_DATA_DIR instead of $HOME to locate shared files and directories.

There are some environment variables that will be set only once for you (you can overwrite them, this is not recommended however), those are:

TOOL_TOOLSDB_USER: tool specific user for toolsdb
TOOL_TOOLSDB_PASSWORD: tool specific password for toolsdb
TOOL_REPLICA_USER: tool specific user for the replica databases
TOOL_REPLICA_PASSWORD: tool specific password for the replica databases

Common problems and solutions

Please add to this section any issues you encountered and how you solved them.

How to add the contents of a file to an enviroment variable?

Though it's not recommended, sometimes there are some files that you will want to put in an environment variable (ex. secret certificate keys). Use shell input redirection to feed the file's contents to the standard input of the toolforge envvars create command:

tools.wm-lol@tools-sgebastion-10:~$ toolforge envvars create MY_CERT_KEY <secret.key

How to know if my code is running inside toolforge?

There's several environment variables that will always be set when running a job or a webservice, these all start with TOOL_*, one of them is TOOL_TOOLFORGE_API_URL, so you can rely that if that variable exists, you are running inside toolforge.

History

Below are some historical discussions that led to its current design and implementation.

Decision request Phabricator task

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support

Chat in real time in the IRC channel #wikimedia-cloud ^connect or the bridged Telegram group
Discuss via email after you have subscribed to the cloud@ mailing list

Stay aware of critical changes and plans

Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Read the News wiki page

Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)