hs-note

AI 에이전트 프레임워크 선택 가이드: 목적별 추천과 학습 경로

jerymy — Mon, 15 Sep 2025 13:32:12 +0900

AI 에이전트 프레임워크 심층 분석: Crew AI, Autogen, OpenAI Agents SDK, Google ADK, Langraph 비교

서론: 왜 지금 AI 에이전트 프레임워크인가?

AI 에이전트는 단순한 대화형 챗봇을 넘어 도구 활용, 의사결정, 멀티 스텝 태스크 수행까지 가능하게 하며 차세대 애플리케이션 개발의 핵심 축으로 떠오르고 있습니다.
하지만 아직 이 시장은 표준화되지 않았습니다. 어떤 프레임워크가 ‘정답’이라고 하기 어려운 상황에서, 여러 솔루션의 특징과 한계를 이해하고 적재적소에 활용하는 능력이 중요합니다.

이번 글에서는 대표적인 5대 프레임워크(Crew AI, Autogen, OpenAI Agents SDK, Google ADK, Langraph)를 심층 분석해, 누구에게 어떤 프레임워크가 적합한지 가이드라인을 제시합니다.

1. Crew AI: 빠른 프로토타이핑의 최강자

키워드: 해커톤, 아이디어 검증, 최소 마찰

특징: “에이전트 + 도구 + 작업”을 블록처럼 조합. 프롬프트 중심 개발.
장점: 20분 안에 작동하는 에이전트 팀을 만들 수 있을 정도로 간단. POC(개념 증명)과 데모에 최적화.
단점: 구조적 유연성이 부족해 틀을 벗어난 시도를 하려면 난관 봉착. 내부 동작이 ‘마법’처럼 숨겨져 있어 커스터마이징이 어려움.
추천 사용처: 빠른 시연, 투자자 대상 데모, 내부 아이디어 검증.

2. Autogen (Microsoft): 닷넷 개발자를 위한 사실상 유일한 선택지

키워드: 그룹 채팅 아키텍처, C# 친화적, 초기 선구자

