Skip to content

Move static runsc flags to configuration file - #2281

Merged
Benjamin Elder (BenTheElder) merged 1 commit into
agent-substrate:mainfrom
fvoznika:runsc-flags-config
Oct 14, 2026
Merged

Benjamin Elder (BenTheElder) merged 1 commit into
agent-substrate:mainfrom
fvoznika:runsc-flags-config

Conversation

@fvoznika

Copy link
Copy Markdown
Collaborator

Move existing hardcoded runsc flags into kodata/flags.json to make it easier to manage and add flags. Flags are reloaded automatically when file changes to allow for setting flags during runtime, e.g. enable debug logs.

AI disclosure: AI tooling assisted in writing and testing parts of this change.

  • Tests pass
  • Appropriate changes to documentation are included in the PR

@BenTheElder

Copy link
Copy Markdown
Collaborator

Once substrate goes GA and we have back-compat, we're probably going to need to conditionally set flags depending on the runsc version to match what was used when the snapshot was taken. (thockin is still drafting the policy)

That seems incompatible with moving them out of the binary.

Maybe we can keep the defaults inline but allow a config to append flags for debugging / development?

@BenTheElder Benjamin Elder (BenTheElder) added area/gvisor kind/feature An enhancement / feature request or implementation labels Oct 6, 2026
@fvoznika

Copy link
Copy Markdown
Collaborator Author

The configuration file is part of the release and goes together with the binary. So it doesn't matter whether the flags are defined in binary or a config file on the side. For supporting multiple versions, with possibly different flags, the configuration file would have to be changed to support multiple versions too. But we'll cross that bridge when we need it.

@BenTheElder

Copy link
Copy Markdown
Collaborator

The configuration file is part of the release and goes together with the binary. So it doesn't matter whether the flags are defined in binary or a config file on the side. For supporting multiple versions, with possibly different flags, the configuration file would have to be changed to support multiple versions too. But we'll cross that bridge when we need it.

Yes ... but then we're introducing a breaking change itself [to the config format], while we're actively planning to cease all breaking changes soon until a possible 2.0. Tim Hockin (@thockin) has been working on a policy for this, I assume it includes all configuration.

Do we need to expose this to users at all?

For developers, is this really significantly faster than a cached go build + editing a go source code with these flags? I've found it pretty fast to iterate on ateom changes just with ko as-is.

If we just wanted to move it to a seperate file on disk, either another go source file, or a https://pkg.go.dev/embed seems more appropriate than allowing runtime override we can't really support yet. (Zoe Zhao (@zoez7) is working on a sandboxconfig design that might have room to enable this in the future).

Do we really need runtime override for these flags?

Flags are reloaded automatically when file changes to allow for setting flags during runtime, e.g. enable debug logs.

For something like "enable debug" we have a pattern to add one top-level debug-mode flag (which must be off by default #2274) that enables relevant underlying flags.

@fvoznika

Copy link
Copy Markdown
Collaborator Author

This is not a public API and it's not intended to be controlled via sandbox config. It's a configuration file that is bundled and released together with the binary. Its reason to exist is to unify flag configuration into a single place that can be easily changed and audited.

There are several advantages to making this a text file:

  • Easy to enable debug flags (by anyone, without the need to recompile+redeploy)
  • Easy to audit and find all flags enabled for gVisor
  • Easy to test new features during development and performance tuning
  • Flags can be set while the sandbox is running

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if we call this experimental-flags-do-not-edit.json and drop the CLI flag?

I just don't want an end user editing this and then complaining when things are broken, if it's meant for developers of substrate.

If we're building an end-user feature to add debug flags, we should probably give them a way to append debug flags instead of fully overriding the flagset.

@fvoznika

Copy link
Copy Markdown
Collaborator Author

As discussed, removed the flag and renamed the file to internal_flags.json.

Move existing hardcoded runsc flags into kodata/internal_flags.json to make it
easier to manage and add flags. Flags are reloaded automatically when file
changes to allow for setting flags during runtime, e.g. enable debug logs.

*AI disclosure: AI tooling assisted in writing and testing parts of this change.*

- [x] Tests pass
- [x] Appropriate changes to documentation are included in the PR
@BenTheElder
Benjamin Elder (BenTheElder) added this pull request to the merge queue Oct 14, 2026
Merged via the queue into agent-substrate:main with commit 3b64794 Oct 14, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/gvisor kind/feature An enhancement / feature request or implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants