연결 구성 및 관리
연결은 app-config.yaml의 루트에 배열로 구성돼요.
출처: 문서
본문
연결은 app-config.yaml의 루트에 배열로 구성돼요. 기본 서비스는 백엔드 시작 시 배열을 로드하고 모든 항목을 검증하며, 생략된 곳에는 표시 제목을 할당해요.
실험적 구성
connections 구성 형식은 실험적이며 연결 프레임워크가 개발되는 동안 변경될 수 있어요.
연결 구성
다음 연결은 백엔드 플러그인과 모듈에 GitHub에 대한 토큰 인증 접근을 제공해요:
app-config.yaml
connections: - type: github title: GitHub production host: github.com auth: - method: token token: ${GITHUB_TOKEN}
type을 내장 연결 타입 중 하나로 설정하세요. 연결 타입은 허용된 연결 필드, 인증 메서드, 조회 쿼리, 검증 규칙을 결정해요.
시크릿 값은 소스 제어 밖에 저장하고 환경 변수 치환을 통해 참조하세요. 연결 서비스는 해결된 값을 검증하므로, 시크릿이 없거나 유효하지 않으면 구성 컨텍스트와 함께 시작이 실패해요.
인증 없는 접근 구성
모든 연결은 최소한 하나의 인증 항목을 요구해요. 타입이 인증 없는 접근을 지원하면 none 메서드를 사용하세요:
app-config.yaml
connections: - type: gitlab host: gitlab.com auth: - method: none
모든 타입이 none을 지원하는 것은 아니에요. 예를 들어 harness는 토큰 인증을 요구하고 aws-codecommit은 액세스 키 또는 assume-role 인증을 요구해요.
한 타입의 여러 엔드포인트 구성
host 조회 전략을 사용하는 연결 타입은 각 항목의 호스트가 다르면 여러 항목을 허용해요:
app-config.yaml
connections: - type: github title: Public GitHub host: github.com auth: - method: token token: ${GITHUB_TOKEN} - type: github title: Company GitHub host: github.example.com apiBaseUrl: https://github.example.com/api/v3 rawBaseUrl: https://github.example.com/raw auth: - method: token token: ${GITHUB_ENTERPRISE_TOKEN}
호스트 기반 타입의 경우 ConnectionsService.find는 소비자의 URL을 파싱하고 호스트를 정확히 일치시켜요. host에 스킴이나 경로를 포함하지 마세요.
기본 연결 제목은 연결 타입의 제목이에요. 같은 타입의 연결이 둘 이상이면 기본에는 호스트가 포함되며, 예를 들어 GitHub (github.example.com)처럼 돼요. 환경별 이름이 더 명확할 때는 title을 설정하세요.
같은 타입과 호스트를 가진 중복된 멀티턴 연결은 거부돼요. aws 같은 싱글턴 타입은 같은 타입의 두 번째 항목을 거부해요.
여러 인증 항목 구성
연결은 둘 이상의 인증 항목을 포함할 수 있어요. 이는 플러그인별 자격 증명과 한 조직에 GitHub App을 선택하는 것 같은 타입별 선택을 지원해요.
플러그인용 자격 증명 선택
인증 항목의 match.plugins를 통한 플러그인 범위 지정을 사용해 나열된 플러그인 ID에만 보이게 하세요:
app-config.yaml
connections: - type: github host: github.com auth: - method: token title: Catalog token token: ${GITHUB_CATALOG_TOKEN} match: plugins: - catalog - method: token title: Default token token: ${GITHUB_DEFAULT_TOKEN}
catalog 플러그인의 경우 명시적으로 일치된 항목이 제한 없는 항목 앞에 배치돼요. 다른 플러그인은 GITHUB_CATALOG_TOKEN을 볼 수 없으며 제한 없는 항목을 사용해요.
전체 연결도 제한할 수 있어요:
app-config.yaml
connections: - type: harness host: app.harness.io match: plugins: - harness auth: - method: token token: ${HARNESS_TOKEN}
다른 플러그인은 harness 타입을 선언하더라도 이 연결을 보지 못해요.
참고
플러그인 일치는 백엔드 플러그인에 어떤 정적 자격 증명을 전달할지 제어해요. 외부 권한을 부여하거나 프론트엔드 사용자를 승인하지 않아요.
조직별 GitHub App 선택
GitHub 타입은 쿼리 URL의 첫 번째 경로 세그먼트를 조직으로 사용해요. 그 조직을 포함하는 orgs 목록을 가진 앱을 선호해요:
app-config.yaml
connections: - type: github host: github.com auth: - method: app title: Backstage organization app appId: ${GITHUB_BACKSTAGE_APP_ID} privateKey: ${GITHUB_BACKSTAGE_PRIVATE_KEY} clientId: ${GITHUB_BACKSTAGE_CLIENT_ID} clientSecret: ${GITHUB_BACKSTAGE_CLIENT_SECRET} orgs: - backstage - method: token token: ${GITHUB_FALLBACK_TOKEN}
URL 조직이 일치 전에 소문자로 정규화되므로 orgs에는 소문자 조직 이름을 사용하세요.
GitHub 인증 선택은 순서대로 다음을 선호해요:
-
orgs가 쿼리 조직을 포함하는 앱. -
orgs제한이 없는 앱. -
정확히 하나의 앱만 남았을 때 그 유일하게 구성된 앱.
-
토큰.
-
none메서드.
선택된 메서드는 소비자의 authMethods 목록에도 나타나야 해요.
AWS 계정 구성
aws 타입은 호스트 기반 타입과 달라요. 하나의 싱글턴 연결이 각 AWS 계정에 대한 account 인증 항목을 포함해요:
app-config.yaml
connections: - type: aws roleName: BackstageReadRole region: eu-west-1 auth: - method: account title: Main AWS account mainAccount: true profile: backstage-main - method: account title: Workload account accountId: '123456789012' roleName: BackstageReadRole
조회는 accountId 또는 Amazon 리소스 이름(ARN)을 제공할 수 있어요. AWS는 정확한 계정 항목이 있으면 그것을 사용하고, 없으면 mainAccount로 표시된 항목으로 폴백해요. 연결 수준 roleName은 메인 계정 항목을 요구하는데, 그 항목이 자체 항목이 없는 계정에서 역할을 수임하는 데 사용되는 자격 증명을 제공하기 때문이에요.
사용 가능한 필드와 검증 제약은 AWS 연결 타입 가이드를 참고하세요.
연결 변경
연결 구성은 정적이에요. 호스트, 엔드포인트, 자격 증명, 플러그인 일치, 또는 인증 메서드를 변경하려면:
-
환경의 구성 소스에서 관련 항목을 업데이트하세요.
-
항목이 참조하는 시크릿을 업데이트하세요.
-
기본 서비스가 전체 연결 목록을 다시 로드하고 검증하도록 백엔드를 다시 시작하세요.
-
영향을 받는 타입과 대상에 대한 플러그인 조회를 실행해보세요.
인증 메서드를 변경하면 소비자에게 영향을 줄 수 있어요. 각 소비자는 이해하는 메서드를 나열하며, 구성된 선택이 지원되지 않는 메서드로 해결되면 조회가 실패해요. 인증 항목을 제거하거나 우선순위를 변경하기 전에 소비 플러그인을 확인하세요.
Backstage 구성 배열은 구성 소스가 병합될 때 전체가 대체돼요. 둘 이상의 구성 파일이 connections를 정의하면 우선순위가 높은 배열이 낮은 배열을 대체해요. 재정의 소스에 환경별 전체 연결 목록을 포함하거나, config includes와 환경 변수 치환을 사용해 값을 체계적으로 유지하세요.
레거시 통합에서 마이그레이션
백엔드 시작 시 기본 연결 서비스는 명시적 connections 구성과 지원되는 레거시 integrations 구성 모두를 자동으로 읽어요. 레거시 최상위 aws 구성을 포함한 레거시 통합을 플러그인에 제공하기 전에 인메모리 연결로 변환해요. 도입자는 이 변환을 활성화하거나 플러그인이 연결 서비스로 마이그레이션하는 동안 기존 통합을 바꿀 필요가 없어요.
변환은 app-config.yaml을 다시 쓰지 않아요. 실행 중인 백엔드가 어떤 연결을 로드할지만 결정해요.
한 번에 하나씩 마이그레이션
레거시와 명시적 항목은 연결 타입이 서로 다를 때 함께 사용할 수 있어요. 다음 구성을 가질 때:
app-config.yaml
# Legacy configurationintegrations: github: - host: github.com token: ${GITHUB_TOKEN}# Explicit connection configurationconnections: - type: gitlab host: gitlab.com auth: - method: token token: ${GITLAB_TOKEN}
서비스는 명시적 GitLab 연결과 함께 레거시 GitHub 통합을 자동으로 변환하고 로드해요.
명시적 연결이 레거시 타입을 대체
우선순위 규칙은 개별 호스트가 아니라 전체 연결 타입에 적용돼요. 한 타입에 대한 명시적 연결이 하나라도 있으면 서비스는 런타임 연결 목록에서 그 타입의 변환된 레거시 통합 항목을 모두 버려요.
예를 들어:
app-config.yaml
integrations: github: - host: github.com token: ${GITHUB_TOKEN} - host: github.example.com token: ${GITHUB_ENTERPRISE_TOKEN}connections: - type: github host: github.example.com auth: - method: token token: ${GITHUB_ENTERPRISE_CONNECTION_TOKEN}
실행 중인 백엔드는 명시적 github 연결만 로드해요. 변환된 레거시 GitHub 항목 두 개 모두, 호스트가 겹치지 않는 github.com 항목을 포함해 버려져요. 서비스는 겹치는 github 타입에 대해 경고 하나를 기록해요.
요약하면:
-
타입에 대한 명시적 연결이 없으면 그 타입의 지원되는 레거시 항목이 모두 자동으로 변환되고 로드돼요.
-
타입에 대한 명시적 연결이 하나라도 있으면 그 타입의 변환된 레거시 항목이 모두 버려져요.
-
서로 다른 타입의 레거시와 명시적 항목은 함께 로드돼요.
변환된 레거시 최상위 aws 구성에도 같은 규칙이 적용돼요.
구성 및 조회 실패 진단
서비스는 백엔드 시작 시 잘못된 구성을 보고해요. 일반적인 원인은 다음과 같아요:
-
알 수 없는 연결 타입 또는 인증 메서드.
-
필수 필드 누락.
-
비어 있거나 없는
auth배열. -
같은 타입과 호스트를 가진 연결 두 개.
-
둘 이상의 싱글턴 연결.
-
중복된 AWS 계정 ID 같은 전체 연결 검증 실패.
조회 시 다음 결과를 구분하세요:
-
NotFoundError는 구성된 연결이 타입과 쿼리에 일치하지 않거나, 타입별 인증 선택기가 후보를 찾지 못했음을 의미해요. -
NotAllowedError는 플러그인이 인증 항목을 볼 수 없거나, 선택된 메서드가 소비자가 지원하지 않음을 의미해요. -
InputError는 잘못된 URL 같은 잘못된 쿼리나, 플러그인이 선언하지 않은 연결 타입의 조회를 나타낼 수 있어요.
플러그인 코드의 오류 처리는 연결 소비 를 참고하세요.