Kubernetes

Esegui il deployment di FoxIDs nel tuo cluster Kubernetes, K8s, oppure in Docker Desktop con Kubernetes abilitato.

Questa e una descrizione di come eseguire un deployment predefinito e accedere per la prima volta, nonche alcune considerazioni. Si presume che dovrai personalizzare i file yaml in base alle tue esigenze, preferenze e ambiente.

Una installazione FoxIDs è autonoma, ha poche dipendenze esterne e può ottenere un uptime molto elevato con poco sforzo. FoxIDs viene aggiornato aggiornando le due docker images www.foxids.com/foxids:x.x.x e www.foxids.com/foxidscontrol:x.x.x a una nuova versione. Le nuove release FoxIDs sono backward compatible. Controlla le release notes prima di aggiornare. Li puoi anche trovare la versione corrente della Docker image.

Per accedere alle release FoxIDs e richiesta una licenza valida. Da li puoi generare un secret per autenticarti con il Docker image registry su www.foxids.com, che usa autenticazione Basic.

Prerequisiti:

• Hai un cluster Kubernetes oppure Docker Desktop con Kubernetes abilitato.
• Hai conoscenze di base di Kubernetes.
• Hai installato kubectl.

In fondo a questa descrizione c'e un elenco di comandi utili.

Questo deployment include:

• Due siti web, uno per FoxIDs e uno per FoxIDs Control, admin Client e API, in due docker images www.foxids.com/foxids:x.x.x e www.foxids.com/foxidscontrol:x.x.x.
• I due siti web sono esposti su due domains differenti protetti con certificati Let's Encrypt generati automaticamente.
• MongoDB e un database NoSQL e contiene tutti i dati inclusi tenant, ambienti e utenti. Distribuito con la official MongoDB Docker image. Puoi facoltativamente usare una tua istanza PostgreSQL invece di MongoDB.
• Per impostazione predefinita la cache viene archiviata nel database configurato. Redis è necessario solo se esegui un cluster FoxIDs ad alto throughput con PostgreSQL. MongoDB ha una cache integrata che offre buone prestazioni quando l'istanza MongoDB ha memoria sufficiente. La cache FoxIDs mantiene sequenze, ad esempio login e logout, gestisce contatori per proteggere l'autenticazione da vari attacchi e data cache, solo Redis, per migliorare le prestazioni. Redis viene distribuito con la official Redis Docker image.
• I log vengono scritti su stdout, dove Kubernetes puo raccoglierli. Si consiglia di usare OpenSearch per il logging, a meno che l’installazione FoxIDs sia piccola. Con OpenSearch, errori, eventi e trace possono essere visualizzati direttamente in FoxIDs Control Client oltre che nel log Kubernetes, rendendo molto piu semplice amministrare il sistema.

Deployment

Il deployment viene eseguito nell'ordine descritto.

Get ready

Scarica i file di configurazione Kubernetes yaml qui e mettili in una cartella sulla tua macchina, ad esempio C:\FoxIDs\Kubernetes.

Apri una console e vai alla cartella Kubernetes.

Namespace

Questa guida usa in generale il namespace foxids; valuta di cambiarlo in base al tuo ambiente kubernetes.

Crea il namespace

kubectl create namespace foxids

Persistent volumes

Hai bisogno di persistent volumes per MongoDB, facoltativamente OpenSearch e facoltativamente Redis se usi Redis con PostgreSQL per un cluster FoxIDs ad alto throughput.

In un cluster Kubernetes usa o crea persistent volumes adatti e crea una persistent volume claim con nome mongo-data-pvc per MongoDB e facoltativamente una per Redis con nome redis-data-pvc.

Potresti essere in grado di usare dynamic storage provisioning con StorageClass.

Crea la persistent volume claim per Mongo

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

Facoltativamente crea la persistent volume claim per Redis

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

Facoltativamente crea la persistent volume claim per OpenSearch

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

