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

Quando começamos a trabalhar no projeto NGINX Modern Apps Reference Architecture (MARA), escolhemos a AWS como nosso provedor de IaaS porque já estávamos familiarizados com a plataforma e poderíamos usar nosso orçamento departamental para pagar por ela. Nem todo mundo tem a mesma experiência ou orçamento, é claro, e muitos de vocês nos pediram para fornecer opções para executar o MARA localmente – em um ambiente de laboratório ou mesmo em uma estação de trabalho – com distribuições Kubernetes como K3s , Canonical MicroK8s e minikube .

Ouvimos você e hoje temos o prazer de anunciar que testamos o MARA no MicroK8s e estamos fornecendo instruções para que você mesmo possa implantá-lo!

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

Nossa expectativa é que esse trabalho facilite nossos testes de outras distribuições do Kubernetes; para obter informações sobre o status atual de várias distribuições, consulte nosso repositório no GitHub . Se você tiver uma distribuição favorita que queira ver na lista, convidamos você a bifurcar, testar e criar solicitações de pull!

Lidando com Restrições de Recursos

As maiores restrições para executar o MARA localmente são memória e CPU. Durante os testes preliminares, descobrimos que a maior parte dos problemas com exaustão de memória diziam respeito ao Elasticsearch. O Kibana é quase inutilizável em configurações com uma quantidade extremamente pequena de memória (menos de 16 GB ). Para resolver esse problema, fornecemos configurações no arquivo de configuração MARA que eliminam as proteções de redundância que uma implantação completa do Elasticsearch normalmente tem. Embora isso aumente o número de modos de falha, é uma compensação necessária em ambientes com recursos limitados.

Restrições na CPU estão diretamente ligadas à quantidade de carga imposta em 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 geração de novos usuários.

Observe que aumentar a carga no Bank of Sirius também afeta o resto do sistema. Se a contagem de usuários ou a taxa de geração for muito alta, o desempenho do MARA será reduzido a ponto de os componentes provavelmente travarem ou paralisarem. Os valores que causam esse comportamento dependem da CPU disponível, mas você pode esperar uma implantação com pelo menos a capacidade especificada em Requisitos para lidar com a carga criada por até 64 usuários e uma taxa de abrangência de 16 usuários por vez.

Implementando MARA em MicroK8s

Com esse pano de fundo resolvido, você está pronto para montar MARA no MicroK8s!

Requisitos

• acesso root em um sistema (servidor Linux bare-metal, virtualizado ou nuvem) executando 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 Python 3 no sistema local com todas as bibliotecas e binários necessários 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 para atribuir à saída do NGINX Ingress Controller. Se você estiver acessando o aplicativo Bank of Sirius via localhost, qualquer endereço privado disponível (compatível com RFC 1918 ) será aceitável. Por exemplo, se sua rede for 192.168.100.0/24, você pode usar um endereço como 10.10.10.10.

• Uma conta Pulumi e token de acesso. Se você ainda não os tiver, você os criará na Etapa 1 de Implantar MARA .

  Observe que, embora o Pulumi permita que você armazene 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 isso no momento da redação deste artigo. Essa limitação será removida em uma versão futura do MARA ou Pulumi.

Instalar e configurar o MicroK8s

1. Instalar MicroK8s:

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

2. Defina as permissões necessárias para executar comandos microk8s . Para <nome de usuário>, substitua sua conta que tem raiz privilégio no sistema:

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

3. Saia da sua conta com privilégios de root e entre novamente para que as novas permissões entrem em vigor.

4. Habilite os complementos MicroK8s para DNS , armazenamento e MetalLB .

   No prompt, especifique um intervalo de endereços IP no formato X . X . X . X ‑ X . X . X . Y para representar:

   • 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 )

   $ 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

5. 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
   ...

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

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

Clone o repositório MARA e configure o cluster 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

2. Trabalhando no diretório raiz do repositório MARA clonado (você alterou o diretório lá na etapa anterior), configure o ambiente virtual Python para o cluster MicroK8s:

   $ ./bin/setup_venv.sh

   Este comando gera um rastreamento longo. Se houver erros, verifique a seção Problemas conhecidos/Advertências no repositório MARA GitHub para obter sugestões.

3. Ative o ambiente virtual Python. O comando define seu PATH e outras variáveis de ambiente para usar o ambiente virtual:

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

4. Confirme se o cluster MicroK8s está configurado corretamente para a implantação 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 MARA

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