특징: 에이전트를 채팅방 참가자처럼 연결. Python뿐만 아니라 .NET 환경을 지원하는 거의 유일한 프레임워크.
장점: Microsoft 기술 스택(C#)과의 자연스러운 통합. 2023년 선구자로 자리잡음.
단점: 구식 아키텍처 느낌. Studio는 버그가 많고, Core API는 과도하게 복잡. 그룹 채팅 패턴에 종속됨.
추천 사용처: .NET 생태계 기반 프로젝트. (Python 중심 프로젝트라면 다른 대안을 고려하는 편이 현명)

3. OpenAI Agents SDK: 프로덕션 배포에 최적화된 툴킷

키워드: 생산 준비, 음성 지원, OpenAI 통합

특징: 계층적 구조(메인 에이전트 ↔ 서브 에이전트). 가드레일, 메모리, 로깅, 관찰 가능성 등 운영 환경 필수 기능 내장.
장점: OpenAI 모델과 완벽히 통합. 웹 검색, 코드 실행 등 호스팅 도구를 단 한 줄 코드로 활성화 가능. Python/TypeScript 지원.
단점: OpenAI 생태계 종속성. 아키텍처 패턴이 고정적(에이전트-서브 에이전트).
추천 사용처: OpenAI 모델 중심의 프로덕션 서비스. 특히 실시간 음성 기반 에이전트 구현.

4. Google ADK: “배터리 포함”형 올인원 솔루션

키워드: 엔터프라이즈, UI 내장, 테스트/배포 편의성

특징: 다양한 프레임워크의 장점을 모아둔 느낌. 내장 웹 UI, 테스트 자동화, REST API 변환, Google Cloud와 원활한 통합.
장점: 엔터프라이즈 수준의 안정성. Vertex AI 기반 완전 관리형 배포 가능. 다양한 모델 및 100+ 커넥터 지원.
단점: 프레임워크 규모가 크고 학습 곡선이 있음. Google 특유의 “서비스 중단 리스크” 존재.
추천 사용처: Google Cloud 기반 기업 환경. Gemini 모델 및 엔터프라이즈 애플리케이션.

5. Langraph: 자유도와 제어의 끝판왕

키워드: 그래프 기반, 유연성, 고급 사용자

특징: 에이전트 구조를 그래프(노드+엣지)로 표현. 최소한의 런타임만 제공 → 다른 프레임워크는 레고 블록, Langraph는 ‘점토’를 제공.
장점: 사실상 모든 아키텍처 구현 가능. 투명한 동작 관찰 및 상태 관리. 실제 기업(JP Morgan, Uber 등)에서도 활용 중.
단점: 높은 학습 곡선. 초기 개발 속도가 느림. 그래프 사고 방식에 익숙해져야 함.
추천 사용처: 커스텀 아키텍처 구축, 복잡한 대규모 시스템, 독창적 프로젝트.

결론: 어떤 프레임워크를 선택해야 할까?

AI 에이전트 프레임워크 선택은 개발 목적·환경·요구 제어 수준에 따라 달라집니다.
하나의 프레임워크에 묶이는 것은 현명하지 않으며, “framework agnostic” 전략이 필요합니다.

빠른 프로토타이핑 → Crew AI
.NET/C# 기반 개발 → Autogen
OpenAI 모델·음성 기능·프로덕션 배포 → OpenAI Agents SDK
Google Cloud·Gemini·엔터프라이즈 → Google ADK
완전한 제어·커스텀 아키텍처 → Langraph

권장 학습 경로

Crew AI로 시작해 개념을 익힌 후,
OpenAI Agents SDK나 Google ADK로 실제 제품을 만들어보고,
최종적으로 Langraph로 졸업해 복잡한 아키텍처를 직접 설계.

요약 및 결론

AI 에이전트 프레임워크는 아직 승자가 없는 레이스에 가깝습니다. 각 프레임워크가 저마다 강점과 한계를 갖고 있으며, 개발자는 이를 이해하고 목적에 맞는 도구를 선택해야 합니다.

궁극적으로 중요한 것은 “유연하게 배우고 선택할 수 있는 능력”입니다. 다양한 프레임워크 경험은 단일 프레임워크 종속의 위험을 줄이고, 프로젝트 요구사항에 가장 적합한 해답을 찾아낼 수 있는 역량을 키워줄 것입니다.

본 글은 NotebookLM, chatgpt를 활용하여 작성되었습니다.

MCP로 보는 AI 생태계의 미래: 표준화, 확장성, 그리고 에이전트

jerymy — Sat, 23 Aug 2025 21:44:53 +0900

MCP(Model Context Protocol): AI와 세상을 연결하는 새로운 표준

서론: 왜 MCP가 주목받는가?

AI가 점점 더 많은 산업과 일상에 스며들고 있습니다. 그러나 대규모 언어 모델(LLM)은 여전히 몇 가지 한계를 가지고 있습니다.

훈련 데이터에 의존 → 최신 정보 부족
외부 시스템과의 연동 방식 부재 → 실질적 활용 제약
다양한 툴과의 호환성 부족

이런 상황에서 **MCP(Model Context Protocol)**는 AI와 외부 세계를 표준화된 방식으로 연결해주는 새로운 개방형 프로토콜로 떠오르고 있습니다. USB-C가 기기 연결의 범용 표준이 되었듯, MCP는 AI 생태계의 범용 연결 포트 역할을 지향합니다.

MCP란 무엇인가?

**MCP(Model Context Protocol)**는 AI 모델이 외부 데이터 소스 및 다양한 도구와 안전하고 표준화된 방식으로 연결될 수 있도록 하는 개방형 프로토콜입니다.

USB-C 비유: 스마트폰, 노트북, 이어폰을 하나의 케이블로 연결하듯, MCP는 AI가 여러 데이터 소스와 도구를 표준적으로 연결할 수 있게 합니다.
양방향 통신 지원: 기존 REST API처럼 단방향 호출만 하는 것이 아니라, AI와 외부 시스템이 지속적으로 정보를 주고받을 수 있습니다.
개방형 표준: 특정 모델에 종속되지 않고, Claude, ChatGPT, Notion, VS Code 등 다양한 환경에서 사용할 수 있습니다.

왜 MCP가 필요한가?

1. 기존 통합의 비효율성 해결

과거에는 M개의 AI 애플리케이션과 N개의 외부 시스템을 연결하기 위해 M×N 방식의 맞춤형 통합이 필요했습니다.
MCP는 이를 M+N 구조로 단순화하여 통합 복잡성을 크게 줄입니다.

2. 개발 효율성 향상

커스텀 API 연동 대신 MCP 표준을 사용하면 개발자가 새로운 도구를 빠르고 쉽게 연결할 수 있습니다. 이는 비개발자도 손쉽게 AI 기능을 확장할 수 있는 환경을 만듭니다.

3. AI 에이전트 시대의 기반

AI가 자율적으로 업무를 수행하려면 외부 데이터 접근과 시스템 연동이 필수입니다. MCP는 이를 위한 표준 솔루션입니다.

MCP의 아키텍처

MCP는 클라이언트-서버 구조를 기반으로 합니다.

MCP 호스트(Host): 사용자가 직접 접하는 인터페이스 (예: Claude Desktop, VS Code, Notion)
MCP 클라이언트(Client): 호스트 내부에서 MCP 서버와 연결되는 중개자
MCP 서버(Server): 실제 외부 도구·데이터를 노출하는 독립 서비스

서버는 세 가지 요소를 제공합니다.

Tools: 실행 가능한 기능(API 호출, 파일 작업, DB 쿼리 등)
Resources: 읽기 전용 데이터(문서, DB 레코드 등)
Prompts: 모델 동작을 안내하는 템플릿

MCP의 작동 방식

MCP는 JSON-RPC 2.0 기반 프로토콜을 사용합니다.

초기화(Initialize): 클라이언트-서버 간 버전 및 기능 협상
도구 탐색(List): 사용 가능한 도구 목록 확인
도구 실행(Call): LLM이 필요할 때 도구 호출
실시간 알림(Notification): 서버 측 변경 사항을 클라이언트에 푸시

기술적 구현

SDK 지원: Python, TypeScript, Java, Kotlin 등 주요 언어용 SDK 제공
전송 방식:
- Stdio Transport: 로컬 환경에서 고성능 통신
- HTTP Transport: 원격 서버 연결, SSE 기반 실시간 스트리밍, OAuth 인증 지원

활용 사례

개발 환경: Zed, Replit, Sourcegraph → 코드 어시스턴트가 실시간 코드 컨텍스트에 접근
기업 시스템: Block, Apollo → 사내 문서·CRM·지식 베이스 연동
데스크톱 어시스턴트: Claude Desktop → 로컬 파일 요약·검색
멀티툴 에이전트: 다양한 툴을 동시에 활용하는 AI 워크플로우

주요 기업도 빠르게 MCP를 채택 중입니다. OpenAI, Google DeepMind, Anthropic이 대표적이며, MCP 서버 생태계도 빠르게 성장하고 있습니다.

MCP의 장점과 한계

장점

표준화된 상호운용성: 한 번 구현하면 모든 MCP 호환 앱에서 사용 가능
확장성: 새로운 툴을 손쉽게 추가 가능
보안 강화: OAuth 지원, 사용자 승인 기반 접근 제어
개발 효율성: 툴 로직과 AI 앱 로직의 분리

한계

보안 취약점: 개방형 구조의 특성상 공격 표면 확대
초기 진입 장벽: 기존 REST API 대비 복잡한 개념
성능·비용 부담: 다수의 상호작용으로 인한 지연·비용 증가
도구 활용 한계: 연결은 가능하지만 AI가 올바르게 활용하지 못하는 경우 존재

향후 전망

AI 연결 표준으로 성장: USB-C처럼 AI 생태계의 기본 규격이 될 가능성
멀티 에이전트 협업: 여러 AI가 역할을 분담해 복잡한 업무를 처리
새로운 비즈니스 기회: MCP 기반 플랫폼, 마켓플레이스, SaaS 등장
멀티모달 확장: 텍스트뿐 아니라 음성·영상·이미지를 연결하는 허브로 진화

결론

MCP(Model Context Protocol)는 AI가 실시간 데이터와 실제 업무 환경에 연결될 수 있도록 설계된 차세대 개방형 표준입니다.

AI 에이전트 시대를 위한 필수 인프라
개발 효율성과 확장성의 획기적 개선
보안, 생태계 성장, 표준화의 잠재력

MCP는 아직 초기 단계의 도전과제를 안고 있지만, AI와 외부 세계를 연결하는 주요한 방법으로 자리 잡을 가능성이 높습니다.

핵심 키워드: MCP, Model Context Protocol, AI 연결 표준, AI 에이전트, AI 툴 통합, AI 생태계, 표준화 프로토콜

본 글은 NotebookLM, chatgpt를 활용하여 작성되었습니다.

AI 에이전트란 무엇인가: 자율적 인공지능의 현재와 미래

jerymy — Sat, 23 Aug 2025 20:43:41 +0900

AI 에이전트: 자율적 인공지능 시스템의 현재와 미래

서론

AI 기술의 발전은 단순히 질문에 답변하거나 텍스트를 생성하는 수준을 넘어, **스스로 목표를 설정하고 문제 해결 과정을 설계하는 ‘AI 에이전트’**로 진화하고 있습니다. 기존의 LLM(Large Language Model)이 텍스트 입력에 반응하는 수동적 도구였다면, AI 에이전트는 다양한 도구와 메모리, 추론 능력을 결합하여 복잡한 목표를 자율적으로 달성하는 차세대 인공지능 시스템입니다. 본 글에서는 AI 에이전트의 개념, 구조, 구현 방식, 그리고 미래 전망까지 포괄적으로 살펴봅니다.

AI 에이전트의 정의와 필요성

AI 에이전트는 단순 응답을 넘어 목표 설정 → 가설 수립 → 실행까지 수행하는 자율적 AI입니다.

기존 LLM의 한계 극복: 초기 LLM은 텍스트 입력에 텍스트를 출력하는 구조에 머물렀습니다. 하지만 다양한 API와 시스템과 연결해 자율적 의사결정을 수행할 수 있는 에이전트 구조가 필요해졌습니다.
복잡한 목표 달성: 단순 질의응답을 넘어 외부 DB 조회, 코드 실행, 검색, 분석 등 복잡한 작업을 자동으로 처리합니다.
자율성: 에이전트는 사전에 정해진 경로가 아닌, 스스로 필요한 도구를 선택하고 반복 실행하며 문제 해결 경로를 탐색합니다.

에이전트와 워크플로우의 차이

Anthropic 연구팀은 AI 시스템을 워크플로우와 에이전트로 구분합니다.

워크플로우: 사람이 미리 정의한 순서에 따라 실행되는 직선적 구조. 예측 가능하고 안정적이지만 유연성이 떨어집니다.
에이전트: 주어진 목표를 위해 LLM이 스스로 도구 사용 여부와 실행 횟수를 결정합니다. 따라서 더 개방적이고 복잡한 문제 해결에 적합합니다.

즉, 워크플로우는 사람이 통제하는 자동화라면, 에이전트는 자율적으로 진화하는 ‘AI 동료’에 가깝습니다.

AI 에이전트의 핵심 구성 요소 (머리·손·기억)

머리(LLM): 문제를 이해하고 추론하며, 어떤 행동을 할지 계획합니다.
손(툴): LLM이 호출하는 외부 도구(API, 계산기, 검색기 등)입니다. 예: Tavily Search, SQL DB 툴, 파일 변환기.
기억(메모리): 사용자 대화 기록과 내부 로그를 저장하여 개인화된 경험을 제공합니다.

이 세 요소가 유기적으로 작동할 때 에이전트는 단순한 자동화가 아닌 지능적 의사결정을 수행할 수 있습니다.

에이전트의 추론·행동 방식

에이전트는 다양한 프레임워크를 활용해 생각하고(Reasoning), 행동하며(Acting) 목표를 달성합니다.

ReAct: 가장 널리 쓰이는 방식으로, Thought → Action → Observation → Final Answer 순환 구조를 따릅니다.
Chain of Thought (CoT): 복잡한 문제를 단계별 추론 과정을 통해 풀어내는 방식.
Tree of Thoughts (ToT): 다양한 시나리오를 나무 구조로 탐색하며 복수의 해결책을 제시합니다.

이러한 접근은 LLM이 단순히 답변을 생성하는 것이 아니라, 실제로 문제 해결 과정을 시뮬레이션하고 학습할 수 있도록 돕습니다.

AI 에이전트 구현 시 고려사항

AI 에이전트 구축은 단순히 모델을 학습시키는 것을 넘어 비즈니스 로직·데이터·도구를 통합하는 과정이 필요합니다.

도메인 지식 주입: RAG(Retrieval Augmented Generation) 기반으로 기업 데이터를 에이전트에 연결.
프롬프트 엔지니어링: 현업 전문가와 협업하여 에이전트의 답변 품질을 제어.
맞춤형 툴 개발: 기업 내부 API, 분석 기능 등을 도구화.
피드백 루프: 지속적인 테스트와 UI 개선을 통한 성능 최적화.
측정 가능한 결과: 정확도, 시간 절약 효과 등 성과 지표를 정의해야 합니다.

현재와 미래 전망

과대평가된 소비자 에이전트: 여행 예약 등 복잡한 개인 서비스는 아직 어려움이 많습니다.
저평가된 업무 에이전트: 반복 작업 자동화, 검색·코딩 보조 등은 빠르게 확산될 것으로 예상됩니다.
2025년 전망:
- 기업 내 반복 업무 자동화 가속화
- 멀티 에이전트 협업 환경 연구 확산
- 모델의 지능 향상과 함께 제품 수준 개선

LangChain과 대안적 방법론

LangChain: 툴 통합, 메모리 관리, 프롬프트 체인 등을 구조화하는 대표 프레임워크.
LangGraph: 더 예측 가능한 워크플로우 기반 접근.
기타 방법론: ReAct, AutoGen, Multi-Agent, TaskWeaver 등 다양한 시도가 병행되고 있습니다.

결론

AI 에이전트는 단순한 LLM을 넘어 자율적 판단과 행동을 수행하는 차세대 AI로 자리매김하고 있습니다. 기업 환경에서는 반복 업무 자동화와 맞춤형 서비스에 큰 가치를 제공하며, LangChain 같은 프레임워크를 통해 빠르게 프로덕션 수준의 구현이 가능해지고 있습니다.

성공적인 도입을 위해서는

현업 데이터와 맥락의 이해,
맞춤형 툴 설계,
지속적인 피드백과 성능 측정

이 필수적입니다. 앞으로 AI 에이전트는 기업 혁신의 핵심 동력으로 자리 잡을 것이며, 특히 금융·제조·IT 분야에서 더 큰 성과가 기대됩니다.

source: https://www.youtube.com/watch?v=j4LgIuY8qTM

https://www.youtube.com/watch?v=HujQhD8J2LQ

https://www.youtube.com/watch?v=EDb37y_MhRw

https://www.youtube.com/watch?v=CUB1JuH1UX8

https://www.youtube.com/watch?v=LP5OCa20Zpg

https://www.youtube.com/watch?v=F8NKVhkZZWI

본 글은 NotebookLM과 chatgpt를 활용하여 작성되었습니다.

LLM 활용의 핵심, 프롬프트 엔지니어링과 컨텍스트 엔지니어링 비교 분석

jerymy — Thu, 21 Aug 2025 15:48:28 +0900

컨텍스트 엔지니어링 vs. 프롬프트 엔지니어링: LLM 활용의 두 축

source : https://www.youtube.com/watch?v=vD0E3EUb8-8

서론

ChatGPT 같은 대규모 언어 모델(LLM)은 다양한 산업 현장에서 빠르게 활용되고 있습니다. 하지만 같은 모델이라도 **“어떻게 질문하고, 어떤 환경을 제공하느냐”**에 따라 결과의 품질은 크게 달라집니다. 이를 이해하는 핵심 개념이 바로 **프롬프트 엔지니어링(Prompt Engineering)**과 **컨텍스트 엔지니어링(Context Engineering)**입니다.

이 글에서는 두 개념의 차이와 상호 보완적인 역할을 살펴보고, 실제 활용 사례를 통해 LLM 기반 시스템을 최적화하는 방법을 소개합니다.

프롬프트 엔지니어링: 더 나은 질문의 기술

정의와 목적

프롬프트 엔지니어링은 LLM에 입력되는 텍스트를 정교하게 설계하는 과정입니다. 지시사항, 예시, 제약 조건 등을 포함해 모델이 원하는 방식으로 응답하도록 유도하는 기술이죠.
즉, **“모델에게 어떻게 질문할 것인가?”**를 다루는 분야입니다.

주요 기법

역할 할당(Role Assignment)
- LLM에게 특정 역할을 부여해 어휘와 관점을 제한합니다.
- 예: “당신은 보안 취약점을 검토하는 Python 선임 개발자입니다.”
소수 예시(Few-shot Examples)
- 2~3개의 입력/출력 쌍을 제공해 응답 형식과 스타일을 학습시킵니다.
사고의 사슬(Chain of Thought, CoT)
- *“단계별로 설명하라”*와 같은 지시를 통해 모델이 논리 과정을 드러내도록 유도합니다.
제약 조건 설정(Constraint Setting)
- 응답 분량, 출처, 형식 등을 제한해 모델이 벗어나지 않도록 합니다.

한계 사례

예를 들어, “Book me a hotel in Paris for the DevOps conference”라는 프롬프트는 불명확해 파리, 프랑스가 아닌 파리, 켄터키에 호텔을 예약하는 오류를 유발할 수 있습니다.

컨텍스트 엔지니어링: 더 나은 시스템의 설계

정의와 목적

프롬프트 엔지니어링이 질문을 잘 던지는 기술이라면, 컨텍스트 엔지니어링은 LLM이 추론하는 전체 환경을 설계하는 시스템적 접근입니다.
즉, **“모델이 작업을 잘 수행하기 위해 어떤 정보와 도구를 제공할 것인가?”**에 집중합니다.

주요 구성 요소

메모리 관리 (Memory Management)
- 단기 메모리: 대화를 요약해 컨텍스트 윈도우에 보존
- 장기 메모리: 벡터DB 기반 사용자 선호도, 과거 기록 관리
상태 관리 (State Management)
- 다단계 프로세스에서 현재 진행 상황 추적
- 예: 항공권 예약 성공 후, 공항 교통편 예약 단계로 연결
검색 증강 생성 (RAG, Retrieval Augmented Generation)
- 관련 문서 중 필요한 부분만 추출해 LLM에 제공
- 불필요한 전체 문서 대신 핵심 맥락만 전달
도구 사용 (Tools Integration)
- LLM 자체는 DB 조회, API 호출을 못함 → 도구를 연결해 외부 작업 수행 가능
- 예: 온라인 캘린더, 회사 정책 JSON 파일 참조

개선 사례

앞선 호텔 예약 예시에서 컨텍스트 엔지니어링이 적용되면,

캘린더를 조회해 컨퍼런스 위치를 확인
회사 여행 정책(JSON)을 불러와 예산 범위 확인
최종적으로 “파리, 프랑스”에서 정책에 맞는 호텔 예약 성공

프롬프트 vs. 컨텍스트: 상호 보완 관계

프롬프트 엔지니어링 = 더 나은 질문
컨텍스트 엔지니어링 = 더 나은 시스템

둘은 경쟁 개념이 아니라 상호 보완적입니다. 성공적인 AI 시스템을 위해서는 정교한 프롬프트와 체계적인 컨텍스트 설계가 함께 필요합니다.

결론

프롬프트 엔지니어링은 LLM의 단기적인 성능 향상에 유효하지만, 장기적으로는 컨텍스트 엔지니어링이 필수입니다.
에이전트 기반 AI가 확산되는 지금, 두 접근법의 조합은 단순한 응답 품질 개선을 넘어 신뢰할 수 있는 AI 시스템 구축의 핵심 전략이 될 것입니다.

결국 “좋은 질문”과 “좋은 시스템”이 만나야 진정한 AI 혁신이 시작됩니다.

본 글은 chatgpt를 활용하여 작성되었습니다.

파이썬 레포지토리 자동 분석 스크립트: 코드 품질·의존성·복잡도를 한 번에

jerymy — Thu, 21 Aug 2025 13:23:10 +0900

파이썬 레포지토리 자동 분석 스크립트: 실행 예시 + 상세 해설 + 전체 코드

키워드: 파이썬 코드 분석, 레포지토리 헬스체크, LOC, 의존성 분석, 복잡도, 유지보수성, pytest, AST, 그래프 시각화

파이썬 프로젝트의 상태를 한 번에 파악하고 싶을 때가 많죠. 이 글은 그런 순간을 위해 준비한 **자동 분석 스크립트(analyze_repo.sh)**의 실행 예시, 상세 동작 해설, 그리고 전체 코드까지 한 번에 제공합니다. 스크립트는 pygount/radon/pydeps/pipreqs/pytest/ripgrep 등 도구를 조합해 레포지토리 헬스 리포트를 생성합니다.

한눈에 보는 기능 요약

디렉터리 트리 & 파일 크기: tree / find, du
LOC(코드 라인) 통계: pygount (언어별/주석/빈 줄)
의존성 분석: pipreqs(추정), pipdeptree(실제 설치 트리)
복잡도/유지보수성: radon cc, radon mi
임포트 그래프: pydeps → Graphviz SVG
테스트 수집: pytest --collect-only
TODO/FIXME 스캔: ripgrep(또는 grep)
AST 인덱스: 함수/클래스를 JSON으로 색인
Fallback 의존성 수집기: 문법 오류 파일도 관대하게 import 추출

⚙️ 설치 (1회)

python -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install pipreqs pipdeptree radon pydeps pygount pytest

# 의존(권장)
# - graphviz: pydeps가 SVG/DOT 출력에 필요
# - tree: 디렉터리 맵 생성
# - ripgrep: TODO/FIXME 검색 가속(없으면 grep로 대체)
# Fedora/RHEL/CentOS:
#   sudo dnf install graphviz tree ripgrep -y
# Ubuntu/Debian:
#   sudo apt-get update && sudo apt-get install graphviz tree ripgrep -y

▶️ 사용 방법

chmod +x analyze_repo.sh
./analyze_repo.sh

업로드 권장 세트(요약 리포트)

analysis_out/repo_map.txt, file_sizes.txt, loc_summary.txt
pipdeptree.txt, complexity.json, maintainability.json
imports.svg(생성 시), test_collection.txt, todos.txt, ast_index.json
requirements_inferred.txt 또는 requirements_inferred_fallback.txt

실행 예시 & 결과 해설 (요점)

레포 트리/파일 크기 → 구조 파악 & 용량 상위 파일 확인
LOC 통계 → 코드/주석/빈 줄 밸런스 진단
의존성 → “실제 설치 트리” vs “코드가 요구하는 패키지” 비교
복잡도/유지보수성 → 리팩터링 우선순위 선정 근거
임포트 그래프 → 결합도 높은 모듈 식별
테스트 수집 → 테스트 존재/명명 규칙 파악
TODO/FIXME → 작업 백로그 추출
AST 인덱스 → 함수/클래스 탐색 및 문서화 자동화 토대

실전 팁

IGNORE_PIPREQS에 문법 오류/실험용 스크립트를 추가하면 pipreqs 실패를 줄일 수 있습니다.
--max-bacon=2로 import 그래프 깊이 제한 → 복잡한 그래프 가독성 개선.
CI 파이프라인에 이 스크립트를 연결해 정기 리포트를 만들면 팀 생산성이 올라갑니다.

analyze_repo.sh 전체 코드

아래 코드를 레포지토리 루트에 analyze_repo.sh로 저장하세요.

#!/usr/bin/env bash
set -euo pipefail

# === 설정 ===
OUT="analysis_out"
IGNORE_PIPREQS="main_bat.py"    # pipreqs가 깨지는 파일/폴더를 ,로 추가(예: "main_bat.py,build,dist")
SKIP_DIRS=".git,.venv,__pycache__,.mypy_cache,.pytest_cache,${OUT}"
PY_EXT=".py"

mkdir -p "$OUT"

# === 유틸 ===
have() { command -v "$1" >/dev/null 2>&1; }

note() { echo -e "\n[INFO] $*"; }
warn() { echo -e "\n[WARN] $*" >&2; }
fail() { echo -e "\n[ERROR] $*" >&2; exit 1; }

# === 1) 레포 트리 & 파일 크기 ===
note "레포 맵/파일 크기 수집..."
{
  echo "### REPO TREE"
  if have tree; then
    tree -a -I "$(echo "$SKIP_DIRS" | tr , '|')" || true
  else
    warn "'tree'가 없어 'find'로 대체합니다(간략 출력). 'sudo dnf/apt install tree' 권장."
    find . -path "./.git" -prune -o -path "./${OUT}" -prune -o -print
  fi
} > "$OUT/repo_map.txt"

du -ah --max-depth=2 2>/dev/null | sort -h > "$OUT/file_sizes.txt" || {
  warn "du 옵션 미지원 환경. 대체 모드로 파일 크기 집계."
  find . -type f -not -path "./${OUT}/*" -not -path "./.git/*" -exec du -ah {} + | sort -h > "$OUT/file_sizes.txt" || true
}

# === 2) LOC/언어 통계 (pygount) ===
note "LOC/언어 통계(pygount)..."
pygount . \
  --format=summary \
  --folders-to-skip "$SKIP_DIRS" \
  > "$OUT/loc_summary.txt"

# (선택) 파일별 상세 필요 시 주석 해제
# pygount . \
#   --format=cloc-xml \
#   --folders-to-skip "$SKIP_DIRS" \
#   > "$OUT/loc_by_file.cloc.xml"

# === 3) 의존성(추정 + 실제 트리) ===
note "의존성 추정(pipreqs) 및 설치 트리(pipdeptree)..."
# pipreqs는 문법 에러 파일에서 중단될 수 있어 --ignore 사용, 실패해도 계속
pipreqs . \
  --force \
  --encoding=utf-8 \
  --ignore "$IGNORE_PIPREQS" \
  --savepath "$OUT/requirements_inferred.txt" || warn "pipreqs 실패(무시하고 계속). --ignore 목록을 늘리거나 fallback 사용 권장."

# requirements.txt가 있다면 설치 후 의존 트리 출력(실패 허용)
if [[ -f requirements.txt ]]; then
  pip install -r requirements.txt || warn "requirements 설치 중 경고 발생(계속 진행)."
fi
pipdeptree > "$OUT/pipdeptree.txt" || warn "pipdeptree 실패(계속)."

# === 4) 복잡도/유지보수성 (radon) ===
note "복잡도/유지보수성(radon)..."
radon cc -s -a -j . > "$OUT/complexity.json"    || warn "radon cc 실패(계속)."
radon mi -s -j . > "$OUT/maintainability.json"  || warn "radon mi 실패(계속)."

# === 5) import 그래프 (pydeps) ===
note "import 그래프(pydeps → SVG)..."
if have dot; then
  :
else
  warn "graphviz(dot) 미설치. 'sudo dnf/apt install graphviz' 권장. 시도는 해봅니다."
fi
# 최신 pydeps: -T svg -o 파일
if have pydeps; then
  pydeps . --noshow --max-bacon=2 -T svg -o "$OUT/imports.svg" || warn "pydeps 그래프 생성 실패(계속)."
else
  warn "pydeps 미설치. 'pip install pydeps' 후 재시도 가능."
fi

# === 6) 테스트 수집 (pytest) ===
note "pytest 테스트 수집..."
pytest --collect-only -q > "$OUT/test_collection.txt" || warn "pytest 수집 실패(계속)."

# === 7) TODO/FIXME/HACK/XXX 검색 ===
note "TODO/FIXME/HACK/XXX 키워드 검색..."
if have rg; then
  rg -n "TODO|FIXME|HACK|XXX" --glob "!${OUT}/**" --glob "!.git/**" > "$OUT/todos.txt" || true
else
  grep -RInE "TODO|FIXME|HACK|XXX" . \
    --exclude-dir="$OUT" --exclude-dir=".git" --exclude-dir=".venv" \
    > "$OUT/todos.txt" || true
fi

# === 8) AST 인덱스(함수/클래스) ===
note "AST 인덱스 생성(함수/클래스)..."
python - << 'PY' || warn "AST 인덱스 생성 중 문제(계속)."
import os, ast, json
skip = set(s.strip() for s in ".git,.venv,__pycache__,.mypy_cache,.pytest_cache,analysis_out".split(","))
index=[]
for root,_,files in os.walk("."):
    if any(k in root for k in skip): 
        continue
    for f in files:
        if f.endswith(".py"):
            p=os.path.join(root,f)
            try:
                with open(p,"r",encoding="utf-8",errors="ignore") as fh:
                    src = fh.read()
                try:
                    m=ast.parse(src, filename=p)
                except SyntaxError as e:
                    # 문법 에러는 기록만 남기고 건너뜀
                    index.append({"path":p,"error":f"SyntaxError: {e}"})
                    continue
                funcs=[n.name for n in ast.walk(m) if isinstance(n,ast.FunctionDef)]
                clss=[n.name for n in ast.walk(m) if isinstance(n,ast.ClassDef)]
                index.append({"path":p,"functions":funcs,"classes":clss})
            except Exception as e:
                index.append({"path":p,"error":str(e)})
open("analysis_out/ast_index.json","w",encoding="utf-8").write(json.dumps(index,ensure_ascii=False,indent=2))
PY

# === 9) (옵션) pipreqs Fallback: 관대한 import 수집기 ===
note "pipreqs Fallback(관대한 import 수집기) 실행..."
python - << 'PY' || warn "Fallback import 수집 실패(계속)."
import os, ast, tokenize, io
root="."
skip=set(s.strip() for s in ".git,.venv,__pycache__,.mypy_cache,.pytest_cache,analysis_out".split(","))
imports=set()
stdlib={"os","sys","json","re","subprocess","pathlib","typing","logging","datetime","time","math","itertools","functools","collections","dataclasses","ast","tokenize","io","enum","statistics","decimal","random","uuid"}

def tolerant_parse(text):
    try:
        return ast.parse(text)
    except SyntaxError:
        return None

for r,_,fs in os.walk(root):
    if any(k in r for k in skip): 
        continue
    for f in fs:
        if f.endswith(".py"):
            p=os.path.join(r,f)
            try:
                txt=open(p,"r",encoding="utf-8",errors="ignore").read()
            except Exception:
                continue
            m=tolerant_parse(txt)
            if m:
                for n in ast.walk(m):
                    if isinstance(n, ast.Import):
                        for a in n.names:
                            imports.add(a.name.split(".")[0])
                    elif isinstance(n, ast.ImportFrom) and n.module:
                        imports.add(n.module.split(".")[0])
            else:
                # 간단 라인 스캔(문법 에러 파일용)
                for line in txt.splitlines():
                    line=line.strip()
                    if line.startswith("import "):
                        for part in line[len("import "):].split(","):
                            imports.add(part.strip().split(".")[0])
                    elif line.startswith("from ") and " import " in line:
                        mod=line.split()[1]
                        imports.add(mod.split(".")[0])

third=sorted(m for m in imports if m and m not in stdlib)
open("analysis_out/requirements_inferred_fallback.txt","w",encoding="utf-8").write("\n".join(third))
print(f"[fallback] third-party candidates: {len(third)} → analysis_out/requirements_inferred_fallback.txt")
PY

# === 완료 요약 ===
note "완료! 산출물 목록:"
ls -lh "$OUT" || true
echo
echo "업로드 권장 파일:"
echo "- $OUT/repo_map.txt"
echo "- $OUT/file_sizes.txt"
echo "- $OUT/loc_summary.txt"
echo "- $OUT/pipdeptree.txt"
echo "- $OUT/complexity.json"
echo "- $OUT/maintainability.json"
echo "- $OUT/imports.svg (있으면)"
echo "- $OUT/test_collection.txt"
echo "- $OUT/todos.txt"
echo "- $OUT/ast_index.json"
echo "- $OUT/requirements_inferred.txt (있으면)"
echo "- $OUT/requirements_inferred_fallback.txt (보조)"

✅ 요약 & 결론

이 스크립트 하나로 프로젝트 상태 진단을 자동화할 수 있습니다.
CI에 붙이면 정기 건강 리포트를 자동 생성할 수 있고, 신규 인수/레거시 관리/리팩터링 기획에 탁월합니다.
필요시 파일별 LOC CSV나 호출 그래프 생성기 등 확장도 손쉽게 추가 가능합니다.

본 글은 chatgpt를 활용하여 작성되었습니다.

AI에게 원하는 답을 얻는 기술: 프롬프트 엔지니어링 실전 가이드북

jerymy — Thu, 21 Aug 2025 13:07:27 +0900

프롬프트 엔지니어링: AI와 효과적으로 대화하는 기술

서론

생성형 AI(ChatGPT, Claude, Gemini 등)의 등장은 우리의 일상과 업무 방식을 크게 바꾸고 있습니다. 하지만 AI가 언제나 정확하고 원하는 답을 주는 것은 아닙니다. 같은 질문을 해도 모호하거나 엉뚱한 답변이 나오곤 하죠. 그 차이를 만드는 핵심 요인이 바로 **프롬프트 엔지니어링(Prompt Engineering)**입니다.

예시

“이 문장을 요약해줘” → AI는 길고 애매한 요약을 할 수 있음
“이 문장을 3줄로 요약하고, 핵심 키워드를 5개 뽑아줘” → AI가 명확하고 구조적인 결과를 제공

프롬프트 엔지니어링이란?

정의: AI 모델에 최적의 입력을 제공해 원하는 결과를 이끌어내는 기술
목적: AI의 잠재력을 극대화하고, 오류(예: 환각 현상)를 줄이며, 사용자 의도에 맞는 답변을 얻는 것

예시

단순 질문: “신제품 홍보 아이디어를 알려줘”
프롬프트 엔지니어링 적용:
당신은 10년 경력의 디지털 마케팅 전문가입니다. 타겟은 20~30대 직장인이고, 플랫폼은 인스타그램입니다. ‘친환경 스마트 텀블러’ 출시를 위한 홍보 아이디어 5가지를 제시해주세요. 각 아이디어는 50단어 이내로 설명해주세요.

효과적인 프롬프트의 구성 요소

지시사항 (Instruction) – AI가 해야 할 작업을 명확하게 전달
맥락 (Context) – 배경 정보 제공
입력 데이터 (Input Data) – AI가 처리할 구체적인 질문/텍스트
출력 형식 (Output Format) – JSON, 표, 글머리 기호 등 원하는 결과 형식
역할 지정 (Role Assignment) – 전문가, 교사, 마케터 등 특정 관점 설정
경계 조건 (Constraints) – 하지 말아야 할 것 지정

예시

지시사항: 다음 문서를 요약해 주세요.  
맥락: 당신은 경영 컨설턴트입니다.  
입력 데이터: """2024년 글로벌 AI 산업 동향 보고서 내용..."""  
출력 형식: 불릿 포인트 5개로 요약  
역할: 전략 기획 전문가  
경계 조건: 과장된 표현은 피하고, 숫자는 원문 그대로 유지

기본 프롬프트 기법

Zero-shot: 예시 없이 바로 지시
Few-shot: 몇 가지 예시 제시
Step-by-step: 복잡한 문제를 단계별로 지시

예시

Zero-shot
이 문장이 긍정, 부정, 중립 중 어디에 속하는지 분류해주세요: "오늘 점심이 맛있었다."
Few-shot
입력: "오늘 날씨가 좋아요." → 긍정 입력: "이 영화는 너무 지루했어." → 부정 입력: "버스가 10분 뒤에 도착한다." → 중립 입력: "이 제품은 기대 이상이었어." → ?
Step-by-step
한 사과는 1,500원이고, 배 한 개는 사과 두 개 가격입니다. 사과 2개와 배 3개의 총 가격을 단계별로 계산해주세요.

고급 프롬프트 기법 (상세 설명 포함)

아래 기법들은 단순 요청 수준을 넘어, 더 정교하고 안정적인 결과를 이끌어내는 고급 전략입니다.

1) Chain-of-Thought (CoT)

