diff --git a/architecture/index.md b/architecture/index.md index 8e36f7e7..9c4e0fc1 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -1,30 +1,49 @@ # 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 +- Provide a unified user interface across the entire process + +## Architecture Goals + +- 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 -- Each subservice can fulfill its primary use cases independently, without relying on other systems’ availability. +- 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. - 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 +## 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 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 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). + +> :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. @@ -133,7 +152,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