Traefik 3.7.18 업그레이드: 인증·경로·Host 규칙 점검

Traefik 3.7.18의 인증·경로·Host 매처 변경과 ingress-nginx 호환 수정에 맞춰 기존 설정과 요청의 업그레이드 검증 범위를 정한다.

2026-11-18

업그레이드 검증 대상을 요청 단위로 고른다

Traefik v3.7.18 (2026-11-10)은 BasicAuth 비밀번호 길이 제한, HTTP Host 매처 값 검증, path parameter를 포함한 dot-segment·빈 세그먼트 처리를 수정했다. 기존 설정을 유지하더라도 인증과 라우팅에 걸친 변경을 확인해야 하는 릴리스다.

공식 릴리스노트는 Important 안내로 마이그레이션 가이드를 읽도록 권고한다. 업그레이드 검증도 프로세스가 뜨는지 확인하는 데서 끝내지 말고, 변경된 기능에 실제 운영 요청을 대조하는 쪽으로 잡는다.

먼저 운영 설정에서 BasicAuth, HTTP Host 매처, 경로 규칙, ingress-nginx 호환 설정의 사용 여부를 찾는다. 사용하는 기능마다 대표 요청과 기대 결과를 기록하면 검증 범위를 정할 수 있다. 인증은 허용·거부 결과, 라우팅은 선택된 라우터와 도착한 백엔드, 호환 설정은 응답과 헤더를 확인 대상으로 삼는다.

다음 그림은 운영 설정에서 출발해 어떤 요청 결과를 검증할지 연결한 것이다.

⤢✕운영 설정BasicAuth경로 규칙HTTP Host 매처ingress-nginx 호환 설정인증 허용·거부 결과선택된 라우터와 백엔드응답과 헤더

릴리스노트에는 BasicAuth의 최대 길이, 허용되는 Host 값의 전체 조건, 경로별 정규화 결과가 적혀 있지 않다. 이 값을 임의로 채우지 말고, 실제 사용하는 입력과 기대 결과를 먼저 정리한 뒤 마이그레이션 가이드와 해당 변경 내용을 대조한다.

경로는 정상 요청과 특수한 입력을 함께 확인한다

경로 관련 수정은 단순히 dot-segment를 처리한다는 설명보다 범위가 구체적이다. 해당 변경은 path parameter를 포함한 dot-segment와 빈 세그먼트 처리를 다룬다.

기존 검증이 일반적인 경로 요청에만 집중돼 있었다면 이 조건을 놓칠 수 있다. 경로 규칙을 사용하는 서비스에서는 실제 요청 중 dot-segment, 빈 세그먼트, path parameter가 등장하는 경우를 찾아 검증에 포함한다. 서로 따로 등장하는 요청뿐 아니라 자료가 명시한 조합인 ‘path parameter를 포함한’ 경우를 확인해야 한다.

확인할 대상은 응답 성공 여부만이 아니다. 의도한 라우터가 선택됐는지, 예상한 백엔드에 도달했는지, 애플리케이션이 받은 경로가 기대와 맞는지를 함께 기록한다. 업그레이드 전후 응답이 같더라도 경로 처리에 대한 확인까지 끝났다고 판단하지 않도록 검증 항목을 나누는 편이 낫다.

다만 릴리스노트만으로 특정 입력 경로가 어떤 문자열로 변환되는지 단정할 수는 없다. 이 자료에는 경로 변환 예시나 설정 예시가 없으므로, 임의의 변환표를 만드는 대신 운영에서 사용하는 요청을 검증 자료로 확보한다.

Host 매처는 설정값과 요청을 짝지어 점검한다

HTTP Host 매처 값 검증 변경은 운영 중인 라우팅 규칙의 값 자체를 확인 대상으로 만든다. 업그레이드 검증 목록에는 요청 호스트뿐 아니라 설정에 들어 있는 Host 매처 값도 남겨야 한다.

호스트 기반 라우팅을 사용하는 환경이라면 다음 항목을 한 묶음으로 기록한다.

  • 운영 설정에 들어 있는 HTTP Host 매처 값
  • 그 규칙에 도달해야 하는 요청 호스트
  • 선택돼야 하는 라우터와 백엔드
  • 해당 규칙에 도달하면 안 되는 요청의 기대 결과

이렇게 묶으면 설정값 검증과 실제 라우팅 검증을 연결할 수 있다. 업그레이드 후에는 설정이 의도대로 반영됐는지 확인하고, 준비한 요청이 기대한 경로로 전달되는지 대조한다.

릴리스노트는 허용·거부되는 Host 값의 문법이나 검증 실패 시 처리 방식을 열거하지 않는다. 따라서 특정 문자열이 새로 금지된다거나, 검증 실패가 어떤 범위에 영향을 준다고 이 자료만으로 쓰지는 않는다. 운영 중인 매처 값이 이번 변경과 관련 있는지 원문으로 확인하는 것이 먼저다.

BasicAuth는 비밀번호 길이와 인증 결과를 연결한다

BasicAuth 비밀번호 길이 제한은 BasicAuth를 사용하는 서비스의 인증 검증에 반영해야 한다. 기존 계정이 인증된다는 확인과 함께, 비밀번호 길이를 검증 항목으로 명시한다.