Kubernetes in Docker Desktop

Se stai usando Kubernetes in Docker Desktop puoi creare persistent volumes nel file system host, non raccomandato per la produzione.

Crea il persistent volume per MongoDB

kubectl apply -f mongo-pv-dockerdesktop.yaml

Crea la persistent volume claim per MongoDB

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

Facoltativamente crea il persistent volume per Redis

kubectl apply -f redis-pv-dockerdesktop.yaml

Facoltativamente crea la persistent volume claim per Redis

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

Facoltativamente crea il persistent volume per OpenSearch

kubectl apply -f opensearch-pv-dockerdesktop.yaml

Facoltativamente crea la persistent volume claim per OpenSearch

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

MongoDB

Cambia username e password per MongoDB in mongo-secret.yaml. Username e password sono codificati in base64.

Puoi codificare in base64 "the text" in un command prompt, a seconda della tua piattaforma:

Windows

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

Linux / Mac

echo -n "the text" | base64

Aggiungi il secret MongoDB

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

Crea MongoDB
Facoltativamente esponi MongoDB sulla porta 27017 rimuovendo il commento da LoadBalancer

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

Aggiungi una ConfigMap per il servizio MongoDB

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

Optionally use PostgreSQL instead of MongoDB

Cambia il valore username in postgres-username e il valore password in postgres-password per farli corrispondere alla tua istanza PostgreSQL in postgres-secret.yaml. Username e password sono codificati in base64.

Aggiungi il secret PostgreSQL

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

Cambia l'endpoint database PostgreSQL in postgres-db per farlo corrispondere alla tua istanza PostgreSQL in postgres-configmap.yaml

Aggiungi una ConfigMap per il servizio PostgreSQL

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

Optionally use Redis

Redis è necessario solo se usi PostgreSQL ed esegui un cluster FoxIDs ad alto throughput. Se usi MongoDB, la cache integrata di MongoDB offre buone prestazioni quando l'istanza MongoDB ha memoria sufficiente.

Facoltativamente crea Redis

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

Facoltativamente aggiungi una ConfigMap per il servizio Redis

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

Optionally use OpenSearch

OpenSearch è consigliato per il logging, a meno che l’installazione FoxIDs sia piccola. Una piccola installazione può funzionare solo con logging Stdout, dove Kubernetes raccoglie i log. Con OpenSearch, errori, eventi e trace possono anche essere cercati direttamente in FoxIDs Control Client, rendendo molto piu semplice amministrare il sistema.

Cambia la password di OpenSearch in opensearch-secret.yaml. La password è codificata in base64.

Aggiungi il secret OpenSearch

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

Crea OpenSearch

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

Aggiungi una ConfigMap per il servizio OpenSearch

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

FoxIDs websites

Domains
I due siti web FoxIDs sono configurati per usare due domains che crei e gestisci nel tuo DNS. Configura il file foxids-deployment.yaml con i domains scelti:

• Il domain del sito FoxIDs https://id.itfoxtec.com, due punti nel file, viene cambiato nel tuo domain - id.my-domain.com
• Il domain del sito FoxIDs Control https://control.itfoxtec.com viene cambiato nel tuo domain - control.my-domain.com

Email provider
Facoltativamente puoi configurare un email provider globale oppure piu tardi configurare email providers per ambiente. FoxIDs supporta l'invio di email con SendGrid e SMTP. Puoi anche configurare provider SMS globalmente o per ambiente.

Il global email provider viene configurato nel file foxids-deployment.yaml sul container, pod, foxids nella sezione env:. Questo esempio mostra come aggiungere Outlook / Microsoft 365 con 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
Cambia la configurazione di database e cache in foxids-deployment.yaml, due punti nel file.

Seleziona PostgreSQL come database invece di MongoDb

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

Seleziona PostgreSQL come cache invece di MongoDb, a meno che tu non stia usando Redis

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

