1. 인삿말(개요 목차)

이 게시글에서는 Kubernetes에 Jenkins 구축에 대한 문서를 살펴보고, 예시만 안내드리는 글입니다.

2. 개요

이 글에서는 Kubernetes를 활용하여 Jenkins를 구축하는 방법을 단계별로 정리했습니다. Kubernetes는 컨테이너화된 애플리케이션을 자동으로 배포하고 스케일링하며 관리하는 오픈 소스 시스템이고, Jenkins는 CI/CD 파이프라인을 자동화하는 대표적인 도구입니다. 두 시스템을 결합하면 동적으로 확장 가능한 Jenkins 에이전트와 함께 자원을 효율적으로 사용하면서 자동화된 파이프라인을 운영할 수 있습니다.

본 문서에 포함된 YAML 매니페스트 파일이나 터미널 명령어는 실제로 Kubernetes와 Jenkins 환경을 구성하는 데 직접 사용 가능합니다. 또한 필요한 곳마다 네임스페이스, 서비스 어카운트, 퍼시스턴트 볼륨(Persistent Volume), 디플로이먼트(Deployment), 서비스(Service) 등을 생성하여 Jenkins를 손쉽게 사용할 수 있도록 안내합니다.

추가로, 프로덕션 환경에서 고려해야 하는 볼륨 구성과 노드 장애 시 데이터 보호 방안도 함께 언급합니다. 만약 Kubernetes 클러스터가 클라우드 환경(AWS, GCP, Azure 등)에서 동작하거나 온프레미스 환경에서 동작한다면, 해당 환경에 적합한 스토리지 클래스를 사용하여 퍼시스턴트를 보장해야 합니다.

아래 소제목별로 Jenkins를 Kubernetes에 배포하기 위한 절차를 구체적으로 살펴보고, 각 터미널 명령을 통해 어떤 효과를 얻을 수 있는지도 함께 설명합니다.

3. Jenkins를 Kubernetes 클러스터에서 활용해야 하는 이유

- 동적 확장: Jenkins 에이전트를 컨테이너로 배포하고, 필요한 시점에 자동으로 확장/축소할 수 있습니다.
- 자원 효율화: Kubernetes가 노드 자원을 모니터링하고 부하를 조정하므로, 특정 노드에 자원이 몰리지 않도록 효과적으로 스케줄링할 수 있습니다.
- 높은 가용성: Kubernetes의 오토힐링(Auto-healing) 기능을 통해 Pod이나 노드 장애 발생 시 자동으로 재시작 또는 재스케줄링이 가능합니다.

4. 준비 사항

Kubernetes 클러스터가 이미 구축되어 있고, kubectl 명령어를 사용할 수 있는 환경이 갖추어져 있어야 합니다. Jenkins를 로컬 스토리지 또는 클라우드 스토리지에 영구적으로 보존하려면 퍼시스턴트 볼륨 구성이 필요합니다. 또한 Jenkins 이미지는 jenkins/jenkins:lts 태그 등 안정 버전을 활용하길 권장합니다.

이제 아래 단계들을 따라가며 Jenkins 환경을 구축해봅시다. 각 과정에서 필요한 YAML 파일의 예시는 전부 제시하였고, 파일 생성 후 kubectl apply 혹은 create 명령어로 배포하게 됩니다.

5. 단계별 구축 과정

5.1. Git 리포지토리 복제

먼저, 예제에 필요한 매니페스트 파일이 GitHub에 저장되어 있다고 가정해 봅시다. 만약 준비된 리포지토리가 있다면 아래 명령으로 간단히 복제할 수 있습니다.

```bash

git clone https://github.com/scriptcamp/kubernetes-jenkins

```

이 명령을 실행하면 kubernetes-jenkins 라는 폴더가 생성되며, 그 안에 Jenkins 관련 Kubernetes 매니페스트 파일들이 포함됩니다.

5.2. 네임스페이스 생성

먼저 Jenkins 등 DevOps 관련 도구들을 하나의 네임스페이스로 구분하여 관리하는 것이 좋습니다. 예시로 devops-tools라는 네임스페이스를 생성해보겠습니다.

```bash

kubectl create namespace devops-tools

```

위 명령을 실행하면 devops-tools라는 네임스페이스가 생성됩니다. 이렇게 구분해두면 Kubernetes 자원(서비스 어카운트, 디플로이먼트, 서비스, PV/PVC 등)을 체계적으로 관리하고, 다른 애플리케이션과 격리하여 운영할 수 있는 이점을 얻을 수 있습니다.

5.3. 서비스 어카운트 생성

Kubernetes에서 Jenkins가 클러스터 리소스를 조작하려면 필요한 권한을 갖춘 서비스 어카운트를 사용해야 합니다. 다음은 jenkins-admin이라는 이름의 서비스 어카운트, ClusterRole, 그리고 ClusterRoleBinding을 정의한 예시입니다.

