MARA: agora em execução em uma estação de trabalho perto de você

Jason Schmidt

Quando começamos a trabalhar no projeto Arquitetura de Referência para Aplicações Modernas da NGINX (MARA), escolhemos a AWS como nosso provedor de IaaS porque já conhecíamos a plataforma e podíamos usar o orçamento do nosso departamento para custeá-la. É claro que nem todos têm a mesma experiência ou o mesmo orçamento, e muitos de vocês nos pediram opções para executar a MARA localmente – em um ambiente de laboratório ou até mesmo em uma estação de trabalho – com distribuições do Kubernetes como K3s, Canonical MicroK8s e minikube.

Atendendo aos seus pedidos, temos o prazer de anunciar que testamos o MARA no MicroK8s e estamos disponibilizando instruções para que você mesmo possa implantá-lo!

Por que escolhemos o MicroK8s para nossos testes? Porque ele oferece os recursos de DNS, armazenamento e saída de rede de que o MARA precisa, em um modelo fácil de implantar e com baixo consumo de memória. Com o MicroK8s, podemos percorrer cenários de teste de forma fácil e repetida para determinar os requisitos mínimos de implantações que ofereçam níveis razoáveis de desempenho.

Esperamos que este trabalho facilite nossos testes de outras distribuições do Kubernetes. Para obter informações sobre o status atual de diversas distribuições, consulte nosso repositório no GitHub. Se você tem uma distribuição favorita que gostaria de ver na lista, convidamos você a criar um fork, testá-la e abrir pull requests!

Como lidar com restrições de recursos

As maiores limitações para executar o MARA localmente são a memória e a CPU. Durante os testes preliminares, constatamos que a maioria dos problemas de esgotamento de memória estava relacionada ao Elasticsearch. O Kibana fica praticamente inutilizável em configurações com uma quantidade extremamente pequena de memória (menos de 16 GB). Para resolver esse problema, disponibilizamos configurações no arquivo de configuração do MARA que eliminam as proteções de redundância normalmente presentes em uma implantação completa do Elasticsearch. Embora isso aumente o número de possíveis modos de falha, trata-se de uma concessão necessária em ambientes com recursos limitados.

As limitações de CPU estão diretamente relacionadas à carga imposta ao nosso aplicativo de exemplo Bank of Sirius. A implantação do MARA inclui o Locust para gerar carga no Bank of Sirius, com configurações controladas pelo usuário para o número de usuários e a taxa de criação de novos usuários.

Observe que aumentar a carga no Bank of Sirius também afeta o restante do sistema. Se o número de usuários ou a taxa de inicialização for muito alto, o desempenho do MARA se degradará a ponto de os componentes provavelmente falharem ou pararem de responder. Os valores que causam esse comportamento dependem da CPU disponível, mas é possível esperar que uma implantação com pelo menos a capacidade especificada em Requisitos seja capaz de processar a carga gerada por até 64 usuários e uma taxa de inicialização de 16 usuários por vez.

Implantação do MARA no MicroK8s

Agora que você já conhece o contexto, está tudo pronto para implantar o MARA no MicroK8s!

Requisitos

• root acesso a um sistema (servidor Linux bare metal, virtualizado ou em nuvem) executando o Ubuntu 20.04 (Focal) ou posterior, com no mínimo:
  • Disco de 20 GB
  • 16 GB de memória
  • O equivalente a 4 CPUs
• Um ambiente virtual do Python 3 no sistema local com todas as bibliotecas e os binários exigidos pelo MARA. Se o Python 3 ainda não estiver instalado, execute estes comandos:

$  sudo apt update$  sudo apt install -y python3-venv

• Pelo menos um endereço IPv4 livre para o balanceador de carga MetalLB integrado do MicroK8s atribuir à saída do NGINX Ingress Controller. Se você estiver acessando o aplicativo Bank of Sirius via localhost, qualquer endereço privado disponível (em conformidade com a RFC 1918) será aceitável. Por exemplo, se a sua rede for 192.168.100.0/24, você poderá usar um endereço como 10.10.10.10.
• Uma conta do Pulumi e um token de acesso. Se você ainda não os tiver, poderá criá-los na Etapa 1 de Implantar o MARA. Observe que, embora o Pulumi permita armazenar o arquivo de estado em um armazenamento de objetos compatível com S3 ou no sistema de arquivos local, o MARA não oferece suporte a essas opções no momento da redação deste texto. Essa limitação será removida em uma versão futura do MARA ou do Pulumi.

