Kubernetes

Faca deployment do FoxIDs no seu cluster Kubernetes, K8s, ou no Docker Desktop com Kubernetes ativado.

Esta e uma descricao de como fazer um deployment predefinido e iniciar sessao pela primeira vez, bem como algumas consideracoes. Pressupoe-se que tera de personalizar os ficheiros yaml para se adequarem as suas necessidades, preferencias e ambiente.

Uma instalação FoxIDs é autónoma, tem poucas dependências externas e consegue obter um uptime muito elevado com pouco esforço. O FoxIDs e atualizado atualizando as duas docker images www.foxids.com/foxids:x.x.x e www.foxids.com/foxidscontrol:x.x.x para uma nova versao. As novas releases do FoxIDs sao backward compatible. Reveja as release notes antes de atualizar. Tambem pode encontrar ai a versao atual da Docker image.

E necessaria uma licenca valida para aceder as releases do FoxIDs. A partir dai, pode gerar um secret para autenticar no Docker image registry em www.foxids.com, que usa autenticacao Basic.

Pre-requisitos:

• Tem um cluster Kubernetes ou Docker Desktop com Kubernetes ativado.
• Tem conhecimentos basicos de Kubernetes.
• Tem o kubectl instalado.

No fim desta descricao existe uma lista de comandos uteis.

Este deployment inclui:

• Dois websites, um para o FoxIDs e outro para o FoxIDs Control, admin Client e API, em duas docker images www.foxids.com/foxids:x.x.x e www.foxids.com/foxidscontrol:x.x.x.
• Os dois websites sao expostos em dois domains diferentes, protegidos com certificados Let's Encrypt gerados automaticamente.
• O MongoDB e uma base de dados NoSQL e contem todos os dados incluindo tenants, ambientes e utilizadores. E distribuido com a official MongoDB Docker image. Opcionalmente pode usar a sua propria instancia PostgreSQL em vez de MongoDB.
• Por predefinicao a cache fica na base de dados configurada. Redis so e necessario se executar um cluster FoxIDs com elevado throughput e PostgreSQL. O MongoDB tem uma cache incorporada que tem bom desempenho quando a instancia MongoDB tem memoria suficiente. A cache FoxIDs mantem sequencias, por exemplo login e logout, gere contadores para proteger a autenticacao contra varios ataques e data cache, apenas Redis, para melhorar o desempenho. O Redis e distribuido com a official Redis Docker image.
• Os logs sao escritos em stdout, onde o Kubernetes os pode recolher. Recomenda-se usar OpenSearch para logging, a menos que a instalacao FoxIDs seja pequena. Com OpenSearch, erros, events e traces podem ser vistos diretamente no FoxIDs Control Client alem do log Kubernetes, o que torna o sistema muito mais facil de administrar.

Deployment

O deployment e executado pela ordem descrita.

Get ready

Descarregue os ficheiros de configuracao Kubernetes yaml aqui e coloque-os numa pasta na sua maquina, por exemplo C:\FoxIDs\Kubernetes.

Abra uma consola e navegue para a pasta Kubernetes.

Namespace

Este guia usa genericamente o namespace foxids; considere altera-lo de acordo com o seu ambiente kubernetes.

Crie o namespace

kubectl create namespace foxids

Persistent volumes

Precisa de persistent volumes para MongoDB, opcionalmente OpenSearch e, opcionalmente, Redis se usar Redis com PostgreSQL para um cluster FoxIDs com elevado throughput.

Num cluster Kubernetes use ou crie persistent volumes adequados e crie uma persistent volume claim com o nome mongo-data-pvc para MongoDB e, opcionalmente, uma para Redis com o nome redis-data-pvc.

Pode conseguir usar dynamic storage provisioning com StorageClass.

Crie a persistent volume claim para Mongo

kubectl apply -f mongo-pvc-dynamic.yaml -n foxids

Opcionalmente crie a persistent volume claim para Redis

kubectl apply -f redis-pvc-dynamic.yaml -n foxids

Opcionalmente crie a persistent volume claim para OpenSearch

kubectl apply -f opensearch-pvc-dynamic.yaml -n foxids

Kubernetes in Docker Desktop

