본문 바로가기
WIKI 기술 지식 베이스

연결 개념

원문 보기 위키 갱신

연결은 정적 외부 서비스 구성을 이를 사용하는 코드에서 분리해요.

출처: 문서

본문

연결은 정적 외부 서비스 구성을 이를 사용하는 코드에서 분리해요. 이 페이지는 연결 프레임워크의 용어집이에요. 모델의 각 부분을 정의한 다음, 구성에서 플러그인에 반환되는 값까지의 조회 과정을 따라가요.

연결 타입

연결 타입은 한 종류의 외부 시스템에 대한 공유 계약이에요. 다음을 정의해요:

  • github 또는 aws 같은 고유한 타입 키.

  • 표시 제목.

  • 구성에 인스턴스가 하나만 들어갈 수 있는지 여러 개 들어갈 수 있는지.

  • ConnectionsService.find가 받는 쿼리를 결정하는 조회 전략.

  • 모든 인증 메서드가 공유하는 필드의 스키마.

  • 하나 이상의 인증 메서드 정의.

  • 선택적 인증 선택 및 전체 연결 검증 로직.

예를 들어 github 타입은 다중 인스턴스, 호스트 기반 타입이에요. 그 연결 필드에는 host, apiBaseUrl, rawBaseUrl이 포함돼요. 그 인증 메서드는 none, token, app이에요.

내보내진 ConnectionType 디스크립터는 lookupStrategy, configSchema, authMethods 같은 런타임 메타데이터를 포함해요. 쿼리와 반환된 인증 형태는 제네릭 정의를 통해 추론되며, 디스크립터의 query나 auth라는 이름의 런타임 속성이 아니에요.

구성된 연결

구성된 연결은 루트 connections 배열의 항목 하나예요. 프레임워크가 소유하는 필드와 연결 타입이 정의하는 필드를 결합해요:

connections:  - type: github    title: GitHub production    host: github.com    auth:      - method: token        token: ${GITHUB_TOKEN}

프레임워크는 다음 연결 수준 필드를 소유해요:

| 필드 | 필수 | 목적 | | type | 예 | 내장 연결 타입을 선택. | | title | 아니요 | 연결에 사람이 읽을 수 있는 이름을 부여. | | auth | 예 | 하나 이상의 구성된 인증 항목을 포함. | | match | 아니요 | 전체 연결을 이름이 지정된 플러그인 ID로 제한. |

다른 모든 필드는 선택한 타입의 연결 스키마에서 옵니다. 호스트 기반 타입의 경우 일반적으로 host가 포함되며 API나 콘텐츠 기본 URL이 포함될 수 있어요.

카디널리티

카디널리티는 한 타입에 대해 구성된 연결이 몇 개 존재할 수 있는지를 제어해요. 대부분의 연결 타입은 multiton 카디널리티를 가지며, 고유한 ID를 가진 구성된 인스턴스가 여러 개 허용돼요. singleton 타입은 해당 타입의 항목 하나만 허용해요.

연결 타입의 조회 전략이 ID 필드를 결정해요. 호스트 기반 타입의 경우 ID는 host이므로 두 GitHub 연결은 호스트가 다르면 유효해요. AWS 타입은 싱글턴이므로 ID가 연결 필드에서 파생되지 않으며, 개별 계정은 대신 하나의 연결 안의 인증 항목으로 표현돼요.

인증 메서드

인증 메서드는 지원되는 인증 방식 하나를 정의해요. 정의에는 메서드 키, 표시 제목, 메서드별 필드용 스키마가 있어요. 예를 들어 GitHub token 메서드는 token을 요구하고, GitHub app 메서드는 애플리케이션 자격 증명을 요구해요.

인증 항목

인증 항목은 한 메서드의 구성된 인스턴스예요:

auth:  - method: token    title: Read-only catalog token    token: ${GITHUB_CATALOG_TOKEN}    match:      plugins:        - catalog

모든 연결은 최소한 하나의 인증 항목을 포함해야 해요. 타입이 인증 없는 접근을 지원하면 none 메서드를 명시적으로 구성하세요. 빈 auth 배열은 인증 없는 접근을 의미하지 않아요.