Instalar e configurar o MicroK8s

1. Instale o MicroK8s:

$ sudo snap install microk8s --classicmicrok8s (1.23/stable) v1.23.3 from Canonical✓ installed

1. Defina as permissões necessárias para executar os comandos do microk8s. No lugar de <username>, informe sua conta que possui privilégios de root no sistema:

$ sudo usermod -a -G microk8s <username>$ sudo chown -f -R <username> ~/.kube
$ newgrp microk8s

1. Saia da sua conta com privilégios de root e entre novamente para que as novas permissões entrem em vigor.
2. Habilite os complementos do MicroK8s para DNS, armazenamento, e MetalLB. Quando solicitado, especifique um intervalo de endereços IP no formato X.X.X.X‑X.X.X.Y para representar uma destas opções:

$ microk8s enable dns storage metallbEnabling DNS
Applying manifest
...
Restarting kubelet
DNS is enabled
Enabling default storage class
...
Storage will be available soon
Enabling MetalLB
Enter each IP address range delimited by comma (e.g. '10.64.140.43-10.64.140.49,192.168.0.105-192.168.0.111'): 192.168.100.100-192.168.100.110
Applying Metallb manifest
...
MetalLB is enabled

• Um intervalo real de endereços IP privados (por exemplo, 192.168.100.100-192.168.100.110, o valor usado abaixo)
• Um único endereço IP privado (por exemplo, 192.168.100.100-192.168.100.100)

1. Confirme se o MicroK8s está em execução:

$ microk8s statusmicrok8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    dns           # CoreDNS
    ha-cluster    # Configure high availability on the current node
    metallb       # Loadbalancer for your Kubernetes cluster
    storage       # Storage class; allocates storage from host directory
...

1. Carregue a configuração do MicroK8s no arquivo em que a maioria dos utilitários espera encontrá-la (~/.kube/config) e defina as permissões recomendadas para o diretório e o arquivo:

$ microk8s config > ~/.kube/config$ sudo chmod 0644 ~/.kube/config

Clone o repositório do MARA e configure o cluster do MicroK8s

1. Clone o repositório MARA e inicialize o submódulo Bank of Sirius:

$ git clone https://github.com/nginxinc/kic-reference-architectures.git$ cd kic-reference-architectures/
$ git submodule update --init --recursive --remote

1. No diretório raiz do repositório MARA clonado (para o qual você mudou no passo anterior), configure o ambiente virtual do Python para o cluster MicroK8s:

$ ./bin/setup_venv.sh

1. Este comando gera um rastreamento extenso. Se houver erros, consulte a seção Problemas conhecidos/ressalvas no repositório do MARA no GitHub para obter sugestões.
2. Ative o ambiente virtual do Python. O comando configura a variável PATH e outras variáveis de ambiente para usar o ambiente virtual:

$ source ./pulumi/python/venv/bin/activate

1. Confirme se o cluster do MicroK8s está configurado corretamente para a implantação do MARA:

$ ./bin/testcap.sh
This script will perform testing on the current kubernetes installation using the currently active kubernetes configuration and context.
Any failures should be investigated, as they will indicate that the installation does not meet the minimum set of capabilities required to run MARA.

...
==============================================================
| All tests passed! This system meets the basic requirements |
| to deploy MARA.                                            |
==============================================================

Implantar o MARA

O script start.sh, usado nesta seção para implantar o MARA, oferece opções que exigem ações adicionais para que a implantação seja bem-sucedida. Para simplificar, pressupomos aqui uma implantação básica que:

• Usa arquivos kubeconfig em vez de uma das outras opções de implantação compatíveis. Para obter detalhes sobre as outras opções, consulte o Guia de Introdução em nosso repositório do GitHub.
• Usa a versão mais recente do NGINX Open Source com a qual testamos o MARA (não necessariamente a versão mais atual disponível).
• Usa o NGINX Ingress Controller baseado no NGINX Open Source. Se quiser usar o NGINX Ingress Controller baseado no NGINX Plus, você deverá usar uma imagem baseada no NGINX Plus do registro Docker da F5 no seu cluster do Kubernetes. Consulte o primeiro AVISO! na Etapa 3 abaixo para obter mais informações.
• Usa um único contexto padrão do Kubernetes. Consulte o segundo AVISO! na Etapa 3.