개념
모델이 답만 내놓지 않고 사고 과정을 단계별로 전개하도록 유도하는 기법. 복잡한 계산·추론·절차 문제에서 정답률을 높입니다.

언제 쓰나

계산/논리/규칙 기반 문제(가격 산출, 일정 최적화, 데이터 전처리 단계 설계)
다단계 의사결정(우선순위 선정, 리스크 평가)

작성 팁 (체크리스트)

“단계별로”, “근거를 제시”, “중간 계산을 명시” 같은 표현 추가
입력 데이터는 정리된 표/리스트로 제공
마지막 줄에 “최종 답만 한 줄로 요약” 요청

흔한 함정

너무 포괄적인 질문 → 군더더기 많은 추론
길이 제한 미설정 → 장황한 결과

템플릿

[역할/맥락]. 아래 문제를 단계별로 해결하세요.
1) 필요한 가정 명시  
2) 단계별 계산/추론  
3) 근거 요약  
4) 최종 답 한 줄
입력: """[데이터/문제]"""
출력 형식: 
- reasoning: 단계별 사고
- answer: 최종 답

실전 예시

당신은 리테일 가격전략 분석가입니다.  
입력: 원가 35,000원, 유통수수료 8%, 광고비 2,000원/개, 목표 마진율 25%  
요구: 1) 판매가 2) 순이익 3) 수수료 ±2% 민감도 분석

