diff options
| author | Khaled (Kal) Henidak <khnidk@outlook.com> | 2021-08-30 20:35:13 +0000 |
|---|---|---|
| committer | Khaled (Kal) Henidak <khnidk@outlook.com> | 2021-09-07 18:40:57 +0000 |
| commit | 99780a63a6d1e33e7f172d7415a545c70f1fdb1d (patch) | |
| tree | c39fe96e8334607bb67f61d0a7b9d5040c4ab130 | |
| parent | 1acc88be28506b3b6a2c8a306f45c4c434631159 (diff) | |
add auto resource release
| -rw-r--r-- | contributors/devel/sig-architecture/api-conventions.md | 24 |
1 files changed, 24 insertions, 0 deletions
diff --git a/contributors/devel/sig-architecture/api-conventions.md b/contributors/devel/sig-architecture/api-conventions.md index 30bee638..e2b72386 100644 --- a/contributors/devel/sig-architecture/api-conventions.md +++ b/contributors/devel/sig-architecture/api-conventions.md @@ -1609,3 +1609,27 @@ Example: "must be greater than \`request\`". be less than 256", "must be greater than or equal to 0". Do not use words like "larger than", "bigger than", "more than", "higher than", etc. * When specifying numeric ranges, use inclusive ranges when possible. + + +## Automatic Resource Allocation And Deallocation + +API objects often are [union](#Unions) object containing the following: +1. One or more fields identifying the `Type` specific to API object (aka the `discriminator`). +2. A set of N fields, only one of which should be set at any given time - effectively a union. + +Controllers operating on the API type often allocate resources based on +the `Type` and/or some additional data provided by user. A canonical example +of this is the `Service` API object where resources such as IPs and network ports +will be set in the API object based on `Type`. When the user does not specify +resources, they will be allocated, and when the user specifies exact value, they will +be reserved or rejected. + +When the user chooses to change the `discriminator` value (e.g., from `Type X` to `Type Y`) without +changing any other fields then the system should clear the fields that were used to represent `Type X` +in the union along with releasing resources that were attached to `Type X`. This should automatically +happen irrespective of how these values and resources were allocated (i.e., reserved by the user or +automatically allocated by the system. A concrete example of this is again `Service` API. The system +allocates resources such as `NodePorts` and `ClusterIPs` and automatically fill in the fields that +represent them in case of the service is of type `NodePort` or `ClusterIP` (`discriminator` values). +These resources and the fields representing them are automatically cleared when the users changes +service type to `ExternalName` where these resources and field values no longer apply. |