선택적 인증 title은 기본적으로 메서드의 표시 제목으로 설정돼요. 선택적 match 규칙은 항목을 특정 플러그인으로 제한해요.

조회 전략

조회 전략은 서비스가 조회 쿼리에서 연결 ID를 파생하는 방식을 정의해요. 또한 ConnectionsService.find가 받는 쿼리 형태도 결정해요.

내장 전략은 다음과 같아요:

| 전략 | 쿼리 | 선택 동작 | | host | { url: string } | URL을 파싱하고 host가 URL 호스트와 일치하는 연결을 선택. | | aws | { accountId?: string; arn?: string } | 싱글턴 AWS 연결을 사용하고 AWS 타입이 계정 인증 항목을 선택하게 함. |

조회 쿼리

조회 쿼리는 플러그인이 접근하려는 리소스를 설명해요. 그 형태는 연결 타입의 조회 전략에서 옵니다. 호스트 기반 타입은 리소스 URL을 사용하고, AWS 타입은 계정 번호나 Amazon 리소스 이름(ARN)을 받아요.

쿼리는 조회 요청의 일부예요. 구성된 연결의 필드로 저장되거나 ConnectionType의 런타임 속성으로 노출되지 않아요.

연결 선언

연결 선언은 백엔드 플러그인이나 모듈이 연결 타입을 조회하려 한다는 것을 기록해요. 선언은 플러그인이나 모듈의 register 콜백 중, 초기화 의존성이 등록되기 전에 이뤄져요.

런타임은 선언되지 않은 타입의 조회를 거부해요. 모듈은 부모 플러그인이 이미 같은 타입을 선언했더라도 자체 연결을 선언해요. 선언은 진단과 도구를 위한 설명과 필수 상태 메타데이터도 담을 수 있어요.

선언은 의도된 접근을 설명해요. 구성된 연결을 선택하거나 자격 증명을 포함하지 않아요.

연결 서비스

연결 서비스는 구성된 연결을 검증하고 선택해요. 플러그인 범위의 백엔드 서비스이므로 각 플러그인은 루트 연결 구성에 대한 자체 뷰를 받아요.

플러그인 범위 지정

플러그인 범위 지정은 match.plugins 규칙을 사용해 각 플러그인이 어떤 연결과 자격 증명을 볼 수 있는지 제어해요. 플러그인과 일치하지 않는 자격 증명은 해당 플러그인에 제공되지 않아요.

이 범위 지정은 다음과 같은 경우를 지원해요:

  • 수집 플러그인에 읽기 전용 토큰을 주고 다른 플러그인은 서로 다른 자격 증명을 사용하게 하기.

  • 필요하지 않은 플러그인에서 민감한 연결을 숨기기.

  • 제한 없는 연결을 모든 플러그인에 공유하면서 이름이 지정된 플러그인의 인증 항목 하나를 덮어쓰기.

연결 범위 지정은 구성 수준 격리예요. Backstage 권한 프레임워크나 외부 시스템의 자체 권한 부여를 대체하지 않아요.

find 중에 어떤 일이 일어나나

플러그인이 연결 타입을 선언하고 플러그인 범위의 연결 서비스를 받은 후, 외부 시스템에 접근해야 할 때 find를 호출해요. 플러그인은 연결 타입을 식별하고, 조회 쿼리로 리소스를 설명하며, 처리할 줄 아는 인증 메서드를 나열해요. 서비스는 이 입력을 사용해 하나의 구성된 연결과 하나의 인증 항목을 선택해요.

예를 들어 호스트 조회는 쿼리의 URL을 사용해 같은 호스트를 가진 연결을 찾아요.

다음 구성을 가질 때

app-config.yaml

connections:  - type: github    title: GitHub.com    host: github.com    apiBaseUrl: https://api.github.com    rawBaseUrl: https://raw.githubusercontent.com    auth:      - method: token        title: Catalog token        token: ${GITHUB_TOKEN}

그리고 이 find 호출

const connection = await connections.find({  type: 'github',  query: {    url: 'https://github.com/backstage/backstage/blob/master/catalog-info.yaml',  },  authMethods: ['token'],});

