Service Passport

Your documentation entry point

Service Passport

If your Service wants to be a good citizen of the Application Landscape (and Service360) - it needs a Passport! 🙂

Service Passport is one of the most important concepts introduced by Service360. This is a document that allows a user by a quick look at it to get a high-level understanding of what is this service about, how it is built, run, and maintained.

Technically Service Passport is nothing more than a way to organize the root README.md file of the repository so it will become structured and easily readable by both humans and the machine. And we promise you that this organization is not that special to not be learned in 5 minutes!

Minimal valid Service Passport looks like:

# HelloWorld Service

Owner|
---|
Team1|

That’s it! You got it right: minimal requirements for README.md to qualify as a Passport is to have h1/# tag with the Service name at the very beginning of the file and have defined Service owner.

But as you might think this minimal Service Passport is not really that useful (while it already allows you to understand what does the code repository contains and whom you should contact in case of questions). Below you will find 3 samples of the valid Service Passports. Those samples show different levels of Service Passport completeness.

Examples

Minimal passport

A showcase of the minimally valid passport with the addition of the service description.

# HelloWorldService

Hello world service greets the world every time it desires to.

What a wonderful service!

Owner|
---|
Team1|

Standard passport

A showcase of all of the special sections supported by the S360.

# HelloWorldLibrary

Hello world library allows you to greet the world.

Type|Owner|Status
---|---|---
Library|AwesomeTeam|Deprecated

##### Contexts

- CustomerData
- Greetings
- Backend

##### Links

- Production AWS account: 123456789
- Production Endpoint: https://helloworld.example/
- Production Metrics dashboard: https://....
- Staging AWS account: 987654321
- Staging Endpoint: https://staging.helloworld.example/
- Staging Metrics dashboard: https://....

##### Tech

- Golang: main implementation language
- Docker: deployment artifact
- AWS ECS: deployment runtime
- AWS SQS
- AWS SNS
- Google BigTable: main storage engine

## How to deploy

Super awesome service is deployed by our CI/CD pipeline,
so just tag the commit and push to master.

In case you still want to do manual deployment:

    make deploy ENV=prod VERSION=v1.2.3

Extended passport

Standard passport + some additional custom sections of your choice.

# HelloWorldService

Hello world service greets the world every time it desires to.

What a wonderful service!

Owner|Status|SLA|Tier|Contexts
---|---|---|---|---
AwesomeTeam|Deprecated|90%|Tier1|CustomerData,Greetings,Backend

##### Deprecated

This service is deprecated in favour of HelloWorldServiceV2.
Please consider using it instead!

This service will be retired in May 2042.

##### Links

- Production AWS account: 123456789
- Production Endpoint: https://helloworld.example/
- Production Metrics dashboard: https://....
- Staging AWS account: 987654321
- Staging Endpoint: https://staging.helloworld.example/
- Staging Metrics dashboard: https://....

##### Tech

- Golang : main implementation language
- Docker : deployment artifact
- AWS ECS : deployment runtime
- AWS SQS
- AWS SNS
- Google BigTable : why not?

##### Metrics

- Amount of processed requests
- Amount of failed requests
- Amount of messages waiting for processing

##### Alerts

- [P1] Healthcheck
  Triggered in case service is not available 3 times via Route53 healthcheck
- [P2] TooBigProcessingQueue
  Triggered in case there is > 1000 messages waiting in the processing queue

## How to deploy

Super awesome service is deployed by our CI/CD pipeline,
so just tag the commit and push to master.

In case you still want to do manual deployment:

    make deploy ENV=prod VERSION=v1.2.3

See? You do not need to learn anything special to create beautiful Service Passports and they stay useful even if you are not using Service360 interface. README structured this way looks nice through any other interface: be it Github, Gitlab, some random developer IDE, or simply in the terminal of your choice.

Let’s have a closer look at the Service Passport structure.

Passport sections

Service Passport consists of the so-called “sections”. Each section provides users with the answer to one question: what does this service do? Who ones the service? How can I contact the service owner? Where is it deployed? Which technologies power the service? And so on.

Almost all sections of the passport are optional. Only the Service name and Owner are the required ones.

Sections can be declared in two ways:

  • via table formatting
  • via h5/##### headers which directly follow h1/# header (i.e. there can be any other content except headers between h1/# header and first h5/#####)

It is up to you what kind of formatting to use for which section, thou we encourage to use table formatting for essential sections which are usually answered with one word. For example: Owner, SLA, Tier, Type, Status, etc

Everything which starts with non-h5/##### title is considered to be basic service documentation and will be shown on the “Docs” the tab of Service360 Service Registry page.

You can create whatever section you like and it will be correctly parsed and shown by Service360, but there are some special ones which have a special meaning and are processed some special way.

The order in which you place sections in the Passport is irrelevant (with the exception of the Title and Description fields).

Owner

There can be one and only one service owner. We encourage to specify a team in this section. Not a person.

Service without an Owner section will be highlighted as a high-risk service in the interface and Service name will be taken from the repository name, not from the README file.

Description

The only special section which does NOT require a specific declaration. Everything between the first h1/# header and next header/table is considered to be a service description

Type

Type of the asset which the repository holds. Based on the type a different set of risk assessments are applied to the repo and Service Registry interface experience might vary.

Valid values:

  • Web Service - default type
  • Mobile App
  • Desktop App
  • Embedded App
  • Library
  • Support
  • External - Risk detection is completely switched off

Status

Any value is allowed here but there are some special ones that trigger specific behavior of the Service360 platform.

Special values:

  • Production - Default value. In case Status section is not mentioned in the Passport Production value is assumed
  • In development - In case this value is specified and any other production service depends on it - risk will be raised for the dependent service.
  • Retired - Service name will be grayed out in the list and all service related risks will be ignored

Contexts

Service360 expects to find here a simple list with service contexts/tags.

It is advised to define all possible Contexts jointly with all owners on the Library/Organization level, not on the owner/team/service. This will allow to separate concerns/draft the domains better. One can treat Contexts as a tag taxonomy of the services. A way to cluster services together.

Contexts are used for filtering and reporting in ServiceRegistry, BigPicture and Pulse as well as for the calculation of the team cognitive load Available in Alpha. Services having the same context are available via a separate “virtual” library.

The Owner is automatically added to the Contexts in case it is present.

Special context values:

  • MaintenanceOnly: negates “Service has no recent releases” risk

Deprecated

In case this section is present huge deprecation warning will be shown and service will be highlighted as a Risk for all dependent consumers.

Tech

Service360 expects to find here a list of technologies used by service.

Technology can be annotated with optional description via a semicolon. We encourage to annotate all used tech with a short description which describes how is this technology applied in the service.

This section is used to assemble TechRadar of the organization.

Example:

##### Tech

- Golang
- RabbitMQ: communication with external services
- Serverless: deployment
- AWS Lambda: execution runtime

That’s it! Simple, right? We encourage you to try organising your repos with the Service Passports. Even if you not gonna use Service360 it will still pay off (while we’d love to see you onboard! :))

You can have a look at properly formatted Service Passports in the SampleOrg github organization.

Service360 Setup
Service Dependency Graph

Very soon

We are working hard with our alpha testers to make sure you will get the best in class product. Subscribe to our newsletter to stay informed about the progress and to receive an invitation to our beta test!