Se estiver a usar Kubernetes no Docker Desktop, pode criar persistent volumes no sistema de ficheiros do host - nao recomendado para producao.

Crie o persistent volume para MongoDB

kubectl apply -f mongo-pv-dockerdesktop.yaml

Crie a persistent volume claim para MongoDB

kubectl apply -f mongo-pvc-dockerdesktop.yaml -n foxids

Opcionalmente crie o persistent volume para Redis

kubectl apply -f redis-pv-dockerdesktop.yaml

Opcionalmente crie a persistent volume claim para Redis

kubectl apply -f redis-pvc-dockerdesktop.yaml -n foxids

Opcionalmente crie o persistent volume para OpenSearch

kubectl apply -f opensearch-pv-dockerdesktop.yaml

Opcionalmente crie a persistent volume claim para OpenSearch

kubectl apply -f opensearch-pvc-dockerdesktop.yaml -n foxids

MongoDB

Altere o username e a password do MongoDB em mongo-secret.yaml. O username e a password estao codificados em base64.

Pode codificar em base64 "the text" num command prompt, dependendo da sua plataforma:

Windows

powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"the text\"))"

Linux / Mac

echo -n "the text" | base64

Adicione o secret do MongoDB

kubectl apply -f mongo-secret.yaml -n foxids

Crie MongoDB
Opcionalmente exponha o MongoDB na porta 27017 removendo o comentario de LoadBalancer

kubectl apply -f mongo-deployment.yaml -n foxids

Adicione uma ConfigMap para o servico MongoDB

kubectl apply -f mongo-configmap.yaml -n foxids

Optionally use PostgreSQL instead of MongoDB

Altere o valor do username em postgres-username e o valor da password em postgres-password para corresponderem a sua instancia PostgreSQL em postgres-secret.yaml. O username e a password estao codificados em base64.

Adicione o secret PostgreSQL

kubectl apply -f postgres-secret.yaml -n foxids

Altere o endpoint da base de dados PostgreSQL em postgres-db para corresponder a sua instancia PostgreSQL em postgres-configmap.yaml

Adicione uma ConfigMap para o servico PostgreSQL

kubectl apply -f postgres-configmap.yaml -n foxids

Optionally use Redis

Redis so e necessario se usar PostgreSQL e executar um cluster FoxIDs com elevado throughput. Se usar MongoDB, a cache incorporada do MongoDB tem bom desempenho quando a instancia MongoDB tem memoria suficiente.

Opcionalmente crie Redis

kubectl apply -f redis-deployment.yaml -n foxids

Opcionalmente adicione uma ConfigMap para o servico Redis

kubectl apply -f redis-configmap.yaml -n foxids

Optionally use OpenSearch

OpenSearch e recomendado para logging, a menos que a instalacao FoxIDs seja pequena. Uma instalacao pequena pode executar apenas com logging Stdout, onde o Kubernetes recolhe os logs. Com OpenSearch, erros, events e traces tambem podem ser pesquisados diretamente no FoxIDs Control Client, o que torna o sistema muito mais facil de administrar.

Altere a password do OpenSearch em opensearch-secret.yaml. A password esta codificada em base64.

Adicione o secret OpenSearch

kubectl apply -f opensearch-secret.yaml -n foxids

Crie OpenSearch

kubectl apply -f opensearch-deployment.yaml -n foxids

Adicione uma ConfigMap para o servico OpenSearch

kubectl apply -f opensearch-configmap.yaml -n foxids

FoxIDs websites

Domains
Os dois websites FoxIDs estao configurados para usar dois domains que cria e gere no seu DNS. Configure o ficheiro foxids-deployment.yaml com os domains escolhidos:

• O domain do site FoxIDs https://id.itfoxtec.com, dois locais no ficheiro, e alterado para o seu domain - id.my-domain.com
• O domain do site FoxIDs Control https://control.itfoxtec.com e alterado para o seu domain - control.my-domain.com

Email provider
Opcionalmente pode configurar um email provider global ou mais tarde configurar email providers por ambiente. O FoxIDs suporta o envio de emails com SendGrid e SMTP. Tambem pode configurar fornecedores SMS globalmente ou por ambiente.