2) Tree-of-Thoughts (ToT)

개념
CoT를 확장해 여러 사고 경로를 가지치기처럼 생성·평가·선택하는 방식. 탐색적 기획·전략 선택에 적합.

언제 쓰나

대안이 여러 개이고 트레이드오프가 명확한 문제
전략/정책 선택, 기획안 비교

작성 팁 (체크리스트)

대안 3~5개 생성
평가기준 수치화(가중치 합계, 리스크 점수 등)
지나친 브랜치 생성은 피함

흔한 함정

평가기준 불명확 → 임의적 선택
브랜치 과다 → 산만함

템플릿

[역할/맥락]. 아래 목표를 위해 3~4개 대안을 제시하세요.
평가기준: 비용(0.3), 시장임팩트(0.4), 리스크(0.3)
출력:
- options: 각 대안 요약
- scoring: 기준별 점수표
- tradeoffs: 장단점
- recommendation: 최적안 + 실행 첫 단계

실전 예시

목표: 분기 내 리드 30% 증가(예산 5천만 원)
대안: 검색광고 / 리타겟팅 / 웨비나 / 파트너십

3) RAG (Retrieval-Augmented Generation)

개념
모델의 답변을 **외부 지식(문서·데이터)**로 보강해 사실성과 신뢰성을 높이는 방식.