Rimuovi il commento dalla configurazione di accesso 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
Cambia la configurazione cache in foxids-deployment.yaml, due punti nel file.

Seleziona Redis come cache invece di MongoDb

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

Facoltativamente memorizza nella cache Redis i dati del database

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

Rimuovi il commento dalla configurazione di accesso 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 Cambia la configurazione log in foxids-deployment.yaml, due punti nel file.

Seleziona OpenSearch logging invece di Stdout

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

Rimuovi il commento dalla configurazione di accesso 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 invia i log a OpenSearch e scrive gli errori su stdout, quindi Kubernetes continua a ricevere i log di errore. AllowInsecureCertificates è impostato su true perché il container OpenSearch predefinito usa un certificato self-signed.

Deploy
Imposta lo username al tuo customer ID e la password al tuo pull secret per il FoxIDs Docker registry. Poi crea il 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

Crea i due siti web FoxIDs

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

La configurazione richiede un Nginx controller. Facoltativamente puoi cambiare la configurazione per usare un altro controller.

Prerequisiti:

• Hai installato Helm.
  Installa Helm su Windows con questo comando CMD winget install Helm.Helm

Installa Ingress-Nginx controller con due comandi

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

Facoltativamente verifica l'installazione Ingress-Nginx

kubectl get pod -n ingress-nginx

Se riprovi tra qualche minuto dovresti ottenere un EXTERNAL-IP

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

I record DNS verso i due domains devono puntare all'indirizzo IP dell'installazione per abilitare la validazione online di Let's Encrypt.
Il firewall deve accettare richieste sulle porte 80 e 443. Let's encrypt valida la proprieta del dominio sulla porta 80.

Facoltativamente scala Ingress-Nginx controller

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

Installa Cert-manager con due comandi

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

Facoltativamente verifica l'installazione di Cert-manager

kubectl get pods -n cert-manager

Aggiungi la tua email nel file letsencrypt-issuer.yaml, due punti nel file.

Configura Let's Encrypt

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

Il file foxids-ingress-deployment.yaml e configurato con i domains:

• Il domain del sito FoxIDs id.itfoxtec.com, due punti nel file, viene cambiato nel tuo domain - id.my-domain.com
• Il domain del sito FoxIDs Control control.itfoxtec.com, due punti nel file, viene cambiato nel tuo domain - control.my-domain.com

Valuta di iniziare con Let's Encrypt in staging per evitare di raggiungere il production rate limit di Let's Encrypt, i certificati di staging non sono trusted dal browser.
Facoltativamente seleziona staging oppure production nel file foxids-ingress-deployment.yaml; per impostazione predefinita e configurato per production.

Aggiungi ingress con domains associati al certificato

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

Importante! Ingress viene installato con le annotations nginx.ingress.kubernetes.io/proxy-buffers-number: "4" e nginx.ingress.kubernetes.io/proxy-buffer-size: "32k" per supportare SAML 2.0 dove le HTTP responses possono essere piuttosto grandi.

Facoltativamente verifica Ingress

kubectl get ingress -n foxids

Facoltativamente verifica il certificate issuer

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

Facoltativamente controlla se il certificato e pronto, READY dovrebbe essere True

kubectl get certificate -n foxids

E facoltativamente verifica il certificato

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

First login

Apri nel browser il domain del tuo sito FoxIDs Control. Dovrebbe reindirizzare al sito FoxIDs dove esegui il login con l'utente admin predefinito admin@foxids.com e password FirstAccess!, ti viene richiesto di cambiare la password al primo login.
Vieni quindi reindirizzato di nuovo al sito FoxIDs Control nel tenant master. Puoi aggiungere altri utenti admin nel tenant master.

Poi fai clic sul tenant main ed esegui di nuovo l'autenticazione con lo stesso utente admin predefinito admin@foxids.com e password FirstAccess!, anche qui ti viene richiesto di cambiare la password.

L'utente admin predefinito e la password sono gli stessi sia per il tenant master sia per il tenant main, ma sono due utenti differenti.