O global email provider e configurado no ficheiro foxids-deployment.yaml no container, pod, foxids na secao env:. Este exemplo mostra como adicionar Outlook / Microsoft 365 com SMTP:

- name: "Settings__Smtp__FromEmail"
    value: "my@email-address.org"
- name: "Settings__Smtp__FromName" # Optional from name associated to the email address 
    value: "e.g, my company name"
- name: "Settings__Smtp__Host"
    value: "smtp.office365.com"
- name: "Settings__Smtp__Port"
    value: "587"
- name: "Settings__Smtp__Username"
    value: "my@email-address.com"
- name: "Settings__Smtp__Password"
    value: "xxxxxxx"

Important if you are using PostgreSQL
Altere a configuracao da base de dados e da cache em foxids-deployment.yaml, dois locais no ficheiro.

Selecione PostgreSQL como base de dados em vez de MongoDb

- name: "Settings__Options__DataStorage"
   # value: "MongoDb"
   value: "PostgreSql"  # PostgreSql database

Selecione PostgreSQL como cache em vez de MongoDb, a menos que esteja a usar Redis

- name: "Settings__Options__Cache"
   # value: "MongoDb"
   value: "PostgreSql"  # Cache in PostgreSql database
   # value: "Redis"  # Cache in Redis 

Remova o comentario da configuracao de acesso PostgreSQL

- name: POSTGRES_USERNAME
    valueFrom:
    secretKeyRef:
        name: postgres-secret
        key: postgres-username
- name: POSTGRES_PASSWORD
    valueFrom:
    secretKeyRef:
        name: postgres-secret
        key: postgres-password
- name: POSTGRES_SERVER
    valueFrom:
    configMapKeyRef:
        name: postgres-configmap
        key: database_url
- name: "Settings__PostgreSql__ConnectionString"
    value: "Host=$(POSTGRES_SERVER);Username=$(POSTGRES_USERNAME);Password=$(POSTGRES_PASSWORD);Database=FoxIDs"

Important if you are using Redis
Altere a configuracao da cache em foxids-deployment.yaml, dois locais no ficheiro.

Selecione Redis como cache em vez de MongoDb

- name: "Settings__Options__Cache"
   # value: "MongoDb"
   # value: "PostgreSql"  # Cache in PostgreSql database
   value: "Redis"  # Cache in Redis

Opcionalmente coloque dados da base de dados em cache no Redis

- name: "Settings__Options__DataCache"
   # value: "None"
   value: "Default"  # Cache DB data in Redis

Remova o comentario da configuracao de acesso Redis

- name: REDIS_SERVER
    valueFrom:
    configMapKeyRef:
        name: redis-configmap
        key: database_url
- name: "Settings__RedisCache__ConnectionString"
    value: "$(REDIS_SERVER):6379"

Important if you are using OpenSearch Altere a configuracao de log em foxids-deployment.yaml, dois locais no ficheiro.

Selecione OpenSearch logging em vez de Stdout

- name: "Settings__Options__Log"
   # value: "Stdout"
   value: "OpenSearchAndStdoutErrors"

Remova o comentario da configuracao de acesso OpenSearch

- name: OPENSEARCH_PASSWORD
    valueFrom:
    secretKeyRef:
        name: opensearch-secret
        key: opensearch-password
- name: OPENSEARCH_SERVER
    valueFrom:
    configMapKeyRef:
        name: opensearch-configmap
        key: opensearch_url
- name: "Settings__OpenSearch__Nodes__0"
    value: "https://admin:$(OPENSEARCH_PASSWORD)@$(OPENSEARCH_SERVER):9200"
- name: "Settings__OpenSearch__LogLifetime"
    value: "Max180Days"
- name: "Settings__OpenSearch__AllowInsecureCertificates"
    value: "true"

OpenSearchAndStdoutErrors envia logs para OpenSearch e escreve erros em stdout, por isso Kubernetes continua a receber logs de erro. AllowInsecureCertificates esta definido como true porque o container OpenSearch predefinido usa um certificado self-signed.

Deploy
Defina o username como o seu customer ID e a password como o seu pull secret para o FoxIDs Docker registry. Depois crie o registry secret.

