bottlerocket-os / bottlerocket-settings-sdk Goto Github PK

The Kubernetes golang controller runtime models migrations as "hub and spoke" graphs, which can be useful in some scenarios compared to our current linear migrator strategy.

We should implement a HubAndSpokeMigrator which gives authors the choice of how to model their migrations.

Bottlerocket will need to produce every migration from a given preferred version. Since linear migrations need to perform every intermediate migration, this will result in a significant amount of throwaway compute.

Implementing a batch migration API will allow the extension to avoid repeating any computed migrations.

Context

It's possible with the CLI-only interface for proto1 that a settings extension command with large JSON values would exceed the max command buffer size on bottlerocket, 128KB.

In order to avoid this issue, we should change proto1 to accept input from stdin.

Definition of done

Settings extensions accept the following input mode:

echo '{"some": "json"}' | extension proto1 set

An initial implementation of the bottlerocket-settings-sdk lives here.

We should modify this to move the migration abstractions out of the model abstraction and make it so that they are done via associated types instead.

DoD:
bottlerocket_settings_sdk::lib has a docstring containing:

• Context for the library's existence
• A quickstart guide
• References to common (anticipated) usage patterns
• Any gotchas that users should be aware of

We should integrate with something like release-plz or cargo-smart-release to automate the process of publishing crates, updating the changelog, etc.

The interface for executing configuration template helpers is not yet implemented. We must implement this such that extensions can appropriately handle CLI input of the form:

extension proto1 helper --helper-name $NAME --arg $ARG1 --arg $ARG2

An example file looks something like this:

[extension]
supported-versions = [
    "v1"
]
default-version = "v1"


[v1]
    [v1.validation.cross-validates]

    [v1.templating]
        helpers = []

    [v1.generation.requires]

Each extension should have its own configuration file describing the exposed API. We should add the ability to run a config validator in tests.

Currently the SDK prints whatever error is bubbled up by a settings extension to stderr and exits 1 if there is an error. We should consider doing something machine-readable for the text output.

DoD:
The library is run through cargo-deny prior to new changes being merged into develop.

We should probably model our build process via make to make it easier to be consistent between developer environments and CI.

The SDK currently uses anyhow for Result types, which expedited development. We should return more structure Err types with pre-defined error enums, probably using snafu.

The model and scalar macros are utility macros that make it easy to derive models of the correct shape based on a struct.

These macros will likely be used in many extensions, it's probably a good idea to move them to the SDK.

This repository needs a README which explains the project's use in the context of out-of-tree builds, as well as instructions on how to get started, links to crates.io/docs.rs, etc.

clap is currently denied for use in the Bottlerocket repository.

We should change settings extensions to use argh instead, which would align it with the expectations of other CLIs in Bottlerocket.

We have the Migrator::validate_migrations interface to validate any migrations provided by a settings extension.

We should expand this with a general-purpose BottlerocketSettings::validate method, then provide a simple macro or function to invoke these during tests.

Once this is finished, we need to add examples on how to use it to existing docstrings.

string_impls_for! is a convenience macro that implements several helpful traits based on an implementation of TryFrom<&'str>. Most importantly, it implements Serialize and Deserialize on your behalf.

This may be worth pulling into the SDK to make it easier for extension authors to add custom validation to their deserialize logic.

Currently all extensions use the LinearMigrator, and we have plans to introduce a HubAndSpokeMigrator; however, new settings extensions are usually defined without needing any migrations. This means that authors need to add a boilerplate implementation of LinearMigrator which does nothing.

We should add a NullMigrator to reduce boilerplate required for new extensions. After all, it is supported to change migrators during the lifespan of an extension.

When we generate settings in a settings extension, we provide two pieces of information:

• Any data that is already specified for the setting
• Any data that exists for other settings that this setting depends on for generation

The GenerateResult type returned from SettingsModel::generate provides back two pieces of information:

• Whether or not generation is complete
• The partial or complete data that has been set so far

Using this interface, the settings API repeatedly invokes settings generators until they are all complete. This works in most cases, but it does not provide a clear picture of what is wrong if something fails. It could also be more efficient.

DoD:
Change the settings generation interface such that:

• The generator knows whether or not its dependencies have completed their own generation
• If the generation is not complete, it can return "hints" pointing to specific settings that need to be generated first (this can direct the settings system to try and run these dependencies first, though it does not guarantee it).

Per a comment from @webern on #31:

We are exposing a library and its traits in our public interface and it might be impossible to avoid a major version break if the Snafu library changes in some way.

We may wish to more closely control the fate of our public API by using our own error types, either across the board or by converting to them at the last moment for any pub methods. The downside to the "JIT"-style conversions is that it's not easy to create a mechanism to check this for us at compile-time.