언제 쓰나

최신 정보/사실 검증이 필요한 리서치
사내 문서 기반 Q&A

작성 팁 (체크리스트)

출처 필드 분리
답변 범위 제한(“문서 범위 밖=모름”)
요약 규칙 명시

흔한 함정

출처 미표기 → 신뢰도 저하
무관한 추론 → 환각

템플릿

[역할/맥락]. 제공 문서 내 근거로만 답하세요.  
문서: """[...]"""  
질문: [질문]  
출력: answer, evidence, sources

실전 예시

당신은 보안 담당자입니다.  
질문: SaaS 도입 시 데이터 암호화 요건은?  
문서: """회사 보안정책 v3.2"""

4) Self-Consistency (자기 일관성)

개념
여러 사고 경로/샘플을 생성한 뒤, 가장 일관된 답을 선택.

언제 쓰나

풀이 경로가 다양한 문제(수학, 최적화, 로지스틱스)
단일 샘플 오류 줄이고 싶을 때

작성 팁 (체크리스트)

최소 3~5회 시도
선정 기준 명시(다수결, 근거 충실성)

흔한 함정

동일한 접근만 생성 → 다양성 부족

템플릿

문제를 5가지 방식으로 풀어주세요.  
각 시도: method, steps, result  
최종: best_result, 선정 근거

