Pular para o conteúdo principal

Executando o Casdoor no Kubernetes: Helm Chart oficial e Configuração como Código

· Leitura de 6 min
Yang Luo
Casdoor Maintainer

O Casdoor possui um Helm chart oficial. Ele reside no repositório principal em manifests/casdoor, é publicado a cada lançamento do Casdoor no GHCR e está listado no Artifact Hub. Começando com o Casdoor v4.18.0, o chart também pode manter suas organizações, aplicações, usuários e provedores como configuração declarativa: altere-os no arquivo values, execute helm upgrade, e os pods em execução aplicam a mudança sem reiniciar.

Este post percorre uma implantação no Kubernetes desde o primeiro helm install até uma configuração que você pode manter no Git.

Instalar​

Você precisa do Helm v3.8+ e de um cluster:

helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor

A versão do chart é a versão do Casdoor, então --version 4.18.0 instala o Casdoor 4.18.0. Sem um Ingress ou Gateway, o serviço só é acessível dentro do cluster. Para testá-lo, encaminhe uma porta:

kubectl port-forward svc/casdoor 8000:8000

Depois abra http://localhost:8000. Na primeira visita, o Casdoor pede para definir a senha de built-in/admin; então faça login com ela. Veja Entrar no console administrativo.

Uma configuração de produção​

Os padrões são destinados a um teste rápido: o Casdoor armazena seus dados em SQLite dentro do contêiner, portanto eles são perdidos quando o pod é substituído. Para uma implantação real, coloque as configurações abaixo em um arquivo values.yaml e instale com helm install casdoor oci://ghcr.io/casdoor/helm-charts/casdoor -f values.yaml.

Banco de dados externo​

database:
driver: postgres # or mysql, cockroachdb
host: postgres.db.svc.cluster.local
user: casdoor
password: change-me
databaseName: casdoor
sslMode: require

Para manter a senha do banco de dados fora do arquivo values, coloque todo o app.conf em um Secret e defina configFromSecret com o nome dele.

Expondo o Casdoor​

O chart suporta tanto um Ingress clássico quanto a API Gateway. Com um controlador Ingress e cert-manager:

ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
hosts:
- host: door.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: casdoor-tls
hosts:
- door.example.com

Com a API Gateway (Istio, Envoy Gateway, Cilium, Kong, NGINX Gateway Fabric e outros), anexe um HTTPRoute a um Gateway existente:

gatewayApi:
enabled: true
parentRefs:
- name: my-gateway
namespace: gateway-system
hostnames:
- door.example.com

O chart também pode criar o Gateway ele mesmo e adicionar um redirecionamento de HTTP para HTTPS, veja o guia do Helm.

Mais de uma réplica​

Por padrão, o Casdoor mantém sessões de login no disco local. Antes de executar mais de uma réplica, aponte todas elas para o mesmo Redis, para que um usuário permaneça autenticado independentemente do pod que atender à solicitação. Cada configuração do app.conf pode ser passada como uma variável de ambiente, então o endpoint pode vir de um Secret:

replicaCount: 3

envFromSecret:
- name: redisEndpoint
secretName: casdoor-redis
key: endpoint # host:port, or host:port,db,password

O mesmo Redis é usado para o estado do fluxo de dispositivo OAuth. Uma vez que o Redis esteja configurado, autoscaling.enabled: true adiciona um HorizontalPodAutoscaler.

Configuração como código​

Clicar em organizações e aplicações juntos na interface web é bom para um primeiro teste, mas a maioria das equipes deseja que a configuração de seu provedor de identidade seja revisada e versionada como o resto de sua infraestrutura. Os valores initData fazem isso:

initData:
enabled: true
data:
organizations:
- owner: admin
name: acme
displayName: Acme
passwordType: bcrypt
applications:
- owner: admin
name: app-acme-portal
organization: acme
displayName: Acme Portal
redirectUris:
- https://portal.acme.example.com/callback
users:
- owner: acme
name: alice
displayName: Alice
password: change-me
signupApplication: app-acme-portal
roles:
- owner: acme
name: admins
displayName: Admins
users: [acme/alice]
isEnabled: true

O chart armazena os dados em um Secret e monta-o nos pods. O Casdoor aplica-os na inicialização, depois verifica-os a cada 30 segundos (initData.watchInterval). Quando você altera os dados e executa helm upgrade, o kubelet atualiza o Secret montado e os pods em execução aplicam-no sem reiniciar.

Algumas regras tornam isso seguro de usar junto com a interface web:

  • Somente os campos que você escreve são gerenciados. Um objeto que já existe recebe os campos definidos no arquivo; seus outros campos mantêm os valores editados na interface. Você pode gerenciar apenas os URIs de redirecionamento de uma aplicação e deixar o resto para o console administrativo.
  • As senhas são senhas iniciais. A password de um usuário é usada apenas quando o usuário é criado, para que os usuários possam alterá-la posteriormente.
  • Nada é excluído. Remover um objeto do arquivo não o remove do Casdoor.
  • Erros não derrubam o Casdoor. Se um objeto falhar ao ser aplicado, o erro é registrado e o Casdoor continua atendendo; os dados são tentados novamente a cada verificação até serem aplicados.

O formato do arquivo é aquele que o Casdoor sempre usou para inicialização de dados: organizações, aplicações, usuários, provedores, certificados, papéis, permissões, grupos, servidores LDAP, webhooks, planos, preços e mais, com os mesmos nomes de campos da API REST. Uma maneira rápida de começar é exportar uma instância existente com casdoor -export e manter os objetos que você deseja gerenciar.

Para manter os dados fora do arquivo de valores, por exemplo, quando gerenciado pelo Sealed Secrets ou External Secrets, crie o Secret você mesmo:

initData:
enabled: true
existingSecret: casdoor-init-data
existingSecretKey: init_data.yaml

O mesmo recurso funciona sem Kubernetes. Monte um arquivo JSON ou YAML e defina:

initDataFile = /init-data/init_data.yaml
initDataMerge = true
initDataWatchInterval = 30

Ou use Terraform​

Se você prefere terraform plan, importações de objetos existentes e detecção de drift, o provedor oficial do Terraform gerencia os mesmos objetos através da API do Casdoor:

resource "casdoor_application" "portal" {
name = "app-acme-portal"
organization = "acme"
redirect_uris = ["https://portal.acme.example.com/callback"]
}

Use os valores do Helm quando a configuração deve acompanhar a implantação, e Terraform quando o Casdoor é um dos muitos sistemas que você já gerencia com ele. Veja o guia do Terraform.

Vindo do chart antigo​

Até a v4.15.0, o chart era publicado como oci://registry-1.docker.io/casbin/casdoor-helm-charts, e o repositório separado casdoor/casdoor-helm agora está arquivado. O chart no Docker Hub ainda recebe todas as versões, mas novas instalações devem usar o do GHCR. Migrar uma versão existente é uma atualização regular, e os nomes dos recursos permanecem os mesmos:

helm upgrade casdoor oci://ghcr.io/casdoor/helm-charts/casdoor --version <version>