|
| 1 | +# VEP #100: Introduce Custom Metadata to Cloud-init |
| 2 | + |
| 3 | +## Release Signoff Checklist |
| 4 | +Items marked with (R) are required *prior to targeting to a milestone / release*. |
| 5 | +- [X] (R) Enhancement issue created, which links to VEP dir in [kubevirt/enhancements] (not the initial VEP PR) |
| 6 | +- [ ] (R) Target version is explicitly mentioned and approved |
| 7 | +- [ ] (R) Graduation criteria filled |
| 8 | + |
| 9 | +## Overview |
| 10 | +This VEP proposes enhancing KubeVirt's cloud-init metadata support by enabling users to add custom metadata to cloud-init. |
| 11 | +This addresses missing functionality for users to be able to add custom values to the cloud-init metadata. |
| 12 | + |
| 13 | +## Motivation |
| 14 | +KubeVirt's cloud-init support previously did not allow users to add custom values to the metadata. |
| 15 | +This prevented users from passing application-specific information to their VMs through cloud-init. |
| 16 | +Issue https://github.com/kubevirt/kubevirt/issues/15836 the motivation behind this VEP. |
| 17 | + |
| 18 | +## Goals |
| 19 | +- Enable users to add custom metadata fields to cloud-init through the metaData field in both `NoCloud` and `ConfigDrive` configurations |
| 20 | +- Implement `MetaData` in the `CloudInitNoCloudSource` struct to allow users add custom metadata to the cloud-init |
| 21 | +- Implement `MetaDataSecretRef` in the `CloudInitNoCloudSource` struct to allow users to reference Kubernetes secrets containing custom metadata |
| 22 | +- Ensure custom metadata is properly merged with standard metadata fields (instance-id, local-hostname, instance-type, etc.) that KubeVirt automatically generates |
| 23 | +- Add a MetaData field with type `map[string]string` to `CloudInitNoCloudSource` to support better type safety and eliminate YAML parsing in the API layer |
| 24 | + |
| 25 | +## Non Goals |
| 26 | + |
| 27 | + |
| 28 | +## Definition of Users |
| 29 | +VM owners and workload developers who need to pass custom metadata to their virtual machines |
| 30 | +through cloud-init for application configuration, environment-specific settings, or runtime parameters. |
| 31 | +This includes developers deploying applications that require custom configuration data accessible via cloud-init metadata, |
| 32 | +such as environment variables, application settings, or deployment-specific parameters. |
| 33 | +Cluster administrators may be indirectly impacted as they need to understand the new |
| 34 | +metadata capabilities and potentially create secrets for users, |
| 35 | +but they are not the primary users of this functionality. |
| 36 | + |
| 37 | +## User Stories |
| 38 | +- As a VM owner, I want to add custom metadata fields to my cloud-init configuration |
| 39 | +so that my applications can access application-specific configuration data. |
| 40 | +- As a VM owner, I want to reference Kubernetes secrets containing |
| 41 | +custom metadata so that I can securely pass sensitive configuration data to my VMs. |
| 42 | + |
| 43 | +## Repos |
| 44 | +- kubevirt/kubevirt (core API) |
| 45 | + |
| 46 | +## Design |
| 47 | +Enhance `CloudInitNoCloudSource` and `CloudInitConfigDriveSource` with `MetaData` field as `map[string]string `and `MetaDataSecretRef` for secret references. |
| 48 | +Secret resolution reads custom metadata and merges with standard fields. |
| 49 | + |
| 50 | +## API Examples |
| 51 | +```yaml |
| 52 | +volumes: |
| 53 | +- name: cloudinitdisk |
| 54 | + cloudInitNoCloud: |
| 55 | + userData: | |
| 56 | + #cloud-config |
| 57 | + package_update: true |
| 58 | + metaData: |
| 59 | + app_name: "my-application" |
| 60 | + environment: "production" |
| 61 | + cost_center: "12345" |
| 62 | +``` |
| 63 | +
|
| 64 | +```yaml |
| 65 | +volumes: |
| 66 | +- name: cloudinitdisk |
| 67 | + cloudInitNoCloud: |
| 68 | + userData: | |
| 69 | + #cloud-config |
| 70 | + package_update: true |
| 71 | + metaDataSecretRef: |
| 72 | + name: my-metadata-secret |
| 73 | +--- |
| 74 | +apiVersion: v1 |
| 75 | +kind: Secret |
| 76 | +metadata: |
| 77 | + name: my-metadata-secret |
| 78 | +type: Opaque |
| 79 | +stringData: |
| 80 | + metadata: | |
| 81 | + app_name: "my-application" |
| 82 | + environment: "production" |
| 83 | + cost_center: "12345" |
| 84 | +``` |
| 85 | +
|
| 86 | +## Alternatives |
| 87 | +
|
| 88 | +## Scalability |
| 89 | +
|
| 90 | +## Update/Rollback Compatibility |
| 91 | +- New field is optional; existing VMIs remain unaffected. |
| 92 | +- On downgrade, projected volumes fall back to errors or no-op. |
| 93 | +## Functional Testing Approach |
| 94 | +- Unit tests: API validation, struct marshaling, metadata merging. |
| 95 | +- Integration tests: Deploy VM/VMI with custom metadata, verify metadata is accessible in guest. |
| 96 | +## Implementation History |
| 97 | +- October 17, 2024: Implementation completed and PR submitted. |
| 98 | +- October 19, 2024: VEP drafted (after reviewer feedback indicated VEP was required for API changes). |
| 99 | +## Graduation Requirements |
| 100 | +### Alpha |
| 101 | +- Custom metadata support implemented. |
| 102 | +- MetaData functionality complete. |
| 103 | +- MetaDataSecretRef functionality complete. |
| 104 | +### Beta |
| 105 | +- Full IRSA support. |
| 106 | +### GA |
| 107 | +
|
0 commit comments