```yaml

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRole

metadata:

 name: jenkins-admin

rules:

 - apiGroups: [""]

  resources: ["*"]

  verbs: ["*"]

---

apiVersion: v1

kind: ServiceAccount

metadata:

 name: jenkins-admin

 namespace: devops-tools

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRoleBinding

metadata:

 name: jenkins-admin

roleRef:

 apiGroup: rbac.authorization.k8s.io

 kind: ClusterRole

 name: jenkins-admin

subjects:

- kind: ServiceAccount

 name: jenkins-admin

 namespace: devops-tools

```

위 구성은 Jenkins Pod가 이 서비스를 통해 클러스터 리소스에 접근할 수 있도록 합니다.
이제 실제로 해당 파일을 적용해봅시다.

```bash

kubectl apply -f serviceAccount.yaml

```

이 명령을 실행하면 앞서 정의한 ClusterRole(jenkins-admin), ServiceAccount(jenkins-admin), 그리고 ClusterRoleBinding이 생성됩니다. 이를 통해 Jenkins가 Kubernetes 작업(파드 생성, 자원 확인 등)에 대한 권한을 행사할 수 있게 됩니다.

5.4. 퍼시스턴트 볼륨 생성

Jenkins 데이터는 파드가 재시작되더라도 보존되어야 합니다. 이를 위해 퍼시스턴트 볼륨(Persistent Volume)을 구성합니다. 예시로 로컬 스토리지를 사용한 volume.yaml 파일입니다.

```yaml

kind: StorageClass

apiVersion: storage.k8s.io/v1

metadata:

 name: local-storage

provisioner: kubernetes.io/no-provisioner

volumeBindingMode: WaitForFirstConsumer

---

apiVersion: v1

kind: PersistentVolume

metadata:

 name: jenkins-pv-volume

 labels:

  type: local

spec:

 storageClassName: local-storage

 claimRef:

  name: jenkins-pv-claim

  namespace: devops-tools

 capacity:

  storage: 10Gi

 accessModes:

  - ReadWriteOnce

 local:

  path: /mnt

 nodeAffinity:

  required:

   nodeSelectorTerms:

   - matchExpressions:

    - key: kubernetes.io/hostname

     operator: In

     values:

     - worker-node01

---

apiVersion: v1

kind: PersistentVolumeClaim

metadata:

 name: jenkins-pv-claim

 namespace: devops-tools

spec:

 storageClassName: local-storage

 accessModes:

  - ReadWriteOnce

 resources:

  requests:

   storage: 3Gi

```

여기서 worker-node01이라는 노드 호스트명을 자신의 실제 환경에 맞게 변경해야 합니다. 해당 노드의 호스트명을 확인하려면 아래 명령을 실행합니다.

```bash

kubectl get nodes

```

이 명령을 실행하면 현재 클러스터의 노드 정보를 확인할 수 있습니다. 그 중 Jenkins를 실행하고자 하는 노드의 이름을 worker-node01 대신에 기입하시면 됩니다.
로컬 스토리지의 경우, 해당 노드가 삭제되면 데이터가 함께 사라질 수 있다는 위험이 있습니다. 프로덕션 환경에서는 클라우드 스토리지 클래스나 외부 NFS, Ceph, GlusterFS 등 다양한 방법을 고려해야 합니다.

아래 명령으로 퍼시스턴트 볼륨 리소스를 생성합니다.

```bash

kubectl create -f volume.yaml

```

이 명령을 실행하면 local-storage라는 StorageClass와 jenkins-pv-volume이라는 PersistentVolume, jenkins-pv-claim이라는 PersistentVolumeClaim이 생성되어, Jenkins가 사용할 스토리지가 준비됩니다. 파드가 재시작되어도 Jenkins 홈 디렉터리(/var/jenkins_home)에 저장된 데이터는 보존됩니다.

5.5. Jenkins 디플로이먼트 생성

아래 deployment.yaml 예시는 Jenkins를 1개의 레플리카로 배포하는 설정을 담고 있습니다. 여기서 중요한 점은 퍼시스턴트 볼륨을 마운트하는 부분, 그리고 Jenkins Pod가 적절한 권한과 유저를 갖도록 securityContext를 지정했다는 것입니다.

