MARA: 이제 가까운 워크스테이션에서 실행됩니다

NGINX | 2022년 4월 22일

저희가 NGINX 최신 앱 참조 아키텍처(MARA) 프로젝트 작업을 시작했을 때, 이미 플랫폼에 익숙했고 부서 예산으로 비용을 지불할 수 있었기 때문에 AWS를 IaaS 공급자로 선택했습니다. 물론 모든 사람이 동일한 경험이나 예산을 갖고 있는 것은 아니며, 많은 분이 K3s, Canonical MicroK8s, minikube와 같은 Kubernetes 배포판을 사용하여 실습 환경이나 워크스테이션에서 MARA를 로컬로 실행할 수 있는 옵션을 제공해 달라고 요청하셨습니다.

여러분의 요청에 따라 MARA를 MicroK8s에서 테스트했으며, 직접 배포할 수 있도록 안내를 제공하게 되어 기쁘게 생각합니다!

워크스테이션에서 실행되는 NGINX Modern Apps Reference Architecture의 토폴로지를 보여주는 다이어그램

테스트에 MicroK8s를 선택한 이유는 무엇일까요? 메모리 사용량이 적고 배포가 간편한 모델로 MARA에 필요한 DNS, 스토리지 및 이그레스 기능을 제공하기 때문입니다. MicroK8s를 사용하면 테스트 시나리오를 쉽고 반복적으로 수행하여 적정 수준의 성능을 제공하는 배포에 필요한 최소 요구 사항을 파악할 수 있습니다.

이 작업을 통해 다른 Kubernetes 배포판을 더 쉽게 테스트할 수 있을 것으로 기대합니다. 다양한 배포판의 현재 상태에 대한 자세한 내용은 GitHub 리포지토리를 참조하세요. 목록에 추가되기를 원하는 배포판이 있다면 포크하고 테스트한 후 풀 리퀘스트를 보내 주세요!

리소스 제약 조건 처리

MARA를 로컬에서 실행할 때 가장 큰 제약 요인은 메모리와 CPU입니다. 예비 테스트 결과, 메모리 부족 문제의 대부분이 Elasticsearch와 관련된 것으로 나타났습니다. 메모리가 극히 적은 구성(16GB 미만)에서는 Kibana를 거의 사용할 수 없습니다. 이 문제를 해결하기 위해 MARA 구성 파일에 일반적인 전체 Elasticsearch 배포 환경의 중복 보호 기능을 제거하는 설정을 제공했습니다. 이로 인해 장애 발생 가능성은 늘어나지만, 리소스가 제한된 환경에서는 불가피한 절충안입니다.

CPU 제약은 샘플 Bank of Sirius 애플리케이션에 가해지는 부하량과 직접적인 관련이 있습니다. MARA 배포에는 Locust가 포함되어 있어 Bank of Sirius에 부하를 생성할 수 있으며, 사용자가 사용자 수와 신규 사용자 생성 속도를 설정할 수 있습니다.

Bank of Sirius의 부하를 늘리면 시스템의 나머지 부분에도 영향을 미친다는 점에 유의하세요. 사용자 수나 사용자 생성 속도가 너무 높으면 MARA의 성능이 저하되어 구성 요소가 충돌하거나 멈출 수 있습니다. 이러한 현상을 일으키는 값은 사용 가능한 CPU에 따라 달라지지만, 요구사항에 명시된 용량 이상으로 배포하면 최대 64명의 사용자와 한 번에 16명의 사용자 생성 속도로 발생하는 부하를 처리할 수 있습니다.

MicroK8s에 MARA 배포하기

이제 배경 설명은 마쳤으니, MicroK8s에 MARA를 구축할 준비가 되었습니다!

요구 사항

root 권한이 있고 Ubuntu 20.04(Focal) 이상을 실행하는 시스템(베어메탈 Linux 서버, 가상화 환경 또는 클라우드). 최소 사양은 다음과 같습니다:
- 20GB 디스크
- 16GB 메모리
- CPU 4개에 해당하는 성능
로컬 시스템에 MARA에 필요한 모든 라이브러리와 바이너리가 포함된 Python 3 가상 환경이 있어야 합니다. Python 3가 아직 설치되어 있지 않다면 다음 명령을 실행하세요:

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

