From 5f92a3b28f89fd53783bd49110fedf1308686e3b Mon Sep 17 00:00:00 2001 From: Avani Bhatt Date: Mon, 30 Oct 2023 19:06:22 +0000 Subject: [PATCH] Cleanup, rewrite, unordered list, use attributes --- content/learn/about-pattern-tiers-types.adoc | 23 +++++---- content/learn/implementation.adoc | 52 +++++++++++--------- content/learn/maintained.adoc | 29 +++++------ content/learn/sandbox.adoc | 24 ++++----- content/learn/test-artefacts.adoc | 3 ++ content/learn/tested.adoc | 30 +++++------ 6 files changed, 84 insertions(+), 77 deletions(-) diff --git a/content/learn/about-pattern-tiers-types.adoc b/content/learn/about-pattern-tiers-types.adoc index acabd59f0..d259c517e 100644 --- a/content/learn/about-pattern-tiers-types.adoc +++ b/content/learn/about-pattern-tiers-types.adoc @@ -2,7 +2,7 @@ menu: learn: parent: Workflow -title: Validated Pattern Tiers +title: Validated Pattern tiers weight: 41 aliases: /learn/pattern-tier-overview --- @@ -15,27 +15,26 @@ include::modules/comm-attributes.adoc[] [id="pattern-type"] == About the {solution-name-upstream} tiers -To know about the patterns that you can use and contribute towards, understand the following pattern tiers: +To contribute to the patterns that suit your usecase or to learn about onboarding your own pattern, understand the following pattern tiers. |=== |Pattern tier|Description |{sandbox-tier-first} -|A pattern categorized under the {sandbox} tier is an inclusive and low-risk way to become associated with the {solution-name-upstream} project. The minimum requirement to qualify for the {sandbox} tier is that you must start with the patterns framework and include minimal documentation. -The patterns in this tier might be in a work-in-progress state; and they might have been manually tested and on a limited set of platforms. +|A pattern categorized under the {sandbox} tier provides you with an entry-point to onboard to the {solution-name-upstream}. The minimum requirement to qualify for the {sandbox} tier is that you must start with the patterns framework and include minimal documentation. + +These patterns in this tier might be in a work-in-progress state; and they might have been manually tested on a limited set of platforms. |{tested-tier-first} -|A pattern categorized under theThe {tested} tier provides you with additional collateral and reassurance that the pattern was known to be recently working on at least one recent version of {rh-ocp}. Inclusion in this tier requires some additional work for the pattern’s owner - which might be a partner or a sufficiently motivated Subject Matter Expert (SME). -Clear business problem with demo -All components are supportable*, and any Red Hat product usage signed-off by BUs -Test plan (manual or automated) that passes at least once for each new OpenShift minor version within 3 months of GA +|A pattern categorized under the {tested} tier implies that the pattern was known to be recently working on at least one recent version of {rh-ocp}. Qualifying for this tier might require additional work for the pattern’s owner, who might be a partner or a sufficiently motivated subject matter expert (SME). +//Additional work such as? +These patterns in this tier might have a defined business problem with demonstration. The patterns might have a test plan - manual or automated, which passes at least once for each new {rh-ocp} minor version. |{maintained-tier-first} -| intended to provide consumers with additional "sales" collateral and reassurance that the pattern was known to be functional on all currently supported LTS versions of OpenShift. Inclusion in this tier may require additional work for the pattern’s owner - which might be a partner or sufficiently motivated SME. -Group 2 plus… -Formal release process with z-streams -CI automation (either weekly or event driven at a similar interval) +|A pattern categorized under the {tested} tier implies that the pattern was known to be functional on all currently supported extended update support (EUS) versions of {rh-ocp}. Qualifying for this tier might require additional work for the pattern’s owner who might be a partner or a sufficiently motivated SME. + +These patterns might have a formal release process with z-streams They might have continuous integration (CI) automation testing. |=== diff --git a/content/learn/implementation.adoc b/content/learn/implementation.adoc index 02247c280..3cc7ea25d 100644 --- a/content/learn/implementation.adoc +++ b/content/learn/implementation.adoc @@ -9,10 +9,13 @@ aliases: /requirements/implementation/ :toc: +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + [id="technical-requirements"] == Technical requirements -Consider these requirements specific to the implementation for all {solution-name-upstream} and their respective tiers. +Consider these requirements specific to the implementation of all {solution-name-upstream} and their respective tiers. The requirements are categorized as follows: @@ -21,24 +24,24 @@ These are non-negotiable, core requirements that must be implemented. Should:: These are important but not critical; their implementation enhances the pattern. Can:: -These are optional or desirable features, but their absence does not hinder the pattern. +These are optional or desirable features, but their absence does not hinder the implementation of a pattern. [id="must-implementation-requirements"] === Must -. Patterns must include one or more Git repositories, in a publicly accessible location, containing configuration elements that can be consumed by the {rh-gitops} Operator without supplying custom ArgoCD images. -. Patterns must be useful without all content stored in private git repos -. Patterns must include a list of names and versions of all the products and projects being consumed by the pattern -. Patterns must be useful without any sample applications that are private or lack public sources. -+ -Patterns must not become useless due to bit rot or opaque incompatibilities in closed source "`applications`". +. Patterns must include one or more Git repositories in a publicly accessible location, containing configuration elements that can be consumed by the {rh-gitops} Operator without supplying custom ArgoCD images. +. Patterns must be useful without all content stored in private Git repositories. +. Patterns must include a list of names and versions of all the products and projects being consumed by the pattern. +. Patterns must be useful without any sample applications that are private or that lack public sources. +//AI:why application was styled that way +Patterns must *not* become useless due to bit rot or opaque incompatibilities in closed source applications. -. Patterns must *not* store sensitive data elements, including but not limited to passwords, in Git -. Patterns must be possible to deploy on any installer-provisioned infrastructure OpenShift cluster (BYO) -+ -We distinguish between the provisioning and configuration requirements of the initial cluster ("`Patterns`"), and of clusters/machines managed by the initial cluster (see "`Managed clusters`") +. Patterns must *not* store sensitive data elements, including but not limited to passwords, in Git repositories. +. Patterns must be possible to deploy on any installer-provisioned infrastructure OpenShift cluster (BYO). +//AI:why Patterns and Managed clusters is styled that way +We distinguish between the provisioning and configuration requirements of the initial cluster (`Patterns`), and of clusters/machines managed by the initial cluster (see `Managed clusters`). -. Patterns must use a standardized https://github.com/validatedpatterns/common/tree/main/clustergroup[clustergroup] Helm chart, as the initial OpenShift GitOps application that describes all namespaces, subscriptions, and any other GitOps applications which contain the configuration elements that make up the solution. +. Patterns must use a standardized https://github.com/validatedpatterns/common/tree/main/clustergroup[clustergroup] Helm chart, as the initial {rh-gitops} application that describes all namespaces, subscriptions, and any other GitOps applications which contain the configuration elements that make up the solution. . Managed clusters must operate on the premise of "`eventual consistency`" (automatic retries, and an expectation of idempotence), which is one of the essential benefits of the GitOps model. . Imperative elements must be implemented as idempotent code stored in Git @@ -47,7 +50,7 @@ We distinguish between the provisioning and configuration requirements of the in . Patterns should include sample application(s) to demonstrate the business problem(s) addressed by the pattern. . Patterns should try to indicate which parts are foundational as opposed to being for demonstration purposes. -. Patterns should use the {validated-patterns-op} to deploy patterns. However anything that creates the OpenShift GitOps subscription and initial clustergroup application could be acceptable. +. Patterns should use the {validated-patterns-op} to deploy patterns. However anything that creates the {rh-gitops-short} subscription and initial clustergroup application could be acceptable. . Patterns should embody the link:https://www.redhat.com/en/products/open-hybrid-cloud[Open Hybrid Cloud model] unless there is a compelling reason to limit the availability of functionality to a specific platform or topology. . Patterns should use industry standards and Red Hat products for all required tooling + @@ -64,20 +67,21 @@ For example, Bucket Notification is a capability in the Medical Diagnosis patter . Patterns should use Ansible Automation Platform to drive the declarative provisioning and management of managed hosts (e.g. RHEL). See also "`Imperative elements`". . Patterns should use RHACM to manage policy and compliance on any managed clusters. -. Patterns should use RHACM and a https://github.com/validatedpatterns/common/tree/main/acm[standardized acm chart] to deploy and configure OpenShift GitOps to managed clusters. -. Managed clusters should be loosely coupled to their hub, and use OpenShift GitOps to consume applications and configuration directly from Git as opposed to having hard dependencies on a centralized cluster. +. Patterns should use RHACM and a https://github.com/validatedpatterns/common/tree/main/acm[standardized acm chart] to deploy and configure {rh-gitops-short} to managed clusters. +. Managed clusters should be loosely coupled to their hub, and use {rh-gitops-short} to consume applications and configuration directly from Git as opposed to having hard dependencies on a centralized cluster. . Managed clusters should use the "`pull`" deployment model for obtaining their configuration. . Imperative elements should be implemented as Ansible playbooks -. Imperative elements should be driven declaratively -- by which we mean that the playbooks should be triggered by Jobs and/or CronJobs stored in Git and delivered by OpenShift GitOps. +. Imperative elements should be driven declaratively -- by which we mean that the playbooks should be triggered by Jobs or CronJobs stored in Git and delivered by {rh-gitops-short}. [id="can-implementation-requirements"] === Can -. Patterns can include additional configuration and/or demo elements located in one or more additional private git repos. -. Patterns can include automation that deploys a known set of clusters and/or machines in a specific topology -. Patterns can limit functionality/testing claims to specific platforms, topologies, and cluster/node sizes -. Patterns can consume Operators from established partners (e.g. Hashicorp Vault, and Seldon) -. Patterns can include managed clusters +. Patterns can include additional configuration and/or demo elements located in one or more additional private Git repositories. +. Patterns can include automation that deploys a known set of clusters and/or machines in a specific topology. +. Patterns can limit functionality/testing claims to specific platforms, topologies, and cluster/node sizes. +. Patterns can consume Operators from established partners (for example, Hashicorp Vault, and Seldon) +. Patterns can include managed clusters. . Patterns can include details or automation for provisioning managed clusters, or rely on the admin to pre-provision them out-of-band. -. Patterns can also choose to model multi-cluster solutions as an uncoordinated collection of "`initial hub clusters`" -. Imperative elements can interact with cluster state and/or external influences \ No newline at end of file +//AI:why initial hub clusters was styled that way. +. Patterns can also choose to model multi-cluster solutions as an uncoordinated collection of `initial hub clusters` +. Imperative elements can interact with cluster state or external influences. \ No newline at end of file diff --git a/content/learn/maintained.adoc b/content/learn/maintained.adoc index 6cd65b1f1..28ae6aa57 100644 --- a/content/learn/maintained.adoc +++ b/content/learn/maintained.adoc @@ -9,6 +9,7 @@ aliases: /requirements/validated/ --- :toc: + :_content-type: ASSEMBLY include::modules/comm-attributes.adoc[] @@ -38,32 +39,32 @@ specified for the link:/requirements/tested/[Tested tier] [id="must-maintained-tier"] === Must -. {maintained} pattern must continue to meet the following criteria to remain in Maintained Tested tier -. {maintained} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] +A {maintained} pattern must continue to meet the following criteria to remain in {maintained} tier: + +* A {maintained} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] . {maintained} pattern must only make use of components that are either supported, or easily substitued for supportable equivalents (eg. HashiCorp vault which has community and enterprise variants) -. {maintained} pattern must *not* rely on functionality in tech-preview, or hidden behind feature gates -. {maintained} pattern must have their architectures reviewed by the PM, TPM, or TMM of each Red Hat product they consume to ensure consistency with the product teams` intentions and roadmaps -. {maintained} pattern must include a presentation deck oriented around the business problem being solved and intended for use by the field to sell and promote the solution -. {maintained} pattern must include test plan automation that runs on every change to the pattern, or a schedule no less frequently than once per week -. {maintained} pattern must be tested on all currently supported OpenShift LTS releases -. {maintained} pattern must fix breakage in a "timely" manner -. {maintained} pattern must document their support policy +* A {maintained} pattern must *not* rely on functionality in tech-preview, or hidden behind feature gates +* A {maintained} pattern must have their architectures reviewed by the PM, TPM, or TMM of each Red Hat product they consume to ensure consistency with the product teams` intentions and roadmaps +* A {maintained} pattern must include a presentation deck oriented around the business problem being solved and intended for use by the field to sell and promote the solution +* A {maintained} pattern must include test plan automation that runs on every change to the pattern, or a schedule no less frequently than once per week +* A {maintained} pattern must be tested on all currently supported OpenShift LTS releases +* A {maintained} pattern must fix breakage in timely manner +* A {maintained} pattern must document their support policy + -The individual products used in a Validated Pattern are backed by the full Red Hat support experience conditional on the customer's subscription to those products, and the individual products`' support policy. +The individual products used in a Validated Pattern are backed by the full Red Hat support experience conditional on the customer's subscription to those products, and the individual products`s support policy. + Additional components in a Validated Pattern that are not supported by Red Hat (e.g. Hashicorp Vault, and Seldon Core) will require a customer to obtain support from that vendor directly. + The {solution-name-upstream} team is very motivated to address any problems in the VP Operator, as well as problems in the common helm charts, but cannot not offer any SLAs at this time. + -TODO: Create an aDoc version of our support statement slide +//TODO: Create an aDoc version of our support statement slide [NOTE] ==== -The {maintained} pattern *do not* imply an obligation of support for partner or community operators by Red Hat. +The {maintained} patterns *do not* imply an obligation of support for partner or community operators by Red Hat. ==== - [id="can-maintained-tier"] === Can -. Teams creating {solution-name-upstream} CAN provide their own SLA +. Teams creating {solution-name-upstream} can provide their own SLA diff --git a/content/learn/sandbox.adoc b/content/learn/sandbox.adoc index 780d790b3..32145a399 100644 --- a/content/learn/sandbox.adoc +++ b/content/learn/sandbox.adoc @@ -39,19 +39,19 @@ General requirements for all {solution-name-upstream} [id="must-sandbox-tier"] === Must - -. {sandbox} pattern must continue to meet the following criteria to remain in the Sandbox tier -. {sandbox} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] -. {sandbox} pattern must be able to be deployed onto a freshly deployed OpenShift cluster without prior modification or tuning -. {sandbox} pattern must include a top-level README highlighting the business problem and how the pattern solves it -. {sandbox} pattern must include an architecture drawing. The specific tool/format is flexible as long as the meaning is clear. -. {sandbox} pattern must undergo an informal technical review by a community leader to ensure that it meets basic reuse standards -. {sandbox} pattern must undergo an informal architecture review by a community leader to ensure that the solution has the right components, and they are generally being used as intended. +A {sandbox} pattern must continue to meet the following criteria to remain in the {sandbox} tier: + +* A {sandbox} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] +* A {sandbox} pattern must be able to be deployed onto a freshly deployed OpenShift cluster without prior modification or tuning +* A {sandbox} pattern must include a top-level README highlighting the business problem and how the pattern solves it +* A {sandbox} pattern must include an architecture drawing. The specific tool/format is flexible as long as the meaning is clear. +* A {sandbox} pattern must undergo an informal technical review by a community leader to ensure that it meets basic reuse standards +* A {sandbox} pattern must undergo an informal architecture review by a community leader to ensure that the solution has the right components, and they are generally being used as intended. + For example: not using a database as a message bus. As community leaders, contributions from within Red Hat may be subject to a higher level of scrutiny. While we strive to be inclusive, the community will have quality standards and generally using the framework does not automatically imply a solution is suitable for the community to endorse/publish. -. {sandbox} pattern must document their support policy +* A {sandbox} pattern must document their support policy + It is anticipated that most{sandbox} pattern will be supported by the community on a best-effort basis, but this should be stated explicitly. The {solution-name-upstream} team commits to maintaining the framework but will also accept help. @@ -60,6 +60,6 @@ The {solution-name-upstream} team commits to maintaining the framework but will [id="can-sandbox-tier"] === Can -. {sandbox} pattern (including works-in-progress) can be hosted in the link:https://github.com/validatedpatterns-sandbox[https://github.com/validatedpatterns-sandbox] GitHub organization -. {sandbox} pattern CAN be listed on the link:https://validatedpatterns.io[https://validatedpatterns.io] site -. {sandbox} pattern meeting additional criteria can be nominated for promotion to the link:/learn/tested/[Tested tier] +* A {sandbox} pattern (including works-in-progress) can be hosted in the link:https://github.com/validatedpatterns-sandbox[https://github.com/validatedpatterns-sandbox] GitHub organization +* A {sandbox} pattern CAN be listed on the link:https://validatedpatterns.io[https://validatedpatterns.io] site +* A {sandbox} pattern meeting additional criteria can be nominated for promotion to the link:/learn/tested/[Tested tier] diff --git a/content/learn/test-artefacts.adoc b/content/learn/test-artefacts.adoc index d3c62c5e3..b82a1b021 100644 --- a/content/learn/test-artefacts.adoc +++ b/content/learn/test-artefacts.adoc @@ -9,6 +9,9 @@ aliases: /requirements/tested/ :toc: +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + [id="testing-artefacts"] = Testing artefacts diff --git a/content/learn/tested.adoc b/content/learn/tested.adoc index 3ea1f5063..bb37acac8 100644 --- a/content/learn/tested.adoc +++ b/content/learn/tested.adoc @@ -41,25 +41,25 @@ specified for the link:/requirements/sandbox/[Sandbox tier] [id="must-tested-tier"] === Must -. {tested} pattern must continue to meet the following criteria to remain in the {tested} tier -. {tested} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] -. {tested} pattern must be meaningful without specialized hardware, including flavors of architectures not explicitly supported. +* A {tested} pattern must continue to meet the following criteria to remain in the {tested} tier +* A {tested} pattern must conform to the common technical link:/requirements/implementation/[implementation requirements] +* A {tested} pattern must be meaningful without specialized hardware, including flavors of architectures not explicitly supported. + Qualification is a {solution-name-upstream} TOC decision with input from the pattern owner. -. {tested} pattern must have their implementation reviewed by the patterns team to ensure that it is sufficiently flexible to function across a variety of platforms, customer environments, and any relevant verticals. -. {tested} pattern must include a standardized architecture drawing, created with (or at least conforming to) the PAC tooling -. {tested} pattern must include a written guide for others to follow when demonstrating the pattern -. {tested} pattern must include a test plan covering all features or attributes being highlighted by the demonstration guide. Negative flow tests (such as resiliency or data retention in the presence of network outages) are also limited to scenarios covered by the demonstration guide. +* A {tested} pattern must have their implementation reviewed by the patterns team to ensure that it is sufficiently flexible to function across a variety of platforms, customer environments, and any relevant verticals. +* A {tested} pattern must include a standardized architecture drawing, created with (or at least conforming to) the PAC tooling +* A {tested} pattern must include a written guide for others to follow when demonstrating the pattern +* A {tested} pattern must include a test plan covering all features or attributes being highlighted by the demonstration guide. Negative flow tests (such as resiliency or data retention in the presence of network outages) are also limited to scenarios covered by the demonstration guide. + The test plan must define how to validate if the pattern has been successfully deployed and is functionally operational. Example: https://docs.google.com/document/d/12KQhdzjVIsxRURTnWAckiEMB3_96oWBjtlTXi1q73cg/view[Validating an Industrial Edge Deployment] + //TODO: Convert above link to adoc -. {tested} pattern must nominate at least one currently supported OpenShift release to test against -. {tested} pattern must ensure the test plan passes at least once per quarter -. {tested} pattern must create a publically available JSON file (eg. in an AWS bucket) that records the result of the latest test for each combination of pattern, platform, and OpenShift version. See link:/learn/test-artefacts/[testing artefacts] +* A {tested} pattern must nominate at least one currently supported OpenShift release to test against +* A {tested} pattern must ensure the test plan passes at least once per quarter +* A {tested} pattern must create a publically available JSON file (eg. in an AWS bucket) that records the result of the latest test for each combination of pattern, platform, and OpenShift version. See link:/learn/test-artefacts/[testing artefacts] [NOTE] ==== @@ -69,15 +69,15 @@ The {tested} pattern *do not* imply an obligation of support for partner or comm [id="should-tested-tier"] === Should -. {tested} pattern should be broadly applicable. -. {tested} pattern should focus on functionality not performance. +* A {tested} pattern should be broadly applicable. +* A {tested} pattern should focus on functionality not performance. [id="can-tested-tier"] === Can -. Teams creating {tested} pattern can provide their own SLA -+ +Teams creating {tested} pattern can provide their own service level agreement (SLA). + A document for QE that defines, at a technical level, how to validate if the pattern has been successfully deployed and is functionally operational. Example: https://docs.google.com/document/d/12KQhdzjVIsxRURTnWAckiEMB3_96oWBjtlTXi1q73cg/view[Validating an Industrial Edge Deployment] -. {tested} pattern meeting additional criteria CAN be nominated for promotion to the link:/learn/maintained/[Maintained tier] +* A {tested} pattern meeting additional criteria CAN be nominated for promotion to the link:/learn/maintained/[Maintained tier]