Environments

Introduction

An environment is a named place inside your organization where apps run. The same app id can run in several of them, and each copy keeps its own configuration, its own versions, its own workers and its own secrets.

Every organization has production, and a request that names no environment addresses it. Nothing you have deployed so far moved: it is already there.

GET /v1/apps                        # production
GET /v1/apps?environment=staging    # the staging copies

The CLI carries the same choice on --env, on deploy, on open and on every apps and secrets command.

runware serverless apps list                  # production
runware serverless apps list --env staging    # the staging copies

A command with no --env does not have to mean production. RUNWARE_ENV picks the environment for one shell, runware config set environment staging picks it until you change it, and --env wins over both. The CLI says which one it used and where it came from before the command runs, and a name the API would refuse fails before any request is sent.

The usage reports read the other way round. serverless usage covers every environment until you narrow it with --env, and usage events covers the organization until you name an --app, whose copy then follows the default like any app command.

One id, one copy per environment

The app id is the name of the application. The environment chooses which copy a request reaches, and the two are separate apps from there on: separate versions, separate workers, separate environment variables, separate secret attachments.

A copy is created where you first deploy it and never moves. Promoting what you tested is deploying the same source into another environment, which builds there. Deleting one copy leaves the others untouched.

What an environment holds

A secret of the same name in another environment is a different secret. One call copies a secret into other environments with its value, so a credential reaches a second environment without being sent again, and each copy is its own secret from then on.

Caps and the monthly budget

An environment carries a cap on the workers it holds and a cap on their GPUs. Both are checked whenever a request adds capacity, so creating an app, deploying, resuming a stopped one and raising a worker count all go through them. They do not bound autoscaling: what is already running keeps scaling inside its own maxWorkers.

The count an environment is judged against is what its other apps hold, each the larger of its live workers and its keep-warm floor, plus what the request starts. A request that would cross a cap is refused, and the apps keep what they hold. Lowering a cap below what already runs refuses the next deploy rather than stopping anything.

The monthly budget is a pay-as-you-go cap for the calendar month, which resets on the 1st at 00:00 UTC. Percentages you choose send an email as the spend passes them, each at most once per month. Where pauseAtBudget is on, reaching the budget stops the environment's apps and refuses invocations until the budget is raised past the spend or the month turns.

Organization defaults

Every cap and the access setting have an organization default that an environment inherits while it sets nothing of its own. An environment reports both: the value set on it, and under resolved the value actually in force.

Changing a default reaches every environment that inherits that field at once, and it does not roll what is already running.

GET /v1/environment-defaults
PUT /v1/environment-defaults

Managing them from the CLI

runware serverless environments covers the same surface as the API, and none of its commands takes --env: the name is the argument.

runware serverless environments list
runware serverless environments show staging
runware serverless environments create staging --max-workers 4 --budget 50 --pause-at-budget
runware serverless environments update staging --max-workers 8
runware serverless environments update staging --clear max-workers,budget
runware serverless environments delete staging --yes
runware serverless environments defaults show
runware serverless environments defaults set --max-workers 10

create and update take --max-workers, --max-gpus, --budget, --alert-percents and --pause-at-budget. On update, a flag you leave out keeps the value it had, and --clear is how a setting goes away: it takes max-workers, max-gpus, budget or alert-percents, comma-separated or repeated. A cleared cap inherits the organization default again, a cleared budget means no budget, and cleared alert percents send no alert.

list and show print - for a cap nothing sets and mark a value that comes from the organization defaults as inherited, so the three cases stay apart.

delete asks before it runs unless you pass --yes. An environment that still holds a live app or a secret is refused, and the refusal is followed by the commands that name what is left.

defaults set changes only the caps you name, because it reads the defaults and writes them back whole. Two people changing them at the same time lose one of the changes, so keep it to one place.

Creating and deleting

A name is 1 to 63 characters: lowercase letters, digits, hyphens, underscores and periods, starting with a letter or a digit. A name no live environment holds is free, including the name of one you deleted.

An environment is deleted only once it is empty, with no live app and no secret left in it. production is never deleted, and a deleted app's history still names the environment it ran in.

Where to go next

• Core concepts for the nouns an environment holds
• Secrets for what changes when the same name lives in two places
• Compute and scaling for the worker settings a cap is checked against
• Errors for the answers a cap and a pause give