다음을 얻어요

{  type: 'github',  title: 'GitHub.com',  host: 'github.com',  apiBaseUrl: 'https://api.github.com',  rawBaseUrl: 'https://raw.githubusercontent.com',  auth: {    method: 'token',    title: 'Catalog token',    token: '<value of GITHUB_TOKEN>',  },}

쿼리는 선택에 사용되며 결과에 포함되지 않아요. 구성된 auth 배열은 이 조회에 대해 선택된 인증 항목 하나로 대체돼요.

서비스는 다음 순서로 결과를 만들어요:

  • 런타임이 호출 플러그인이나 모듈이 요청된 타입을 선언했는지 확인해요.

  • 플러그인 범위 서비스가 다른 플러그인을 대상으로 하는 연결과 인증 항목을 제거해요.

  • 조회 전략이 쿼리에서 연결 ID를 파생해요. 호스트 조회는 query.url에서 호스트를 파생해요.

  • 서비스가 요청된 타입과 ID를 가진 구성된 연결을 선택해요.

  • 연결 타입이 적격 인증 항목 하나를 선택해요. 대부분의 타입은 첫 번째 적격 항목을 사용해요. GitHub와 AWS 같은 타입은 더 구체적인 선택 로직을 제공해요.

  • 서비스가 선택된 메서드가 소비자의 비어 있지 않은 authMethods 목록에 나타나는지 확인해요.

  • 서비스가 auth를 선택된 인증 값 하나로 대체한 연결 필드를 반환해요.

authMethods 목록은 소비자가 무엇을 처리할 수 있는지 선언해요. 타입별 인증 선택 전에 후보를 필터링하지 않아요. 타입이 소비자가 나열하지 않은 메서드를 선택하면, 조회는 조용히 다른 자격 증명을 반환하는 대신 실패해요.

제한 사항

연결은 정적 연결 및 인증 구성만 관리해요. 연결 서비스는 해당 구성을 검증하고 관련 항목을 선택하며 그 필드를 반환해요. 반환된 인증 값의 수명 주기를 관리하지 않아요.

연결 인증 값은 정적 구성 또는 부트스트랩 자료예요. 유효한 자격 증명으로 유지된다는 보장이 없어요. 특히 연결 서비스는 다음을 수행하지 않아요:

  • 구성된 토큰이 유효한지 만료됐는지 확인.

  • 애플리케이션, 역할, 또는 ID 구성을 단기 자격 증명으로 교환.

  • 동적 자격 증명을 갱신하거나 캐시.

  • 실행 중인 백엔드 외부에서 값이 변할 때 토큰을 다시 로드.

구성된 토큰은 직접 사용할 수 있을 수 있지만, 소비자가 거부나 만료를 처리할 책임이 있어요. 애플리케이션, 역할, 프로필, 관리 ID 같은 다른 메서드는 별도의 자격 증명 공급자가 필요로 하는 필드를 반환해요. 하나가 필요한 내장 인증 메서드 목록은 알려진 자격 증명 공급자 를 참고하세요.

예를 들어 GitHub app 항목은 애플리케이션 ID와 개인 키를 반환해요. GitHub 설치 토큰은 반환하지 않아요. GitHub 자격 증명 공급자가 이 필드를 사용해 설치 토큰을 얻고, 캐시하고, 갱신해야 해요.

소비자를 설계할 때 이 제한을 염두에 두세요:

  • 연결을 사용해 엔드포인트를 찾고 정적 인증 구성을 선택하세요.

  • 토큰 교환, 갱신, 또는 캐싱이 필요할 때 부트스트랩 필드를 서비스별 자격 증명 공급자에 전달하세요.

  • 직접 구성된 토큰을 정적으로 취급하세요. 만료되거나 교체되면 구성을 업데이트하고 백엔드를 다시 시작하세요.

  • 클라이언트 팩토리를 사용해 서비스별 API 클라이언트를 구성하세요.

  • 연결 인증 값을 프론트엔드에 보내거나 로그에 포함하지 마세요.

다음으로 연결 구성 및 관리 또는 연결 소비 를 참고하세요.

더 알아보기 (Learn more)