실전 예시

배송 경로 최적화: 도시 7곳, 차량 2대, 시간창 제약  
서로 다른 알고리즘으로 5회 시도 후 최적안 제시

5) 프롬프트 체이닝 (Prompt Chaining)

개념
복잡한 작업을 여러 단계 프롬프트로 나누어 순차 실행.

언제 쓰나

보고서/콘텐츠 제작 프로세스
데이터 파이프라인 설계

작성 팁 (체크리스트)

각 단계 입력·출력 포맷 고정
중간 산출물 검증 규칙 포함

흔한 함정

단계 간 포맷 불일치 → 실패

예시 (제품 백서 작성)
1단계: 목차 추출(JSON)
2단계: 본문 초안 작성
3단계: 요약, 표, CTA 추가

6) XML/태그 기반 지시

개념
프롬프트를 태그 구조로 분리 → 모델이 혼동 없이 처리.

언제 쓰나

여러 규칙, 금지어, 예시 포함해야 할 때

작성 팁

<instruction>, <context>, <input>, <constraints> 활용

예시

<instruction>중견기업 CTO 대상 블로그 작성</instruction>
<context>톤=전문+친근, 길이=1200단어</context>
<constraints>과장 금지, 통계 출처 필수</constraints>

7) Prefill & Few-Shot 결합

개념
모델 답변의 첫 문장/형식을 미리 채워 톤·구조를 고정.

언제 쓰나

브랜드 톤, 보고서 표준 서식 고정 필요할 때

예시

제목: [자동생성]
요약: [2문장]
본문: 1) ... 2) ...
결론: ...

8) 도메인 특화 템플릿

개념
산업·조직에 맞춘 반복 템플릿.

예시 (채용 공고)

회사 소개(3문장)
주요 업무(3~5개)
자격 요건(필수·우대)
포용성 문구 포함

9) 메타 프롬프팅

개념
프롬프트 자체를 평가·개선하거나 A/B 테스트.

예시 (FAQ 최적화)

프롬프트 A와 B를 동일 데이터에 적용해 테스트.  
평가 기준: 사실성, 톤, 구조 준수.  
승자와 개선 포인트 제시.

도전 과제와 해결 전략

편향(Bias) → 표현 균형 유지
환각(Hallucination) → 출처 요구, “모름” 허용
모델 한계 → 비판적 검토, 외부 데이터 결합

예시

출처 없는 답변은 허용하지 말고, 
근거 없을 경우 "알 수 없음"이라고 답하세요.

결론

프롬프트 엔지니어링은 단순한 기술이 아니라 AI 활용 역량을 결정짓는 핵심 스킬입니다.

