API Depreciations
Vamos entender um pouco do ciclo de vida de uma api.
Um novo api group pode ser adicionado no kubernetes mas sempre iniciará com v1alpha1.
Vamos imagina uma api teste/v1alpha1 que foi adicionada ao kubernetes e que possuimos dois objetivos que poderíamos declarar, ou seja, dois diferentes kind.
- course
- webinar
Mas vamos imaginar que webinar não foi uma boa escolha e queremos remover.
Não é possível remover da versão v1alpha1, é necessário lançar a v1alpha2, pois a primeira regra das políticas do api group é.
Os elementos de API somente podem ser removidos incrementando a versão do API Group.
Na versão v1alpha1 teremos o kind course e webinar disponívies e na versão v1alpha2 somente o course.
O do kubernetes suportar várias versões evita ter que alterar todos os manifestos que usem uma versão anterior.
O que mudaria seria a versão preferencial que viria setada agora para v1alpha2 quando utilizarmos o course.
Isso nos leva a segunda regra das políticas de depreciação de uma API.
Os objetos da API devem ser capazes de percorrer as versões da API em uma determinada versão sem perda de informações, com a excessões de recursos REST que não existem em algumas versões.
Se criarmos um API e um objeto na versão v1alpha1 e ele for convertido para v1alpha2 e voltar para a v1alpha1 ele deve ser igual ao original.
Isso significa que se um campo for adicionado em v1alpha2 ele também deve ser adicionado em v1alpha1 pois não seria possíve uma conversão direta se um campo não existir.
Com o tempo é lançado a o v1beta1, v1beta2 até chegar na versão estável v1. Nesta nova v1, não precisamos que o kubernetes suporte todas essas versões se a v1 possui compatiblidade com as anteriores então será depreciado para manter somente a v1.
Uma nova regra deve ser respeitada.
Além das versões mais recentes da API em cada faixa, as versões mais antigas da API devem ser suportadas após sua descontinuação anunciada por um período não inferior a:
- GA: 12 meses ou 3 releases
- Beta: 9 meses ou 3 releases
- Alpha: 0 releases
Alpha versions não precisam ser suportadas por nenhuma release mas as versões beta e GA (stable) precisam ser suportadas entre 9 e 12 meses. Se olharmos abaixo o exemplo a versão x+! não precisa suportar a versão v1alpha1.
Quando isso acontece é necessário criar uma nota de lançamento avisando dessa mudança, pois ações são requeridas para usuários que já fizeram uso do v1alpha1.
Também é possível que em uma versão v1beta1 por exemplo não precise suportar as versões alpha. Se isso não acontecer será dada uma nova nota de lançamento. Por isso não é muito interessante usar alphas em produção.
Quando a versão chega em beta as coisas mudam pois precisam ser suportadas por um tempo mínimo. Temos também a regra 3.
As versão preferencial e a versão de armazenamento de uma API group não podem avançar até que um lançamento que suporte a nova versão e a versão anterior tenha sido feito.
O que temos aqui é que apesar de uma nova versão aparecer ela não pode ser a preferencial em sua primeira aparição.
Depreciar uma verão não quer dizer que ele simplesmente não será suportada imediatamente pois pelo menos 3 releases precisará ser mantida.
Vamos analisar um fluxo de lançamentos e depreciações.
| Api Group Version | Preferred/ Storage Version | Release Versions | Notes |
|---|---|---|---|
| /v1alpha1 | x | Primeiro lançamento | |
| /v1alpha2 | x+1 | Alphas não precisam suportar versões anteriores | |
| /v1beta1 | x+2 | Primeira beta, será necessário respeitar regras | |
| /v1beta2 | /v1beta1 (deprecated) | x+3 | Lançamos a nova versão mas v1beta1 ainda é a preferencial |
| /v1beta1(deprecated) | /v1beta2 | x+4 | Segunda vez que a versão v1beta1 aparece como deprecated Nesse momomento v1beta2 já é a preferencial. |
| /v1 /v1beta1(deprecated) | /v1beta2 (deprecated) | x+5 | Lançamento da v1 Terceira vez que v1beta1 aparece como deprecated Primeira vez que v1beta2 aparece como deprecated Como foi a primeira vez do aparecimento de v1 v1beta1 ainda é preferencial |
| /v1beta2 (deprecated) | /v1 | x+6 | Removido v1beta1 após 3 releases /v1beta2 é deprecated pela segunda vez /v1 assume o preferencial |
| /v1beta2 (deprecated) | /v1 | x+7 | /v1beta2 não pode ser removida ainda É necessário suportar mais uma vez para contar 3 |
| /v1 | x+8 | /v1beta2 removido completamente |
Se uma v2alpha1 for criada a v1 versão stable não pode ser depreciada até que uma v2 stable exista completamente. Seria necessário criar uma v2aphaXs, v2betaXs, v2 para depois depreciar a v1.
Como vimos, em novas releases, novas apis podem ser adicionadas ou removidas mudando inclusive as apis preferenciais e armazenadas.
Em um update do kubernetes para uma nova release pode ser necessário converter os manifestos que uma api version foi completamente removida depois de 3 releases deprecated.
Podemos utilizar o kubectl convert para isso. Esse é um plugin que precisa ser instalado separadamente pois não é built-in.
Podemos usar a cli kubectl-convert diretamente, mas se tivermos ele no path o comando kubectl convert irá fazer uma chamada para este cli.
