API Depreciations
Vamos a entender un poco del ciclo de vida de una api.
Un nuevo api group puede ser adicionado en kubernetes pero siempre iniciará con v1alpha1.
Vamos a imaginar una api teste/v1alpha1 que fue adicionada al kubernetes y que poseemos dos objetivos que podríamos declarar, o sea, dos diferentes kind.
- course
- webinar
Pero vamos a imaginar que webinar no fue una buena elección y queremos remover.
No es posible remover de la versión v1alpha1, es necesario lanzar la v1alpha2, pues la primera regla de las políticas del api group es.
Los elementos de API solamente pueden ser removidos incrementando la versión del API Group.
En la versión v1alpha1 tendremos el kind course y webinar disponibles y en la versión v1alpha2 solamente el course.
El de kubernetes soportar varias versiones evita tener que alterar todos los manifestos que usen una versión anterior.
Lo que cambiaría sería la versión preferencial que vendría setada ahora para v1alpha2 cuando utilizamos el course.
Eso nos lleva a segunda regla de las políticas de depreciación de una API.
Los objetos de la API deben ser capaces de recorrer las versiones de la API en una determinada versión sin pérdida de informaciones, con la excepción de recursos REST que no existen en algunas versiones.
Si creamos un API y un objeto en la versión v1alpha1 y él for convertido para v1alpha2 y volver para la v1alpha1 él debe ser igual al original.
Eso significa que si un campo for adicionado en v1alpha2 él también debe ser adicionado en v1alpha1 pues no sería posible una conversión directa si un campo no existir.
Con el tiempo es lanzado la o v1beta1, v1beta2 hasta llegar en la versión estable v1. En esta nueva v1, no precisamos que el kubernetes soporte todas esas versiones si la v1 posee compatibilidad con las anteriores entonces será depreciado para mantener solamente la v1.
Una nueva regla debe ser respetada.
Además de las versiones más recientes de la API en cada franja, las versiones más antiguas de la API deben ser soportadas después de su descontinuación anunciada por un período no inferior a:
- GA: 12 meses o 3 releases
- Beta: 9 meses o 3 releases
- Alpha: 0 releases
Alpha versions no precisan ser soportadas por ninguna release pero las versiones beta y GA (stable) precisan ser soportadas entre 9 y 12 meses. Si miramos abajo el ejemplo la versión x+1 no precisa soportar la versión v1alpha1.
Cuando eso acontece es necesario crear una nota de lanzamiento avisando de esa mudanza, pues acciones son requeridas para usuarios que ya hicieron uso del v1alpha1.
También es posible que en una versión v1beta1 por ejemplo no precise soportar las versiones alpha. Si eso no acontece será dada una nueva nota de lanzamiento. Por eso no es muy interesante usar alphas en producción.
Cuando la versión llega en beta las cosas mudan pues precisan ser soportadas por un tiempo mínimo. Tenemos también la regla 3.
Las versión preferencial y la versión de almacenamiento de una API group no pueden avanzar hasta que un lanzamiento que soporte la nueva versión y la versión anterior tenga sido hecho.
Lo que tenemos aquí es que a pesar de una nueva versión aparecer ella no puede ser la preferencial en su primera aparición.
Depreciar una versión no quiere decir que él simplemente no será soportada inmediatamente pues por lo menos 3 releases precisará ser mantenida.
Vamos a analizar un flujo de lanzamientos y depreciaciones.
| Api Group Version | Preferred/ Storage Version | Release Versions | Notes |
|---|---|---|---|
| /v1alpha1 | x | Primer lanzamiento | |
| /v1alpha2 | x+1 | Alphas no precisan soportar versiones anteriores | |
| /v1beta1 | x+2 | Primera beta, será necesario respetar reglas | |
| /v1beta2 | /v1beta1 (deprecated) | x+3 | Lanzamos la nueva versión pero v1beta1 todavía es la preferencial |
| /v1beta1(deprecated) | /v1beta2 | x+4 | Segunda vez que la versión v1beta1 aparece como deprecated En ese momento v1beta2 ya es la preferencial. |
Podemos utilizar el kubectl convert para eso. Ese es un plugin que precisa ser instalado separadamente pues no es built-in.
Podemos usar la cli kubectl-convert directamente, pero si tenemos él en el path el comando kubectl convert irá hacer una llamada para este cli.