design-proposal: Expand during initial submission

Signed-off-by: Lee Yarwood <[email protected]>

design-proposals/instancetype.kubevirt.io/expand-during-submission.md

@@ -0,0 +1,156 @@
+# Overview
+
+The initial design of instance types and preferences captured a point in time copy of the original resource for future use by the VirtualMachine to ensure we always generate the same VirtualMachineInstance at runtime.
+
+This additionally allows users to easily switch between classes, sizes and generations of these resources at some point in the future. However this flexibility comes at the cost of complexity within KubeVirt itself especially handling more advanced VirtualMachine lifecycle flows.
+
+This design proposal aims to set out new configurable behavior where any referenced instance types and/or preferences are expanded into the VirtualMachine during initial submission.
+
+## Motivation
+
+TBD
+
+## Goals
+
+* Provide simple configurables at the cluster and VirtualMachine level to expand instance types and preferences during initial submission
+
+## Non Goals
+
+* The default behavior will not change as part of this work
+
+## User Stories
+
+* As a cluster owner I want to configure the expansion of all new `VirtualMachines` referencing instance types and preferences during initial submission
+* As a VirtualMachine owner I want to optionally enable or disable the expansion my VirtualMachine referencing an instance type or preference
+
+## Repos
+
+* kubevirt/kubevirt
+
+# Design
+
+A new `KubeVirt` configurable will be introduced to have newly submitted `VirtualMachines` referencing instance types and/or preferences expanded.
+
+Additional `VirtualMachine` configurables will also be introduced to allow a specific newly submitted VirtualMachine referencing instance types and/or preferences to be expanded.
+
+Both sets of configurables will default to `reference`.
+
+The `VirtualMachine` configurable will override the cluster-wide `KubeVirt` configurable in situations where they are not equal.
+
+When requested the `VirtualMachine` controller will expand any referenced instance type or preference when the `VirtualMachine` is first seen.
+
+> *NOTE*: This expansion behavior will break any declarative management of these `VirtualMachines` as they will substantially change after initial submission.
+> Users will need to explicitly request to not expand their `VirtualMachines` referencing instance types and/or preferences to retain this ability.
+
+## Alternatives
+
+An alternative to this approach would be to handle the expansion prior to submission either within `virtctl create vm` *or* by forcing users to first call the `expand-spec` API.
+
+## API Examples
+
+By default `policy` will be `reference`.
+
+A cluster admin can default the policy of all new `VirtualMachines` by setting `expand` within the `KubeVirt` `CR`:
+
+```yaml
+apiVersion: kubevirt.io/v1
+kind: KubeVirt
+metadata:
+  name: kv
+spec:
+  configuration:
+    instancetype:
+      policy: expand
+    preference:
+      policy: expand
+```
+
+Additionally a VM owner can explicitly request `expand` by setting the policy directly on the `VirtualMachine`:
+
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: cirros
+spec:
+  instancetype:
+    name: foo
+    policy: expand
+  preference:
+    name: bar
+    policy: expand
+```
+
+Likewise users can explicitly request the `reference` policy to counter a different default being defined in the `KubeVirt` `CR`:
+
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: cirros
+spec:
+  instancetype:
+    name: foo
+    policy: reference
+```
+
+```go
+// KubeVirtConfiguration holds all kubevirt configurations
+type KubeVirtConfiguration struct {
+[..]
+    // Instancetype configuration
+    Instancetype *InstancetypeConfiguration `json:"instancetype,omitempty"`
+
+    // Preference configuration
+    Preference *PreferenceConfiguration `json:"preference,omitempty"`
+}
+
+type ExpansionPolicy string
+
+const (
+    Expand    ExpansionPolicy = "expand"
+    Reference ExpansionPolicy = "reference"
+)
+
+type InstancetypeConfiguration struct {
+    Policy *ExpansionPolicy `json:"policy,omitempty"`
+}
+
+type PreferenceConfiguration struct {
+    Policy *ExpansionPolicy `json:"policy,omitempty"`
+}
+
+[..]
+
+// InstancetypeMatcher references a instancetype that is used to fill fields in the VMI template.
+type InstancetypeMatcher struct {
+    [..]
+    Policy *ExpansionPolicy `json:"policy,omitempty"`
+}
+
+[..]
+
+// PreferenceMatcher references a set of preference that is used to fill fields in the VMI template.
+type PreferenceMatcher struct {
+    [..]
+    Policy *ExpansionPolicy `json:"policy,omitempty"`
+}
+```
+
+## Scalability
+
+TBD
+
+## Update/Rollback Compatibility
+
+Existing `VirtualMachines` referencing instance types and/or preferences will not be changed as a result of this behaviour.
+
+There will be no ability to automatically rollback new `VirtualMachines` once they have their instance type and/or preference expanded by this new functionality.
+
+## Functional Testing Approach
+
+TBD
+
+# Implementation Phases
+
+TBD