Implante o MARA no cluster MicroK8s:

1. Execute o script start.sh. Se você ainda não configurou sua estação de trabalho para usar o Pulumi, será direcionado a fazer login no Pulumi (criando uma conta, se necessário) e, em seguida, será solicitado o token de API associado à sua conta do Pulumi.

$ ./bin/start.shAdding to [/home/ubuntu/kic-reference-architectures/bin/venv/bin] to PATH
Manage your Pulumi stacks by logging in.
Run `pulumi login --help` for alternative login options.
Enter your access token from https://app.pulumi.com/account/tokens
    or hit <ENTER> to log in using your browser            : <token>

Please read the documentation for more details.

1. Selecione o tipo de implantação, digitando k no prompt para criar a implantação com arquivos kubeconfig. Ignore os avisos de que o make e o Docker não estão instalados – em vez disso, a implantação usa uma imagem do NGINX Ingress Controller proveniente de um registro.

Type a for AWS, k for kubeconfig? k
Calling kubeconfig startup script
make is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.
docker is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.

1. Quando solicitado, especifique o nome da stack do Pulumi a ser criada (neste caso, mara). Ele deve ser exclusivo na sua conta do Pulumi.

Enter the name of the Pulumi stack to use in all projects: maraSubmodule source found
Configuring all Pulumi projects to use the stack: mara
Created stack 'mara'

NOTICE! Currently the deployment via kubeconfig only supports pulling images from the registry! A JWT is required in order to access the NGINX Plus repository. This should be placed in a file in the extras directory in the root, in a file named jwt.token

See https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret/ for more details and examples.

No JWT found; writing placeholder manifest

NOTICE! When using a kubeconfig file you need to ensure that your environment is configured to connect to Kubernetes properly. If you have multiple kubernetes contexts (or custom contexts) you may need to remove them and replace them with a simple ~/.kube/config file. This will be addressed in a future release.

1. Quando solicitado, especifique o caminho completo para o arquivo kubeconfig e o nome do cluster. Neste exemplo, eles são /home/<username>/.kube/config e microk8s-cluster.

Provide an absolute path to your kubeconfig filevalue: /home/<username>/.kube/config
Provide your clustername
value: microk8s-cluster
Attempting to connect to kubernetes cluster

1. No próximo prompt, especifique o nome de domínio totalmente qualificado (FQDN) do cluster. O script usa o FQDN para duas finalidades: configurar o NGINX Ingress Controller e criar o certificado autoassinado (a segunda finalidade significa que o valor não pode ser um endereço IP). Se você substituir mara.example.com por outro FQDN, lembre-se de usá-lo também nas etapas a seguir.

Create a fqdn for your deploymentvalue: mara.example.com

1. Especifique a senha de administrador do Grafana:

Create a password for the grafana admin user; this password will be used to access the Grafana dashboardThis should be an alphanumeric string without any shell special characters; it is presented in plain text due to current limitations with Pulumi secrets. You will need this password to access the Grafana dashboard.
value: <password>

Um registro do processo de instalação será exibido, mostrando as seguintes informações para cada etapa:

• Um banner que descreve a principal ação realizada na etapa (por exemplo, Logstore sinaliza o início da implantação do Elasticsearch)
• Uma lista das tarefas que o Pulumi realizará
• Um indicador de status em tempo real para cada tarefa do Pulumi
• Diagnósticos gerados pelo Pulumi e pelo MARA, por exemplo, o nome do host e o endereço IP definidos
• O número de recursos afetados
• O tempo decorrido

Quando a etapa final (do Bank of Sirius) for concluída, o rastreamento informará o endereço IP atribuído ao NGINX Ingress Controller pelo MetalLB (neste caso, 192.168.100.100) e o FQDN escolhido para a implantação (neste caso, mara.example.com), além de outras informações sobre a implantação.

