카탈로그 엔티티의 잘 알려진 어노테이션
이 섹션은 정의된 의미를 가진 잘 알려진 어노테이션들을 나열합니다. 그것들은 카탈로그 엔티티에 붙일 수 있고, 필요에 따라 플러그인이 소비할 수 있습니다.
출처: 문서
본문
이 섹션은 정의된 의미를 가진 잘 알려진 어노테이션들을 나열합니다. 그것들은 카탈로그 엔티티에 붙일 수 있고, 필요에 따라 플러그인이 소비할 수 있습니다.
어노테이션
이것은 실제로 활발히 사용되는 것으로 알려진 어노테이션의 (완전하지 않은) 목록입니다.
backstage.io/managed-by-location
# Example:metadata: annotations: backstage.io/managed-by-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml
이 어노테이션의 값은 소위 로케이션 참조 문자열(location reference string)로, 엔티티가 원래 가져온 소스를 가리킵니다. 이 어노테이션은 카탈로그가 등록된 로케이션에서 데이터를 가져올 때 자동으로 추가되며, 보통 사람이 직접 쓰도록 의도된 것이 아닙니다. 이 어노테이션은 카탈로그가 지원하는 어떤 종류의 일반 로케이션이든 가리킬 수 있으므로, 항상 특별히 url 타입이라거나 심지어 단일 파일을 나타낸다고 믿을 수는 없습니다. 또한 단일 로케이션이 많은 엔티티의 소스일 수 있으므로, 이는 다대일 관계를 나타낸다는 점에 주목하세요.
값의 형식은 <type>:<target>입니다. target은 콜론도 포함할 수 있으므로, 값을 :로 순진하게 분할해 두 항목 배열을 기대하는 것은 바람직하지 않습니다. target 부분의 형식은 타입에 따라 달라지며 상상할 수 있듯 빈 문자열일 수도 있지만, 구분자 콜론은 항상 존재합니다.
backstage.io/managed-by-origin-location
# Example:metadata: annotations: backstage.io/managed-by-origin-location: url:http://github.com/backstage/backstage/blob/master/catalog-info.yaml
이 어노테이션의 값은 로케이션 참조 문자열입니다(위 참조). 그 등록이 엔티티의 생성을 이끈 로케이션을 가리킵니다. 대부분의 경우 backstage.io/managed-by-location과 backstage.io/managed-by-origin-location은 같을 것입니다. 원래 로케이션이 다른 로케이션에 위임한다면 다를 것입니다. 흔한 경우는 로케이션이 bootstrap:bootstrap으로 등록되어 Backstage 설치의 app-config.yaml의 일부임을 의미하는 경우입니다.
backstage.io/orphan
이 어노테이션은 없거나, 정확히 문자열 값 "true"로 존재합니다. 수동으로 추가해서는 안 됩니다. 대신 카탈로그 자체가 처리 루프의 일부로, 그것을 "활성"/"살아있게" 유지하는 등록된 로케이션 또는 구성 로케이션이 없다고 발견된 엔티티에 이 어노테이션을 주입합니다.
예를 들어, 사용자가 먼저 Location 종류 엔티티를 가리키는 로케이션 URL을 등록하고, 그 엔티티가 근처의 두 다른 파일에 있는 두 Component 종류 엔티티를 참조한다고 가정해 보세요. 최종 결과는 카탈로그에 그 세 엔티티가 포함되는 것입니다. 이제 사용자가 원래 Location 엔티티를 편집해 Component 종류 엔티티 중 첫 번째만 참조하게 한다고 가정해 보세요. 이것은 의도적으로 다른 Component 엔티티가 카탈로그에서 제거되도록 이어지지 않습니다(안전상의 이유로). 대신 그것은 이 고아 표시 어노테이션을 얻어, 원한다면 완전히 제거하려면 사용자 조치가 필요하다는 것을 분명히 합니다.
# Example:metadata: annotations: backstage.io/orphan: 'true'
backstage.io/techdocs-ref
# Example:metadata: annotations: backstage.io/techdocs-ref: dir:.
이 어노테이션의 값은 TechDocs 소스 콘텐츠가 어디에 저장되어 있는지 알려주어, 그것을 읽고 거기서 문서를 생성할 수 있게 합니다. 가장 흔하게는 연관된 mkdocs.yml 파일을 찾을 수 있는, catalog-info.yaml 자체의 위치에 상대적인 경로로 작성됩니다.
카탈로그 엔티티의 문서가 엔티티의 소스 코드와 함께 살지 않는 이례적인 상황에서는, 이 어노테이션의 값이 위에 설명된 로케이션 참조 문자열 형식과 일치하는 절대 URL을 가리킬 수 있습니다. 예: url:https://github.com/backstage/backstage/tree/master
backstage.io/techdocs-entity
# Example:metadata: annotations: backstage.io/techdocs-entity: component:default/example
이 어노테이션의 값은 TechDocs를 소유하는 외부 엔티티를 알려줍니다. 이렇게 하면 TechDocs 페이지에서 TechDocs를 중복하지 않고, 같은 문서의 여러 빌드를 필요로 하지도 않으면서 단일 소스에서 TechDocs를 참조할 수 있습니다.
이것은 단일 저장소를 공유하고, 아마 단일 TechDoc 위치를 가진 복잡한 시스템이 있는 상황을 위한 것입니다.
backstage.io/techdocs-entity-path
# Example:metadata: annotations: backstage.io/techdocs-entity: component:default/example backstage.io/techdocs-entity-path: /path/to/this/component
이 어노테이션의 값은 TechDocs를 소유하는 외부 엔티티 안에서 이 컴포넌트의 TechDocs까지의 경로를 알려줍니다. backstage.io/techdocs-entity와 함께 사용하면 다른 엔티티의 TechDocs 루트에 연결하는 것뿐 아니라 TechDocs로의 딥 링크를 가능하게 합니다.
backstage.io/view-url, backstage.io/edit-url
# Example:metadata: annotations: backstage.io/view-url: https://some.website/catalog-info.yaml backstage.io/edit-url: https://github.com/my-org/catalog/edit/master/my-service.jsonnet
이 어노테이션들은 카탈로그 페이지의 링크를 커스터마이즈할 수 있게 해 줍니다. view URL은 이 엔티티를 지배하는 표준 메타데이터 YAML을 가리켜야 합니다. edit URL은 메타데이터의 소스 파일을 가리켜야 합니다. 위 예에서 my-org는 모노레포의 Jsonnet 파일에서 카탈로그 데이터를 생성하므로, view와 edit 링크를 바꿔야 합니다.
backstage.io/source-location
# Example:metadata: annotations: backstage.io/source-location: url:https://github.com/my-org/my-service/
엔티티(보통 Component)의 소스 코드를 가리키는 Location 참조입니다. 카탈로그 파일이 소스 코드 저장소 자체에서 수집되지 않을 때 유용합니다. URL이 폴더를 가리키면, 상대 경로 해석이 일관되게 작동하도록 '/'로 끝나야 한다는 것이 중요합니다.
backstage.io/source-template
# Example:metadata: annotations: backstage.io/source-template: template:default/create-react-app-template
주어진 엔티티를 원래 만들 때 사용된 Scaffolder 템플릿의 엔티티 참조를 나타냅니다. "비슷한 것 만들기(create something similar)" 경험을 구동하고, 카탈로그 전반에 걸쳐 소프트웨어 표준 준수를 추적하는 데 유용합니다.
이 값은 catalog:write 액션이 catalog-info.yaml 파일을 만드는 데 사용될 때만 엔티티에 자동으로 추가된다는 점에 주목하세요. 그 외에는 템플릿의 일부로 포함된 어떤 엔티티 정의가 이 어노테이션을 포함하도록 보장하는 것은 템플릿 작성자의 책임입니다.
jenkins.io/job-full-name
# Example:metadata: annotations: jenkins.io/job-full-name: folder-name/job-name
이 어노테이션의 값은 이 엔티티를 빌드하는 Jenkins의 작업 경로입니다.
값은 [folder-path] 형식이거나, app-config.yaml에 여러 인스턴스가 구성된 경우 [instanceName]:[folder-path] 형식일 수 있습니다.
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 Jenkins 관련 기능이 활성화될 수 있습니다.
github.com/project-slug
# Example:metadata: annotations: github.com/project-slug: backstage/backstage
이 어노테이션의 값은 이 엔티티와 관련된 GitHub(공개 또는 비공개 GitHub Enterprise 설치)의 저장소를 식별하는 소위 slug입니다. <organization or owner>/<repository> 형식이며, 그 저장소를 볼 때 브라우저의 URL 주소창에 보이는 것과 같습니다.
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 GitHub 관련 기능이 활성화됩니다.
github.com/team-slug
# Example:metadata: annotations: github.com/team-slug: backstage/maintainers
이 어노테이션의 값은 이 엔티티와 관련된 GitHub(공개 또는 비공개 GitHub Enterprise 설치)의 팀을 식별하는 소위 slug입니다. <organization>/<team> 형식이며, 그 팀을 볼 때 브라우저의 URL 주소창에 보이는 것과 같습니다.
이 어노테이션은 Group 엔티티에서 그 팀이 GitHub의 그 팀에서 비롯되었음을 표시하는 데 사용할 수 있습니다.
github.com/user-login
# Example:metadata: annotations: github.com/user-login: freben
이 어노테이션의 값은 이 엔티티와 관련된 GitHub(공개 또는 비공개 GitHub Enterprise 설치)의 사용자를 식별하는 소위 로그인입니다. <username> 형식이며, 그 사용자를 볼 때 브라우저의 URL 주소창에 보이는 것과 같습니다.
이 어노테이션은 User 엔티티에서 그 사용자가 GitHub의 그 사용자에서 비롯되었음을 표시하는 데 사용할 수 있습니다.
github.com/user-id
# Example:metadata: annotations: github.com/user-id: 'MDQ6VXNlcmJhY2tzdGFnZS5leGFtcGxl'
이 어노테이션의 값은 이 엔티티와 관련된 GitHub(공개 또는 비공개 GitHub Enterprise 설치)의 사용자를 식별하는 전역 노드 ID입니다. REST API에서는 node_id 필드이고 GraphQL API에서는 id 필드입니다. 사용자가 바꿀 수 있는 사용자 이름과 달리, 노드 ID는 변경 불가능합니다.
이 어노테이션은 User 엔티티에서 그 사용자가 GitHub의 그 사용자에서 비롯되었음을 표시하는 데 사용할 수 있습니다. 인증 중에 userIdMatchingUserEntityAnnotation sign-in resolver가 GitHub 사용자 ID로 사용자를 일치시킬 수 있게 해 줍니다.
gitlab.com/user-id
# Example:metadata: annotations: gitlab.com/user-id: '123456'
이 어노테이션의 값은 이 엔티티와 관련된 GitLab(공개 또는 비공개 GitLab 설치)의 사용자를 식별하는 숫자 사용자 ID입니다. 자체 호스팅 GitLab 인스턴스의 경우 어노테이션 키는 {integration-host}/user-id이며, 여기서 {integration-host}는 여러분의 GitLab 인스턴스 호스트 이름입니다. 바꿀 수 있는 사용자 이름과 달리, 사용자 ID는 변경 불가능합니다.
이 어노테이션은 User 엔티티에서 그 사용자가 GitLab의 그 사용자에서 비롯되었음을 표시하는 데 사용할 수 있습니다. 인증 중에 userIdMatchingUserEntityAnnotation sign-in resolver가 GitLab 사용자 ID로 사용자를 일치시킬 수 있게 해 줍니다.
gocd.org/pipelines
# Example:metadata: annotations: gocd.org/pipelines: backstage,backstage-pr,backstage-builder
이 어노테이션의 값은 CI/CD 정보를 가져올 GoCD 파이프라인 이름의 쉼표 구분 목록입니다.
파이프라인 이름은 보통 파이프라인 정의의 gocd.yml 파일에 정의됩니다.
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 GoCD 관련 기능이 활성화됩니다.
periskop.io/service-name
# Example:metadata: annotations: periskop.io/service-name: pump-station
이 어노테이션의 값은 주어진 엔티티에 대한 periskop 프로젝트 이름입니다.
periskop 플러그인이 설치되어 있다면, 이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 Periskop 관련 기능이 활성화됩니다.
sentry.io/project-slug
# Example:metadata: annotations: sentry.io/project-slug: backstage/pump-station
이 어노테이션의 값은 여러분의 조직 안에서 Sentry 프로젝트의 소위 slug(또는 대안적으로 ID)입니다. 값은 [organization]/[project-slug] 또는 그냥 [project-slug] 형식일 수 있습니다. 조직 slug가 생략되면 app-config.yaml이 폴백으로 사용됩니다(sentry.organization).
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 Sentry 관련 기능이 활성화될 수 있습니다.
rollbar.com/project-slug
# Example:metadata: annotations: rollbar.com/project-slug: backstage/pump-station
이 어노테이션의 값은 여러분의 조직 안에서 Rollbar 프로젝트의 소위 slug(또는 대안적으로 ID)입니다. 값은 [organization]/[project-slug] 또는 그냥 [project-slug] 형식일 수 있습니다. 조직 slug가 생략되면 app-config.yaml이 폴백으로 사용됩니다(rollbar.organization 다음에 organization.name).
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 Rollbar 관련 기능이 활성화될 수 있습니다.
circleci.com/project-slug
# Example:metadata: annotations: circleci.com/project-slug: github/spotify/pump-station
이 어노테이션의 값은 여러분의 조직 안에서 CircleCI 프로젝트의 소위 slug(또는 대안적으로 ID)입니다. 값은 [source-control-manager]/[organization]/[project-slug] 또는 그냥 [organization]/[project-slug] 형식일 수 있습니다. [source-control-manager] slug가 생략되면 bitbucket이 폴백으로 사용됩니다.
이 어노테이션을 지정하면 Backstage의 CI/CD 기능이 그 엔티티에 대해 CircleCI의 데이터를 표시하게 됩니다.
github.com/project-slug와 circleci.com/project-slug 어노테이션을 모두 제공하면 둘 다 CI/CD 기능에 사용될 수 있어 문제를 일으킬 수 있습니다.
backstage.io/ldap-rdn, backstage.io/ldap-uuid, backstage.io/ldap-dn
# Example:metadata: annotations: backstage.io/ldap-rdn: my-team backstage.io/ldap-uuid: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21 backstage.io/ldap-dn: cn=my-team,ou=access,ou=groups,ou=spotify,dc=spotify,dc=net
이 어노테이션들의 값은 LDAP에서 엔티티를 수집할 때 발견된 대응 속성들입니다. 수집 시 서버가 제시한 속성에 따라 모두 존재하지 않을 수 있습니다.
graph.microsoft.com/tenant-id, graph.microsoft.com/group-id, graph.microsoft.com/user-id
# Example:metadata: annotations: graph.microsoft.com/tenant-id: 6902611b-ffc1-463f-8af3-4d5285dc057b graph.microsoft.com/group-id: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21 graph.microsoft.com/user-id: 2de244b5-104b-4e8f-a3b8-dce3c31e54b6
이 어노테이션들의 값은 Microsoft Graph API에서 엔티티를 수집할 때 발견된 대응 속성들입니다. 수집 시 서버가 제시한 속성에 따라 모두 존재하지 않을 수 있습니다.
sonarqube.org/project-key
# Example:metadata: annotations: sonarqube.org/project-key: pump-station
이 어노테이션의 값은 여러분의 조직 안에서 SonarQube 또는 SonarCloud 프로젝트의 프로젝트 키입니다.
이 어노테이션을 지정하면 Backstage에서 그 엔티티에 대해 SonarQube 관련 기능이 활성화될 수 있습니다.
backstage.io/code-coverage
# Example:metadata: annotations: backstage.io/code-coverage: scm-only
이 어노테이션의 값은 code-coverage backstage 플러그인을 제어합니다. scm-only로 설정하면 플러그인은 소스 제어에 저장된 파일만 고려합니다(예: 생성된 코드 무시). enabled로 설정하면 커버리지 보고서가 다루는 모든 파일이 고려됩니다.
vault.io/secrets-path
# Example:metadata: annotations: vault.io/secrets-path: test/backstage
이 어노테이션의 값은 Vault에서 엔티티의 비밀로 가는 경로를 포함합니다. Vault 플러그인을 사용할 때 존재하지 않으면, 대신 catalog-info.yaml에서 무엇이 빠졌는지 사용자에게 알려주는 메시지가 표시됩니다.
더 이상 사용되지 않는 어노테이션
다음 어노테이션들은 더 이상 사용되지 않으며, 그것에서 벗어나 마이그레이션하는 것을 돕기 위해서만 여기에 나열됩니다.
backstage.io/github-actions-id
이 어노테이션은 한동안 GitHub Actions 기능을 활성화하는 데 사용되었습니다. 이제는 같은 값 형식의 github.com/project-slug 어노테이션을 대신 사용합니다.
backstage.io/definition-at-location
이 어노테이션은 다른 로케이션에서 API 정의를 로드할 수 있게 했습니다. 대신 치환(substitution)을 사용하세요.
jenkins.io/github-folder
대신 jenkins.io/job-full-name을 사용하세요.
링크
- 서술자 형식(Descriptor Format): 어노테이션