Deprecation of static CPU templates

[zulinx86]

Dear community,

After introducing the custom CPU template feature in Firecracker v1.4.0, we are now planning to start the deprecation process of all the static CPU templates and the cpu_template field in the /machine-config API in Firecracker v1.5.0. This discussion aims to improve the visibility of the deprecation to inform any user of static CPU templates as early as possible.

Background

CPU templates allow users to manipulate how the vCPUs are represented to the guest. A common application of this feature is to provide CPU feature parity to guests that run in a heterogeneous fleet made up of hosts with different CPU models.

To improve customer experience and operation agility for our customers, we introduced the custom CPU template in Firecracker v1.4.0, which is an improved iteration of the previously released static CPU templates. This will give flexibility to any customer to define their own CPU template and be completely decoupled from the static set of templates hardcoded in the Firecracker binary. As a result, we plan to deprecate all the static CPU templates in Firecracker v.1.5.0 and remove them in accordance with our deprecation policy.

Transition from static CPU templates to custom CPU templates

To facilitate the transition from the old feature to the new one, we have prepared corresponding custom CPU templates in the new JSON format for all the existing static CPU templates. The set of templates is available here and will be maintained at least until the static CPU templates are removed from Firecracker. For more details about static and custom CPU templates, please refer to our documentation.

Maintenance of custom CPU templates

Custom CPU templates are user-defined and strictly depend on the combination of CPU, microcode, BIOS, operating system and Firecracker version in use. The user who defined a custom CPU template is also responsible for maintaining the template according to the CPU features that need to be exposed to the guest whenver there is an update to its dependencies. In Firecracker v1.4.0, we released the custom CPU template helper tool (cpu-template-helper binary) which assists a user in creating and maintaining custom CPU templates. For more details on the CPU template helper tool, please refer to our documentation.

Should you have any questions, please feel free to ask in this discussion.

Sincerely,
The Firecracker team

[alexellis]

Hi @zulinx86

What's the side-effect of not using CPU templates?

How does this change integrate with the Firecracker Go SDK? Is there already a new example available of how to use a custom CPU template?

[zulinx86]

Hi @alexellis,

Thank you for the questions!

What's the side-effect of not using CPU templates?

Let me answer this question in the context of the following two interpretations:

1. Is any change required for users who are not specifying the field?
2. In what kind of situation is the CPU template feature useful? Does not using the CPU template feature harm anything?

To answer the first one:

There is no side-effect for users who do not specify the cpu_template field in the /machine-config API, because the field is originally optional.

To answer the second question:

As stated in the public documentation, the CPU template feature itself allows users to customize how the vCPUs are represented to guests. For instance, it can present a consistent CPU feature set to guests across a fleet consisting of different CPU models. The use cases for the existing static CPU templates are also documented in the documentation. Like these examples, the CPU template feature addresses certain use cases, but not using it does not mean your system is harmed.

How does this change integrate with the Firecracker Go SDK? Is there already a new example available of how to use a custom CPU template?

As can be seen in the commit history ([Upgrade firecracker to 1.4.0] [Upgrade firecracker from 1.4.0 to 1.4.1]), firecracker-go-sdk has already upgraded Firecracker to 1.4.1, which supports custom CPU templates, on its main branch. Should you have any questions/requests to firecracker-go-sdk, feel free to open a GitHub issue or discussion on its repository!

Best regards,
Takahiro

[alexellis]

Thank you for the answer.

It seems like the templates can be used to communicate available features like, for instance avx2 etc?

[zulinx86]

It seems like the templates can be used to communicate available features like, for instance avx2 etc?

Yes, that's right. For example, on x86_64, CPU template is able to modify guest's CPUID and MSRs that are used to advertise CPU features including avx2.

[zulinx86]

This discussion has been open for a month and we conducted the deprecation in v1.5.0 (PR #4126). They are supposed to be removed in v2.0.0 according to the policy.

We close this discussion for now, but please feel free to reopen this and ask the migration path!