kubectl create secret docker-registry foxids-registry-secret --docker-server=www.foxids.com --docker-username=<customer-id> --docker-password=<pull-secret> -n foxids

Crie os dois websites FoxIDs

kubectl apply -f foxids-deployment.yaml -n foxids

A configuracao requer um Nginx controller. Opcionalmente pode alterar a configuracao para usar outro controller.

Pre-requisitos:

• Tem o Helm instalado.
  Instale o Helm no Windows com este comando CMD winget install Helm.Helm

Instale o Ingress-Nginx controller com dois comandos

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx --force-update
helm -n ingress-nginx install ingress-nginx ingress-nginx/ingress-nginx --create-namespace

Opcionalmente verifique a instalacao do Ingress-Nginx

kubectl get pod -n ingress-nginx

Se tentar novamente dentro de alguns minutos, devera obter um EXTERNAL-IP

kubectl get svc -n ingress-nginx ingress-nginx-controller

Os registos DNS dos dois domains precisam de apontar para o endereco IP da instalacao para permitir a validacao online do Let's Encrypt.
A firewall precisa de aceitar pedidos nas portas 80 e 443. O Let's encrypt valida a posse do dominio na porta 80.

Opcionalmente escale o Ingress-Nginx controller

kubectl scale deployment ingress-nginx-controller -n ingress-nginx --replicas=2

Instale o Cert-manager com dois comandos

helm repo add jetstack https://charts.jetstack.io --force-update
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set crds.enabled=true

Opcionalmente verifique a instalacao do Cert-manager

kubectl get pods -n cert-manager

Adicione o seu email no ficheiro letsencrypt-issuer.yaml, dois locais no ficheiro.

Configure o Let's Encrypt

kubectl apply -f letsencrypt-issuer.yaml -n foxids

O ficheiro foxids-ingress-deployment.yaml esta configurado com os domains:

• O domain do site FoxIDs id.itfoxtec.com, dois locais no ficheiro, e alterado para o seu domain - id.my-domain.com
• O domain do site FoxIDs Control control.itfoxtec.com, dois locais no ficheiro, e alterado para o seu domain - control.my-domain.com

Considere comecar com Let's Encrypt em staging para evitar atingir o production rate limit do Let's Encrypt, os certificados de staging nao sao trusted pelo browser.
Opcionalmente selecione staging ou production no ficheiro foxids-ingress-deployment.yaml; por predefinicao esta configurado para production.

Adicione ingress com domains ligados a certificados

kubectl apply -f foxids-ingress-deployment.yaml -n foxids

Importante! O Ingress e instalado com as annotations nginx.ingress.kubernetes.io/proxy-buffers-number: "4" e nginx.ingress.kubernetes.io/proxy-buffer-size: "32k" para suportar SAML 2.0, onde as HTTP responses podem ser bastante grandes.

Opcionalmente verifique o Ingress

kubectl get ingress -n foxids

Opcionalmente verifique o certificate issuer

kubectl describe ClusterIssuer letsencrypt-production -n foxids
#staging 
# kubectl describe ClusterIssuer letsencrypt-staging -n foxids

Opcionalmente verifique se o certificado esta pronto, READY deve ser True

kubectl get certificate -n foxids

E opcionalmente verifique o certificado

kubectl describe certificate letsencrypt-production -n foxids
#staging 
# kubectl describe certificate letsencrypt-staging -n foxids

First login

Abra o domain do seu site FoxIDs Control num browser. Devera redirecionar para o site FoxIDs, onde inicia sessao com o utilizador admin predefinido admin@foxids.com e password FirstAccess!, sendo obrigatorio alterar a password no primeiro login.
Depois e redirecionado de volta para o site FoxIDs Control no tenant master. Pode adicionar mais utilizadores admin no tenant master.

Depois clique no tenant main e autentique-se novamente com o mesmo utilizador admin predefinido admin@foxids.com e password FirstAccess!, mais uma vez sendo obrigatorio alterar a password.

O utilizador admin predefinido e a password sao os mesmos tanto para o tenant master como para o tenant main, mas sao dois utilizadores diferentes.

Esta agora autenticado no tenant main e pode comecar a configurar as suas applications e os seus authentication methods.

Seed data

