Skip to content

Add process for reference architectures #63

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

Merged
rochaporto merged 4 commits into from
Jul 21, 2025
Merged

Add process for reference architectures #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bdac1b5
Add process for reference architectures
rochaporto Jun 26, 2025
44658e8
Update reference-architectures.md
chadbeaudin Jun 27, 2025
8f04beb
Add numbers to states in refarchs process
rochaporto Jul 8, 2025
b51078f
Add coming soon note to issue template for submission
rochaporto Jul 21, 2025
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
Binary file added process/reference-architectures-workflow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
73 changes: 73 additions & 0 deletions process/reference-architectures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Reference Architecture Submission Process

This document summarizes the process for the submission, review, and publication of new reference architectures in the CNCF. It describes the expected workflow and the different stakeholders involved in each step.

![Reference Architecture Workflow Diagram](reference-architectures-workflow.png)
<p align="center">
( <a href="https://docs.google.com/drawings/d/1VkNwpQS_IxZKSl49B-RXzo1Zh2mofQ-MFRyoYhnDkus/edit?usp=sharing">original diagram</a> )
</p>

## Workflow Steps

### 1. Proposed
Copy link

@ride808 ride808 Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should there be any up front guidance in the process explaining the intent of reference architectures and maybe also what would not be considered acceptable? Or do we just let that come out in the review process?

Copy link
Contributor Author

@rochaporto rochaporto Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Absolutely. We should add goals, DOs and DONTs, etc. Should we keep it in the process here or have a separate doc page and link to that later?


*Who: Individual End Users, Groups of End Users, Community Groups*

New reference architectures should be submitted via [this github template (coming soon)]() by individual end users, groups of end users from a specific domain or end user group, or community groups.

The information to be included in the proposal is in the template, and includes at a minimum:
* The contact for the reference architecture;
* The end user(s) organization(s) backing the submission and its content;
* The CNCF projects being used by the stack;
* (optional) The domain or industry of the reference architecture;

### 2a. Accepted

*Who: Acceptance should be done by the TAB members*

Each submission should be reviewed by the TAB and accepted before the detailed work starts. The purpose of this step is to validate its relevance to the community and clarify any open items, potential overlaps with existing documents, etc.

Once accepted, work should start in expanding the content of the reference architecture.

### 2b. Rejected

*Who: Rejection should be done by the TAB members*

After a review by the assigned TAB member and consultation with the complete TAB a proposal can be rejected.

Rejection can happen due to different reasons, such as a proposal being out of scope for cloud native architectures, excessive reliance on proprietary products, etc.

### 3a. Reviewed

*Who: One or more members of the TAB previously assigned to this reference architecture*

Review of reference architectures is expected to be an iterative process between the submitters and the reviewers assigned by the TAB - usually TAB members. This process aims at keeping the content consistent across different submissions as well as ensuring the key take-aways are properly highlighted.

### 3b. Feedback

*Who: TAB members assigned to this reference architecture*

Feedback should be provided for every reference architecture being rejected (see 2b above). Where appropriate, additional information regarding a potential later resubmission should also be included.

### 4. Validated

*Who: Technical Oversight Committee (TOC)*

Reference architectures often include extensive information regarding the usage of projects in the CNCF, including the end user perspective on the project maturity and production readiness. These might in some cases conflict with the project maturity levels as set by the TOC.

To prevent confusion and conflicting information, the TOC is consulted to validate the reference architecture. The TOC might, if appropriate, request the submitters add additional context information on the usage of a project and explanations on any conflicting views of the project maturity.

### 5. Published

*Who: Reference Architecture submitters, reviewers and CNCF staff*

Once validated the new reference architecture is published under [https://architecture.cncf.io/](https://architecture.cncf.io/). This is done by CNCF staff in coordination with the submitters and the reviewers, collecting additional information relevant for the announcement.

### 6. Announced

*Who: CNCF Staff and TAB*

After publication CNCF staff and TAB take care of the announcement of the new reference architecture via different mechanisms, at least:
* As a news item in the monthly TAB public meeting
* An email circulated to the end user mailing list
* A message in the #enduser and #tab channels in the CNCF slack