NGINX Ingress Controller의 송신 트래픽에 할당할 수 있도록 MicroK8s에 통합된 MetalLB 로드 밸런서용 미사용 IPv4 주소가 하나 이상 필요합니다. localhost를 통해 Bank of Sirius 애플리케이션에 액세스하는 경우, 사용 가능한 사설(RFC 1918 준수) 주소라면 무엇이든 사용할 수 있습니다. 예를 들어 네트워크가 192.168.100.0/24인 경우 10.10.10.10과 같은 주소를 사용할 수 있습니다.
Pulumi 계정과 액세스 토큰이 필요합니다. 아직 없다면 1단계에서 생성합니다. 자세한 내용은 MARA 배포를 참조하세요. Pulumi에서는 상태 파일을 S3 호환 객체 스토리지나 로컬 파일 시스템에 저장할 수 있지만, 이 글을 작성하는 시점에는 MARA에서 이를 지원하지 않습니다. 이 제한은 향후 MARA 또는 Pulumi 릴리스에서 제거될 예정입니다.

MicroK8s 설치 및 구성

MicroK8s를 설치합니다:

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

Set the necessary permissions for running microk8s 명령어를 실행하는 데 필요한 권한을 설정합니다. <username>에는 시스템에서 root 권한이 있는 계정을 입력합니다:

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

새 권한이 적용되도록 루트 권한이 있는 계정에서 로그아웃한 후 다시 로그인합니다.
MicroK8s의 다음 애드온을 활성화합니다: DNS, 스토리지, MetalLB. 프롬프트가 표시되면 다음 형식의 IP 주소 범위를 지정하여 X.X.X.X‑X.X.X.Y 다음 중 하나를 나타냅니다:

$ 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

실제 사설 IP 주소 범위(예: 192.168.100.100-192.168.100.110, 아래에서 사용하는 값)
단일 사설 IP 주소(예: 192.168.100.100-192.168.100.100)

MicroK8s가 실행 중인지 확인합니다:

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

MicroK8s 구성을 대부분의 유틸리티가 찾을 것으로 예상하는 파일(~/.kube/config)에 로드하고 디렉터리와 파일에 권장 권한을 설정합니다:

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

MARA 리포지토리를 복제하고 MicroK8s 클러스터 설정하기

MARA 리포지토리를 복제하고 Bank of Sirius 하위 모듈을 초기화합니다:

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

복제한 MARA 리포지토리의 루트 디렉터리에서(이전 단계에서 해당 디렉터리로 이동했습니다) MicroK8s 클러스터용 Python 가상 환경을 설정합니다:

$ ./bin/setup_venv.sh

이 명령은 긴 추적 로그를 생성합니다. 오류가 발생하면 MARA GitHub 저장소의 알려진 문제/주의 사항 섹션에서 해결 방법을 확인하세요.
Python 가상 환경을 활성화합니다. 이 명령은 가상 환경을 사용하도록 PATH 및 기타 환경 변수를 설정합니다:

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

MicroK8s 클러스터가 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.                                            |
==============================================================

MARA 배포

이 섹션에서 MARA를 배포하는 데 사용하는 start.sh 스크립트는 배포를 성공적으로 완료하기 위해 추가 작업이 필요한 옵션을 지원합니다. 여기서는 설명을 간소화하기 위해 다음과 같은 기본 배포를 가정합니다:

지원되는 다른 배포 옵션 대신 kubeconfig 파일을 사용합니다. 다른 옵션에 대한 자세한 내용은 GitHub 리포지토리의 시작 가이드를 참조하세요.
MARA 테스트를 완료한 NGINX Open Source의 최신 버전을 사용합니다(반드시 가장 최근에 출시된 버전인 것은 아닙니다).
NGINX Open Source 기반 NGINX Ingress Controller를 사용합니다. NGINX Plus 기반 NGINX Ingress Controller를 사용하려면 Kubernetes 클러스터에서 F5 Docker 레지스트리의 NGINX Plus 기반 이미지를 사용해야 합니다. 자세한 내용은 아래 주의!(첫 번째) 3단계를 참조하세요.
단일 표준 Kubernetes 컨텍스트를 사용합니다. 3단계의 두 번째 주의!를 참조하세요.

MicroK8s 클러스터에 MARA를 배포합니다:

Run the start.sh 스크립트를 실행합니다. 워크스테이션에서 Pulumi를 사용하도록 아직 구성하지 않았다면 Pulumi에 로그인하라는 안내가 표시됩니다. 필요한 경우 계정을 생성한 후 Pulumi 계정과 연결된 API 토큰을 입력하라는 메시지가 표시됩니다.

$ ./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.

배포 유형을 선택하고, 프롬프트에 k를 입력하여 kubeconfig 파일로 배포를 빌드합니다. make와 Docker가 설치되어 있지 않다는 경고는 무시하세요. 이 배포에서는 그 대신 레지스트리의 NGINX Ingress Controller 이미지를 사용합니다.

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.

