Atualizando Keycloak usando Helm Chart da Bitnami
Um guia rápido e fácil de seguir, escrito com base em desafios enfrentados ao atualizar o Keycloak provisionado com Helm Chart da Bitnami.
An english version is coming soon. Stay tuned. 😃
Uma breve introdução
Sempre fui contra utilizar os Helm Charts da Bitnami - as imagens dos conteineres são super modificadas e no caso do Keycloak especificamente, é uma confusão enorme com as ENV VARs para configurá-lo (KC_*), as ENV VARs para configurar o conteiner da Bitnami (KEYCLOAK_*) e a documentação não é das melhores. Mas não posso negar que em alguns momentos esses Charts ajudam a subir algo rápido, e foi por esse motivo que o time que trabalho decidiu subir dessa forma, ao invés de utilizar o Keycloak Operator.
No fim do ano passado, puxei a iniciativa de atualizar as intâncias de Keycloak que utilizamos na Pier com outros Staff Engineers para suportar algumas funcionalidades que seriam interessantes implementar em algumas aplicações. Foi um trabalho de formiguinha, mas deu certo. Nesse post, irei explicar o processo e dar algumas dicas.
Vale ressaltar que nem todos ambientes são iguais, no nosso caso, utilizamos ALB Ingress Controller no AWS EKS, rodando Kubernetes 1.31.
Após uma pergunta no grupo Cloud & Infra da comunidade Platform Engineering no Whatsapp, resolvi escrever esse post para ajudar outras pessoas. Espero que possa te ajudar também!
Dicas de ouro
A ideia era atualizar para a última versão do Keycloak (26.0.7) e meu primeiro erro foi tentar subir da versão 22 direto para 26 e subindo a versão do Helm Chart da 16 para 24. E as coisas não funcionam assim.
Por isso, faça upgrades sequenciais, tanto do Keycloak quanto do Helm Chart. Entre as major versions do Keycloak, o banco é atualizado diversas vezes e não senti segurança na execução das migrations entre a 22 e a 26, principalmente pela alta customização da imagem feita pela Bitnami. Os Helm Charts também devem ser atualizados de forma sequencial, porém, nem sempre atualizações entre major versions funcionam bem.
Segunda dica, antes de cada upgrade leia o Upgrading Guide na documentação oficial do Keycloak. A doc não é das melhores, mas explica mudanças significativas como alteração do hostname_v1 para hostname_v2 e na API.
A terceira dica é, testar, testar e testar. Verifique se o login na console de administração está funcionando e o principal, se sua aplicação continua funcionando conforme o esperado.
Atualizando
Os values utilizados a partir da versão 16.0.3 do Chart (Keycloak 22.0.1) estão nesse Gist. Eu usarei o mesmo YAML como referência até a versão 24.2.3 e mencionando apenas as mudanças, caso você não queira ir até a última versão do Chart.
Upgrades sem mudanças nos values
Helm Chart: 16.0.3 → 17.3.6 / Keycloak: 22.0.5
Helm Chart: 17.3.6 → 18.7.1 / Keycloak: 23.0.7
Helm Chart: 18.7.1 → 19.4.1 / Keycloak: 23.0.7
Você pode pular esse upgrade e ir direto para a 19.4.1, caso queira ir para a versão 24.0.2 do Keycloak.
Helm Chart: 19.4.1 → 21.0.0 / Keycloak: 24.0.2
Helm Chart: 21.0.0 → 21.1.3 / Keycloak: 24.0.4
Helm Chart: 21.1.3 → 21.2.2 / Keycloak: 24.0.4
Você pode pular esse upgrade e ir direto para a 21.3.4, caso queira ir para a versão 24.0.5 do Keycloak.
Helm Chart: 21.2.2 → 21.3.4 / Keycloak: 24.0.5
Helm Chart: 21.3.4 → 21.4.6 / Keycloak: 24.0.5
Helm Chart: 21.4.64 → 21.5.0 / Keycloak: 24.0.5
Helm Chart: 21.5.0 → 21.6.0 / Keycloak: 24.0.5
Upgrades com mudanças nos values
A partir da versão 21.6.0, uma série de releases foram lançadas tentando corrigir vários bugs, regressões e etc… um caos completo.
Você também irá notar que eu voltei para a 21.5.0. Isso se deve ao fato de puro troubleshooting, tentando quebrar minha cabeça para entender a bagunça feita pelos mantenedores e comunidade.
Helm Chart: 21.5.0 → 22.1.0 / Keycloak: 25.0.2
Mudanças:
proxy: none- Isso se deve ao fato da remoção de como o Keycloak trata requests atrás de um proxy reverso.proxyHeaders: forwarded- Devido a mudança acima, existe uma nova forma de tratar e configurar os proxy headers atrás de um ingress ou proxy reverso. Vale a pena ler a documentação oficial sobre o tema.ingress.controller: gce- Alguns usuários utilizando o ingress-gce, setam/*noingress.path, assim como eu, utilizando o ALB Ingress Controller. Setargcenesse parâmetro vai fazer com que ao utilizar/*, o ingress rule não quebre.hostnameStrict: false- Ajustando o configuração de hostname v2 do Keycloak.
Helm Chart: 22.1.0 → 24.0.0 / Keycloak: 26.0.0
Sem mudanças
Helm Chart: 24.0.0 → 24.2.3 / Keycloak: 26.0.7
As mudanças realizadas aqui foram feitas para resolver problemas que tivemos no nosso cenário:
global.security.allowInsecureImages: true- Utilizamos uma imagem customizada do Keycloak onde inserimos temas e mais alguns componentes desenvolvidos internamente. Mais infos aqui.proxyHeaders: xforwarded- Após iniciarmos os testes, alguns fluxos de autenticação retornavam erros relacionados aos cookies. Setarxforwardedresolveu o problema.
O resultado final dessa saga, você pode conferir nesse Gist.
Notas finais
Eu levei um dia e meio para ler e entender todas as mudanças feitas no Helm Chart entre as versões 16.0.3 e a 24.2.3. Recomendo não só para o Keycloak, mas para qualquer Chart da Bitnami fazer o mesmo. Anotar e documentar o processo é importante para não perder o fio da meada.
Se atentar as mudanças na API do Keycloak no Upgrading Guide é super importante também. No nosso caso tivemos que fazer alguns ajustes nas aplicações, então tenha tudo mapeado.
Espero que esse post possa ajudar a comunidade de alguma forma.
Até mais!