Contributors:
Index:
- RFC 002 - dazn-manifest
We are aiming to provide a better structure around the documentation and understanding of every repository. To do so, it is important to adopt a standard and centralised approach across all repositories.
This document has been reviewed and approved by majority vote, it is now to be fully adopted as a DAZN standard.
The .dazn-manifest.yml described in this document would provide important information about the repository.
The manifest is particularly helpful when it documents a microservice. The aim is to bring service documentation closer to the source code, so that it becomes part of the development cycle.
The .dazn-manifest.yml file is written in a machine-readable format, YAML, to allow it to drive tooling and automation. Its content is also made available in a human-friendly format to all stakeholders by the Alexandria project. This metadata-driven approach allows us to standardise the format of our service documentation.
All DAZN projects must introduce the .dazn-manifest.yml file described in this RFC.
The SRE team is the custodian of the dazn-manifest, for any question they be reached
This .dazn-manifest.yml has several audiences and is used in a number of different ways.
Some projects contain tooling or applications intended to be shared with other DAZN engineers. Some fields within the .dazn-manifest.yml allow maintainers to expose information about a given package to facilitate discovery and sharing throughout DAZN engineering.
With Alexandria the developers will have a central place to browse all services with a consistent experience; the .dazn-manifest.yml metadata presented by Alexandria can be used to understand how internal upstream and downstream dependencies work as well as for dev onboarding.
The dazn-linter project would read the .dazn-manifest.yml file and parse it for each commit made on any repository.
It uses the configuration under the linter property to know which rules are relevant to that specific repository.
The current manifest version is 3.3.0.
The dazn manifest file name is .dazn-manifest.yml, it is located in the root of the git repository. The format of the manifest is yaml.
🔗 dazn-manifest
A YAML file which describes the contents of a code repository in a machine readable format.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| dazn-manifest | string | REQUIRED The dazn-manifest version. This schema describes 3.3.0. | 3.3.0[ "3.3.0"] |
|
| owner | string | REQUIRED The owner of the repo. Must be an email address and is usually the mailing list of a development team. If this field is provided it becomes possible to discover the owner of the service by looking in the service dictionary. This field also enables grouping services by team. | ||
| inner-source | Inner Source Projects[] |
Information about the inner source projects contained in the repo | ||
| services | Service[] |
Information about the services contained in the repo. Providing this information fuels services such as Alexandria. | ||
| systems | System[] |
Information about the systems contained in the repo. | ||
| linter | Linter | Provides context used by the dazn-linter to know which rules should apply to this repository. | ||
| pact | Pact | Allows configuring our custom integration of PACT.io. Check out our custom integration repository for more information - https://github.com/getndazn/dapact. |
🔗 Inner Source Projects
A list of Inner Source projects that exist in the current repo.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| directory | string | File path to the inner source package, defaults to the top level directory. | ||
| description | string | Describes the inner source package (especially useful for mono repos). | ||
| friendly-name | string | An optional alternative to the package name (defaults to repo name) | ||
| distribution-method | enum: ["Drone Plugin","NPM","Go Module","Browser Extension","Document","Cloud Infrastructure","CLI","GitHub","Web App"] | REQUIRED Identifies the type of distribution for the inner-source package. Must be one of: 'Drone Plugin', 'NPM', 'Go Module', 'Chrome Extension', 'Document', 'Cloud Infrastructure', 'CLI', 'Github' | ||
| maintainers | string[] |
REQUIRED A list of maintainers of the inner source packages. | ||
| categories | string[] |
A structured set of categories, used to categorise the inner source package. Must be one of 'frontend' or 'backend' | ||
| labels | string[] |
An unstructured set of labels, used to aid discovery of the inner source package. | ||
| rfcs | string[] |
A list of the RFC identifiers which the inner source project implements. RFC name must match the ^RFC-[0-9]{3,10}$ regular expression. |
🔗 Service
Represents a Service or Application located in your repository.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| name | string | REQUIRED Unique, machine readable name of the service. This should match the 'Application' tag in your services' AWS resource tagging. Often it will match the name of your repository. | ^[A-Za-z0-9-]+$ |
playback[ "playback", "rails", "awesome-payment-service"] |
| description | string | A short description of the service. | Service which creates custom widgets for Acme corporation.[ "Service which creates custom widgets for Acme corporation."] |
|
| aws-accounts | string[] |
A list of AWS accounts which this service is deployed to. This list makes it possible to focus tag scanning to particular accounts. | ||
| gcp-projects | string[] |
A list of GCP projects which this service is deployed to. | ||
| azure-subscriptions | string[] |
A list of Azure subscriptions which this service is deployed to. | ||
| application-tags | string[] |
A custom list of 'Application' AWS resource tags assigned to the components within this service. These tags can be used for cost attribution. | ||
| tags | string[] |
A list of strings, used to classify the services in various ways. This is different to the application-tags in metadata, as application-tags are AWS resource tags. | ||
| annotations | Annotations | An object with arbitrary non-identifying metadata attached to the service, Identical in use to Backstage annotations | ||
| domains | Domain[] |
A list of domains exposed by the service. By including a list of domains, it will become possible to search for this service by domain in the service dictionary. | ||
| gateway-enabled | boolean | If true, the service will be registered and all resources will be created | ||
| links | Link[] |
A list of links to external resources related to the service. By including this list, useful documentation and resources become more discoverable from the service dictionary. | ||
| dependencies | Dependency[] |
A description of the dependencies between the service and other services. By completing this section, it will become possible to visualize your service in a service map. | ||
| slo | SLO[] |
A list of Service Level Objectives (SLOs). By providing a list of SLOs it becomes possible to discover and visualize them in the service dictionary. | ||
| security | Security | Security metadata about your service. By completing this section, you make it possible to discover security-related service information in the service dictionary. This section should be completed in collaboration with an application security champion and the information security team. | ||
| support | Support | Support info about the service | ||
| environments | Environments | The environments that the service is deployed to | ||
| system | string | The system that this service belongs to. The system must either be defined in this manifest or in another manifest. | ||
| errors | Error[] |
A list or Errors that this service can cause |
🔗 Annotations
An object with arbitrary non-identifying metadata attached to the service, Identical in use to Backstage annotations
🔗 Domain
A domain exposed by the service. By including a domain, it will become possible to search for this service by this domain in the service dictionary.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| env | enum: ["dev","test","stage","prod"] | The environment the domain belongs to. | ||
| domain | string | The domain exposed by the service. | service-name.dazn-dev.com[ "service-name.dazn-dev.com", "service-name.dazn-test.com", "service-name.dazn-stage.com", "service-name.dazn.com"] |
|
| region | string | The AWS region the domain belongs to, if the domain is region specific. If the domain is global, or the service is not multi-region, this field can be omitted. | eu-central-1[ "eu-central-1", "us-east-1", "ap-northeast-1"] |
🔗 Link
A link to an external resource related to the service.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| type | enum: ["architecture","monitoring","alerting","logging","runbook","other","support-channel"] | REQUIRED The type of link. | ||
| label | string | REQUIRED A description of the link. | Component A dashboard[ "Component A dashboard", "3rd party API docs"] |
|
| url | string | REQUIRED External web page URL. |
🔗 Dependency
A description of a dependency between the service and another service.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| service | string | REQUIRED The name of the other service as defined in its manifest. Service names can be found in the service dictionary. | ^[A-Za-z0-9-]+$ |
playback[ "playback", "rails", "awesome-payment-service"] |
| type | enum: ["requests-from","requests-to","async-requests-from","async-requests-to","notifies","consumes"] | REQUIRED The type of dependency. By providing this value it becomes possible to visualise the different types of dependencies in the service map. | ||
| security | string[] |
A list of techniques used to authenticate the client in inter-service communication. By providing this it becomes possible to visualize service communication security techniques in the dependency map. | ||
| retries | boolean | true if dependency failures are being retried, false if dependency failures are not being retried |
||
| failure-handling | enum: ["ok","fail"] | Defines how the service behaves when request to the dependency are failing (after all resilience mechanisms, eg. retries, caching etc). |
🔗 SLO
A Service Level Objective (SLO).
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| type | enum: ["latency","error","availability","freshness"] | REQUIRED The Service Level Indicator (SLI). | ||
| description | string | REQUIRED Information to appear alongside this SLO in error budget dashboards/alerts | HTTP API latency 3s[ "HTTP API latency 3s"] |
|
| value | number | REQUIRED The service level objective (SLO) value. For example, in '85% of your traffic should have a latency of <= 100ms' the value should be 85. | 95[ 95, 99, 99.95] |
|
| error-budget-tracking | error-budget-tracking-rule[] |
|||
| tags | tags | Optional metric tags to use when querying your SLI data |
🔗 error-budget-tracking-rule
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| window | string | REQUIRED The period to use for tracking expressed as a duration string | `^\d+(s | m |
| threshold | number | REQUIRED Trigger the alert when a given percentage of the error budget has been spent | ||
| alert-enabled | boolean | REQUIRED If true, an alert will be sent to PagerDuty if the threshold is breached |
🔗 tags
Optional metric tags to use when querying your SLI data
🔗 Security
Security metadata about your service. By completing this section, you make it possible to discover security-related service information in the service dictionary. This section should be completed in collaboration with an application security champion and the information security team.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| risk-owner | string | REQUIRED Contact e-mail address to person responsible for risk assessment. If this property is provided, it becomes possible to build automation around finding a replacement risk owner if the risk owner leaves the company. | ||
| risk-tier | enum: ["Low","Medium","High"] | REQUIRED Controls what should be added during the architecture phase and what security practices should be employed during development, testing and maintenance. | ||
| threats | string[] |
Key-threat is person/entity capable of interfering with company security. | ||
| crown-jewels-impact | Crown Jewel[] |
Crown Jewels are assets and data that need special care, their compromise might have a disastrous impact on the company. | ||
| stored-asset-types | string[] |
List of assets that are stored by system. |
🔗 Crown Jewel
A Crown Jewel is an asset or some data that needs special care as their compromise might have a disastrous impact on the company.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| risk-rating | enum: ["Low","Medium","High"] | Risk rating associated with given Crown Jewel in similar fashion to Risk Tier assigned to whole project. | ||
| name | enum: ["The Global Video Network","Production Hubs","CDN network","DRM","Playback","Customer sign up, sign in, account management","Geofencing and geo portability","Other services with big revenue impact","Architectural & technical designs","Proprietary code & binaries","Mergers & Acquisition","ExeCo and senior management identities (CXO Fraud)","Management Information","Card Holder Data (CHD)","Customer Personal Data","HR & Employee Information","Enterprise IdPs (Active Directory, LDAP, AWS IAMs)","Privileged Access Management systems","Secrets, keys & authN credentials"] | Name of given Crown Jewel. |
🔗 Support
Support info about the service
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| escalation-policies | Escalation Policies | REQUIRED Escalation policies for each environment. | ||
| acknowledgement-timeout | integer | Time in seconds that an incident changes to the Triggered State after being Acknowledged | 3600[ 3600] |
|
| urgencies | Urgency[] |
Define the urgency and paging schedules for the service |
🔗 Escalation Policies
Escalation policies for each environment.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| dev | string | Escalation policy to use in dev environment | My teams pre-prod EP[ "My teams pre-prod EP"] |
|
| test | string | Escalation policy to use in test environment | My teams pre-prod EP[ "My teams pre-prod EP"] |
|
| stage | string | Escalation policy to use in stage environment | My teams pre-prod EP[ "My teams pre-prod EP"] |
|
| prod | string | REQUIRED Escalation policy to use in prod environment | My teams prod EP[ "My teams prod EP"] |
🔗 Urgency
Represents an urgency to be used for an environment
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| environment | string[] |
REQUIRED Environment | ||
| urgency | enum: ["low","high"] | Urgency for selected environments | ||
| support-hours | Support Hours | Set support hours for paging. Outside of the schedule hours, pages will not be sent | ||
| subscribe-ops | boolean | Set this to true to ensure that ops are notified whenever the service has an incident | true[ true, false] |
🔗 Support Hours
Set support hours for paging. Outside of the schedule hours, pages will not be sent
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| days-of-week | integer[] |
REQUIRED The days of the week to enable these support hours | ||
| start-time | string | REQUIRED The start time of the support hours in the PagerDuty default timezone (London time) | `^([0-1][0-9] | 2[0-3]):[0-5][0-9]` |
| end-time | string | REQUIRED The end time of the support hours in the PagerDuty default timezone (London time) | `^([0-1][0-9] | 2[0-3]):[0-5][0-9]` |
🔗 Environments
The environments that the service is deployed to. All environments (dev, test, stage, prod) are enabled when this attribute is not qualified.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| dev | boolean | REQUIRED set to false to disable the dev environment | ||
| test | boolean | REQUIRED set to false to disable the test environment | ||
| stage | boolean | REQUIRED set to false to disable the stage environment | ||
| prod | boolean | REQUIRED set to false to disable the prod environment |
🔗 Error
A Error that this service can cause.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| code | string | REQUIRED The error code. Must be unique across all DAZN Manifests | ||
| description | string | REQUIRED Information that describes the error in simple terms | This error code indicates an issue with the payment backend["This error code indicates an issue with the payment backend" ] |
|
| error-originator | string | The name of the service that caused this error. | sre-smart-scaling["sre-smart-scaling" ] |
|
| links | Link[] |
A list of links to external resources related to the error. |
🔗 Links.Link
A link to an external resource related to the error.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| label | string | REQUIRED A description of the link. | ||
| url | string | REQUIRED External web page URL. |
🔗 System
Represents a System that can consist of multiple services.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| name | string | REQUIRED Unique, machine readable name of the system. | ^[A-Za-z0-9-]+$ |
login[ "login", "smart-scaling"] |
| description | string | A short description of the system. | System for logging in users to the platform.[ "System for logging in users to the platform."] |
🔗 Linter
Provides context used by the dazn-linter to know which rules should apply to this repository.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| rules | Rule[] |
A list of linter rules. |
🔗 Rule
A linter rule.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| name | string | Name of the rule to apply the other flags in this object. E.g. name: drone-linter/roles. | drone-linter/roles[ "drone-linter/roles"] |
|
| enabled | boolean | true if the rule is enabled, false if it is disabled. |
🔗 Pact
Allows configuring our custom integration of PACT.io. Check out our custom integration repository for more information - https://github.com/getndazn/dapact.
| Field Name | Type | Description | Format or Pattern | Examples |
|---|---|---|---|---|
| enabled | boolean | Defaults to false because it is an opt-in feature. If set to true, you acknowledge that the .drone.yml file is ready to be executed with an event deployment and environment pact (All other deployment events should either specifically run for an environment, or exclude the pact environment). |
dazn-manifest: 3.3.0
owner: [email protected]
services:
- name: awesome-service
description: A short description of the service.
aws-accounts:
- dazn-ar-dev
- dazn-ar-test
- dazn-ar-stage
- dazn-ar-prod
dependencies:
- type: requests-to
service: some-http-service
- type: consumes
service: some-message-sending-service
security:
risk-owner: "[email protected]"
risk-tier: "Medium"dazn-manifest: 3.3.0
owner: [email protected]
services:
- name: awesome-service
description: A short description of the service.
system: my-awesome-system
aws-accounts:
- dazn-ar-dev
- dazn-ar-test
- dazn-ar-stage
- dazn-ar-prod
application-tags:
- some-service
tags:
- backend
dependencies:
- service: some-other-service
type: requests-to
- service: some-other-service
type: requests-from
security:
- api-key
- jwt
- service: some-other-service-with-sqs-queue
type: async-requests-to
security:
- iam
- service: some-other-service-with-sns-topic
type: async-requests-from
security:
- iam
domains:
- env: dev
domain: some-dev-url.dazn.com
region: eu-central-1
- env: test
domain: some-test-url.dazn.com
region: eu-central-1
- env: stage
domain: some-stage-url.dazn.com
- env: prod
domain: some-prod-url.dazn.com
gateway-enabled: false
links:
- label: Amazing runbook
type: runbook
url: https://livesport.atlassian.net/browse/awesome-runbook
- label: Amazing dashboard
type: monitoring
url: https://one.newrelic.com/somedashboard
slo:
- type: latency
value: 85
description: latency SLO for eu-central-1
tags:
region: eu-central-1
error-budget-tracking:
- threshold: 0
window: 1d
alert-enabled: false
- threshold: 25
window: 1h
alert-enabled: true
- type: availability
value: 99.95
description: avaliability SLO for us-east-1
tags:
region: us-east-1
support:
escalation-policies:
prod: "My Escalation Policy"
acknowledgement-timeout: 3600
urgencies:
- environment:
- dev
- test
- stage
urgency: low
subscribe-ops: false
support-hours:
days-of-week:
- 1
- 2
- 3
- 4
- 5
start-time: 09:00
end-time: 17:30
- environment:
- prod
urgency: high
subscribe-ops: true
security:
risk-owner: "[email protected]"
risk-tier: "Medium"
crown-jewels-impact:
- name: "Card Holder Data (CHD)"
risk-rating: "High"
- name: "Proprietary code & binaries"
risk-rating: "Medium"
threats:
- "External dependencies in code"
- "Ransomeware attack on database"
stored-asset-types:
- "Log of customer actions"
- "Encrypted customer data"
annotations:
backstage.io/techdocs-ref: dir:.
backstage.io/code-coverage: scm-only
errors:
- code: myerrorprefix-myerrorssuffix
description: An error that is returned whenever a user's account has been blocked
systems:
- name: my-awesome-system
description: "This is an awesome system"
inner-source:
- distribution-method: NPM
directory: ./packages/my-inner-source-one
maintainers:
- [email protected]
- distribution-method: "Go Module"
friendly-name: "Go Package"
description: "My lovely package"
maintainers:
- [email protected]
directory: ./packages/my-inner-source-two
categories:
- frontend
- backend
labels:
- api
- javascript
- REST
rfcs:
- RFC-001
- RFC-002
linter:
rules:
- name: linter-rule-foo
enabled: true
pact:
enabled: trueThe schema documentation contained in this page was built from the dazn-manifest.schema.json, which contains more in-depth validation rules than are displayed here.
Most IDEs will provide auto-completion and validation if you configure a mapping between .dazn-manifest.yml files and the schema. To make this as easy as possible, the schema is also hosted publicly.
To re-generate this markdown file, use this project.
node ./ -s ../../getndazn/rfc/attachments/RFC-002/dazn-manifest.schema.json -o ../../getndazn/rfc/RFC-002\ -\ dazn-manifest.md --header 'Schema'