Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.
Summary
Jobs currently do not especially care what is in their environment, provided by start events or commands. This specification proposes allowing a job to require certain variables in the environment before it can start.
Rationale
Now that the environment is fixed for an instance, and used by Upstart itself as well as the process, it would be useful to be able to rely on the existance of certain variables before starting the job; providing a useful error message if they aren't set.
Use cases
The getty job requires that the $TTY environment variable is set before it can be started. Since users can start jobs directly, it would be better for them to get an error informing them that they need to set it, than something cryptic.
Scope
This scope of this specification is limited to allowing jobs to specify mandatory variables for their environment and reporting when they are missing to users.
Design
- Job definitions may specify the variables that they require:
require TTY
If a required variable is not provided, the start command will error:
# start getty start: required parameter TTY not set
Implementation
Code
The JobConfig structure would gain an array of required variable names.
When starting a job, we would check this array against the environment against to make sure that all the required variables are set, returning an error if not. If not, an error would be raised and caught to send back to the user.
Data preservation and migration
These changes are backwards compatible with the previous behaviour.
Unresolved issues
Are variables referenced in instance inherently required? The job will fail to start anyway if they're not set, since the expansion will fail and raise an error. We'd have to catch this error and pass it back to the client in order to present the non-cryptic response. The alternative would be to pre-parse the instance stanza to try and figure out what is actually required and what is not, that would be bad.
I think otherwise you'd end up with silly things like:
instance $TTY require TTY env BAUD=38400 exec /sbin/getty $BAUD $TTY
Assuming that the other uses of environment variables like ["Resources"] error in a similarly useful way when trying to start the job, do we actually need another mandatory field? The job can check things it uses itself on its own.