From 538e92fa6fcca0250c09b8d440a33d8bb746d714 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 13:44:14 -0500 Subject: [PATCH 01/18] Update goals and constraints Recently, more people are coming around the project to learn more about it, how they might use it, and how they might contribute. The aim here is to try to give them the most helpful high level introduction possible before they get to the specifics further down in the doc and further out in the repo. --- architecture/index.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/architecture/index.md b/architecture/index.md index 8e36f7e7..c20f9005 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -1,23 +1,23 @@ # AppStudio ## Overview -AppStudio is a platform for building integrated experiences that streamline, consolidate, and secure the application lifecycle. +AppStudio is a platform for building integrated software that streamlines, consolidates, and secures the development lifecycle. ### Goals -- Compose cloud native applications that consist of multiple components and services -- Provide managed application lifecycle -- Rapid bootstrapping of applications -- Fast onboarding of applications to the cloud -- Supports both existing and new applications -- Provide APIs to manage your application lifecycle -- Provide a surface for partners to integrate into the application lifecycle - -## Architecture Goals and Constraints -- Robust delivery automation: Establish continuous delivery practices but also deliver operational tooling. +- Compose software that consists of multiple components, from multiple repositories. +- Provide transparency on the software supply chain, including both what makes up the software and how it was built. +- Provide a way for software teams to release to destinations under the control of their SRE or release engineering team(s). +- Rapid bootstrapping of new software projects +- Support both existing and new projects +- Provide APIs to manage your software lifecycle +- Provide a surface for partners to integrate, add value + +## Architecture Goals + - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired -- Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. +- Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. - Each sub-service owns its data and logic. - Communication among services and participants is always asynchronous. - Each sub-service is owned by one team. Ownership does not mean that only one team can change the code, but the owning team has the final decision. @@ -25,6 +25,16 @@ AppStudio is a platform for building integrated experiences that streamline, con - Participants: onboarding new participants, the flexibility to satisfy the technology preferences of a heterogeneous set of participants. Think of this as the ability to easily create an ecosystem and the ability to support that ecosystem’s heterogeneous needs. - Security, Privacy, and Governance: Sensitive data is protected by fine-grained access control +## Architecture Constraints + +- Our API server is **the kube API server**. Services expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that RBAC is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like tekton results), use SubjectAccessReviews to ensure RBAC is consistent. +- **Use tekton** for anything that should be configurable by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. +- As a corollary, adding new functionality usually looks like either adding a new controller or adding new tekton tasks. +- The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected as release time. +- The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. +- Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. +- While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See (!148)[https://github.com/redhat-appstudio/architecture/pull/148] for an example of attempting to achieve this. + ## Application Context The diagram below shows the services that make up AppStudio and their API resources. From cdc9da5d5992808b40999836ba75f2d589bd427e Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 14:39:57 -0500 Subject: [PATCH 02/18] Update architecture/index.md Co-authored-by: Scott Hebert --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index c20f9005..fbf895ae 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -16,7 +16,7 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Goals - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. -- Static stability: the overall system continues to work when a dependency is impaired +- Static stability: the overall system continues to work when a dependency is impaired. - Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. - Each sub-service owns its data and logic. - Communication among services and participants is always asynchronous. From 38ddbefdd37c7b7f9991086be315f7ce7133081a Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 14:40:05 -0500 Subject: [PATCH 03/18] Update architecture/index.md Co-authored-by: Scott Hebert --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index fbf895ae..fd5be808 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -30,7 +30,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Our API server is **the kube API server**. Services expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that RBAC is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like tekton results), use SubjectAccessReviews to ensure RBAC is consistent. - **Use tekton** for anything that should be configurable by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. - As a corollary, adding new functionality usually looks like either adding a new controller or adding new tekton tasks. -- The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected as release time. +- The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. - Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. - While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See (!148)[https://github.com/redhat-appstudio/architecture/pull/148] for an example of attempting to achieve this. From 517c712cbd3d9968ecd1ff2d3ae877a44df9b60d Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 14:41:02 -0500 Subject: [PATCH 04/18] Update architecture/index.md --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index fd5be808..6c1d90a1 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -28,7 +28,7 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Constraints - Our API server is **the kube API server**. Services expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that RBAC is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like tekton results), use SubjectAccessReviews to ensure RBAC is consistent. -- **Use tekton** for anything that should be configurable by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. +- **Use tekton** for anything that should be extended by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. - As a corollary, adding new functionality usually looks like either adding a new controller or adding new tekton tasks. - The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. From b1eeb29d6e2b02a8950eb668052d7370c349d002 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 14:39:27 -0500 Subject: [PATCH 05/18] Incorporate additional goals, paraphrased from Andrew --- architecture/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/architecture/index.md b/architecture/index.md index 6c1d90a1..469e4273 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -15,6 +15,9 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Goals +- Build artifacts once with enough data to determine suitability for releasing. +- Build artifacts once that can be released to multiple locations, use cases. +- "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. - Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. From d2bb4a34c9027ef1862041bf52c1158a594199ae Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 29 Jan 2024 14:42:48 -0500 Subject: [PATCH 06/18] Adding contstraint from Andrew --- architecture/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/architecture/index.md b/architecture/index.md index 469e4273..f3fac42a 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -37,6 +37,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. - Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. - While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See (!148)[https://github.com/redhat-appstudio/architecture/pull/148] for an example of attempting to achieve this. +- Any attestation used for making a release-time decision should be provably trusted (either because it is GPG signed or its immutable reference is added to the provenance by a trusted task). ## Application Context From a50575030966cc8b5a5fa92baed4d875a7bc9fdb Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 09:45:55 -0500 Subject: [PATCH 07/18] Mention hermetic builds as a goal --- architecture/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/architecture/index.md b/architecture/index.md index f3fac42a..19a547bb 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -17,6 +17,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Build artifacts once with enough data to determine suitability for releasing. - Build artifacts once that can be released to multiple locations, use cases. +- Build artifacts should be fully determined by git, not by transient state of the build system. Employ tools like [renovate](https://docs.renovatebot.com/) to manage dependency updates. - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. From a8f22acc24cc8ba008786bbb1c6f1772af5987cc Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 09:51:53 -0500 Subject: [PATCH 08/18] Move the note about controller or task out of the list of constraints It's more of an observation than a constraint on its own. --- architecture/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/architecture/index.md b/architecture/index.md index 19a547bb..4df3f444 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -31,15 +31,16 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Constraints -- Our API server is **the kube API server**. Services expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that RBAC is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like tekton results), use SubjectAccessReviews to ensure RBAC is consistent. +- Our API server is **the kube API server**. Services are [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) that expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like [tekton results](https://github.com/tektoncd/results)), use `SubjectAccessReviews` to ensure RBAC is consistent. - **Use tekton** for anything that should be extended by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. -- As a corollary, adding new functionality usually looks like either adding a new controller or adding new tekton tasks. - The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. - Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. - While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See (!148)[https://github.com/redhat-appstudio/architecture/pull/148] for an example of attempting to achieve this. - Any attestation used for making a release-time decision should be provably trusted (either because it is GPG signed or its immutable reference is added to the provenance by a trusted task). +> :bulb: Adding new functionality usually looks like either adding a new **controller** or adding a new **tekton task**. + ## Application Context The diagram below shows the services that make up AppStudio and their API resources. From aa27d60533a3b8d42789132b10f566d40a84e884 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:16:46 -0500 Subject: [PATCH 09/18] Turn the grammar around to match the command phrasing of the preceding bullets --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index 4df3f444..1b4d0990 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -17,7 +17,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Build artifacts once with enough data to determine suitability for releasing. - Build artifacts once that can be released to multiple locations, use cases. -- Build artifacts should be fully determined by git, not by transient state of the build system. Employ tools like [renovate](https://docs.renovatebot.com/) to manage dependency updates. +- Specify builds and their dependencies entirely from git and not from transient state of the build system. Employ tools like [renovate](https://docs.renovatebot.com/) to manage dependency updates. - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. From bbcc99cd41a66850e44c68c3f01029eebbdc3205 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:19:41 -0500 Subject: [PATCH 10/18] Grammar adjustment --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index 1b4d0990..75d94ef3 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -16,7 +16,7 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Goals - Build artifacts once with enough data to determine suitability for releasing. -- Build artifacts once that can be released to multiple locations, use cases. +- Build artifacts once that can be released to multiple locations, multiple use cases. - Specify builds and their dependencies entirely from git and not from transient state of the build system. Employ tools like [renovate](https://docs.renovatebot.com/) to manage dependency updates. - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. From 103a116d233b5c70b78ecb54d041dcb950e3dff3 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:19:51 -0500 Subject: [PATCH 11/18] List extensibility as a goal --- architecture/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/architecture/index.md b/architecture/index.md index 75d94ef3..f74d639a 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -18,6 +18,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Build artifacts once with enough data to determine suitability for releasing. - Build artifacts once that can be released to multiple locations, multiple use cases. - Specify builds and their dependencies entirely from git and not from transient state of the build system. Employ tools like [renovate](https://docs.renovatebot.com/) to manage dependency updates. +- Be extensible. Provide opinionated [build pipelines](https://github.com/redhat-appstudio/build-definitions/) and [release pipelines](https://github.com/redhat-appstudio/release-service-catalog), but let users extend those and create their own. - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. From b68d904d7f1b5803ff0ae5e2a018e630340d809e Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:25:35 -0500 Subject: [PATCH 12/18] Note common dependence on tekton and pipeline-service --- architecture/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index f74d639a..a9162592 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -22,7 +22,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. -- Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. +- Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. An exception to this is the tekton [pipeline service] which provides foundational APIs on which [build-service], [integration-service], and [release-service] depend. - Each sub-service owns its data and logic. - Communication among services and participants is always asynchronous. - Each sub-service is owned by one team. Ownership does not mean that only one team can change the code, but the owning team has the final decision. @@ -150,7 +150,9 @@ Each service that makes up AppStudio is further explained in its own document. [integration-service promotes OCI artifacts]: ../ADR/0016-integration-service-promotion-logic.md [application-service]: ./hybrid-application-service.md +[pipeline-service]: ./pipeline-service.md [gitops-service]: ./gitops-service.md +[build-service]: ./build-service.md [integration-service]: ./integration-service.md [release-service]: ./release-service.md [Application]: ../ref/application-environment-api.md#application From f96208b2a92ee08311dd5cd2f9967a0210fc5bff Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:32:28 -0500 Subject: [PATCH 13/18] Note additional endpoints --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index a9162592..6010eb23 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -32,7 +32,7 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Architecture Constraints -- Our API server is **the kube API server**. Services are [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) that expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is implemented the same way across services. In any exceptional case that a service needs to expose its own bespoke HTTP endpoint (like [tekton results](https://github.com/tektoncd/results)), use `SubjectAccessReviews` to ensure RBAC is consistent. +- Our API server is **the kube API server**. Services are [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) that expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is implemented the same way across services. In any exceptional case that a service needs to expose its own user-facing HTTP endpoint (like [tekton results](https://github.com/tektoncd/results)), use `SubjectAccessReviews` to ensure RBAC is consistent. Note, a few other supporting endpoints are exposed outside of kube (the [sprayproxy](https://github.com/redhat-appstudio/sprayproxy) from [pipeline-service] for receiving webhooks, [registration-service](https://github.com/codeready-toolchain/registration-service) from [codeready-toolchain](https://github.com/codeready-toolchain/) for signing up new users). - **Use tekton** for anything that should be extended by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. - The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. From 5418dd4726abb653fbe3079a2022b7660d929862 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:33:15 -0500 Subject: [PATCH 14/18] Markdown link syntax fix --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index 6010eb23..34d60c5f 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -37,7 +37,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. - The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. - Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. -- While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See (!148)[https://github.com/redhat-appstudio/architecture/pull/148] for an example of attempting to achieve this. +- While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See [!148](https://github.com/redhat-appstudio/architecture/pull/148) for an example of attempting to achieve this. - Any attestation used for making a release-time decision should be provably trusted (either because it is GPG signed or its immutable reference is added to the provenance by a trusted task). > :bulb: Adding new functionality usually looks like either adding a new **controller** or adding a new **tekton task**. From ec727cb0695dc8b1d77ea33387baffa554d06ad4 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:35:01 -0500 Subject: [PATCH 15/18] Typofix --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index 34d60c5f..f47978f7 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -35,7 +35,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Our API server is **the kube API server**. Services are [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) that expose their API as Custom Resource Definitions. This means that requests are necessarily asyncronous. This means that [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) is implemented the same way across services. In any exceptional case that a service needs to expose its own user-facing HTTP endpoint (like [tekton results](https://github.com/tektoncd/results)), use `SubjectAccessReviews` to ensure RBAC is consistent. Note, a few other supporting endpoints are exposed outside of kube (the [sprayproxy](https://github.com/redhat-appstudio/sprayproxy) from [pipeline-service] for receiving webhooks, [registration-service](https://github.com/codeready-toolchain/registration-service) from [codeready-toolchain](https://github.com/codeready-toolchain/) for signing up new users). - **Use tekton** for anything that should be extended by the user (building, testing, releasing). Expose as much detail via kube resources as possible. Prefer to implement native tasks to perform work on cluster, rather than calling out to third-party services. - The **user has admin** in their workspace. This means that the user can access secrets in their workspace. This means that the system can never provide secrets to the user that are scoped beyond that user's domain. A user can exfiltrate the push secret from their workspace, build invalid content on their laptop, and push it to their buildtime registry. Such a build will be rejected at release time. -- The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystems. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. +- The cluster is our **unit of sharding**. Each cluster is independent and runs an instance of every subsystem. User workspaces are allocated to one cluster. If we lose a cluster, all workspaces on that cluster are inaccessible, but workspaces on other clusters are not impacted, limiting the blast radius. No subsystem should coordinate across clusters. - Artifacts built, tested, and shipped by the system are **OCI artifacts**. SBOMs, attestations, signatures, and other supporting metadata are stored in the registry alongside the artifact, tagged by the `cosign triangulate` convention. - While not true today, it should be possible to **install** one subsystem without the others and to replace one subsystem with a new one without affecting the others. See [!148](https://github.com/redhat-appstudio/architecture/pull/148) for an example of attempting to achieve this. - Any attestation used for making a release-time decision should be provably trusted (either because it is GPG signed or its immutable reference is added to the provenance by a trusted task). From 9b944f18514f19daa68594741d06a37588a7c176 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Wed, 31 Jan 2024 12:40:14 -0500 Subject: [PATCH 16/18] Add a goal around eventual compliance --- architecture/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/architecture/index.md b/architecture/index.md index f47978f7..c753beda 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -22,6 +22,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - "Shift left" the decisions for releasing into PRs; you should be able to release artifacts from a PR as soon as it is merged. - Just in time scaling: In contrast to “just in case” scaling. The system should be able to scale without capacity reserved ahead of time. - Static stability: the overall system continues to work when a dependency is impaired. +- Enhancements to the pipelines (the extensible elements of the system) should be rolled out in such a way that individual users can control **when** they accept the update to their workspaces, their processes. Use policy to drive eventual compliance. - Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. An exception to this is the tekton [pipeline service] which provides foundational APIs on which [build-service], [integration-service], and [release-service] depend. - Each sub-service owns its data and logic. - Communication among services and participants is always asynchronous. From 5c4490ebb30b716ee11f7f82aaad6db5784fd3fd Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Thu, 1 Feb 2024 10:17:55 -0500 Subject: [PATCH 17/18] Infrastructure may have been confusing We don't mean that the cluster shouldn't be shared. We do mean that databases should not be shared. --- architecture/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architecture/index.md b/architecture/index.md index c753beda..10ee4c90 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -27,7 +27,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Each sub-service owns its data and logic. - Communication among services and participants is always asynchronous. - Each sub-service is owned by one team. Ownership does not mean that only one team can change the code, but the owning team has the final decision. -- Minimize shared infrastructure among sub-services +- Minimize shared resources among sub-services. - Participants: onboarding new participants, the flexibility to satisfy the technology preferences of a heterogeneous set of participants. Think of this as the ability to easily create an ecosystem and the ability to support that ecosystem’s heterogeneous needs. - Security, Privacy, and Governance: Sensitive data is protected by fine-grained access control From 2735855f53961c05caf8375e296a2978a1e21599 Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Mon, 12 Feb 2024 07:44:45 -0500 Subject: [PATCH 18/18] Add unified UI as a goal The "commit view" is a good example of this. --- architecture/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/architecture/index.md b/architecture/index.md index 10ee4c90..9c4e0fc1 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -12,6 +12,7 @@ AppStudio is a platform for building integrated software that streamlines, conso - Support both existing and new projects - Provide APIs to manage your software lifecycle - Provide a surface for partners to integrate, add value +- Provide a unified user interface across the entire process ## Architecture Goals