The startup process has finished successfully
Next Steps:
1. Map the IP address (192.168.100.100) of your Ingress Controller with your FQDN (mara.example.com).
2. Use the ./bin/test-forward.sh program to establish tunnels you can use to connect to the management tools.
3. Use kubectl, k9s, or the Kubernetes dashboard to explore your deployment.

To review your configuration options, including the passwords defined, you can access the pulumi secrets via the following commands:

Main Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/config

Bank of Sirius (Example Application) Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/kubernetes/applications/sirius

K8 Loadbalancer IP: kubectl get services --namespace nginx-ingress

Please see the documentation in the github repository for more information

1. Crie um mapeamento entre o FQDN e o endereço IP informados na etapa anterior na ferramenta usada para resolver FQDNs (como o arquivo local /etc/hosts ou o servidor DNS).
2. Verifique se uma solicitação à implantação do MARA é bem-sucedida. Inclua a opção -k para que o curl aceite um certificado autoassinado. Para exibir mais informações sobre o certificado, adicione a opção -v.

$ curl -k -I https://mara.example.comHTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Day, DD Mon YYYY hh:mm:ss TZ
Content-Type: text/html; charset=utf-8
Content-Length: 7016
Connection: keep-alive

1. Acesse em um navegador o endereço https://mara.example.com para exibir o site do Bank of Sirius. No momento da redação deste texto, em muitos navegadores (incluindo Firefox e Safari), você pode ignorar com segurança o aviso exibido sobre o uso de um certificado autoassinado pelo site. Recomendamos que você não use o Chrome, pois, devido a alterações recentes de segurança, ele provavelmente impedirá o acesso ao site.
2. Execute o script test-forward.sh para configurar o encaminhamento de portas do Kubernetes e acessar as ferramentas do pacote de gerenciamento MARA – Elasticsearch, Grafana, Kibana, Locust e Prometheus. O script identifica os nomes de serviço apropriados e executa comandos kubectl para encaminhá-los às portas locais. Observação: Para que o encaminhamento de portas funcione corretamente, o navegador deve estar em execução no mesmo sistema que o shell de comando no qual você executa esse comando. Caso contrário (por exemplo, se você estiver usando um ambiente de virtualização), o comando parecerá ser executado com sucesso, mas o encaminhamento de portas não funcionará de fato. Para obter mais informações, consulte Como acessar as ferramentas de gerenciamento no MARA em nosso repositório do GitHub.

$ ./bin/test-forward.shConnections Details
====================================
Kibana:        http://localhost:5601
Grafana:       http://localhost:3000
Locust:        http://localhost:8089
Prometheus:    http://localhost:9090
Elasticsearch: http://localhost:9200
====================================

Issue Ctrl-C to Exit

Resumo

É isso! Com estas instruções, uma implantação funcional do MARA estará em execução no seu ambiente em cerca de 20 minutos. A partir daí, você poderá interagir com o aplicativo Bank of Sirius como faria com qualquer outro aplicativo Kubernetes. Um bom ponto de partida é usar as ferramentas de observabilidade integradas para testar como o ambiente se comporta à medida que você gera diferentes níveis de carga com o Locust.

Nosso objetivo é tornar o MARA o mais útil possível para o maior número possível de usuários do Kubernetes. Não gostou das escolhas que fizemos para alguns dos componentes? Recomendamos que você os substitua pelos componentes de sua preferência e abra uma solicitação de pull caso queira compartilhar. Além disso, compartilhe suas ideias e faça perguntas — inclusive sobre quaisquer suposições questionáveis que tenhamos feito — nas páginas de Issues e Discussions do nosso repositório.

Posts relacionados

Este post faz parte de uma série. À medida que adicionamos novos recursos ao MARA, publicamos os detalhes no blog:

• Uma nova arquitetura de referência de código aberto para aplicações modernas
• Integração do OpenTelemetry à arquitetura de referência para aplicações modernas – um relatório de progresso
• MARA: agora em execução em uma estação de trabalho perto de você (esta publicação)
• Anunciando a versão 1.0.0 da Arquitetura de Referência para Aplicações Modernas da NGINX

Sobre o autor

Jason Schmidt

Mais publicações de Jason Schmidt