diff --git a/backend-java/.dockerignore b/backend-java/.dockerignore new file mode 100644 index 0000000..84d2250 --- /dev/null +++ b/backend-java/.dockerignore @@ -0,0 +1,4 @@ +build/ +.gradle/ +.idea/ +*.iml diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..b03154a --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,239 @@ +# Tasteby 배포 트러블슈팅 기록 + +## 1. OCI DevOps Build Pipeline - 코드 접근 권한 오류 + +**오류:** +``` +Unable to fetch build_spec file build_spec.yaml due to RelatedResourceNotAuthorizedOrNotFound. +Please check if dynamic groups and the corresponding policies are properly configured. +``` + +**원인:** OCI DevOps Build Pipeline이 Code Repository에 접근할 IAM 권한이 없음 + +**해결:** +1. Dynamic Group 생성 — 빌드 파이프라인 리소스를 포함하는 매칭 룰: + ``` + ANY { + resource.type = 'devopsbuildpipeline', + resource.type = 'devopsrepository', + resource.type = 'devopsdeploypipeline', + resource.type = 'devopsconnection' + } + ``` +2. IAM Policy 생성: + ``` + Allow dynamic-group tasteby-build-pipeline to manage devops-family in tenancy + Allow dynamic-group tasteby-build-pipeline to manage repos in tenancy + Allow dynamic-group tasteby-build-pipeline to read secret-family in tenancy + Allow dynamic-group tasteby-build-pipeline to manage generic-artifacts in tenancy + Allow dynamic-group tasteby-build-pipeline to use ons-topics in tenancy + ``` +3. IAM 정책 전파에 수 분 소요 — 적용 후 바로 빌드하면 동일 오류 발생할 수 있음 + +--- + +## 2. OCI DevOps Build Pipeline - Logs 미설정 + +**오류:** +``` +Logs need to be enabled in order to run the builds. +Please enable logs for your project. +``` + +**원인:** DevOps 프로젝트에 OCI Logging이 설정되지 않음 + +**해결:** +1. OCI Logging > Log Group 생성 (예: `tasteby-devops-logs`) +2. Log Group에 Service Log 생성: + - Source: `devops` 서비스 + - Resource: DevOps 프로젝트 OCID + - Category: `all` +3. DevOps 프로젝트에 Notification Topic 설정 필요 + +--- + +## 3. OCI DevOps Build Pipeline - ARM64 이미지 빌드 불가 + +**오류:** +``` +Step 'Step_CommandV1_2' failed with exit code: '1' (docker build --platform linux/arm64) +Step 'Step_CommandV1_1' failed with exit code: '125' (QEMU 설정 시도) +``` + +**원인:** +- OCI DevOps Managed Build는 x86_64 러너만 제공 (`OL7_X86_64_STANDARD_10`) +- ARM64 이미지를 직접 빌드할 수 없음 +- `--privileged` 모드가 허용되지 않아 QEMU 크로스빌드도 불가 + +**해결:** +- Colima (macOS 경량 Docker) 설치로 로컬 ARM64 빌드: + ```bash + brew install colima docker + colima start --arch aarch64 --cpu 2 --memory 4 + ``` +- deploy.sh로 로컬 빌드 → OCIR push → K8s 배포 + +--- + +## 4. OCI Code Repository - HTTPS 인증 실패 + +**오류:** +``` +fatal: Authentication failed for 'https://devops.scmservice.ap-seoul-1.oci.oraclecloud.com/...' +``` + +**원인:** OCI Code Repository HTTPS 인증의 username 형식이 특수함 + +**해결:** +- IDCS 연동 사용자의 경우 username 형식: + ``` + /oracleidentitycloudservice/ + ``` + 예시: `joungminkoaws/oracleidentitycloudservice/joungmin.ko.aws@gmail.com` +- Password: OCI Auth Token (User Settings > Auth Tokens에서 생성) +- `idyhsdamac8c` (namespace)가 아닌 `joungminkoaws` (tenancy name)을 사용해야 함 + +--- + +## 5. Docker 빌드 컨텍스트 과대 (276MB) + +**증상:** +``` +Sending build context to Docker daemon 276.4MB +``` + +**원인:** `.dockerignore` 파일이 없어 `build/`, `.gradle/`, `node_modules/` 등이 포함됨 + +**해결:** +- `backend-java/.dockerignore` 생성: + ``` + build/ + .gradle/ + .idea/ + *.iml + ``` +- `frontend/.dockerignore` 생성: + ``` + node_modules/ + .next/ + .env.local + ``` +- 결과: 276MB → 336KB (backend), 602KB (frontend) + +--- + +## 6. Redis ImageInspectError (OKE CRI-O) + +**오류:** +``` +Failed to inspect image "": rpc error: code = Unknown desc = short name mode is enforcing, +but image name redis:7-alpine returns ambiguous list +``` + +**원인:** OKE는 CRI-O 컨테이너 런타임을 사용하며, short name (예: `redis:7-alpine`)을 허용하지 않음 + +**해결:** +- 이미지명에 full registry prefix 추가: + ```yaml + # 변경 전 + image: redis:7-alpine + # 변경 후 + image: docker.io/library/redis:7-alpine + ``` + +--- + +## 7. OCIR ImagePullBackOff (K8s) + +**오류:** +``` +Failed to pull image "icn.ocir.io/.../backend:latest": unable to retrieve auth token: +invalid username/password: unknown: Unauthorized +``` + +**원인:** K8s `ocir-secret`의 username 형식이 잘못됨 + +**해결:** +- IDCS 사용자의 경우 OCIR pull secret 생성 시: + ```bash + kubectl create secret docker-registry ocir-secret \ + --docker-server=icn.ocir.io \ + --docker-username='/oracleidentitycloudservice/' \ + --docker-password='' \ + -n tasteby + ``` +- Docker login 시에도 동일한 형식: + ```bash + docker login icn.ocir.io \ + -u "/oracleidentitycloudservice/" + ``` + +--- + +## 8. kubectl 인증 실패 + +**오류:** +``` +error: You must be logged in to the server (Unauthorized) +``` + +**원인:** kubeconfig 생성 시 OCI 프로필이 지정되지 않음 + +**해결:** +- `~/.kube/config`의 user args에 `--profile JOUNGMINKOAWS` 추가: + ```yaml + users: + - name: user-xxx + user: + exec: + args: + - ce + - cluster + - generate-token + - --cluster-id + - ocid1.cluster.oc1... + - --region + - ap-seoul-1 + - --profile # ← 추가 + - JOUNGMINKOAWS # ← 추가 + ``` + +--- + +## 9. Let's Encrypt 인증서 발급 실패 - Timeout during connect + +**오류:** +``` +acme: authorization error for www.tasteby.net: 400 urn:ietf:params:acme:error:connection: +64.110.90.89: Timeout during connect (likely firewall problem) +``` + +**원인:** OKE VCN의 Security List에서 LB 서브넷으로의 80/443 포트가 열려있지 않음 + +**해결:** +1. **LB 서브넷 Security List**에 Ingress 규칙 추가: + - `0.0.0.0/0` → TCP 80 (HTTP) + - `0.0.0.0/0` → TCP 443 (HTTPS) + - Egress: `0.0.0.0/0` → All protocols + +2. **노드 서브넷 Security List**에 LB→노드 Ingress 규칙 추가: + - `10.0.20.0/24` (LB 서브넷 CIDR) → TCP 30000-32767 (NodePort) + - `10.0.20.0/24` → TCP 10256 (Health check) + +3. 인증서 재발급: + ```bash + kubectl delete certificate tasteby-tls -n tasteby + kubectl apply -f k8s/ingress.yaml + ``` + +--- + +## 10. tasteby.net (root domain) DNS 미전파 + +**증상:** www.tasteby.net은 되지만 tasteby.net challenge가 `pending` 상태 + +**원인:** Namecheap에서 @ (root) A 레코드가 설정되지 않았거나 전파가 안 됨 + +**해결:** +- Ingress TLS에서 www.tasteby.net만 먼저 설정하여 인증서 발급 +- root domain DNS 전파 완료 후 TLS hosts에 tasteby.net 추가하고 인증서 재발급 diff --git a/frontend/.dockerignore b/frontend/.dockerignore new file mode 100644 index 0000000..565ea56 --- /dev/null +++ b/frontend/.dockerignore @@ -0,0 +1,3 @@ +node_modules/ +.next/ +.env.local diff --git a/k8s/ingress.yaml b/k8s/ingress.yaml index 527de64..643d2f4 100644 --- a/k8s/ingress.yaml +++ b/k8s/ingress.yaml @@ -16,7 +16,6 @@ spec: tls: - hosts: - www.tasteby.net - - tasteby.net secretName: tasteby-tls rules: - host: www.tasteby.net diff --git a/k8s/redis-deployment.yaml b/k8s/redis-deployment.yaml index 74f184a..eb0f436 100644 --- a/k8s/redis-deployment.yaml +++ b/k8s/redis-deployment.yaml @@ -15,7 +15,7 @@ spec: spec: containers: - name: redis - image: redis:7-alpine + image: docker.io/library/redis:7-alpine ports: - containerPort: 6379 resources: