diff options
| author | Kubernetes Prow Robot <k8s-ci-robot@users.noreply.github.com> | 2021-09-07 14:58:34 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-07 14:58:34 -0700 |
| commit | 22b6ce57ac4a5d8d0e368da45d2b35340169dec4 (patch) | |
| tree | ab46d930115ea65ddd1cc6e276daab10a5acc6d3 | |
| parent | 88d4fbe82e326f32c8b339c65743e1df5f356dd5 (diff) | |
| parent | 99780a63a6d1e33e7f172d7415a545c70f1fdb1d (diff) | |
Merge pull request #5983 from khenidak/alloc-release-resources
Auto resource release based on api changes
| -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. |