26M19b
좋아. 기존 SOP 체계에 아래 컴포넌트들을 별도 공통 플랫폼 SOP 영역으로 추가하는 게 좋습니다.
추가 대상은 크게 이렇게 묶는 게 자연스럽습니다.
1. Identity / Access : Keycloak
2. CI / Automation : Jenkins
3. GitOps / CD : ArgoCD
4. Artifact Repository : Nexus
5. Container Registry : Harbor
6. Local / CSI Storage : OpenEBS특히 귀사 환경에서는 이 6개가 단독 서비스라기보다 Kubernetes 운영, GitOps, Air-gap 반입, 인증/인가, 배포 자동화의 기반 서비스라서 장애 SOP뿐 아니라 변경 SOP, 백업/복구 SOP, 권한관리 SOP가 반드시 같이 있어야 합니다.
1. Keycloak SOP
Keycloak은 귀사 환경에서 SSO 브로커, LDAP/AD 연동, OIDC/JWT 발급, Kubernetes kubelogin, ArgoCD/Jenkins/Harbor/Nexus 인증 연동의 중심으로 봐야 합니다. Keycloak은 SSO, OIDC, OAuth 2.0, SAML, LDAP/AD User Federation, Role/Group/Client 관리 기능을 제공하므로 SOP는 단순 로그인 장애 대응이 아니라 Realm / Client / Group / Token / LDAP / 인증서 / DB / 세션까지 포함해야 합니다. (Keycloak)
1.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| Keycloak 일일 상태 점검 | Pod 상태, readiness/liveness, DB 연결, realm 접근, token 발급 확인 |
| Realm 생성/변경 절차 | realm name, token lifetime, session timeout, password policy, MFA 정책 |
| Client 생성/변경 절차 | OIDC client, redirect URI, client secret, PKCE, audience, scope 설정 |
| Client Secret Rotation 절차 | secret 교체, 영향 시스템 확인, rollback secret 보관 |
| LDAP/AD Federation 설정 절차 | LDAP URL, bind DN, group mapper, user mapper, sync 주기 |
| LDAP/AD 동기화 점검 절차 | 신규 사용자/그룹 반영, disabled user 반영, sync failure 확인 |
| Group/Role Mapping 절차 | LDAP group → Keycloak group/role → app role mapping |
| Token Claim Mapping 절차 | username, email, groups, roles, tenant, namespace claim |
| kubelogin 연동 절차 | kube-apiserver OIDC 설정, kubeconfig 발급, RBAC 연결 |
| ArgoCD SSO 연동 절차 | OIDC client, group claim, ArgoCD RBAC mapping |
| Jenkins SSO 연동 절차 | OIDC/SAML plugin, admin group mapping, fallback admin |
| Harbor/Nexus SSO 연동 절차 | OIDC/LDAP 연결, project/repository 권한 mapping |
| MFA 설정 절차 | OTP/WebAuthn/Passkey 정책, 관리자 예외 계정 |
| Password Policy 변경 절차 | 복잡도, 만료, lockout, brute-force 보호 |
| Session/Token Lifetime 변경 절차 | access token, refresh token, SSO idle/max timeout |
| Admin 계정 관리 절차 | break-glass 계정, MFA, 사용 기록, 비상 접근 |
| Realm Export 절차 | realm 설정 백업, client/role/group export |
| Keycloak DB 백업 절차 | PostgreSQL 백업, schema/version 일치성 확인 |
| Keycloak 업그레이드 절차 | migration note 확인, DB 백업, realm export, rollback |
| Health/Metrics 설정 절차 | health endpoint, metrics endpoint, Prometheus scrape 설정 |
Keycloak은 버전별로 health/metrics 옵션이 달라질 수 있습니다. 예를 들어 공식 릴리스 노트에서는 metrics-enabled와 health-enabled가 분리된 이력이 있으므로, probe/metric SOP는 현재 사용 버전 기준으로 작성해야 합니다. (Keycloak)
1.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| Keycloak 로그인 장애 대응 | 전체 SSO 로그인 실패 |
| 특정 애플리케이션 로그인 장애 대응 | ArgoCD/Jenkins/Harbor/Nexus 중 일부만 로그인 실패 |
| LDAP/AD 연동 장애 대응 | 사용자 인증 실패, 그룹 미반영 |
| Token 발급 실패 대응 | invalid client, invalid grant, client secret mismatch |
| Token 검증 실패 대응 | issuer/audience/realm/JWKS 오류 |
| Redirect URI 오류 대응 | invalid redirect_uri |
| Client Secret 만료/불일치 대응 | app에서 OIDC 인증 실패 |
| JWKS 조회 실패 대응 | application token validation 실패 |
| Group Claim 누락 대응 | 로그인은 되지만 권한 없음 |
| Admin Console 접속 장애 대응 | admin UI 5xx/timeout |
| Keycloak DB 연결 장애 대응 | login timeout, pod crash, startup failure |
| Keycloak Pod CrashLoopBackOff 대응 | DB, config, theme, SPI, image 문제 |
| Keycloak Readiness 실패 대응 | health 설정, DB connection pool, startup delay |
| Session 폭증 대응 | DB 부하, login latency 증가 |
| Brute-force lockout 대응 | 정상 사용자 계정 잠김 |
| 인증서 만료 대응 | TLS handshake 실패, OIDC discovery 실패 |
| Realm 설정 오변경 대응 | 전체 인증 장애 |
| LDAP group mapping 오변경 대응 | 권한 전체 누락 |
| Token lifetime 오설정 대응 | 너무 잦은 재로그인 또는 과도한 세션 유지 |
| Keycloak 업그레이드 후 인증 장애 | migration, adapter/client 호환성 문제 |
1.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| Keycloak Realm 신규 생성 | realm 설정, token 정책, 관리자 그룹, 백업 |
| OIDC Client 신규 생성 | redirect URI, secret, scope, claim, 테스트 계정 |
| LDAP/AD 연동 변경 | sync 영향, group mapper, rollback |
| Token Claim 추가/변경 | 영향 애플리케이션, JWT 샘플, 검증 |
| ArgoCD/Jenkins/Harbor/Nexus SSO 연동 | client 설정, group claim, 권한 mapping |
| Keycloak 인증서 갱신 | ingress TLS, internal TLS, trust chain |
| Keycloak DB 백업/복구 리허설 | DB restore, realm/client 유효성 검증 |
| Keycloak 업그레이드 | migration guide, DB 백업, export/import, rollback |
2. Jenkins SOP
Jenkins는 귀사 환경에서 CI 검증, GitOps 배포 전 검증, air-gap artifact 반입 검증, Kubernetes 설치 자동화, 운영 자동화 job 실행 플랫폼입니다. Jenkins의 credential은 controller에 암호화 저장되며 Pipeline에서는 credential ID로 사용되는 구조이므로, credential 관리와 controller 백업/복구가 매우 중요합니다. ([Jenkins][3])
2.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| Jenkins 일일 상태 점검 | controller/agent 상태, queue, executor, failed job |
| Jenkins Controller 상태 점검 | CPU, memory, disk, GC, thread, response time |
| Jenkins Agent 상태 점검 | Kubernetes dynamic agent, node agent, agent disconnect |
| Pipeline 생성/변경 절차 | Jenkinsfile 위치, branch, credential, shared library |
| Shared Library 변경 절차 | 공통 pipeline library versioning, rollback |
| Credential 생성/변경 절차 | Git, Nexus, Harbor, SSH, kubeconfig, S3 key |
| Credential Rotation 절차 | 영향 job 파악, dual credential 기간, rollback |
| Plugin 설치/업그레이드 절차 | dependency, compatibility, rollback, restart 필요성 |
| Jenkins 권한 관리 절차 | admin/dev/operator 권한 분리 |
| Job 권한 위임 절차 | Folder 기반 권한, 팀별 운영권 |
| Kubernetes Agent Template 관리 | image, SA, volume, resource limit |
| Jenkinsfile CI 검증 표준 | yaml lint, helm template, kubeconform, conftest, policy check |
| Air-gap 패키지 반입 검증 Job | checksum, signature, SBOM, CVE scan |
| Jenkins 로그 관리 절차 | build log retention, controller log, audit log |
| Jenkins 백업 절차 | JENKINS_HOME, jobs, config, plugins, credentials 관련 파일 |
| Jenkins 복구 절차 | controller 재기동, backup restore, credential decrypt 확인 |
| Jenkins 업그레이드 절차 | LTS/core/plugin matrix, test controller 검증 |
| Jenkins Job 정리 절차 | 오래된 job, workspace, artifact, build history cleanup |
Jenkins 공식 문서는 전체 $JENKINS_HOME 백업이 controller 보존에 필요하고, master.key/controller key는 일반 백업에 함께 넣지 말고 별도 보안 위치에 보관해야 한다고 설명합니다. 따라서 귀사 SOP에는 “Jenkins 일반 백업”과 “Jenkins key 보관/복구”를 분리해야 합니다. ([Jenkins][4])
2.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| Jenkins Controller 접속 장애 | UI/API 접속 불가 |
| Jenkins Controller CrashLoopBackOff | plugin, config, disk, permission 문제 |
| Jenkins Queue 적체 대응 | executor 부족, agent 기동 실패 |
| Kubernetes Agent 생성 실패 대응 | Pod Pending, image pull, SA/RBAC, quota |
| Pipeline 전체 실패 대응 | Git/Nexus/Harbor/credential 공통 장애 |
| 특정 Pipeline 실패 대응 | Jenkinsfile 오류, 환경변수, script 오류 |
| Credential 오류 대응 | Git clone 실패, registry login 실패, kube API 실패 |
| Plugin 충돌 대응 | startup failure, UI broken, job 실행 실패 |
| Jenkins 권한 오류 대응 | job 실행/수정/credential 접근 불가 |
| Workspace 용량 부족 대응 | build 실패, disk full |
| Build artifact 용량 폭증 대응 | JENKINS_HOME full |
| Git webhook 미수신 대응 | SCM trigger 장애 |
| Nexus/Harbor 연동 실패 대응 | artifact upload/download 실패 |
| Kubernetes 배포 검증 실패 대응 | kubeconform, helm template, policy check 실패 |
| Script Console 오남용 대응 | 보안사고, 임의 명령 실행 가능성 |
| Jenkins 백업 실패 대응 | backup job 실패, snapshot 불일치 |
| Jenkins 복구 실패 대응 | plugin mismatch, credential decrypt 실패 |
Jenkins의 Overall/Administer 권한은 plugin 설치, Script Console 사용, controller/agent에서 임의 코드 실행까지 가능하므로, SOP에는 관리자 권한 부여/회수/감사 절차를 반드시 포함해야 합니다. ([Jenkins][5])
2.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| 신규 CI Pipeline 생성 | repo, branch, Jenkinsfile, credential, 검증 단계 |
| Jenkins Shared Library 변경 | 영향 pipeline 목록, test job, rollback |
| Jenkins Plugin 업그레이드 | plugin list, dependency, test controller 검증 |
| Jenkins Credential Rotation | 대상 job, 교체 순서, 실패 시 rollback |
| Jenkins Controller 재기동 | build 중단 여부, queue drain, 사후 확인 |
| Jenkins Agent Image 변경 | image 반입, scan, pod template 변경 |
| Jenkins 백업/복구 리허설 | JENKINS_HOME restore, credential decrypt, job 실행 |
| Air-gap artifact 반입 Job 변경 | checksum, signature, SBOM, Nexus/Harbor 등록 |
3. ArgoCD SOP
ArgoCD는 귀사 환경에서 GitOps 배포의 핵심 제어면입니다. ArgoCD는 Git repository의 desired state와 cluster live state를 비교하고, 차이가 나면 OutOfSync 상태로 보여주며 수동/자동 sync를 수행합니다. 또한 SSO, RBAC, rollback, drift detection, Prometheus metrics, audit trail 등을 지원하므로 SOP는 단순 배포 도구가 아니라 운영 통제 도구 기준으로 작성해야 합니다. (Argo CD)
3.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| ArgoCD 일일 상태 점검 | app health, sync, repo-server, application-controller |
| Application 생성/변경 절차 | repo, path, targetRevision, destination, namespace |
| AppProject 생성/변경 절차 | source repo, destination cluster/namespace, resource whitelist |
| App-of-Apps 운영 절차 | root app, child app, sync order |
| ApplicationSet 운영 절차 | generator, cluster/list/git matrix 관리 |
| Sync Policy 설정 절차 | manual/auto sync, prune, self-heal |
| Sync Window 설정 절차 | 배포 허용/금지 시간 |
| Diff Ignore 설정 절차 | operator-managed field, webhook mutation field |
| Resource Hook 사용 절차 | PreSync, Sync, PostSync, SyncFail |
| Sync Wave 설정 절차 | CRD → namespace → operator → workload 순서 |
| ArgoCD RBAC 설정 절차 | Keycloak group claim → ArgoCD role mapping |
| Repository Credential 등록 절차 | Git/Helm repo credential, SSH known_hosts |
| Cluster Credential 등록 절차 | 관리 대상 cluster 등록, token rotation |
| ArgoCD Notification 설정 | sync fail, degraded, out-of-sync 알림 |
| Drift 점검 절차 | 수동 변경 탐지, Git 기준 원복 |
| ArgoCD Backup 절차 | argocd admin export, secret/config 백업 |
| ArgoCD Restore 절차 | argocd admin import, repo/cluster credential 확인 |
| ArgoCD 업그레이드 절차 | CRD, controller, repo-server, Dex/Redis 영향 |
ArgoCD RBAC는 자체 사용자 관리가 아니라 SSO 또는 로컬 사용자를 기반으로 role을 매핑하며, 기본 admin은 superuser입니다. 따라서 기본 admin 비활성화/보호, Keycloak group claim 기반 role mapping, AppProject 단위 RBAC가 핵심 SOP가 됩니다. (Argo CD)
3.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| ArgoCD UI/API 접속 장애 | UI 접속 불가, CLI login 실패 |
| ArgoCD SSO 로그인 장애 | Keycloak/OIDC 연동 실패 |
| Application OutOfSync 대응 | Git과 live state 불일치 |
| Application Degraded 대응 | 리소스 unhealthy |
| Sync 실패 대응 | 권한 부족, CRD 없음, webhook 실패, validation 실패 |
| Repo-server 장애 대응 | manifest generation 실패 |
| Git repo 접근 실패 대응 | credential, SSH known_hosts, TLS |
| Helm chart rendering 실패 대응 | values 오류, dependency 누락 |
| Kustomize build 실패 대응 | patch, overlay, resource path 오류 |
| Application controller 지연 대응 | app reconcile delay |
| Redis 장애 대응 | session/cache 영향 |
| Cluster credential 만료 대응 | 대상 cluster sync 실패 |
| AppProject 권한 오류 대응 | source/destination not permitted |
| Prune 오동작 대응 | 의도치 않은 리소스 삭제 위험 |
| Self-heal 오동작 대응 | 수동 변경 즉시 원복 |
| CRD sync 순서 오류 대응 | CRD 적용 전 CR 생성 실패 |
| Webhook/Admission 장애로 sync 실패 | OPA/Gatekeeper/cert-manager webhook timeout |
| ArgoCD drift 감지 실패 대응 | tracking label/annotation 문제 |
| ArgoCD 백업/복구 실패 대응 | import 후 credential/secret 누락 |
ArgoCD는 argocd admin export/import로 데이터를 백업/복구할 수 있지만, namespace를 잘못 지정해도 export가 실패하지 않을 수 있다는 주의가 공식 문서에 있으므로 백업 SOP에는 namespace 검증 단계를 넣는 게 좋습니다. (Argo CD)
3.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| 신규 Application 등록 | repo/path/revision/destination/project |
| AppProject 신규 생성 | source repo, destination, resource allow/deny |
| Auto Sync 활성화 | prune/self-heal 여부, 영향 namespace |
| Sync Window 변경 | 배포 가능 시간, freeze 기간 |
| ArgoCD RBAC 변경 | Keycloak group, role, project scope |
| Git repository credential 변경 | SSH key/token rotation |
| 대상 cluster 등록/삭제 | cluster secret, SA/RBAC, sync 검증 |
| ArgoCD 업그레이드 | CRD 변경, rollback, app health 검증 |
| App-of-Apps 구조 변경 | root app 영향, child app sync order |
4. Nexus Repository SOP
Nexus는 귀사 환경에서 Maven/npm/PyPI/raw/Helm 등 artifact 저장소, 그리고 air-gap 환경의 외부 의존성 반입 창구 역할을 합니다. Nexus는 blob store와 metadata/database를 함께 다루므로, 백업/복구 SOP가 매우 중요합니다. Sonatype 문서도 Nexus Repository는 blob store와 metadata/database를 함께 백업해야 데이터 정합성을 유지할 수 있다고 설명합니다. (Sonatype 도움말)
4.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| Nexus 일일 상태 점검 | 서비스 상태, repo별 접근, disk/blob store 사용량 |
| Repository 생성 절차 | hosted/proxy/group, format별 Maven/npm/PyPI/raw/Helm |
| Repository 권한 설정 절차 | role, privilege, LDAP group mapping |
| Blob Store 생성/변경 절차 | file/object store, repository mapping |
| Cleanup Policy 생성 절차 | format별 retention, preview, 승인 |
| Cleanup Task 운영 절차 | repository cleanup, unused asset blobs, compact blob store |
| Proxy Repository 설정 절차 | 외부 repo mirror, cache TTL, negative cache |
| Air-gap 반입 Repository 운영 | 외부 artifact 승인 후 hosted repo 등록 |
| Role/Privilege 관리 절차 | service account, team account, 최소권한 |
| LDAP 연동 절차 | LDAP realm, group mapping, cache clear |
| Anonymous 접근 관리 절차 | 허용/차단 기준 |
| Component 검색/추적 절차 | artifact version, uploader, repository |
| Repository Quota/용량 점검 | blob store 사용량, format별 증가율 |
| Blob Store 백업 절차 | blob 디렉토리/object store 백업 |
| Database 백업 절차 | H2/PostgreSQL 백업 |
| Nexus 복구 절차 | DB + blob store 정합성, node ID 복구 |
| Nexus 업그레이드 절차 | DB migration, plugin, repository format 검증 |
Nexus cleanup policy는 기본 설정이 아니며, 정책 생성 → repository에 정책 연결 → cleanup task 정기 실행 → compact blob store로 공간 회수 순서가 필요합니다. 따라서 “삭제 정책”과 “실제 공간 회수”를 구분한 SOP가 필요합니다. (Sonatype 도움말)
4.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| Nexus UI/API 접속 장애 | 접속 불가, 5xx |
| Repository download 실패 | Maven/npm/PyPI pull 실패 |
| Artifact upload 실패 | deploy 권한, quota, blob store 문제 |
| Blob Store 용량 부족 대응 | disk full, upload 실패 |
| Cleanup Policy 오동작 대응 | artifact 의도치 않은 삭제 |
| Compact Blob Store 장시간 실행 대응 | I/O 부하, task stuck |
| Proxy Repository cache 장애 | 외부 repo mirror 불일치, cache stale |
| Group Repository 응답 장애 | member repo 장애, routing 문제 |
| LDAP 로그인 장애 | 인증 실패, group mapping 실패 |
| Role/Privilege 오류 대응 | 정상 사용자가 artifact 접근 불가 |
| Service Account token 오류 | CI pipeline download/upload 실패 |
| Nexus DB 연결 장애 | startup 실패, metadata 조회 실패 |
| Blob/DB 불일치 대응 | artifact는 있는데 metadata 없음 |
| Search Index 장애 | 검색 불가, component listing 오류 |
| Nexus 백업 실패 대응 | DB export 실패, blob backup 지연 |
| Nexus 복구 실패 대응 | DB/blob backup 시점 불일치 |
| Nexus 업그레이드 후 장애 | repository format, DB migration 문제 |
중요한 주의점이 있습니다. Sonatype 문서는 Nexus Repository 3.83.0~3.89.1에서 Verify and Repair/Data Repair Plan 작업이 유효한 asset을 잘못 삭제할 수 있는 known issue가 있었고 3.90.0에서 수정되었다고 안내합니다. 따라서 Nexus 데이터 복구/repair SOP에는 “현재 버전 확인 후 repair task 실행”을 필수 단계로 넣어야 합니다. (Sonatype 도움말)
4.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| 신규 Repository 생성 | format, hosted/proxy/group, 권한, retention |
| Cleanup Policy 적용 | preview 결과, 제외 artifact, rollback 가능성 |
| Blob Store 증설/이관 | 대상 repo, downtime, 백업, 검증 |
| LDAP 연동 변경 | group mapping, admin fallback, cache clear |
| Service Account 생성 | CI job, 권한 범위, 만료/rotation |
| Nexus 백업/복구 리허설 | DB/blob 동시성, node ID, artifact pull 검증 |
| Nexus 업그레이드 | version issue, DB migration, repository smoke test |
| Air-gap artifact 대량 반입 | checksum, SBOM, license, repository 등록 |
5. Harbor SOP
Harbor는 귀사 환경에서 air-gap container image registry, vulnerability scanning, robot account, replication, project quota, audit log, image retention/GC의 중심입니다. Harbor 공식 문서도 관리 항목으로 인증, 사용자, global setting, project quota, replication, vulnerability scanning, garbage collection, audit log, backup/restore 등을 제시합니다. ([Harbor][12])
5.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| Harbor 일일 상태 점검 | core, registry, jobservice, database, redis, trivy |
| Project 생성/변경 절차 | project naming, public/private, quota, owner |
| Project 권한 관리 절차 | developer/maintainer/project admin |
| Robot Account 생성/변경 절차 | CI/CD pull/push 계정, scope 제한 |
| Robot Token Rotation 절차 | Jenkins/ArgoCD/K8s imagePullSecret 영향 |
| Image Push/Pull 검증 절차 | docker/containerd/nerdctl login, pull test |
| Image Retention Policy 설정 | tag pattern, count/time based retention |
| Garbage Collection 운영 절차 | dry-run, worker 수, schedule, 영향 확인 |
| Vulnerability Scan 절차 | Trivy DB 업데이트, scan all, critical image 차단 |
| CVE 예외 승인 절차 | false positive, business exception, 만료일 |
| Project Quota 관리 절차 | project별 storage quota, 증설 승인 |
| Replication 설정 절차 | source/target registry, push/pull mode |
| Proxy Cache 설정 절차 | 외부 registry mirror, air-gap 반입 전 cache |
| OCI Artifact 관리 절차 | Helm chart, SBOM, signature artifact |
| Notary/Signature 검증 절차 | 서명된 image만 배포 |
| Audit Log 관리 절차 | login, push, pull, delete, policy 변경 |
| Harbor Backup 절차 | K8s resource, PV, DB, registry data |
| Harbor Restore 절차 | Velero/DB/registry restore, image pull 검증 |
| Harbor 업그레이드 절차 | Helm chart, DB migration, Trivy, jobservice 영향 |
Harbor에서 image/artifact를 삭제해도 즉시 공간이 반환되지 않으며, 참조되지 않는 blob을 제거하려면 garbage collection을 실행해야 합니다. GC는 dry-run을 지원하므로, 대용량 registry에서는 dry-run → 승인 → 본 실행 순서로 SOP를 구성하는 것이 안전합니다. ([Harbor][13])
5.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| Harbor UI/API 접속 장애 | UI/API 5xx |
| Image Pull 실패 대응 | ImagePullBackOff, unauthorized, manifest unknown |
| Image Push 실패 대응 | denied, blob upload invalid, quota exceeded |
| Robot Account 오류 대응 | CI/CD push/pull 실패 |
| OIDC/LDAP 로그인 장애 | 사용자 로그인 실패 |
| Project 권한 오류 대응 | push/pull/delete 권한 불일치 |
| Registry storage full 대응 | push 실패, jobservice 오류 |
| Garbage Collection 실패 대응 | GC stuck, space 미회수 |
| Retention Policy 오동작 대응 | 필요한 image/tag 삭제 위험 |
| Vulnerability Scanner 장애 | scan pending, Trivy DB update 실패 |
| CVE DB 업데이트 실패 대응 | air-gap 환경 DB 반입 실패 |
| Replication 실패 대응 | target registry 접근 불가, auth 오류 |
| Harbor DB 장애 대응 | metadata 조회 실패, project list 오류 |
| Redis 장애 대응 | job queue/session 영향 |
| Jobservice 장애 대응 | scan/GC/replication job 미실행 |
| Registry backend 장애 대응 | blob read/write 실패 |
| Image 서명 검증 실패 대응 | admission에서 image 배포 차단 |
| Harbor 백업/복구 실패 대응 | DB/registry data 불일치 |
Harbor의 Kubernetes 배포는 Velero를 사용한 backup/restore 시나리오가 공식 문서에 포함되어 있으며, Harbor 관련 K8s 리소스와 database/registry/jobservice/Trivy 등 PV 데이터를 함께 고려해야 합니다. ([Harbor][14])
5.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| 신규 Project 생성 | quota, owner, robot account, retention |
| Robot Account Rotation | Jenkins/ArgoCD/imagePullSecret 변경 |
| Image Retention Policy 적용 | dry-run, 제외 tag, rollback 불가성 |
| Garbage Collection 실행 | dry-run 결과, worker 수, 성능 영향 |
| Vulnerability DB 반입 | Trivy DB bundle, 검증, scan test |
| Harbor Replication 설정 | source/target, credential, schedule |
| Harbor Storage 증설 | registry PV, DB, Redis, jobservice 영향 |
| Harbor 업그레이드 | DB backup, Helm chart, image pull smoke test |
| Harbor 복구 리허설 | image push/pull, project/robot/account 검증 |
6. OpenEBS SOP
OpenEBS는 귀사 환경에서 Longhorn과 별개로 LocalPV HostPath/LVM/ZFS, 또는 Mayastor 기반 replicated storage를 사용할 수 있는 storage layer입니다. OpenEBS Local PV LVM은 StorageClass에서 volgroup, scheduler, reclaim policy, volume expansion 등을 다루므로, SOP는 단순 PVC 생성이 아니라 노드 디스크/VG/LV/CSI/PVC/Pod scheduling까지 포함해야 합니다. (https://openebs.io)
6.1 일반 운영 SOP
| SOP 항목 | 주요 내용 |
|---|---|
| OpenEBS 일일 상태 점검 | controller, CSI node, provisioner, NDM 상태 |
| StorageClass 생성/변경 절차 | LocalPV HostPath/LVM/ZFS/Mayastor 구분 |
| LVM VolumeGroup 생성 절차 | 대상 disk, VG name, node label, capacity |
| LocalPV LVM PVC 생성 절차 | storageClass, accessMode, node affinity |
| LocalPV 용량 점검 절차 | VG free, LV count, thin pool 사용률 |
| StorageClass Scheduler 설정 | SpaceWeighted, CapacityWeighted, VolumeWeighted |
| ReclaimPolicy 관리 절차 | Retain/Delete 기준 |
| PVC 확장 절차 | allowVolumeExpansion, filesystem resize |
| Node 추가 시 OpenEBS 설정 | disk discovery, VG 생성, label/taint |
| Node drain 전 점검 | local PV가 붙은 pod, PDB, workload 이관 가능성 |
| Volume Snapshot/Backup 절차 | workload별 backup 방식 |
| OpenEBS Upgrade 절차 | CRD, CSI, engine, workload 영향 |
| OpenEBS Migration 절차 | LocalPV Device → LVM, cStor/Jiva → Mayastor 등 |
| OpenEBS Observability 절차 | CSI metrics, volume health, provisioning latency |
| 장애 전 사전점검 절차 | disk SMART, node disk pressure, kubelet mount 상태 |
OpenEBS Mayastor/Replicated Storage는 여러 노드에 volume replica를 유지해 고가용성/내구성을 제공하는 방향의 storage engine입니다. 반면 LocalPV 계열은 노드 로컬 디스크 의존성이 크므로, 어떤 workload에 OpenEBS를 적용할지에 따라 SOP가 달라져야 합니다. (https://openebs.io)
6.2 장애 SOP
| 장애 SOP 항목 | 대표 증상 |
|---|---|
| PVC Pending 대응 | StorageClass, VG 없음, topology mismatch |
| PV Provisioning 실패 대응 | CSI provisioner 오류, VG capacity 부족 |
| Pod FailedMount 대응 | mount option, filesystem, device path 문제 |
| Node 장애로 LocalPV 접근 불가 | local PV workload 중단 |
| VG 용량 부족 대응 | 신규 PVC 생성 실패 |
| LV 생성 실패 대응 | LVM metadata, thin pool full |
| PVC 확장 실패 대응 | filesystem resize, allowVolumeExpansion |
| OpenEBS CSI Node 장애 | mount/unmount 실패 |
| OpenEBS Controller 장애 | provisioning 중단 |
| NDM disk discovery 오류 | disk 미탐지, 잘못된 blockdevice claim |
| LocalPV 데이터 복구 대응 | Retain PV, node disk 직접 확인 |
| PV/PVC Terminating stuck 대응 | finalizer, volumeattachment 문제 |
| Mayastor replica degraded 대응 | replica 손실, rebuild 필요 |
| Mayastor volume offline 대응 | workload I/O 중단 |
| OpenEBS 업그레이드 후 장애 | CRD/CSI compatibility 문제 |
| Node drain 실패 대응 | local PV pod 이동 불가 |
| Snapshot/backup 실패 대응 | engine별 지원 여부, backup target 문제 |
OpenEBS 공식 문서는 legacy OpenEBS storage에서 최신 storage로의 migration 예시를 제공하며, LocalPV Device → LocalPV LVM, cStor/Jiva → Replicated/Mayastor 같은 흐름을 다룹니다. 따라서 migration SOP는 “기존 PVC 백업 → 신규 PVC 생성 → 앱 scale down → 데이터 복제 → 앱 재기동 → 검증 → 기존 PV 정리” 흐름으로 작성하는 것이 좋습니다. (https://openebs.io)
6.3 작업계획서 Case
| 작업계획서 Case | 포함할 내용 |
|---|---|
| 신규 OpenEBS StorageClass 생성 | engine, volgroup, topology, reclaimPolicy |
| 노드에 VG 추가 | disk list, pvcreate/vgcreate, label, capacity |
| PVC 확장 | workload 영향, filesystem resize, rollback 한계 |
| LocalPV workload 노드 점검 | pod 위치, node drain 가능성 |
| OpenEBS 업그레이드 | CRD/CSI/engine 순서, backup |
| LocalPV → LVM migration | 신규 PVC, 데이터 복사, cutover |
| cStor/Jiva → Mayastor migration | 신규 replicated PVC, downtime, 검증 |
| Mayastor replica 장애 대응 | replica rebuild, node/disk 점검 |
| OpenEBS 제거 | PV/PVC 정리, finalizer, CRD 삭제 위험 |
7. 6개 컴포넌트 공통 SOP도 따로 만들어야 함
위 도구들은 서로 얽혀 있으므로, 개별 SOP 외에 공통 연계 SOP가 필요합니다.
7.1 인증 연계 SOP
| SOP 항목 | 대상 |
|---|---|
| Keycloak 장애 시 영향도 판단 | ArgoCD, Jenkins, Harbor, Nexus, kubelogin |
| LDAP 장애 시 영향도 판단 | Keycloak, Nexus, Harbor, Jenkins |
| OIDC Client Secret Rotation | ArgoCD/Jenkins/Harbor/Nexus |
| Group Claim 변경 영향 분석 | 모든 RBAC 연동 시스템 |
| Break-glass 계정 사용 절차 | Keycloak, ArgoCD, Jenkins, Harbor, Nexus |
| 관리자 권한 정기 점검 | 전체 플랫폼 |
7.2 Air-gap Artifact Chain SOP
| SOP 항목 | 흐름 |
|---|---|
| 외부 artifact 반입 | 외부망 → 보안검토 → checksum/signature → Nexus/Harbor |
| Container image 반입 | 외부 registry → scan → Harbor push |
| Helm chart 반입 | 외부 chart → dependency pull → Nexus/Harbor/OCI |
| Maven/npm/PyPI 반입 | 외부 repo → Nexus hosted/proxy/group |
| CVE DB 반입 | 외부 DB → Harbor Trivy DB update |
| Jenkins plugin 반입 | plugin/download → checksum → Jenkins plugin dir |
| ArgoCD/Keycloak/Harbor image 반입 | image scan → Harbor 등록 → GitOps 배포 |
7.3 GitOps 배포 연계 SOP
| SOP 항목 | 흐름 |
|---|---|
| Manifest 변경 검증 | Git PR → Jenkins CI → ArgoCD Sync |
| Image tag 배포 | Harbor image push → Git tag 변경 → ArgoCD sync |
| Helm chart 배포 | Nexus/Harbor chart 등록 → Git values 변경 → ArgoCD sync |
| Secret 변경 | Secret source → sealed/external secret → ArgoCD sync |
| Rollback | Git revert → ArgoCD sync → smoke test |
| Drift 원복 | ArgoCD diff → Git 기준 원복 |
7.4 백업/복구 공통 SOP
| 컴포넌트 | 반드시 백업할 것 |
|---|---|
| Keycloak | PostgreSQL DB, realm export, client 설정, custom theme/SPI |
| Jenkins | JENKINS_HOME, jobs, config.xml, plugins, credentials 관련 파일, master.key 별도 보관 |
| ArgoCD | Application/AppProject/ApplicationSet, repo/cluster secrets, RBAC config |
| Nexus | DB/metadata, blob store, node ID, custom config |
| Harbor | DB, registry storage, project/robot/account metadata, Trivy/jobservice PV |
| OpenEBS | PV/PVC metadata, workload backup, VG/LV 구성정보, engine별 backup |
8. 우선순위로 보면 이렇게 정비하면 좋음
장애 SOP가 부족한 상황이라면, 아래 순서로 문서화하는 게 가장 효과적입니다.
| 우선순위 | SOP 묶음 | 이유 |
|---|---|---|
| 1 | Keycloak 로그인/LDAP/OIDC 장애 SOP | 인증이 막히면 대부분의 운영 도구 접근이 막힘 |
| 2 | ArgoCD Sync/OutOfSync/Degraded SOP | 배포와 drift 원복의 중심 |
| 3 | Harbor ImagePullBackOff/Robot Account SOP | workload 기동 실패와 직결 |
| 4 | Nexus artifact download/upload 장애 SOP | CI/CD와 air-gap dependency 반입에 영향 |
| 5 | Jenkins Pipeline/Agent/Credential 장애 SOP | 검증/자동화 작업 중단 |
| 6 | OpenEBS PVC/PV/FailedMount SOP | stateful workload 장애와 직결 |
| 7 | 각 컴포넌트 백업/복구 SOP | 장애 후 복구 가능성 확보 |
| 8 | 각 컴포넌트 업그레이드 SOP | 장기 운영 안정성 확보 |
| 9 | 권한/계정/credential rotation SOP | 보안 운영 성숙도 확보 |
| 10 | 용량/cleanup/retention SOP | Nexus/Harbor/Jenkins/OpenEBS 장애 예방 |
9. 바로 추가하면 좋은 장애 SOP Top 25
1. Keycloak 전체 로그인 장애 대응
2. Keycloak LDAP/AD 연동 장애 대응
3. Keycloak OIDC Token 발급/검증 실패 대응
4. Keycloak Group Claim 누락으로 권한 미부여 대응
5. ArgoCD SSO 로그인 장애 대응
6. ArgoCD Application OutOfSync 대응
7. ArgoCD Application Degraded 대응
8. ArgoCD Sync 실패 대응
9. ArgoCD Repo-server Manifest Generation 실패 대응
10. Jenkins Controller 접속 장애 대응
11. Jenkins Kubernetes Agent 생성 실패 대응
12. Jenkins Credential 오류 대응
13. Jenkins Plugin 업그레이드 후 장애 대응
14. Nexus Artifact Download 실패 대응
15. Nexus Artifact Upload 실패 대응
16. Nexus Blob Store 용량 부족 대응
17. Nexus Cleanup Policy 오동작 대응
18. Harbor ImagePullBackOff 대응
19. Harbor Robot Account 인증 실패 대응
20. Harbor Registry Storage Full 대응
21. Harbor Vulnerability Scan 실패 대응
22. Harbor Garbage Collection 실패 대응
23. OpenEBS PVC Pending 대응
24. OpenEBS Pod FailedMount 대응
25. OpenEBS LocalPV Node 장애 대응10. 문서 구조는 이렇게 추가하면 좋음
기존 SOP Git repository 구조가 있다면 아래처럼 넣는 것을 추천합니다.
sop/
common/
daily-check.md
weekly-check.md
incident-severity.md
escalation.md
backup-restore-policy.md
credential-rotation-policy.md
identity/
keycloak/
daily-check.md
ldap-federation.md
oidc-client-create.md
token-troubleshooting.md
login-failure.md
realm-backup-restore.md
upgrade.md
cicd/
jenkins/
daily-check.md
pipeline-failure.md
agent-failure.md
credential-rotation.md
plugin-upgrade.md
backup-restore.md
gitops/
argocd/
daily-check.md
app-outofsync.md
app-degraded.md
sync-failure.md
rbac-sso.md
backup-restore.md
upgrade.md
artifact/
nexus/
daily-check.md
repository-create.md
artifact-upload-failure.md
artifact-download-failure.md
cleanup-policy.md
blobstore-capacity.md
backup-restore.md
registry/
harbor/
daily-check.md
project-create.md
robot-account.md
imagepullbackoff.md
retention-gc.md
vulnerability-scan.md
backup-restore.md
storage/
openebs/
daily-check.md
storageclass-create.md
pvc-pending.md
failedmount.md
localpv-node-failure.md
migration.md
upgrade.md11. 결론
기존에 정리한 Kubernetes / Cilium / AIStor / Longhorn / Observability SOP에 더해, 지금 말씀하신 컴포넌트들은 아래처럼 추가하는 게 좋습니다.
Keycloak : 인증/인가의 Root of Trust
Jenkins : 검증/자동화의 실행 엔진
ArgoCD : GitOps 배포 제어면
Nexus : 일반 artifact 저장소
Harbor : container image registry
OpenEBS : local/CSI storage layer그리고 이 6개는 각각 따로 문서화하되, 실제 운영에서는 아래 4개 연계 SOP가 더 중요합니다.
1. 인증 연계 SOP
Keycloak → ArgoCD/Jenkins/Harbor/Nexus/kubelogin
2. 배포 연계 SOP
Git → Jenkins CI → Harbor/Nexus → ArgoCD → K8s
3. Air-gap 반입 SOP
외부 artifact/image/package → 검증 → Nexus/Harbor 등록
4. 백업/복구 SOP
Keycloak/Jenkins/ArgoCD/Nexus/Harbor/OpenEBS 전체 복구 순서장애 SOP가 부족한 상태라면, 우선 Keycloak, ArgoCD, Harbor, Nexus, Jenkins, OpenEBS 순서로 만들고, 각 도구별로는 로그인/인증 장애 → 배포/동기화 장애 → artifact/image pull 장애 → storage mount 장애 → 백업/복구 순서로 정비하는 것을 추천합니다.
[3]: https://www.jenkins.io/doc/book/using/using-credentials/ "
Using credentials
"
[4]: https://www.jenkins.io/doc/book/system-administration/backing-up/ "
Backing-up/Restoring Jenkins
"
[5]: https://www.jenkins.io/doc/book/security/access-control/permissions/ "
Permissions
"
[12]: https://goharbor.io/docs/main/administration/ "
Harbor docs | Harbor Administration
"[13]: https://goharbor.io/docs/2.9.0/administration/garbage-collection/ "
Harbor docs | Garbage Collection
"[14]: https://goharbor.io/docs/2.12.0/administration/backup-restore/ "
Harbor docs | Backup And Restore Harbor With Velero
"