• Usa arquivos kubeconfig em vez de uma das outras opções de implantação suportadas. Para obter detalhes sobre as outras opções, consulte o Guia de primeiros passos em nosso repositório GitHub.
• Usa a versão mais recente do NGINX Open Source com a qual testamos o MARA (não necessariamente a versão mais recente).
• Usa o NGINX Ingress Controller baseado no NGINX Open Source. Se você quiser usar o NGINX Ingress Controller baseado no NGINX Plus, deverá usar uma imagem baseada no NGINX Plus do registro do F5 Docker no seu cluster Kubernetes. Veja o primeiro AVISO! na Etapa 3 abaixo para mais informações.
• Usa um único contexto padrão do Kubernetes. Veja o segundo AVISO! no Passo 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, você será direcionado a efetuar login no Pulumi (criando uma conta, se necessário) e então será solicitado o token de API associado à sua conta 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.

2. Selecione o tipo de implantação, digitando k no prompt para construir a implantação com arquivos kubeconfig. Ignore os avisos sobre o make e o Docker não estarem instalados – a implantação usa uma imagem do NGINX Ingress Controller 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.

3. No prompt, especifique o nome da pilha Pulumi a ser criada (aqui, mara ). Deve ser exclusivo na sua conta 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.

4. Nos prompts, especifique o caminho completo para o arquivo kubeconfig e o nome do cluster. Aqui estão eles /lar/<nome de usuário>/.kube/config e microk8s-agrupamento.

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

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

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

6. Especifique a senha do 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 rastreamento do processo de instalação é exibido, exibindo as seguintes informações para cada etapa:

• Um banner descrevendo a ação principal realizada na etapa (por exemplo, o Logstore sinaliza o início da implantação do Elasticsearch)
• Uma lista das tarefas que Pulumi irá realizar
• Um indicador de status em tempo real para cada tarefa Pulumi
• Diagnósticos gerados por Pulumi e 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 (para o Bank of Sirius) for concluída, o rastreamento relatará o endereço IP atribuído ao NGINX Ingress Controller pelo MetalLB (aqui192.168.100.100 ) e o FQDN que você escolheu para a implantação (aqui mara.example.com ), juntamente com 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

7. Crie um mapeamento entre o FQDN e o endereço IP relatados na etapa anterior, na ferramenta que você usa para resolver FQDNs (como o arquivo local /etc/hosts ou o servidor DNS).

8. Verifique se uma solicitação para a implantação MARA foi 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

9. Navegue em um navegador até https://mara.example.com para exibir o site do Bank of Sirius. No momento em que este artigo foi escrito, com muitos navegadores (incluindo Firefox e Safari), você pode clicar com segurança no aviso que aparece sobre o site usando um certificado autoassinado. Recomendamos que você não use o Chrome – devido às recentes mudanças de segurança, é provável que ele proíba você de acessar o site.

10. Execute o script test-forward.sh para configurar o encaminhamento de porta do Kubernetes para que você possa acessar as ferramentas no pacote de gerenciamento MARA – Elasticsearch , Grafana , Kibana , Locust e Prometheus . O script determina os nomes de serviço apropriados e executa comandos kubectl para encaminhá-los para portas locais.

    Observação:  Para que o encaminhamento de porta funcione corretamente, seu navegador deve estar sendo executado no mesmo sistema que o shell de comando onde você executa este comando. Caso contrário (porque você está usando um ambiente de virtualização, por exemplo), o comando parece ter sucesso, mas o encaminhamento de porta não funciona. Para obter mais informações, consulte Acessando 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 essas instruções, uma implantação MARA funcional estará pronta e funcionando em seu ambiente em cerca de 20 minutos. Neste ponto, você pode interagir com o aplicativo Bank of Sirius como qualquer outro aplicativo Kubernetes. Um bom lugar para começar é usar as ferramentas de observabilidade integradas para testar como o ambiente se comporta à medida que você gera diferentes quantidades 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ê substitua seus componentes e abra uma solicitação de pull se quiser compartilhar. Além disso, compartilhe suas ideias e faça perguntas — inclusive sobre quaisquer suposições questionáveis que fizemos — nas páginas de Problemas e Discussões em nosso repositório.

Postagens relacionadas

Esta postagem faz parte de uma série. À medida que adicionamos recursos ao MARA ao longo do tempo, publicamos os detalhes no blog:

• Uma nova arquitetura de referência de aplicativos modernos de código aberto
• Integrando OpenTelemetry na Arquitetura de Referência de Aplicativos Modernos – Um Relatório de Progresso
• MARA: Agora em execução em uma estação de trabalho perto de você (esta postagem)
• Anunciando a versão 1.0.0 da arquitetura de referência de aplicativos modernos do NGINX