Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

AP-20 adding details #103

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

AP-20 adding details #103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 12 additions & 72 deletions _ap/20/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,91 +7,31 @@ authors:
tags: []
---

// Let's set some key guidelines and define the audience
//
// This Architecture Pattern is to be read by a person who
// * is not expert in the field of services
// * wants to understand and use good practices
// * has to read 90 other documents like that in the course of a week
//
// So clear, simple, concise and appealing is paramount.
// Bite size is awesome (it's ok to create several of these document to stay focused in each).
// Aim to provide as early and clearly as possible the following:
// * what for (context)
// * why it's useful (value)
// * how it is done (with examples)
//
// Your title should describe what the document *solves*: `How to write guidelines useful for noobs`
// If you have several recommendations, try to separate them visually (paragraphs) as it makes them stand out and can be read / parsed faster.
// Use examples for minds that can extrapolate rules from concrete example, it's an anchor to understand the problem and the solution.
//
// More writing style tips:
// * Use one sentence per line
// * No unexpanded acronyms
// * No undefined jargon
// * avoid Red Hat specific lingo, this is community centric
//
// You don't have to use the following sections, but they provide a
// useful structure for writing a clear document.

## Intent
// Summarize in a single sentence what the pattern tries to achieve.
//
// For example:
//
// Define a policy for exposing metrics to customers in a consistent way.

Track the decision to use Addons Monitoring as the default Observability Solution for addons.

## Motivation

// In a few paragraphs describe the motivating factors for this pattern
//
// For example:
//
// Prometheus scrape endpoints are the defacto standard for exposing metric information for collection.
// However this format and the associated conventions are not sufficient in themselves to ensure
// that metrics are exposed in a consistent way. Problems include:
// * Insufficient guidance on metric and label naming to provide consistency and
// establishing the principal of hiding implementation details.
// * Treatment of this as a first-class API, with established mechanisms for API evolution
// * etc.
Being required to have an observability stack is a common consideration for addons so recommending a common approach makes sense.

## Applicability

// Call out when this pattern might apply (and when it should not apply, if relevant)
// For example:
//
// This pattern applies to any service which exposes metrics as Prometheus-scrape endpoints.
// It does not apply to services which provide access to metrics in other formats, or via
// means other than an API (e.g. metric visualization via a system such as Grafana).
This applies to any addon as there is a need to provide observability in order to be fully supported as a Managed Service.

## Description

// Describe the pattern in enough detail that a fresh pair of eyes can understand it
// and apply it elsewhere.
//
// For this metrics example we might link to existing guidelines on naming, augment them with extra rules
// which apply to services, explain how the API would allow for graceful API evolution without "flag days".
Usage of Addons Monitoring is described in the https://docs.google.com/document/d/15dxGKVUygUJ7NSmil8uf_yOidI9__lGEi_q6FJIE2ic/edit#[ADR document].

## Participants

// What components and/or teams are directly involved
//
// For this metrics example this would include the customer and the control plane via which
// the metrics are exposed
The component which is used is the https://github.com/rhobs/observability-operator[rhobs/observability-operator]
The team managing the component can be found in slack channel #forum-monitoring

## Trade-offs

// Explain any consequences of using this pattern.
// Be sure to cover both pros and cons:
// * what this pattern enables and the benefits it brings
// * what this pattern prevents or makes harder
//
// For this metrics example such benefits would include:
// * A mechanism for API evolution
// * Consistency in naming of metrics and labels within this service
// * Consistency with other services which also apply this AP
//
// And on the down side:
// * The Prometheus format eventually be superseded
// * Naming and consistency is hard, so multiple versions of the API
// might be needed to achieve those goals.
Maintaining an observability stack that is life-cycled by the addon itself is a pattern that does exist currently via the
https://github.com/redhat-developer/observability-operator[redhat-developer/observability-operator].
By maintaining a separate stack, changes needed can be made available more quickly as it's tied to the addon version
rather than the OSD version. This comes with its own challenges such as increase workload to manage the release
if a new version of the observability-operator.