우선 현재 인증 검증에 사용하는 입력의 길이 범위를 파악한다. 이후 제한 조건을 원문으로 확인하고, 그 조건에 해당하는 입력의 허용·거부 결과를 검증한다. 릴리스노트에는 제한값과 초과 시 응답이 없으므로 특정 길이나 상태 코드를 합격 기준으로 지어내면 안 된다.

인증 관련 수정에는 Proxy-Authorization의 연결 바인딩 인증 스킴 지원도 있다. 이 인증 방식을 사용하는 환경은 별도 검증 대상으로 넣는다. BasicAuth 길이 제한을 확인했다는 이유로 Proxy-Authorization 관련 확인까지 끝난 것으로 처리하지 않는다.

실무에서는 인증 기능 이름만 적은 체크리스트보다 ‘어떤 입력으로 어떤 결과를 기대하는가’를 남기는 편이 유용하다. 기존에 허용하던 인증 요청과 거부하던 요청을 확보하고, 이번 변경 조건에 해당하는 입력을 추가해 업그레이드 후 결과를 비교한다.

ingress-nginx 호환 설정은 적용 조건별로 나눈다

ingress-nginx 호환 수정은 모든 Ingress를 같은 방식으로 검사하기보다, 릴리스노트에 적힌 적용 조건으로 대상을 추리는 편이 정확하다.

적용 조건 릴리스에 명시된 수정 업그레이드 검증 대상
host 없는 Ingress의 auth-tls 어노테이션 기본 TLS 옵션에 적용 해당 어노테이션과 기본 TLS 옵션의 반영 결과
CORS와 리다이렉트 어노테이션 사용 CORS를 리다이렉트보다 먼저 적용 두 설정이 함께 걸리는 요청의 응답과 헤더
여러 Ingress가 호스트를 공유 Ssl-Client-* 헤더 수정 각 Ingress에서 백엔드로 전달되는 해당 헤더

host 없는 auth-tls 변경을 확인할 때는 호스트가 명시된 Ingress만 검사하지 않도록 대상을 구분한다. CORS 적용 순서 변경은 CORS와 리다이렉트가 함께 적용되는 요청을 준비해야 검증 의도가 분명해진다.

호스트 공유 시 헤더 수정은 같은 호스트를 사용하는 Ingress들을 각각 확인하는 것이 핵심이다. 릴리스노트는 Ssl-Client-*의 개별 헤더 이름과 수정 전후 값을 제공하지 않으므로, 실제 사용 중인 헤더와 기대값을 검증 기록에 남긴다.

다음 그림은 어노테이션의 적용 범위, 처리 순서, Ingress 간 공유 조건이 서로 다른 점검 축임을 보여 준다.

⤢✕ ingress-nginx 호환 수정의 점검 축 적용 범위 · 처리 순서 · 호스트 공유 조건 적용 범위 처리 순서 호스트 공유 조건 적용 host 없는 Ingress auth-tls 어노테이션 기본 TLS 옵션 먼저 적용 CORS 리다이렉트 1 2 확인 확인 공유 호스트 Ingress A Ingress B Ssl-Client-* 헤더 Ssl-Client-* 헤더 Traefik 3.7.18 업그레이드: 인증·경로·Host 규칙 점검 | infra-system

문서 변경에는 누락된 ingress-nginx 어노테이션을 미지원으로 명시한 항목도 있다. 이번 호환 수정만으로 사용 중인 어노테이션 전체가 지원된다고 판단하지 말고, 실제 설정 목록과 지원 문서를 대조한다.

미들웨어와 전송 기능은 사용하는 항목만 검증에 더한다

핵심 라우팅 검증을 정한 뒤에는 나머지 수정 중 운영 환경에 해당하는 항목을 추가한다. 기능을 사용하지 않는 환경까지 동일한 검증 목록을 강제할 필요는 없다.

사용하는 기능 릴리스에 명시된 변경 검증에 포함할 대상
Compress 미들웨어 Accept-Encoding 파싱에서 대문자 Q 가중치 허용 대문자 Q 가중치가 포함된 요청
Compress의 zstd 인코딩 인코더 메모리 제한 zstd 압축을 사용하는 요청과 자원 사용 관찰
WASM 플러그인 결정적 난수 동작 수정 난수 동작에 의존하는 플러그인 기능
TCP servers transport의 SPIFFE SPIFFE 설정 수정 해당 전송 설정을 사용하는 연결
TCP 연결 감싸진 오류에서 읽기 중 연결 리셋 감지 해당 연결 리셋 조건의 처리

이 표는 검증 대상을 고르는 기준이다. zstd 변경에 대해서도 릴리스노트에는 메모리 상한이나 절감량이 없으므로, 특정 수치의 개선을 업그레이드 효과로 약속할 수 없다.

또한 gRPC 양방향 스트림 항목은 회귀 테스트 추가로 적혀 있다. 이를 새로운 스트림 동작이나 성능 개선으로 바꿔 해석하지 않는다.

업그레이드 완료 기록에는 적용 버전과 함께 실제 확인한 요청, 기대 결과, 관찰 결과를 남긴다. BasicAuth 입력, 경로 처리 조건, Host 매처 값, ingress-nginx 적용 조건이 그 기록에 연결돼 있으면 이번 릴리스에서 무엇을 검증했는지 설명할 수 있다. 확인하지 못한 제한값이나 세부 동작은 통과로 표시하지 않고 남겨 둔다.

Traefik업그레이드BasicAuth라우팅ingress-nginx