A base de dados e automaticamente inicializada com base nos domains configurados. Por isso, precisa de eliminar a base de dados se os domains forem alterados.
Para eliminar os dados, pode parar o pod da base de dados e apagar a pasta fisica ou os ficheiros da base de dados. Ou expor o endpoint da base de dados e abrir a base de dados no MongoDB Compass, download MongoDB Compass Download (GUI), e eliminar a base de dados.
Depois disso, o pod FoxIDs Control precisa de ser reiniciado para iniciar um novo processo de seed.

Opcao avancada: os domains tambem podem ser alterados manualmente na base de dados.

Considerations

Esta secao lista algumas consideracoes de deployment e seguranca.

Kubernetes Service Mesh
Recomenda-se usar uma Kubernetes Service Mesh para obter uma arquitetura zero-trust, onde o trafego interno e protegido com mutual TLS, mTLS, e cifragem.

Internal PKI / root CA
Se o trafego interno for terminado e reencriptado por um proxy ou service mesh com uma internal root CA, configure os containers do FoxIDs para confiarem nessa CA. Veja Kubernetes internal CA.

Namespace
Este guia usa genericamente o namespace foxids; considere altera-lo de acordo com o seu ambiente kubernetes.

Crie o namespace

kubectl create namespace test

Liste namespaces

kubectl get namespaces

Aplique namespace na criacao do pod

kubectl apply -f xxx.yaml --namespace=test

Log
Todos os logs do FoxIDs, incluindo erros, trace e eventos, sao escritos em stdout. Considere como gerir application logs e recolher logs dos containers.

Rate Limiting
Configure limites em ligacoes e taxas de transmissao em foxids-ingress-deployment.yaml.

MongoDB Operator
Considere o MongoDB Operator se precisar de varias instancias de MongoDB.

1. MongoDB Community Kubernetes Operator (free)
2. MongoDB Enterprise Kubernetes Operator

Redis multiple pods / cluster
Considere uma configuracao Redis escalada se precisar de varias instancias Redis.

• Redis master/replica setup in Kubernetes
• Redis on Kubernetes
• Redis Enterprise cluster on Kubernetes e architecture

Backup
Considere se os dados MongoDB precisam de backup e a que nivel; aqui estao tres possiveis solucoes. Considera-se menos importante fazer backup do Redis.

1. Fazer backup do data store fisico do persistent volume.
2. Backup with a Kubernetes Cron Job.
3. O backup e suportado pelo MongoDB Enterprise Kubernetes Operator.

Update

O FoxIDs ? atualizado alterando as tags de vers?o das imagens em foxids-deployment.yaml para ambos os containers FoxIDs:

image: www.foxids.com/foxids:x.x.x
image: www.foxids.com/foxidscontrol:x.x.x

Consulte as notas da vers?o antes de atualizar. As notas da vers?o tamb?m indicam a vers?o atual da imagem Docker. As novas vers?es do FoxIDs s?o compat?veis com vers?es anteriores.

Aplique o ficheiro de deployment atualizado:

kubectl apply -f foxids-deployment.yaml -n foxids

O Kubernetes atualiza depois os dois deployments para as novas vers?es das imagens.

Da mesma forma, tamb?m dever? ser poss?vel atualizar as imagens MongoDB, Redis e OpenSearch com dados em persistent volumes.

Useful commands

Esta e uma lista de comandos que podem ser uteis durante o deployment para ver detalhes e fazer alteracoes ao deployment.

Criar pod

kubectl apply -f xxx.yaml -n foxids

Remover pod

kubectl delete -f xxx.yaml -n foxids

Listar pods

kubectl get pods -n foxids

Obter descricao do pod

kubectl describe pod xxx -n foxids

Obter logs do pod

kubectl logs xxx -n foxids

Listar deployments

kubectl get deployments -n foxids

Listar services

kubectl get services -n foxids

Listar secrets

kubectl get secrets -n foxids

Mostrar o FoxIDs docker registry secret

kubectl get secret foxids-registry-secret -n foxids --output=yaml

Listar persistent volumes

kubectl get pv

Listar persistent volume claims

kubectl get pvc

Listar ingress

kubectl get ingress

Descrever ingress

kubectl describe ingress xxx