Ora hai effettuato l'accesso al tenant main e puoi iniziare a configurare le tue applications e i tuoi authentication methods.

Seed data

Il database viene automaticamente inizializzato in base ai domains configurati. Pertanto devi eliminare il database se i domains vengono cambiati.
Per eliminare i dati puoi arrestare il pod del database e cancellare la cartella o i file fisici del database. Oppure esporre l'endpoint del database e aprire il database in MongoDB Compass, download MongoDB Compass Download (GUI), e cancellare il database.
Successivamente il pod FoxIDs Control deve essere riavviato per avviare un nuovo processo di seed.

Opzione avanzata: i domains possono anche essere cambiati manualmente nel database.

Considerations

Questa sezione elenca alcune considerazioni di deployment e sicurezza.

Kubernetes Service Mesh
Si raccomanda di usare un Kubernetes Service Mesh per ottenere una architettura zero-trust, in cui il traffico interno e protetto con mutual TLS, mTLS, e cifratura.

Internal PKI / root CA
Se il traffico interno viene terminato e ricifrato da un proxy o da un service mesh con una internal root CA, configura i container FoxIDs in modo che considerino affidabile quella CA. Vedi Kubernetes internal CA.

Namespace
Questa guida usa in generale il namespace foxids; valuta di cambiarlo in base al tuo ambiente kubernetes.

Crea il namespace

kubectl create namespace test

Elenca i namespaces

kubectl get namespaces

Applica il namespace alla creazione del pod

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

Log
Tutti i log di FoxIDs inclusi errori, trace ed eventi vengono scritti su stdout. Valuta come gestire gli application logs e raccogliere i log dai container.

Rate Limiting
Configura limiti su connessioni e velocita di trasmissione in foxids-ingress-deployment.yaml.

MongoDB Operator
Valuta MongoDB Operator se hai bisogno di piu istanze MongoDB.

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

Redis multiple pods / cluster
Valuta una configurazione Redis scalata se hai bisogno di piu istanze Redis.

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

Backup
Valuta se i dati MongoDB debbano essere sottoposti a backup e a quale livello; ecco tre possibili soluzioni. Si considera meno importante fare il backup di Redis.

1. Eseguire il backup del data store fisico del persistent volume.
2. Backup with a Kubernetes Cron Job.
3. Il backup e supportato in MongoDB Enterprise Kubernetes Operator.

Update

FoxIDs viene aggiornato modificando i tag di versione delle immagini in foxids-deployment.yaml per entrambi i container FoxIDs:

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

Consulta le note di rilascio prima dell'aggiornamento. Le note di rilascio indicano anche la versione corrente dell'immagine Docker. Le nuove release di FoxIDs sono retrocompatibili.

Applica il file di deployment aggiornato:

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

Kubernetes aggiorna quindi i due deployment alle nuove versioni delle immagini.

Allo stesso modo dovrebbe essere possibile aggiornare le immagini MongoDB, Redis e OpenSearch con dati nei persistent volumes.

Useful commands

Questo e un elenco di comandi che possono essere utili durante il deployment per vedere dettagli e apportare modifiche al deployment.

Crea pod

kubectl apply -f xxx.yaml -n foxids

Arresta e rimuovi pod

kubectl delete -f xxx.yaml -n foxids

Elenca pod

kubectl get pods -n foxids

Ottieni la descrizione del pod

kubectl describe pod xxx -n foxids

Ottieni i log del pod

kubectl logs xxx -n foxids

Elenca deployments

kubectl get deployments -n foxids

Elenca services

kubectl get services -n foxids

Elenca secrets

kubectl get secrets -n foxids

Mostra il FoxIDs docker registry secret

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

Elenca persistent volumes

kubectl get pv

Elenca persistent volume claims

kubectl get pvc

Elenca ingress

kubectl get ingress

Descrivi ingress

kubectl describe ingress xxx