hashicorp / hashicorp/nomad

deprecate client-side interpolation for known values in lieu of HCL2

Open
#20,362 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

stage/needs-discussion theme/hcl theme/tech-debt type/enhancement
Dominant language
Go
Stars
17k
Forks
2.1k
Avg merge
1d 9h
Merged PRs (30d)
105

Description

In https://github.com/hashicorp/nomad/pull/20344#pullrequestreview-1994707912 @schmichael noted:

I wonder if we should deprecate this form of interpolation in this place in favor of HCL variables? I think an HCL variable with a default value could specify both the group and service names in a way that would make them static by the time they're submitted to Nomad. It would be nice to have a path away from this extremely buggy phased interpolation approach.

There are broadly two kinds of interpolation that happen in Nomad jobs:

This two-phase interpolation has been a source of confusion and bugs for a while now. Any field that's being interpolated on the client cannot be used by the server. One particularly confusing thing is that this information can't be used for scheduling decisions, even if the server could do the interpolation, because the allocation hasn't been placed yet! But some of that information is available already (like task name), but because we do all the interpolation on the client we haven't built the mechanisms on the server to use it.

All of which is to say this is a bit of a mess.

To untangle this, we could:

  • Retire the environment variable syntax for the jobspec (we'd probably need to think about what this looks like for task args fields)
  • Add all the runtime environment variables for allocation and node data as ${env.*} attributes, but not the submit-time attributes like task name and group name
  • Add functions to our HCL2 that allow users to refer to submit-time attributes like task name and group name

An alternate approach could be:

  • Leave all the existing syntax in place
  • Rework the client's taskenv builder so that it only interpolates runtime-side variables
  • Add a submit-time equivalent as the first job submit hook, that does interpolation of submit-time data like task name and group name, so that these never reach the client side uninterpolated.

Either way we could also use more documentation here. There's probably some subsets of fields that we could say "you're allowed to interpolate these fields with node metadata, and these fields only with HCL2 (or submit time)". Being able to document which those are would be nice for users and for us developers.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the client's taskenv builder and the proposed first job-submit hook, then compare the HCL2 variables, runtime interpolation, and runtime environment documentation linked in the issue. Done requires an agreed interpolation boundary, a chosen implementation approach, and corresponding documentation, but the issue does not identify files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
devops
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.