```yaml

apiVersion: apps/v1

kind: Deployment

metadata:

 name: jenkins

 namespace: devops-tools

spec:

 replicas: 1

 selector:

  matchLabels:

   app: jenkins-server

 template:

  metadata:

   labels:

    app: jenkins-server

  spec:

   securityContext:

    fsGroup: 1000

    runAsUser: 1000

   serviceAccountName: jenkins-admin

   containers:

    - name: jenkins

     image: jenkins/jenkins:lts

     resources:

      limits:

       memory: "2Gi"

       cpu: "1000m"

      requests:

       memory: "500Mi"

       cpu: "500m"

     ports:

      - name: httpport

       containerPort: 8080

      - name: jnlpport

       containerPort: 50000

     livenessProbe:

      httpGet:

       path: "/login"

       port: 8080

      initialDelaySeconds: 90

      periodSeconds: 10

      timeoutSeconds: 5

      failureThreshold: 5

     readinessProbe:

      httpGet:

       path: "/login"

       port: 8080

      initialDelaySeconds: 60

      periodSeconds: 10

      timeoutSeconds: 5

      failureThreshold: 3

     volumeMounts:

      - name: jenkins-data

       mountPath: /var/jenkins_home

   volumes:

    - name: jenkins-data

     persistentVolumeClaim:

      claimName: jenkins-pv-claim

```

livenessProbe와 readinessProbe는 Jenkins 컨테이너의 상태를 주기적으로 확인하여, 문제가 있을 시 Kubernetes가 파드를 재시작하게 하거나 트래픽을 전달하지 않도록 도와줍니다. 로컬 스토리지 대신 emptyDir나 호스트 디렉터리를 사용하는 방법도 있지만, 지속적인 데이터 보존이 어렵다는 한계가 있습니다.

이제 아래 명령어로 해당 디플로이먼트를 생성합니다.

```bash

kubectl apply -f deployment.yaml

```

이 명령을 실행하면 jenkins라는 디플로이먼트가 생성되고, devops-tools 네임스페이스 안에서 Jenkins Pod가 실행됩니다.

배포 상태를 확인해보려면 아래 명령어를 사용할 수 있습니다.

```bash

kubectl get deployments -n devops-tools

```

그리고 디플로이먼트 상세 정보를 보려면 다음을 입력합니다.

```bash

kubectl describe deployments --namespace=devops-tools

```

이 명령을 실행하면 디플로이먼트 내 파드 상태, 이벤트, 리비전 등을 상세히 알 수 있어 문제 해결이나 튜닝 시에 도움이 됩니다.

5.6. 서비스(Service)로 Jenkins 외부 접근

이제 Jenkins 디플로이먼트를 외부에서 접근할 수 있도록 NodePort 유형의 서비스를 생성해야 합니다. service.yaml 예시는 다음과 같습니다.

```yaml

apiVersion: v1

kind: Service

metadata:

 name: jenkins-service

 namespace: devops-tools

 annotations:

  prometheus.io/scrape: 'true'

  prometheus.io/path: /

  prometheus.io/port: '8080'

spec:

 selector:

  app: jenkins-server

 type: NodePort

 ports:

  - port: 8080

   targetPort: 8080

   nodePort: 32000

```

type이 NodePort로 설정되어 있으므로, Jenkins는 클러스터 내 모든 노드 IP의 32000번 포트를 통해 접근할 수 있게 됩니다.
이제 아래 명령어를 실행합니다.

```bash

kubectl apply -f service.yaml

```

서비스가 정상적으로 생성되면, 브라우저에서 http://노드IP:32000 으로 접속하여 Jenkins에 접근할 수 있습니다.

노드 IP는 클러스터에 속해있는 어떤 노드든 상관없지만, 외부에서 접근 가능해야 합니다. 로드밸런서를 사용하는 환경이라면 type을 LoadBalancer로 설정하거나, Ingress를 구성해 도메인 기반으로 접근할 수도 있습니다.

6. 초기 관리자 비밀번호 확인

Jenkins에 처음 접속하면 초기 관리자 비밀번호를 요구합니다. 이는 Jenkins Pod의 log 또는 /var/jenkins_home/secrets/initialAdminPassword 파일에서 확인 가능합니다. 아래와 같이 파드 목록을 확인합니다.

```bash

kubectl get pods --namespace=devops-tools

```

그리고 파드 이름을 확인한 뒤, 해당 파드의 로그를 출력해봅니다.

```bash

kubectl logs jenkins-deployment-2539456353-j00w5 --namespace=devops-tools

```

로그 하단에 초기 관리자 비밀번호가 출력됩니다. 또는 exec 명령어를 통해 직접 파일을 읽을 수 있습니다.

```bash

kubectl exec -it jenkins-559d8cd85c-cfcgk -n devops-tools cat /var/jenkins_home/secrets/initialAdminPassword

```

이 비밀번호를 Jenkins 초기 설정 화면에 입력한 뒤, 플러그인 설치와 관리자 계정 생성을 진행하면 Jenkins를 본격적으로 사용할 수 있게 됩니다.

출처: [Jenkins] https://www.jenkins.io/doc/book/installing/kubernetes/ (CC BY-SA 4.0)