명확하고 구체적인 프롬프트는 결과 품질을 극대화합니다.
CoT, ToT, RAG 같은 고급 기법은 복잡한 문제 해결에 유용합니다.
반복적 개선과 비판적 검토가 좋은 프롬프트를 만듭니다.

최종 예시

당신은 채용 담당자입니다.  
20대 신입 개발자가 쓸 자기소개서 예시를 작성해주세요.  
항목: ① 성장 과정, ② 지원 동기, ③ 기술 역량, ④ 향후 포부  
각 항목은 300자 내외, 전문적이면서 진솔한 톤으로 작성

본 글은 chatgpt를 활용하여 작성되었습니다.

Install minikube with Driver none and cri-dockerd on CentOS 9

jerymy — Fri, 7 Jun 2024 18:20:42 +0900

minikube start --driver=none 환경으로 실행하기 위한 방법

driver=none 방식은 vm 같은곳에 설치하게되면 클러스터 접속을 위한 proxy가 필요없이 host의 IP로 바로 접근가능하여 k8s의 구조를 이해하는데 도움이 된다.

install minikube using docker, cri-dockerd on CentOS 9 stream

2024-06-07 확인
- runtime을 crio로 설치는 가능하지만 minikube addons enable시 오류 발생함
- podman 설치하면 minikube start --driver=podman --force 실행가능함
  - 명령어를 minikube kubectl get po 이런식으로 하거나 alias kubectl="minikube kubectl --" 를 주면됨
    - 이 방식은 클러스터에 접근히기 위해서는 proxy 를 통해야함
- crio를 설치하면 minikube start --driver=none --container-runtime=cri-o 시작가능함 ->

설치 순서

dnf update
install docker
install crio
install conntrack
install cri-dockerd
- /etc/crictl.yaml 내용 확인
  - container rumtime 위치 확인 -> "runtime-endpoint: unix:///var/run/cri-dockerd.sock"
- copy /etc/crio/crio.conf.d/10-crio.conf --> /etc/crio/crio.conf.d/02-crio.conf
install kubectl
install minikube
- minikube start --driver=none --container-runtime=cri-o

update dnf

dnf update

install docker

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker

install crio

curl https://raw.githubusercontent.com/cri-o/packaging/main/get | bash
systemctl status crio
systemctl start crio
crio status info
crictl info

yum install -y conntrack

cri-dockerd 설치

아래 2개 모두 download필요함
소스에는 cri-dockerd 파일이 없다.

wget https://github.com/Mirantis/cri-dockerd/releases/download/v0.3.14/cri-dockerd-0.3.14.amd64.tgz
wget https://github.com/Mirantis/cri-dockerd/archive/refs/tags/v0.3.14.tar.gz


tar -xvf cri-dockerd-0.3.14.amd64.tgz
install -o root -g root -m 0755 ./cri-dockerd/cri-dockerd /usr/local/bin/cri-dockerd
install -o root -g root -m 0755 ./cri-dockerd/cri-dockerd /usr/bin/cri-dockerd