프롬프트에서 생성할 Pulumi 스택의 이름(여기서는 mara)을 지정합니다. 이 이름은 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.

프롬프트가 표시되면 kubeconfig 파일의 전체 경로와 클러스터 이름을 지정합니다. 여기서는 각각 /home/<username>/.kube/config 및 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

다음 프롬프트에서 클러스터의 FQDN(정규화된 도메인 이름)을 지정합니다. 스크립트는 FQDN을 NGINX Ingress Controller 구성과 자체 서명 인증서 생성이라는 두 가지 용도로 사용합니다. 두 번째 용도 때문에 이 값에는 IP 주소를 사용할 수 없습니다. mara.example.com 대신 다른 FQDN을 사용하는 경우 다음 단계에서도 해당 FQDN을 사용해야 합니다.

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

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>

설치 과정의 추적 로그가 표시되며, 각 단계에 대해 다음 정보가 제공됩니다:

단계에서 수행되는 주요 작업을 설명하는 배너(예: Logstore는 Elasticsearch 배포 시작을 나타냄)
Pulumi가 수행할 작업 목록
각 Pulumi 작업의 실시간 상태 표시기
Pulumi 및 MARA에서 생성된 진단 정보(예: 정의된 호스트 이름 및 IP 주소)
영향을 받는 리소스 수
경과 시간

마지막 단계(Bank of Sirius 관련)가 완료되면 추적 결과에 MetalLB가 NGINX Ingress Controller에 할당한 IP 주소(여기서는 192.168.100.100)와 배포에 사용하도록 선택한 FQDN(여기서는 mara.example.com)을 비롯한 기타 배포 정보가 표시됩니다.

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

이전 단계에서 확인한 FQDN과 IP 주소 간의 매핑을 FQDN 확인에 사용하는 도구(예: 로컬 /etc/hosts 파일 또는 DNS 서버)에 생성합니다.
MARA 배포에 대한 요청이 성공하는지 확인합니다. -k 옵션을 포함하여 curl이 자체 서명 인증서를 허용하도록 합니다. 인증서에 대한 자세한 정보를 표시하려면 -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

브라우저에서 https://mara.example.com(으)로 이동하여 Bank of Sirius 웹사이트를 표시합니다. 이 글을 작성하는 시점에는 Firefox와 Safari를 비롯한 여러 브라우저에서 자체 서명 인증서를 사용하는 사이트라는 경고가 표시되더라도 안전하게 계속 진행할 수 있습니다. Chrome은 사용하지 않는 것이 좋습니다. 최근 보안 변경으로 인해 사이트 접속이 차단될 가능성이 높기 때문입니다.
Run the test-forward.sh 스크립트를 실행하여 Kubernetes 포트 포워딩을 설정하면 MARA 관리 제품군의 도구인 Elasticsearch, Grafana, Kibana, Locust, Prometheus에 액세스할 수 있습니다. 이 스크립트는 적절한 서비스 이름을 확인하고 kubectl 명령을 실행하여 해당 서비스를 로컬 포트로 포워딩합니다. 참고: 포트 포워딩이 제대로 작동하려면 이 명령을 실행하는 명령 셸과 동일한 시스템에서 브라우저가 실행되고 있어야 합니다. 그렇지 않은 경우(예: 가상화 환경을 사용하는 경우) 명령이 성공한 것처럼 보이지만 실제로는 포트 포워딩이 작동하지 않습니다. 자세한 내용은 GitHub 리포지토리의 MARA에서 관리 도구에 액세스하기를 참조하세요.

$ ./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

요약

이것으로 끝입니다! 이 안내에 따라 약 20분이면 환경에 정상적으로 작동하는 MARA 배포를 구축하고 실행할 수 있습니다. 이제 다른 Kubernetes 애플리케이션과 마찬가지로 Bank of Sirius 애플리케이션을 사용할 수 있습니다. 먼저 기본 제공되는 관측 가능성 도구를 사용하여 Locust로 다양한 수준의 부하를 생성할 때 환경이 어떻게 동작하는지 테스트해 보세요.

저희의 목표는 최대한 많은 Kubernetes 사용자가 MARA를 최대한 유용하게 활용할 수 있도록 하는 것입니다. 일부 구성 요소에 대한 저희의 선택이 마음에 들지 않으시나요? 여러분의 구성 요소로 교체해 보시고, 이를 공유하고 싶다면 풀 리퀘스트를 생성해 주세요 또한 저희가 세운 의문스러운 가정에 대한 내용을 포함해 의견을 공유하고 질문이 있다면 저희 리포지토리의 이슈 및 토론 페이지에 남겨 주세요.