tar -xvf v0.3.14.tar.gz
install ./cri-dockerd-0.3.14/packaging/systemd/* /etc/systemd/system

systemctl daemon-reload
systemctl status cri-docker
systemctl enable cri-docker.service
systemctl start cri-docker.service


# /etc/crio/crio.conf.d/10-crio.conf 파일 복사
cp /etc/crio/crio.conf.d/10-crio.conf /etc/crio/crio.conf.d/02-crio.conf

Install kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

kubectl version

install minikube

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube


minikube start --driver=none 
# minikube start --driver=none  --container-runtime=cri-o --force

정상 동작확인.

cri-dockerd 설치

$ minikube profile list
|----------|-----------|---------|--------------|------|---------|---------|-------|----------------|--------------------|
| Profile  | VM Driver | Runtime |      IP      | Port | Version | Status  | Nodes | Active Profile | Active Kubecontext |
|----------|-----------|---------|--------------|------|---------|---------|-------|----------------|--------------------|
| minikube | none      | docker  | 10.30.147.175 | 8443 | v1.30.0 | Running |     1 | *              | *                  |
|----------|-----------|---------|--------------|------|---------|---------|-------|----------------|--------------------|

troubleshooting

containerd 로 설정하는 방법 -> minikube에서는 안된다

sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo systemctl restart containerd

runtime을 docker로 사용하는 경우

cri-dockerd 설치 필수
cni-plugin 필요 없음

runtime을 containerd, cri-o로 사용하는 경우

설치는 되지만, minikube addons enable 하면 아래 오류 발생함
Exiting due to MK_ADDON_ENABLE_PAUSED: enabled failed: check paused: list paused:

❌  Exiting due to MK_ADDON_ENABLE_PAUSED: enabled failed: check paused: list paused: crictl list: sudo -s eval "crictl ps -a --quiet --label io.kubernetes.pod.namespace=kube-system": exit status 127
stdout:

stderr:
/bin/bash: line 1: crictl: command not found

crictl 설치 오류

crictl 설치후 /etc/crictl.yaml 파일 생성 내용 추가 필요
cri-dockerd 설치후 cri-dockerd.sock 오류 나면
visudo의 default secure path 에 /usr/local/bin 추가 필요

설치시 오류 발생

이렇게 하면 minikube addons enable dashboard 에서 오류 발생함

install docker, conntrack, minikube
- minikube start --driver=none
- crictl 필요하다고 오류남. GUEST_MISSING_CONNTRACK -> conntrack은 설치했지만 오류가 난다?
- cni plugin 설치후 crictl info에서 오류 보임 /etc/cni/net.d/에 파일이 없다고
- minikube start --driver=none 하면 cri-docerd가 필요하다고 실행 실패
- containerd 를 기본으로 설정하고, crictl.yaml에 runtime-endpoint: unix:///var/run/containerd/containerd.sock 설정하고 minikube start --driver=none --container-runtime=containerd 해도 -> crictl 없다고 오류 발생
- install crio -> minikube start 헤도 같은 crictl 오류남
- crictl.yaml 내용을 crio.sock으로 변경
- minikube start --driver=none --container-runtime=cri-o -> 실행됨 addons enable 하면 오류남

instll cni-plugin

없어도 된다

CNI_PLUGIN_VERSION="<version_here>"
CNI_PLUGIN_VERSION="v1.5.0"

# change arch if not on amd64
CNI_PLUGIN_TAR="cni-plugins-linux-amd64-$CNI_PLUGIN_VERSION.tgz" 
CNI_PLUGIN_INSTALL_DIR="/opt/cni/bin"

curl -LO "https://github.com/containernetworking/plugins/releases/download/$CNI_PLUGIN_VERSION/$CNI_PLUGIN_TAR"
sudo mkdir -p "$CNI_PLUGIN_INSTALL_DIR"
sudo tar -xf "$CNI_PLUGIN_TAR" -C "$CNI_PLUGIN_INSTALL_DIR"
rm "$CNI_PLUGIN_TAR"

# 설치후 crictl info 하면 아래 오류 보임
  "lastCNILoadStatus": "cni config load failed: no network config found in /etc/cni/net.d: cni plugin not initialized: failed to load cni config",
  "lastCNILoadStatus.default": "cni config load failed: no network config found in /etc/cni/net.d: cni plugin not initialized: failed to load cni config"

install containerd-based k8s using Ansible

jerymy — Fri, 10 Mar 2023 09:54:00 +0900

CentOS 7.9 에 설치 확인(2022-12-09)
참조 : https://www.hostafrica.co.za/blog/kubernetes/kubernetes-ansible-centos-stream-containerd/
containerd 기반 k8s 설치
- 사전준비: yum update, ssh key생성 , ansible 설치
- install-kube-v2.yml (설정변경 및 containerd, kubeadm 등 설치)
- master-setup.yml (kubeadm init)
- worker-setup.yml (kubeadm join)

# yum upgrade in all node
yum -y upgrade


# ssh keygen in master
ssh-keygen -b 4096 -f ~/.ssh/mysshkey_rsa


# ssh key copy to worker1,2
ssh-copy-id -i ~/.ssh/mysshkey_rsa.pub root@worker1
ssh-copy-id -i ~/.ssh/mysshkey_rsa.pub root@worker2


# host명, hosts 파일 수정 -> 각 노드에서 수행
hostnamectl set-hostname master
hostnamectl set-hostname worker1
hostnamectl set-hostname worker2


# install ansible in master node
yum -y install epel-release 
yum -y install ansible

ansible --version


# edit ansible-hosts 파일수정 /etc/ansible/hosts
[masters]
control-plane ansible_host={MASTER IP} ansible_user=root

[workers]
worker1 ansible_host={WORDER1 IP} ansible_user=root
worker2 ansible_host={WORKER2 IP} ansible_user=root


# ansible 연결 확인
ansible all -m ping


# install-kube
ansible-playbook install-kube-v2.yml


# master-setup
ansible-playbook master-setup.yml


# worker-setup -> /etc/kube_join_command 파일 확인
ansible-playbook worker-setup.yml

install-kube-v2.yaml

---
- hosts: "masters, workers"
  remote_user: root
  become: yes
  become_method: sudo
  become_user: root
  gather_facts: yes
  connection: ssh

  tasks:
     - name: Stop and disable firewalld.
       service:
         name: firewalld
         state: stopped
         enabled: False       
  
     - name: disable SELinux
       shell: |
                sudo setenforce 0
                sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

     - name: disabling swap as its required for kubelet
       shell: |
               sudo swapoff -a
               sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
               sudo mount -a


     - name: Creating a configuration file for containerd, our container runtime
       shell: |
               cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
               overlay
               br_netfilter
               EOF

     - name: setting up pre-requisites for containerd
       shell: |
               sudo modprobe overlay
               sudo modprobe br_netfilter
     
     - name: sysctl params required by setup, params persist across reboots
       shell: |
               cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
               net.bridge.bridge-nf-call-iptables  = 1
               net.bridge.bridge-nf-call-ip6tables = 1
               net.ipv4.ip_forward                 = 1
               EOF


     - name: make settings applicable without restart
       command: sudo sysctl --system

# ipv4 강제로 설정
     - name: set proc/sys/net/ipv4/ip_forward
       shell: |
               sudo sysctl -w net.ipv4.ip_forward=1

     - name: installing containerd and settings its config. restart as well.
       shell: |
               sudo yum-config-manager     --add-repo     https://download.docker.com/linux/centos/docker-ce.repo
               sudo yum install -y containerd.io
               sudo mkdir -p /etc/containerd
               sudo containerd config default | sudo tee /etc/containerd/config.toml
               sudo systemctl restart containerd

     - name: Create a kube repo file
       file:
         path: "/etc/yum.repos.d/kubernetes.repo"
         state: "touch"

     - name: write repo information in kube repo file
       blockinfile:
         path: "/etc/yum.repos.d/kubernetes.repo"
         block: |
                [kubernetes]
                name=Kubernetes
                baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64
                enabled=1
                gpgcheck=1
                repo_gpgcheck=1
                gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg

     - name: install kubernetes
       shell: |
               sudo yum install -y kubelet kubeadm kubectl
               sudo systemctl enable --now kubelet
               sudo systemctl start kubelet

master-setup.yml

- hosts: masters
  become: yes
  tasks:
    - name: start the cluster
      shell: kubeadm init --pod-network-cidr=192.168.0.0/16
      args:
        chdir: $HOME
      async: 60
      poll: 60

    - name: create a new directory to hold kube conf
      # ansible.builtin.file:
      #   path: /etc/kubernetes
      #   state: directory
      #   mode: '0755'
    
      become: yes
      become_user: root
      file:
        path: $HOME/.kube
        state: directory
        mode: 0755

    - name: copy configuration file to the newly created dir
      # become: true
      # become_user: root
      # ansible.builtin.copy:
      #   src: /etc/kubernetes/admin.conf
      #   dest: $HOME/.kube/config
      #   remote_src: true
    
      copy:
        src: /etc/kubernetes/admin.conf
        dest: $HOME/.kube/config
        remote_src: yes
        owner: root

    - name: set kubeconfig file permissions
      file:
        path: $HOME/.kube/config 
        owner: "{{ ansible_effective_user_id }}"
        group: "{{ ansible_effective_group_id }}"
        
    - name: Apply a calico manifset to init the pod network
      # args:
      #   chdir: $HOME
      # ansible.builtin.command: kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
    
      become: yes
      become_user: root
      shell: |
              curl https://raw.githubusercontent.com/projectcalico/calico/v3.24.5/manifests/calico.yaml -O
              kubectl apply -f calico.yaml 
      args:
        chdir: $HOME
        
    - name: Get the join command to be used by the worker
      become: yes
      become_user: root
      shell: kubeadm token create  --print-join-command
      register: kube_join_command

    - name: Save the join command to a local file
      become: yes
      local_action: copy content="{{ kube_join_command.stdout_lines[0] }}" dest="/etc/kube_join_command" mode=0777

Worker-setup.yaml

- hosts: workers
  become: yes
  gather_facts: yes

  tasks:
   - name: Fetch the join command we wrote to a file in previous step and move it to the worker node.
     become: yes
     copy:
       src: /etc/kube_join_command
       dest: /etc/kube_join_command
       mode: 0777

   - name: Join the Worker node to the cluster.
     become: yes
     command: sh /etc/kube_join_command

Trouble shoot

# 오류발생하면 kubeadm reset 하고 playbook 다시 실행.
kubeadm reset


# ipv4 에러 인 경우 master, worker 노드에서 아래 명령어 실행하고 kubelet 재시작하고 playbook 다시 실행하면 됨
modprobe br_netfilter
echo 1 > /proc/sys/net/ipv4/ip_forward

jenkins pipeline build error

jerymy — Wed, 5 Jan 2022 22:57:20 +0900

k8s에 jenkins 2.319.1 설치후 pipeline 생성해서 build 할때
jenkins 화면의 build 로그에는 별 다른 에러 내용이 없으나 build 가 제대로 안되는 경우 발생

jenkins 컨테이너 로그를 확인해 보면 아래와 같은 메세지가 보임

org.csanchez.jenkins.plugins.kubernetes.KubernetesClientProvider$UpdateConnectionCount@1bbc917c failed

구글링 해보면 kubernetes-client-api plugin 최근 버전의 문제라고 나옴. 아래 페이지(https://issues.jenkins.io/browse/JENKINS-67484)에 있는 이전 버전을 받아서 설치하면 해결됨

jenkins plugin 파일로 설치는 plugin manager 화면의 advanced 탭에서 (확장자가 hpi 인 파일 업로드)

docker install on CentOS 8.x

jerymy — Wed, 29 Sep 2021 23:04:58 +0900

# install docker-ce, docker-ce-cli, containerd from https://docs.docker.com/engine/install/centos/

# Set up the repository
sudo yum install -y yum-utils

sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo


# Install Docker Engine
- Install the latest version of Docker Engine and containerd, or go to the next step to install a specific version:

# 가이드에는 아래 명령어로 되어있음 -> 실행하면 dependency 오류로 설치 안됨 -> 아래 --allowerasing 옵션 주면 podman 등 package remove 하면서 설치됨.

sudo yum install docker-ce docker-ce-cli containerd.io
sudo yum install docker-ce docker-ce-cli containerd.io --allowerasing


# Start Docker.
sudo systemctl start docker

# Verify that Docker Engine is installed correctly by running the hello-world image.
sudo docker run hello-world

# Uninstall Docker Engine

1. Uninstall the Docker Engine, CLI, and Containerd packages:

sudo yum remove docker-ce docker-ce-cli containerd.io


2. Images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers, and volumes:

sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd