From 2e42660976f97a83a9752e9b0c57302286b7fc1c Mon Sep 17 00:00:00 2001 From: Ralph Bean Date: Tue, 23 Apr 2024 19:38:19 -0400 Subject: [PATCH] Replace most mentions of AppStudio with Konflux --- ...0003-interacting-with-internal-services.md | 4 +-- ADR/0006-log-conventions.md | 4 +-- ADR/0008-environment-provisioning.md | 6 ++-- ADR/0010-namespace-metadata.md | 8 ++--- ADR/0011-roles-and-permissions.md | 6 ++-- ADR/0012-namespace-name-format.md | 10 +++--- ADR/0013-integration-service-api-contracts.md | 18 +++++----- ADR/0014-let-pipelines-proceed.md | 2 +- ...016-integration-service-promotion-logic.md | 6 ++-- ADR/0017-use-our-pipelines.md | 14 ++++---- ADR/0018-apps-continuous-perf-testing.md | 14 ++++---- ADR/0019-customize-url-github.md | 32 +++++++++--------- ADR/0020-source-retention.md | 4 +-- ADR/0025-appstudio-pipeline-serviceaccount.md | 6 ++-- ADR/0026-specifying-ocp-targets-for-fbc.md | 16 ++++----- ADR/0027-availability-probe-framework.md | 16 ++++----- ADR/0027-container-images.md | 6 ++-- ADR/0029-component-dependencies.md | 10 +++--- ADR/0030-tekton-results-naming-convention.md | 12 +++---- ADR/0031-sprayproxy.md | 6 ++-- ADR/0032-decoupling-deployment.md | 8 ++--- README.md | 4 +-- _config.yml | 4 +-- .../HAS/hybrid-application-service-api.md | 2 +- ...rid-application-service-component-types.md | 10 +++--- .../HAS/hybrid-application-service-crds.md | 4 +-- .../HAS/hybrid-application-service-design.md | 6 ++-- .../hybrid-application-service-glossary.md | 4 +-- architecture/enterprise-contract.md | 18 +++++----- architecture/hybrid-application-service.md | 4 +-- architecture/image-controller.md | 4 +-- architecture/index.md | 10 +++--- architecture/integration-service.md | 12 +++---- architecture/internal-services.md | 2 +- architecture/jvm-build-service.md | 2 +- architecture/release-service.md | 2 +- diagrams/index.md | 6 ++-- ...vg => konflux-workspace-layout.drawio.svg} | 16 ++++----- ...ppstudio.drawio.svg => konflux.drawio.svg} | 0 diagrams/personal-data.drawio.svg | 2 +- ... => konflux-release-service-data-flow.jpg} | Bin ref/index.md | 2 +- tools/security-tools.MD | 24 ++++++------- 43 files changed, 173 insertions(+), 173 deletions(-) rename diagrams/{appstudio-workspace-layout.drawio.svg => konflux-workspace-layout.drawio.svg} (99%) rename diagrams/{appstudio.drawio.svg => konflux.drawio.svg} (100%) rename diagrams/release-service/{hacbs-release-service-data-flow.jpg => konflux-release-service-data-flow.jpg} (100%) diff --git a/ADR/0003-interacting-with-internal-services.md b/ADR/0003-interacting-with-internal-services.md index 4b1419ce..4757a78f 100644 --- a/ADR/0003-interacting-with-internal-services.md +++ b/ADR/0003-interacting-with-internal-services.md @@ -13,12 +13,12 @@ Accepted --- Many organizations, including Red Hat, possess numerous internal services that help productize their software. -In many cases, these internal services will continue to play a role in the release workflows used in AppStudio/HACBS. +In many cases, these internal services will continue to play a role in the release workflows used in Konflux. We originally thought that we should expose access to an organization's internal services by encouraging the use of "[bastion](https://en.wikipedia.org/wiki/Bastion_host)" interfaces that are publicly addressable but which also have some degree of internal network access. On review, we see now that internal network ingress like this opens up unwanted attack vectors towards an organization's internal networks. -**Problem**: AppStudio/Release pipelines need to **initiate** processes with an organization's internal services which +**Problem**: Konflux Release pipelines need to **initiate** processes with an organization's internal services which are **not publicly addressable** in a secure fashion and be able to obtain process status and completion results. ## Decision diff --git a/ADR/0006-log-conventions.md b/ADR/0006-log-conventions.md index d368c98c..76ad3fc3 100644 --- a/ADR/0006-log-conventions.md +++ b/ADR/0006-log-conventions.md @@ -47,13 +47,13 @@ Optionally, also describe the action in the human-readable `msg`. **Included in:** _none_ -There is no need to identify which AppStudio subsystem the log is coming from (i.e., HAS, SPI, or +There is no need to identify which Konflux subsystem the log is coming from (i.e., HAS, SPI, or GitOps). Consider: if an engineer is looking at logs directly in the namespace where a controller is deployed, then you know which service you are looking at. If an engineer is looking at logs centralized in cloudwatch or splunk, then the namespace from which the log came will be included -automatically as `namespace_name`, which is sufficient to determine what AppStudio subsystem +automatically as `namespace_name`, which is sufficient to determine what Konflux subsystem produced the log. See section on automatically added logs below. ### 4. Who was involved? diff --git a/ADR/0008-environment-provisioning.md b/ADR/0008-environment-provisioning.md index 6775dc4f..def7b69d 100644 --- a/ADR/0008-environment-provisioning.md +++ b/ADR/0008-environment-provisioning.md @@ -32,7 +32,7 @@ In our old KCP architecture, we had [a design](https://docs.google.com/document/d/1WKd1FVHAxaNQKCIzIW-vUQRgsoOP9T-8rYozAMDpYc0/edit#) for provisioning a new deployment target in support of new [Environments]. This design was to be implemented in [GITOPSRVCE-228](https://issues.redhat.com/browse/GITOPSRVCE-228) by an environment -controller that would create and manage sub-workspaces of the user’s main AppStudio workspace, and +controller that would create and manage sub-workspaces of the user’s main Konflux workspace, and that would provide a serviceaccount to Argo in order to deploy the user’s application to those sub-workspaces. Now, without KCP, we need a new design. @@ -43,7 +43,7 @@ The [Environment] CR serves two purposes: Some use cases to consider for [Environments]: -1. As a part of the AppStudio workspace initialization process, the user should find that both a **dev and stage environment** with corresponding deployment targets are ready for them ([STONE-180](https://issues.redhat.com/browse/STONE-180)). In our post-KCP architecture, these will be backed by **namespaces** on a devsandbox member cluster. +1. As a part of the Konflux workspace initialization process, the user should find that both a **dev and stage environment** with corresponding deployment targets are ready for them ([STONE-180](https://issues.redhat.com/browse/STONE-180)). In our post-KCP architecture, these will be backed by **namespaces** on a devsandbox member cluster. 2. The user will want to manually create **additional** [Environments] (for example, a prod environment). The user may want to use our compute resources provided in the form of a new **namespace on a devsandbox member cluster** for this ([STONE-183](https://issues.redhat.com/browse/STONE-183)) or they may want to **bring their own cluster** as a target ([STONE-162](https://issues.redhat.com/browse/STONE-162)). 3. The integration-service expects to be able to create **ephemeral** [Environments] for automated testing purposes ([STONE-114](https://issues.redhat.com/browse/STONE-114)). For our short-term goals, the automated testing use case requires the same kind of compute as for the dev and stage [Environments] (devsandbox member cluster namespaces), but will expand to include other kinds of deployment targets in the future - like hypershift clusters ([STONE-185](https://issues.redhat.com/browse/STONE-185)). @@ -408,7 +408,7 @@ spec: ### Phase 3 -The result of this phase is to automatically provisioning of Hypershift cluster using AppStudio's +The result of this phase is to automatically provisioning of Hypershift cluster using Konflux's credentials. We call it `provided compute` (compute that we provide, not the user) and it’s included as part of the offering. This compute can be used for both long lived clusters and for ephemeral clusters used by the integration service. diff --git a/ADR/0010-namespace-metadata.md b/ADR/0010-namespace-metadata.md index 47861969..cade554e 100644 --- a/ADR/0010-namespace-metadata.md +++ b/ADR/0010-namespace-metadata.md @@ -19,13 +19,13 @@ Accepted ## Context -We need metadata on our namespaces to make AppStudio easier to operate and maintain. Standardizing namespace metadata will make it easier for us to search our logs and metrics across clusters. It will also allow us to enable logging for outgoing network traffic, one of our security requirements. +We need metadata on our namespaces to make Konflux easier to operate and maintain. Standardizing namespace metadata will make it easier for us to search our logs and metrics across clusters. It will also allow us to enable logging for outgoing network traffic, one of our security requirements. ## Namespace labels -We will apply the following labels to AppStudio namespaces, to make them easier to identify programmatically. One namespace can have multiple types/labels: +We will apply the following labels to Konflux namespaces, to make them easier to identify programmatically. One namespace can have multiple types/labels: -- `appstudio.redhat.com/namespacetype: "controller"` for namespaces containing controllers developed for AppStudio. For example, we would annotate the `gitops-service-argocd` namespace but not the `openshift-gitops` namespace. +- `appstudio.redhat.com/namespacetype: "controller"` for namespaces containing controllers developed for Konflux. For example, we would annotate the `gitops-service-argocd` namespace but not the `openshift-gitops` namespace. - `appstudio.redhat.com/namespacetype: "user-workspace-data"` for User workspaces where Applications, Components, and so on are stored - `appstudio.redhat.com/namespacetype: "user-deployments"` for the namespaces where GitOps deploys applications for users - `appstudio.redhat.com/namespacetype: "user-builds"` for the namespaces where the Pipeline Service manages users' PipelineRun resources @@ -47,7 +47,7 @@ The following labels are used by required operators: ## Namespace annotations -We will apply the following annotation to namespaces installed and maintained by AppStudio on the clusters that Red Hat manages. This will enable OVN network logging to log outgoing network traffic: +We will apply the following annotation to namespaces installed and maintained by Konflux on the clusters that Red Hat manages. This will enable OVN network logging to log outgoing network traffic: metadata: annotations: diff --git a/ADR/0011-roles-and-permissions.md b/ADR/0011-roles-and-permissions.md index 4bd763ba..efa6ca04 100644 --- a/ADR/0011-roles-and-permissions.md +++ b/ADR/0011-roles-and-permissions.md @@ -1,4 +1,4 @@ -# 11. Roles and Permissions for AppStudio +# 11. Roles and Permissions for Konflux Date: 2023-01-10 @@ -7,11 +7,11 @@ Date: 2023-01-10 Accepted ## Context -AppStudio is using Kubernetes as the control plane for managing its resources. We require a system for managing user roles and permissions in this context. We have defined the following roles for our project: "Contributor", "Maintainer", and "Admin". We need to map these roles to specific permissions in the Kubernetes RBAC system, in terms of API groups, verbs, and resources. +Konflux is using Kubernetes as the control plane for managing its resources. We require a system for managing user roles and permissions in this context. We have defined the following roles for our project: "Contributor", "Maintainer", and "Admin". We need to map these roles to specific permissions in the Kubernetes RBAC system, in terms of API groups, verbs, and resources. ## Decision -We will use the built-in Kubernetes RBAC system for AppStudio's role and permissions management, and map the following roles to specific permissions, as described in the table below: +We will use the built-in Kubernetes RBAC system for Konflux's role and permissions management, and map the following roles to specific permissions, as described in the table below: ### Roles **Contributor:** Members who interact with the workspace mostly through pull requests. diff --git a/ADR/0012-namespace-name-format.md b/ADR/0012-namespace-name-format.md index fdb84306..e83cdd92 100644 --- a/ADR/0012-namespace-name-format.md +++ b/ADR/0012-namespace-name-format.md @@ -8,15 +8,15 @@ Accepted ## Context -The OSD-based control plane provisions one namespace in the target member cluster for every workspace (internally represented by a Space CR) which is created for a AppStudio user. All the namespace names provisioned in this way should have a fixed suffix because of two reasons: -1. Visual separation of the namespaces provisioned for AppStudio workspaces. +The OSD-based control plane provisions one namespace in the target member cluster for every workspace (internally represented by a Space CR) which is created for a Konflux user. All the namespace names provisioned in this way should have a fixed suffix because of two reasons: +1. Visual separation of the namespaces provisioned for Konflux workspaces. 2. Limiting the risk of conflicting with the names used for other namespaces that are present in the cluster - either by default for every OCP/OSD/ROSA cluster or created via other SRE pipelines. ## Decision -Every namespace provisioned for an AppStudio top-level workspace will have a name with the fixed suffix `-tenant`. The complete format will be `-tenant`. -Every namespace provisioned for an AppStudio environment sub-workspace (created from a `SpaceRequest` CR using `appstudio-env` tier) will have a name with the fixed suffix `-env`. The complete format will be `-env`. +Every namespace provisioned for an Konflux top-level workspace will have a name with the fixed suffix `-tenant`. The complete format will be `-tenant`. +Every namespace provisioned for an Konflux environment sub-workspace (created from a `SpaceRequest` CR using `appstudio-env` tier) will have a name with the fixed suffix `-env`. The complete format will be `-env`. ## Consequences -Any changes in the format of the namespace names cause the deletion of all existing namespaces (provisioned for AppStudio workspaces), followed by the creation of the namespaces which will use the new format. In other words, all data in the old namespaces will be deleted. +Any changes in the format of the namespace names cause the deletion of all existing namespaces (provisioned for Konflux workspaces), followed by the creation of the namespaces which will use the new format. In other words, all data in the old namespaces will be deleted. diff --git a/ADR/0013-integration-service-api-contracts.md b/ADR/0013-integration-service-api-contracts.md index 1493cdb6..28bd9025 100644 --- a/ADR/0013-integration-service-api-contracts.md +++ b/ADR/0013-integration-service-api-contracts.md @@ -1,4 +1,4 @@ -# 13. AppStudio Test Stream - API contracts +# 13. Konflux Test Stream - API contracts Date: 2023-01-30 @@ -10,9 +10,9 @@ Relates to [ADR 14. Let Pipelines Proceed](0014-let-pipelines-proceed.html) ## Context -The AppStudio project being developed aims to serve Red Hat teams but also partners and customers. This requires a level of adaptability to avoid recreating custom flows and Tasks for each stakeholder. +The Konflux project being developed aims to serve Red Hat teams but also partners and customers. This requires a level of adaptability to avoid recreating custom flows and Tasks for each stakeholder. -In this respect Tasks developed by AppStudio test stream should allow swapping external systems to accommodate different environments. This swap should not induce the complete recreation of pipelines. +In this respect Tasks developed by Konflux test stream should allow swapping external systems to accommodate different environments. This swap should not induce the complete recreation of pipelines. This and the idea of providing a homogeneous experience, which is easier to comprehend and navigate complex systems, leads to the definition of `API contracts`. These contracts need to be understood as guidance that may evolve with time and experience while keeping the aim of building a flexible homogeneous system. @@ -40,7 +40,7 @@ To display count of found vulnerabilities and make it easy to understand and eva The maximum size of a [Task's Results](https://tekton.dev/vault/pipelines-v0.17.3/tasks/#emitting-results) is limited by the container [termination message](https://kubernetes.io/docs/tasks/debug/debug-application/determine-reason-pod-failure/#customizing-the-termination-message) feature of Kubernetes. -App Studio builds are structured as [a shared Persistent Volume per AppStudio Workspace](https://docs.google.com/document/d/1IPlihVjkJ4Kb9tdhsk7iz3bn5rkT_SvJCNQhyXzK3aI/edit#bookmark=id.gefgys3vno2). This allows teams to share builds, implement caching and other shared volumes. A single persistent volume is mapped to each default build pipeline. Builds are passed a directory specific to their builds. +App Studio builds are structured as [a shared Persistent Volume per Konflux Workspace](https://docs.google.com/document/d/1IPlihVjkJ4Kb9tdhsk7iz3bn5rkT_SvJCNQhyXzK3aI/edit#bookmark=id.gefgys3vno2). This allows teams to share builds, implement caching and other shared volumes. A single persistent volume is mapped to each default build pipeline. Builds are passed a directory specific to their builds. #### Tekton Result Format for `HACBS_TEST_OUTPUT` @@ -57,11 +57,11 @@ The output will provide the following information about the overall test result: Example contents of the test result output file (**HACBS_TEST_OUTPUT**) for a failed run: ``` -{ +{ "result": "FAILURE", "namespace": "image_labels", "timestamp": "1649148140", - "successes": 12, + "successes": 12, "note": "Task fbc-related-image-check failed: Command skopeo inspect could not inspect images. For details, check Tekton task log.", "failures": 2, "warnings": 0 @@ -170,7 +170,7 @@ Each test will have a standardized short name in snake case, e.g. `release_label The output will provide the following information about the overall test result: - **filename** - Name of the file that was inspected by the Tekton task - This will reflect the data that the test was executed on, such as `image-inspect.json`, `clair-vulnerabilities.json` etc. -- **namespace** - The rego namespace of the test policy. +- **namespace** - The rego namespace of the test policy. - **successes** - The number of successful checks in the form of an integer - **failures** - A JSON list containing objects describing each failure @@ -238,7 +238,7 @@ Since tags can be moved from one image to another, they should not be relied on ## Consequences As a result of the decision here to summarize results in a **HACBS_TEST_OUTPUT** result and store the larger test output as a file named **test_name_output.json**, we should find that: -* Other components in AppStudio can leverage information exposed by TaskRuns - notably the UI (HAC), integration-service, and enterprise-contract - enabling features for the larger system that need to depend on some data from inside a variety of TaskRuns. +* Other components in Konflux can leverage information exposed by TaskRuns - notably the UI (HAC), integration-service, and enterprise-contract - enabling features for the larger system that need to depend on some data from inside a variety of TaskRuns. * We'll be able to have PipelineRuns that _succeed_ and continue, even if they have tasks whose payloads fail and expose errors. This enables a progressive model where the user can get a build and a functional test and a deployment to their development Environment, even if a linter or scanner in their build pipeline emits an error. * By having chosen a convention that has "HACBS" in the name, we're going to have trouble integrating third-party Task providers in the future. In order to have its output respected by our system, a hypothetical vendor of a third-party scanner will need to add a "HACBS_TEST_OUTPUT" result on their Task, which is oddly specific to our system. At some point in the future, we should revise this decision to instead align to a common upstream convention that gains traction in the broader tekton ecosystem. See also [HACBS-1563](https://issues.redhat.com/browse/HACBS-1563). @@ -269,7 +269,7 @@ Information, which relates to an environment like connection details and credent ## Appendix - **Task recommendations**: This document focuses (it was at least the original intention) on API contracts but there are more recommendations regarding Task developments. The following ones have been collected by the Tekton project: https://github.com/tektoncd/catalog/blob/main/recommendations.md -- **Programming language**: Tekton supports “choosing the right language for the right task”. That said, from an operational point of view it is beneficial to limit the number of programming languages needed to support AppStudio. Defining “default” languages helps with limiting the skills required to support the platform. This also helps with avoiding knowledge islands where only a few people are able to maintain some Tasks. +- **Programming language**: Tekton supports “choosing the right language for the right task”. That said, from an operational point of view it is beneficial to limit the number of programming languages needed to support Konflux. Defining “default” languages helps with limiting the skills required to support the platform. This also helps with avoiding knowledge islands where only a few people are able to maintain some Tasks. - **Failure behavior**: A retry mechanism with configurable timeout and exponential backoff needs to be implemented for technical or functional recoverable failures. A scenario example: An image may not have been completely indexed when the result of the security scan is interrogated. In such a case the Task should have a retry mechanism that may wait till completion of the indexing or time out. - **Repositories**: Whenever there is no sensitive information we aim to have the PoC sources in a public repository. Is there a public GitHub organization for that? Can we use [this](https://github.com/redhat-appstudio)? When a Task is specifically for Red Hat’s infrastructure it should be kept in a private repository. Is there a private GitLab group for that? diff --git a/ADR/0014-let-pipelines-proceed.md b/ADR/0014-let-pipelines-proceed.md index a67d8aa7..47f49301 100644 --- a/ADR/0014-let-pipelines-proceed.md +++ b/ADR/0014-let-pipelines-proceed.md @@ -8,7 +8,7 @@ Accepted Relates to: -* [ADR 13. AppStudio Test Stream - API contracts](0013-integration-service-api-contracts.html) +* [ADR 13. Konflux Test Stream - API contracts](0013-integration-service-api-contracts.html) * [ADR 30. Tekton Results Naming Convention](0030-tekton-results-naming-convention.html) * [ADR 32. Decoupling Deployment](0032-decoupling-deployment.html) diff --git a/ADR/0016-integration-service-promotion-logic.md b/ADR/0016-integration-service-promotion-logic.md index 3b5c0a3d..bf169845 100644 --- a/ADR/0016-integration-service-promotion-logic.md +++ b/ADR/0016-integration-service-promotion-logic.md @@ -9,7 +9,7 @@ Superceded by [ADR 32. Decoupling Deployment](0032-decoupling-deployment.html) ## Context -Before the merge of HACBS & AppStudio, the AppStudio build-service created the +Before the merge of HACBS & AppStudio, the Konflux build-service created the ApplicationSnapshot and promoted the content to the user's lowest environment as soon as the build was completed and once the environment was built. The integration-service fulfilled the same role for HACBS in addition to running the @@ -27,7 +27,7 @@ that the workloads are properly tested before being further promoted to an envir service level agreement. The promotion path can be represented with a directed acyclic graph from the environment with the lowest SLA to the one with the highest, for example development -> staging -> production. -In AppStudio, this promotion logic would be represented by a set of components (container images) defined by +In Konflux, this promotion logic would be represented by a set of components (container images) defined by an immutable Snapshot being deployed to the relevant environment. Once the Snapshot is tested and verified successfully, its contents will then be deployed to the user's defined @@ -36,7 +36,7 @@ lowest environments. ## Decision Consolidate the promotion logic for both HACBS & AppStudio and move it to the integration-service after -the merger of AppStudio. +the merger of Konflux. ![](../diagrams/ADR-0016/promotion-logic.jpg) diff --git a/ADR/0017-use-our-pipelines.md b/ADR/0017-use-our-pipelines.md index fc2b8e91..901c52ce 100644 --- a/ADR/0017-use-our-pipelines.md +++ b/ADR/0017-use-our-pipelines.md @@ -11,7 +11,7 @@ Accepted ## Context -The maintainers of AppStudio components need to demonstrate evidence of practices that support +The maintainers of Konflux components need to demonstrate evidence of practices that support a secure software development lifecycle (for example scanning, manifesting, vulnerability detection, etc.) @@ -20,23 +20,23 @@ a ci/cd platform that is meant to support a secure software development lifecycl ## Decision -Use our own pipelines to build and scan AppStudio components. Almost all of our components already +Use our own pipelines to build and scan Konflux components. Almost all of our components already do this today. Look for evidence in the `.tekton/` directory of their git repo. -However, we have stopped short of configuring an [Application] and [Components] for AppStudio. -We're using the pipelines directly, but not via the AppStudio UI. This is something we intend to +However, we have stopped short of configuring an [Application] and [Components] for Konflux. +We're using the pipelines directly, but not via the Konflux UI. This is something we intend to start doing, but haven't made time to do so yet. ## Consequences -* When asked for evidence that teams are practicing secure development, they can point to AppStudio +* When asked for evidence that teams are practicing secure development, they can point to Konflux pipelines in some cases. * If our pipelines produce incorrect or erroneous errors, we will be in a position to notice this sooner and act to fix them. * If there are gaps in the user experience, we'll also be in a position to notice this and work to improve UX (i.e. [STONE-459](https://issues.redhat.com/browse/STONE-459)). -* We won't get to exercise or benefit from the [integration-service] or the AppStudio UI so long as - we are only using the AppStudio build pipelines and not yet onboarding to use of the [Application] +* We won't get to exercise or benefit from the [integration-service] or the Konflux UI so long as + we are only using the Konflux build pipelines and not yet onboarding to use of the [Application] and [Component] APIs. * This ADR supports [STONE-434](https://issues.redhat.com/browse/STONE-434). diff --git a/ADR/0018-apps-continuous-perf-testing.md b/ADR/0018-apps-continuous-perf-testing.md index 995e91d7..3033402f 100644 --- a/ADR/0018-apps-continuous-perf-testing.md +++ b/ADR/0018-apps-continuous-perf-testing.md @@ -1,4 +1,4 @@ -# 18. Continuous Performance Testing (CPT) of Apps in AppStudio +# 18. Continuous Performance Testing (CPT) of Apps in Konflux Date: 2023-03-10 @@ -10,7 +10,7 @@ In consideration In general, performance testing is just another form of testing that helps application teams to ensure there are no regressions in their code and that their application behaves as expected. -The IntegrationTestScenario pipelines in AppStudio are not suitable for full-blown performance and scale testing (that usually takes lots of time and involves human analysis so it is not suitable for quick automated checks we need for release gating runs in AppStudio), but are a good place for a quick and small-scale regression test. +The IntegrationTestScenario pipelines in Konflux are not suitable for full-blown performance and scale testing (that usually takes lots of time and involves human analysis so it is not suitable for quick automated checks we need for release gating runs in Konflux), but are a good place for a quick and small-scale regression test. What makes performance testing different from functional testing is it is harder to decide if the test passed or failed as every performance test tests different aspects of the application and so it expects different performance, different metrics, different thresholds. Furthermore, even if the measured performance of the app under test did not change, there might be some significant resource usage by the application which we want to cause the test to be marked as failed. @@ -32,7 +32,7 @@ The algorithm that says if the current test passes or fails when compared to his - Using a floating average of historical data and setting a safe range around it and making sure the new result is in that range. - Some other possibilities might evolve later. Above is just an example used now by some Performance teams. -Goal of this ADR is to propose a way for this kind of testing to be implemented in AppStudio (feature [STONE-679](https://issues.redhat.com/browse/STONE-679)). Even if it would not deprecate full-blown performance and scale testing, having a release gate with some short and small scale performance test is desirable for many application teams. +Goal of this ADR is to propose a way for this kind of testing to be implemented in Konflux (feature [STONE-679](https://issues.redhat.com/browse/STONE-679)). Even if it would not deprecate full-blown performance and scale testing, having a release gate with some short and small scale performance test is desirable for many application teams. ### Glossary @@ -53,7 +53,7 @@ Horreum instances would be managed by Red Hat and used by tenants on specific cl 4. Horreum performs result analysis, looking for changes in configured metrics. 5. Pipeline gets PASS/FAIL decision from Horreum back to the pipeline, so pipeline can return proper result. -Although Horreum provides rich web UI for configuring JSON parsing, change detection and data visualization, it will stay hidden to AppStudio users. AppStudio will expose subset of that functionality in it's own web UI and will talk to Horreum via it's API interface. +Although Horreum provides rich web UI for configuring JSON parsing, change detection and data visualization, it will stay hidden to Konflux users. Konflux will expose subset of that functionality in it's own web UI and will talk to Horreum via it's API interface. We need to make a decision about one instance per cluster or one instance per tenant. @@ -63,7 +63,7 @@ Pros: - We can provide some best practices to customers wanting to do some basic performance regression testing. - Horreum is end-to-end solution that already exists, is already used by multiple teams and has documentation for the whole process. -- AppStudio UI can display all the trends because historical data will be available in Horreum. +- Konflux UI can display all the trends because historical data will be available in Horreum. - Red Hat team that develops Horreum is willing to help with this effort. - Integration scripts needed to run in the pipeline (to gather monitoring data, to upload results to Horreum, to get PASS/FAIL decision from Horreum...) that already exists: - Monitor performance workloads. @@ -73,10 +73,10 @@ Pros: Cons: - Somebody has to manage the Horreum instance. Required development time on it. Service instance needs ownership. -- Although Horreum uses Keycloak as well, some changes in the Horreum authentication mechanism might be required to cooperate with AppStudio member cluster RBAC. +- Although Horreum uses Keycloak as well, some changes in the Horreum authentication mechanism might be required to cooperate with Konflux member cluster RBAC. - To make sure Horreum users from one tenant are not able to access data from different tenant, created . - Horreum is used by multiple teams without any capacity issues, but Horreum itself was not perf&scale tested formally, so there might be some scaling issues. -- We would need to develop AppStudio UI to get graphs/results from Horreum and to allow users to configure the change detection parameters for their tests. +- We would need to develop Konflux UI to get graphs/results from Horreum and to allow users to configure the change detection parameters for their tests. - If we need one Horreum instance per workspace, that would require further development work (i.e. operator for provisioning per worksapce, data backup/restore etc). - As the performance testing pipelines can be some heavy on resources, attribution of costs to users/workspaces might be tricky, but can be measured in a same way as we plan to measure functional tests or build pipelines. - Attribution of costs to run the Horreum, maybe tracking these can be added to scope of . diff --git a/ADR/0019-customize-url-github.md b/ADR/0019-customize-url-github.md index 93d2b0f6..7859a384 100644 --- a/ADR/0019-customize-url-github.md +++ b/ADR/0019-customize-url-github.md @@ -12,7 +12,7 @@ Accepted ### Motivation When we run builds and tests on PRs (see [STONE-134](https://issues.redhat.com/browse/STONE-134)), -developers need to be provided a link to the AppStudio UI so they can see the details of their +developers need to be provided a link to the Konflux UI so they can see the details of their `PipelineRuns`. This is particularly important when a `PipelineRun` produces an error/failure. The current implementation sends links back to the OpenShift developer console on the member cluster, which should not be accessed by general public users. @@ -25,33 +25,33 @@ Adding `/logs` to the URL lets the user drill in the logs of a particular TaskRu there is no bookmarkable URL which allows users to see the logs of a specific TaskRun. This feature may be added in the near future (see [HAC-3370](https://issues.redhat.com/browse/HAC-3307)). -The following components in AppStudio send data/results back to GitHub via the Checks API: +The following components in Konflux send data/results back to GitHub via the Checks API: - Pipelines as Code (PaC) - Integration Service - Other services which may run Pipelines in response to a GitHub event (ex - potentially Release Service). -An AppStudio workspace is associated with a Kubernetes namespace on a AppStudio “member cluster”, +An Konflux workspace is associated with a Kubernetes namespace on a Konflux “member cluster”, which is not directly accessible by end users. The namespace name on the member cluster currently correlates with the workspace name (a suffix is added). [ADR 10](0010-namespace-metadata.html) specifies that a namespace label should exist which links the member cluster namespace back to the -AppStudio workspace. +Konflux workspace. -Artifacts in AppStudio are organized into `Applications` and `Components`. A namespace can have more +Artifacts in Konflux are organized into `Applications` and `Components`. A namespace can have more than one `Application`, and an `Application` can have one or more `Components`. At present, each `Component` has an associated PaC `Repository` object, though this may be subject to change in the future. ### Requirements -For a given PipelineRun in AppStudio, the following information must be identifiable based on -information in the AppStudio member cluster: +For a given PipelineRun in Konflux, the following information must be identifiable based on +information in the Konflux member cluster: - Workspace ID - Application ID - Pipeline run ID -AppStudio components that report data back to GitHub must know the root URL for the AppStudio UI. -This URL must be configurable per AppStudio deployment (ex - staging, production in +Konflux components that report data back to GitHub must know the root URL for the Konflux UI. +This URL must be configurable per Konflux deployment (ex - staging, production in [infra-deployments](https://github.com/redhat-appstudio/infra-deployments)). Workspace and application IDs should _not_ be added to PipelineRun YAML that is added to git repositories for PaC. PaC PipelineRun templates should be transportable when a user forks someone @@ -59,7 +59,7 @@ else’s git repo. ## Decision -AppStudio components that provide `PipelineRun` result links to GitHub or other source control +Konflux components that provide `PipelineRun` result links to GitHub or other source control management systems must provide URLs that are accessible to registered end users who have permission to view the requested `PipelineRun` resource. @@ -77,20 +77,20 @@ customize the `PipelineRun` URL sent to SCM providers. This will take advantage parameters feature in Pipelines as Code (see [SRVKP-2940](https://issues.redhat.com/browse/SRVKP-2940)). The mechanism for how the console URL can be templated using parameters will be documented upstream -and published [online](https://pipelinesascode.com). AppStudio will configure Pipelines as Code to +and published [online](https://pipelinesascode.com). Konflux will configure Pipelines as Code to use the following parameters in the console URL templates: - `workspace` - `application` -### Build Service: Propagate AppStudio Data to Repository CR +### Build Service: Propagate Konflux Data to Repository CR -The AppStudio build service should be enhanced as follows: +The Konflux build service should be enhanced as follows: - When the `Component` CR is created/reconciled, add the following parameters to the respective `Repository`: - - `workspace` - the AppStudio workspace (`appstudio.redhat.com/workspace_name` label on namespace) - - `application` - the AppStudio application name for the `Component`. + - `workspace` - the Konflux workspace (`appstudio.redhat.com/workspace_name` label on namespace) + - `application` - the Konflux application name for the `Component`. ### Integration Test Service: Customize URLs @@ -99,7 +99,7 @@ sent back to the respective SCM provider. Namely: - Use the same custom console URL - Use similar templating mechanisms for getting the PipelineRun URL - example by inferring the - AppStudio workspace from the appropriate namespace and application via the parent Application + Konflux workspace from the appropriate namespace and application via the parent Application for a respective component. ### Privacy Impact diff --git a/ADR/0020-source-retention.md b/ADR/0020-source-retention.md index 27dcbed3..023e2d46 100644 --- a/ADR/0020-source-retention.md +++ b/ADR/0020-source-retention.md @@ -15,7 +15,7 @@ revision and its change history are preserved indefinitely and cannot be deleted subject to an established and transparent policy for obliteration, such as a legal or policy requirement." -We intend for the AppStudio pipeline to support this requirement in +We intend for the Konflux pipeline to support this requirement in [RHTAP-107](https://issues.redhat.com/browse/RHTAP-107). Since we [Use our own pipelines (ADR .17)](0017-use-our-pipelines.html), this would satisfy the control for us, if it were implemented. @@ -24,7 +24,7 @@ a "technical control") that precribes how our own source repositories must be ma ## Decision -The source history of branches used to build AppStudio components (usually the `main` branch), must +The source history of branches used to build Konflux components (usually the `main` branch), must not be overwritten or deleted. This practice can be supported by enabling branch protection rules on a repo by repo basis that diff --git a/ADR/0025-appstudio-pipeline-serviceaccount.md b/ADR/0025-appstudio-pipeline-serviceaccount.md index 1a51569d..73be252d 100644 --- a/ADR/0025-appstudio-pipeline-serviceaccount.md +++ b/ADR/0025-appstudio-pipeline-serviceaccount.md @@ -8,13 +8,13 @@ Accepted ## Context -A default service account must be provided to allow AppStudio components to run pipelines. +A default service account must be provided to allow Konflux components to run pipelines. While OpenShift Pipelines has the option to automatically create a `pipeline` ServiceAccount on any namespace, the permissions granted to the account are overly broad and the solution was rejected after a security review. -Therefore AppStudio must manage this default service account. +Therefore Konflux must manage this default service account. ## Decision -AppStudio will provide a service account named `appstudio-pipeline`. +Konflux will provide a service account named `appstudio-pipeline`. ### Ownership diff --git a/ADR/0026-specifying-ocp-targets-for-fbc.md b/ADR/0026-specifying-ocp-targets-for-fbc.md index 6a0a88e8..222ccd76 100644 --- a/ADR/0026-specifying-ocp-targets-for-fbc.md +++ b/ADR/0026-specifying-ocp-targets-for-fbc.md @@ -8,7 +8,7 @@ Accepted ## Context -One of the supported component types within AppStudio are [File-based Catalogs (FBC)]. +One of the supported component types within Konflux are [File-based Catalogs (FBC)]. These catalogs can either be used in isolation with a version of `opm` packaged in the container itself or in conjunction with other catalog configurations via a service such as [IIB Image Builder]. Red Hat OpenShift Container Platform (OCP) is one example of a platform that @@ -16,9 +16,9 @@ leverages FBCs for defining the operator graphs. In order to enable operator sup version-by-version basis, Red Hat maintains one catalog per OpenShift version. In order to support being able to target FBC components to specific versions of Red Hat OpenShift, -AppStudio needs to be able to keep track of the specific targeted version. In addition to the concerns +Konflux needs to be able to keep track of the specific targeted version. In addition to the concerns around releasing FBC components to OpenShift, the version of `opm` used by each version of OpenShift -may differ, so the AppStudio integration process will need to ensure that tests are run using an appropriate +may differ, so the Konflux integration process will need to ensure that tests are run using an appropriate binary version. ## Decision @@ -57,20 +57,20 @@ $ skopeo inspect --raw docker://quay.io/hacbs-release-tests/managed-release-team ``` The target Red Hat OpenShift version will then be able to be pulled from the image tag on the -"org.opencontainers.image.base.name" annotation. If a task within the AppStudio pipeline needs to access +"org.opencontainers.image.base.name" annotation. If a task within the Konflux pipeline needs to access an appropriate `opm` binary for performing validation, it can determine the base image and use the binary from -that container if it is trusted (for example, if it is an image from the +that container if it is trusted (for example, if it is an image from the `registry.redhat.io/openshift4/ose-operator-registry` repository), or fail if the base image isn't trusted. ## Consequences -* AppStudio services should be able to avoid directly using the `opm` version packaged in FBC components +* Konflux services should be able to avoid directly using the `opm` version packaged in FBC components to prevent the execution of untrusted binaries by a process in the trusted control plane. * No additional kubernetes objects need to be created to track the target OCP versions -* There is a desire to use [FBC templates] within AppStudio in the future. The current decision can be +* There is a desire to use [FBC templates] within Konflux in the future. The current decision can be re-evaluated if and when that functionality is introduced. [FBC templates]: https://olm.operatorframework.io/docs/reference/catalog-templates/ [File-based Catalogs (FBC)]: https://olm.operatorframework.io/docs/reference/file-based-catalogs/ -[IIB Image Builder]: https://github.com/release-engineering/iib \ No newline at end of file +[IIB Image Builder]: https://github.com/release-engineering/iib diff --git a/ADR/0027-availability-probe-framework.md b/ADR/0027-availability-probe-framework.md index a0e6d1d7..01b9f2fc 100644 --- a/ADR/0027-availability-probe-framework.md +++ b/ADR/0027-availability-probe-framework.md @@ -8,15 +8,15 @@ Accepted ## Context -As an AppStudio developer building functionality for the platform, I want to be able to +As an Konflux developer building functionality for the platform, I want to be able to easily visualize and comprehend the stability and availability of deployed systems in order to inform and influence future work towards improving the overall system reliability. - -Such indication should tell us the overall uptime of AppStudio with respect to services -under the control of AppStudio developers. -AppStudio is defined to be available at a given moment if all of its components are +Such indication should tell us the overall uptime of Konflux with respect to services +under the control of Konflux developers. + +Konflux is defined to be available at a given moment if all of its components are reporting to be available at that given moment, and unavailable otherwise. A component is defined to be available at a given moment if all of its availability @@ -25,7 +25,7 @@ probes are reporting to be available at that given moment, and unavailable other A convention is required for providing the availability of a probe. Once this is in place, those indicators can be aggregated in order to report the overall -availability of AppStudio. +availability of Konflux. ## Decision @@ -59,7 +59,7 @@ API server. It generates and [CronJob](https://github.com/kubernetes/kube-state-metrics/blob/main/docs/cronjob-metrics.md) metrics that will be processed using Prometheus recording rules in order to -generate AppStudio's availability Prometheus metric. +generate Konflux's availability Prometheus metric. A single set of rules will be defined globally which will apply for all CronJobs. @@ -122,7 +122,7 @@ Considerations for defining probes' CronJobs: ## Consequences -* The different teams for all AppStudio services will define the CronJobs required for +* The different teams for all Konflux services will define the CronJobs required for testing their components' availability, and will name them according to the naming convention. * A single set of Prometheus recording rules will be defined for transforming the diff --git a/ADR/0027-container-images.md b/ADR/0027-container-images.md index 78d433d0..a85ac0b1 100644 --- a/ADR/0027-container-images.md +++ b/ADR/0027-container-images.md @@ -10,11 +10,11 @@ Proposed ## Context -The purpose of this document is to establish container image management practices for AppStudio container images that are deployed in the staging and production environments. The goal is to ensure that AppStudio is continuously maintaining secure operations that are in accordance with the ESS SEC-PATCH-REQ-2 (OS Patching) requirements. +The purpose of this document is to establish container image management practices for Konflux container images that are deployed in the staging and production environments. The goal is to ensure that Konflux is continuously maintaining secure operations that are in accordance with the ESS SEC-PATCH-REQ-2 (OS Patching) requirements. ### Scope * The scope of this process is limited to the images found in our [quay.io/organization/redhat-appstudio](https://quay.io/organization/redhat-appstudio) repository. -* Images from dependencies that fall outside of this AppStudio process should follow the [ESS Security Patching at Application/OS Level (requirements 27 and 28)](https://drive.google.com/file/d/1P6-q2HJxA3yZhykaI29gF2IV4avzxtjM/view). It is up to the component teams to ensure they are adhering to these requirements. +* Images from dependencies that fall outside of this Konflux process should follow the [ESS Security Patching at Application/OS Level (requirements 27 and 28)](https://drive.google.com/file/d/1P6-q2HJxA3yZhykaI29gF2IV4avzxtjM/view). It is up to the component teams to ensure they are adhering to these requirements. * Images that are not intended for the staging and/or production environments are out of scope. @@ -22,7 +22,7 @@ The purpose of this document is to establish container image management practice ### Role -**Component Team**: Develops and maintains components that are built as images and deployed as part of AppStudio +**Component Team**: Develops and maintains components that are built as images and deployed as part of Konflux ### Responsibilities diff --git a/ADR/0029-component-dependencies.md b/ADR/0029-component-dependencies.md index d5dff797..c7f2341f 100644 --- a/ADR/0029-component-dependencies.md +++ b/ADR/0029-component-dependencies.md @@ -8,14 +8,14 @@ Accepted ## Context -As an AppStudio user, I want to be able to build and test multiple coupled components which depend on each other by digest reference. I want that process to be easy. +As an Konflux user, I want to be able to build and test multiple coupled components which depend on each other by digest reference. I want that process to be easy. There are three use cases in scope for this document: -* A user team has their own **common parent image**. When they propose an update to their base image with new content, they want to see if that’s going to break any of their Components that depend on it before merging. AppStudio should posit what rebuilds of those Components will look like and if they will pass their tests, and report that feedback back to the original pull request that updated content of the common parent image ([RHTAP-967](https://issues.redhat.com/browse/RHTAP-967)). A real example of this is in stolostron, where a [layered image component](https://github.com/stolostron/console/blob/main/Dockerfile.mce.prow#L20) refers to a [common parent image](https://github.com/stolostron/common-nodejs-parent). +* A user team has their own **common parent image**. When they propose an update to their base image with new content, they want to see if that’s going to break any of their Components that depend on it before merging. Konflux should posit what rebuilds of those Components will look like and if they will pass their tests, and report that feedback back to the original pull request that updated content of the common parent image ([RHTAP-967](https://issues.redhat.com/browse/RHTAP-967)). A real example of this is in stolostron, where a [layered image component](https://github.com/stolostron/console/blob/main/Dockerfile.mce.prow#L20) refers to a [common parent image](https://github.com/stolostron/common-nodejs-parent). * In this case, the dependent images must be rebuilt to include the common parent image update in order to determine the actual effect of the proposed change. * This is a many-to-one dependency. Many component images depend on one common parent image. -* A user team has an **OLM operator**. When they propose an update to one of their operands with new code, they want to see if that’s going to break their operator. In order to be fully tested, a single rebuilt image needs to be included as a reference in a bundle image in order to be tested as a whole unit when deployed via OLM, i.e. for integration tests ([RHTAP-992](https://issues.redhat.com/browse/RHTAP-992)). A real example of this is in [gatekeeper](https://github.com/gatekeeper/gatekeeper-operator) where the operator repo contains both the [controller code](https://github.com/gatekeeper/gatekeeper-operator/blob/main/controllers/gatekeeper_controller.go) and the [bundle metadata](https://github.com/gatekeeper/gatekeeper-operator/blob/main/config/manifests/bases/gatekeeper-operator.clusterserviceversion.yaml), which need to be built into separate images([1](https://github.com/gatekeeper/gatekeeper-operator/blob/main/Dockerfile) and [2](https://github.com/gatekeeper/gatekeeper-operator/blob/main/bundle.Dockerfile)), separate Components in AppStudio. +* A user team has an **OLM operator**. When they propose an update to one of their operands with new code, they want to see if that’s going to break their operator. In order to be fully tested, a single rebuilt image needs to be included as a reference in a bundle image in order to be tested as a whole unit when deployed via OLM, i.e. for integration tests ([RHTAP-992](https://issues.redhat.com/browse/RHTAP-992)). A real example of this is in [gatekeeper](https://github.com/gatekeeper/gatekeeper-operator) where the operator repo contains both the [controller code](https://github.com/gatekeeper/gatekeeper-operator/blob/main/controllers/gatekeeper_controller.go) and the [bundle metadata](https://github.com/gatekeeper/gatekeeper-operator/blob/main/config/manifests/bases/gatekeeper-operator.clusterserviceversion.yaml), which need to be built into separate images([1](https://github.com/gatekeeper/gatekeeper-operator/blob/main/Dockerfile) and [2](https://github.com/gatekeeper/gatekeeper-operator/blob/main/bundle.Dockerfile)), separate Components in Konflux. * In this case, the bundle image must be rebuilt for the operand image update to be tested at all (assuming OLM is the strategy for deploying the operator). * This is a one-to-many dependency. One operator bundle depends on many operand images. * A user team just has **two components that depend on each other in a functional way**. When they propose an update to one component, they want to submit a corresponding change to the second component, and have those tested together before merging both. @@ -169,8 +169,8 @@ Think about branches: ## Consequences -* The basics of AppStudio builds are unchanged with this design (an alternative design that we considered involved changing the way pull-request build pipelines were defined and processed by PaC). This means less change spidering out to other AppStudio systems to support this change. -* The user can pin their digest references in git. AppStudio will automate maintaining them. No magical resolution of tags in the buildsystem at build time, or worse at runtime. +* The basics of Konflux builds are unchanged with this design (an alternative design that we considered involved changing the way pull-request build pipelines were defined and processed by PaC). This means less change spidering out to other Konflux systems to support this change. +* The user can pin their digest references in git. Konflux will automate maintaining them. No magical resolution of tags in the buildsystem at build time, or worse at runtime. * The user is going to get more PRs on their repo. Maybe too many PRs for a positive UX. * Since more PRs will trigger more PipelineRuns, our current PVC quota issues (which limit how many PipelineRuns can be run at any one time) may be exacerbated. * Users may have only a few Components, or they may have many (many dozens) of Components. Once they get past so many component dependencies, we suspect that users will likely change from checking that all dependent images work with the new parent image to "sharing" the verification load: building the image and pushing it out for other components/dependencies to update and test within their own PRs. With this design, the user can achieve this by purging the `build-nudges-ref` field values from their Component CRs. The parent image will be built and tested as normal. [build-service] will not send PRs. The user can still hypothethically construct their own PR Group to test a particular layered component on an unmerged parent image change. diff --git a/ADR/0030-tekton-results-naming-convention.md b/ADR/0030-tekton-results-naming-convention.md index 71a83e57..7cac6880 100644 --- a/ADR/0030-tekton-results-naming-convention.md +++ b/ADR/0030-tekton-results-naming-convention.md @@ -7,12 +7,12 @@ Date: 2023-09-27 Accepted Relates to: -* [ADR 13. AppStudio Test Stream - API contracts](0013-integration-service-api-contracts.html) +* [ADR 13. Konflux Test Stream - API contracts](0013-integration-service-api-contracts.html) * [ADR 14. Let Pipelines Proceed](0014-let-pipelines-proceed.html) ## Context -In order to [Let Pipelines Proceed](0014-let-pipelines-proceed.html), the default interface of a Tekton Task's status code becomes an unsuitable API contract for communicating the successes and failures of tasks. [ADR 13. AppStudio Test Stream - API contracts](0013-integration-service-api-contracts.html) established the first API contract for Tekton result standardization within AppStudio for the built-in Task definitions when task failure was not an option. As AppStudio onboarding continues, more non-default tasks (partner and user tasks, for example) will be defined and the current standardization's narrow scope may start to confuse task authors. Further compounding this issue is the lack of a concrete guidance or standard from the Tekton community around standard sets of result names. Therefore, the AppStudio components should adhere to generic standards for supported results types while still enabling the platform to operate within the Tekton result size limitations. +In order to [Let Pipelines Proceed](0014-let-pipelines-proceed.html), the default interface of a Tekton Task's status code becomes an unsuitable API contract for communicating the successes and failures of tasks. [ADR 13. Konflux Test Stream - API contracts](0013-integration-service-api-contracts.html) established the first API contract for Tekton result standardization within Konflux for the built-in Task definitions when task failure was not an option. As Konflux onboarding continues, more non-default tasks (partner and user tasks, for example) will be defined and the current standardization's narrow scope may start to confuse task authors. Further compounding this issue is the lack of a concrete guidance or standard from the Tekton community around standard sets of result names. Therefore, the Konflux components should adhere to generic standards for supported results types while still enabling the platform to operate within the Tekton result size limitations. ## Decision @@ -25,7 +25,7 @@ If tasks exist outside of the build pipeline, they _may_ adhere to the following There are two defined standards for minimized [Tekton result](https://tekton.dev/docs/pipelines/tasks/#emitting-results) formats based on the common task types -- test-like and scan-like tasks. Each of these standards will have a unique result name as well as their own result format. -The standards presented in this ADR supersede those in [ADR 13. AppStudio Test Stream - API contracts](0013-integration-service-api-contracts.html). All other standards presented in the previous ADR hold unless _this_ ADR is superseded by an additional ADR that deprecates those standards. These other non-deprecated standards presented include [Detailed Conftest Output JSON](0013-integration-service-api-contracts.html#detailed-conftest-output-json), [Information injection](0013-integration-service-api-contracts.html#information-injection), [Information format](0013-integration-service-api-contracts.html#information-format), and [Image references](0013-integration-service-api-contracts.html#image-references). +The standards presented in this ADR supersede those in [ADR 13. Konflux Test Stream - API contracts](0013-integration-service-api-contracts.html). All other standards presented in the previous ADR hold unless _this_ ADR is superseded by an additional ADR that deprecates those standards. These other non-deprecated standards presented include [Detailed Conftest Output JSON](0013-integration-service-api-contracts.html#detailed-conftest-output-json), [Information injection](0013-integration-service-api-contracts.html#information-injection), [Information format](0013-integration-service-api-contracts.html#information-format), and [Image references](0013-integration-service-api-contracts.html#image-references). ### Results for Test-like Tasks Test-like tasks are those whose results can be immediately classified as successful or failed. If these tests are taken into account in the final suitability of an artifact for promotion or release, then all pass/fail determination would be deferred to the task run. @@ -94,7 +94,7 @@ Scan-like results should still use the **TEST_OUTPUT** result for indicating whe To display count of found vulnerabilities and make it easy to understand and evaluate the state of scanned content, the additional output of scan-like tasks will be provided in a minimized [Tekton result](https://tekton.dev/docs/pipelines/tasks/#emitting-results) in JSON format listing. The name of the result will be **SCAN_OUTPUT**. -While the vulnerability classifications should remain consistent in order to enable easier extensions into other AppStudio components (namely the user interface and enterprise contract), it is the responsibility of every scan-like task to inform the user about what criteria fits each vulnerability classification used. The vulnerability classifications from most important/severe to least are **critical**, **high**, **medium**, and **low**. If a vulnerability is classified as **unknown** then the scanner cannot make further judgement about its severity. +While the vulnerability classifications should remain consistent in order to enable easier extensions into other Konflux components (namely the user interface and enterprise contract), it is the responsibility of every scan-like task to inform the user about what criteria fits each vulnerability classification used. The vulnerability classifications from most important/severe to least are **critical**, **high**, **medium**, and **low**. If a vulnerability is classified as **unknown** then the scanner cannot make further judgement about its severity. Some scanners are additionally aware of whether a specific vulnerability is patched or unpatched (i.e. whether there is a known fix that has been published by the vulnerable package's maintainers). If vulnerabilities are known to be unpatched, the scanner may use the **unpatched_vulnerabilities** object to represent their quantities and severities. @@ -257,5 +257,5 @@ The output of the Tekton result **IMAGES_PROCESSED** can be validated using the ## Consequences -* Until a time arrives when a standard is set upstream around the best practices for defining a result API, AppStudio will define its own standard for adherence. -* In situations where pipelines do not _need_ to proceed, (**IntegrationTestScenario**s, for example), this API does not need to be leveraged. Instead, the default API of the Task's status of success/failure can be used in lieu of the test-like results. \ No newline at end of file +* Until a time arrives when a standard is set upstream around the best practices for defining a result API, Konflux will define its own standard for adherence. +* In situations where pipelines do not _need_ to proceed, (**IntegrationTestScenario**s, for example), this API does not need to be leveraged. Instead, the default API of the Task's status of success/failure can be used in lieu of the test-like results. diff --git a/ADR/0031-sprayproxy.md b/ADR/0031-sprayproxy.md index 4bcc99c1..dd12bd2e 100644 --- a/ADR/0031-sprayproxy.md +++ b/ADR/0031-sprayproxy.md @@ -8,11 +8,11 @@ Accepted ## Context -AppStudio has multiple member (backend) clusters. Each member cluster is running a Pipelines-As-Code (PaC) service, accepting webhook requests. A GitHub App can only specify a single destination for webhook requests. We need to forward those requests to multiple clusters. +Konflux has multiple member (backend) clusters. Each member cluster is running a Pipelines-As-Code (PaC) service, accepting webhook requests. A GitHub App can only specify a single destination for webhook requests. We need to forward those requests to multiple clusters. ## Decision -Deploy a service (`Sprayproxy`) on the AppStudio host (frontend) clusters. The service route is configured in the GitHub App as a `Webhook URL`, so all webhook requests are directed to it. The service has a list of backends configured. The service does not distinguish between the type of requests the way PaC does (pull-request/push/comment etc), it treats them all equally. For each incoming request, a new outgoing request is constructed with the original payload and destination of each of the member clusters. +Deploy a service (`Sprayproxy`) on the Konflux host (frontend) clusters. The service route is configured in the GitHub App as a `Webhook URL`, so all webhook requests are directed to it. The service has a list of backends configured. The service does not distinguish between the type of requests the way PaC does (pull-request/push/comment etc), it treats them all equally. For each incoming request, a new outgoing request is constructed with the original payload and destination of each of the member clusters. The service performs the following checks on incoming requests: @@ -25,5 +25,5 @@ The service exports metrics visible only on the dashboards on the host clusters ## Consequences -- Each AppStudio customer is onboarded to one cluster which means a pipeline on that particular cluster will be triggered as a result of the request. By "blindly" forwarding the request to all clusters, requests are also sent to clusters where they won't have effect and are discarded. +- Each Konflux customer is onboarded to one cluster which means a pipeline on that particular cluster will be triggered as a result of the request. By "blindly" forwarding the request to all clusters, requests are also sent to clusters where they won't have effect and are discarded. - Sprayproxy performs the same type of request verification as does PaC. The reason for doing that is we do not forward invalid requests to multiple clusters, but it also means extra workload. Operationally both services use the same shared secret, so when rotating the secret it only has to be done in a single place. diff --git a/ADR/0032-decoupling-deployment.md b/ADR/0032-decoupling-deployment.md index 18d2eda8..727c46f2 100644 --- a/ADR/0032-decoupling-deployment.md +++ b/ADR/0032-decoupling-deployment.md @@ -120,7 +120,7 @@ flowchart TD argocd --> |deploys to| cluster[User provided cluster] ``` -Outside of the AppStudio member cluster, the user is responsible for acquiring a gitops repo and +Outside of the Konflux member cluster, the user is responsible for acquiring a gitops repo and deployment environments of their choice, manually laying out their application resources in the repo (assisted by tools like `kam`), specifying image references by tag to match the `:released` or `:validated` tagging schem mentioned above, configuring ArgoCD to deploy from their gitops repo, and @@ -129,7 +129,7 @@ here is just an example and other gitops tools could be used; renovate could eve with the new images. Options for the user are not limited. **For manual creation of new environments** - the user manages this directly using a combination of -their gitops repo and argo, outside of the AppStudio member cluster. +their gitops repo and argo, outside of the Konflux member cluster. **For automated testing in ephemeral environments** - the user specifies an [IntegrationTestScenario] CR, which references a pipeline which (somehow) creates a `resourceClaim`. @@ -164,13 +164,13 @@ flowchart TD - Users who expect effortless deployment of their app when onboarding to the system will be dissapointed. They have more work to do to set up a deployment of their app outside the system. -- Users will lose visibility of their applications' deployments and status in the AppStudio UI +- Users will lose visibility of their applications' deployments and status in the Konflux UI (HAC). Other systems like the Argo UI are arguably better at this than we are. - Users who expect to provide and manage their own resources to control their app will be delighted. They now no longer have to interact with an intermediary API to try to express details about their deployment(s). - As a team, we'll be in a better position to try to achieve independence for [integration-service], - make it usable outside the context of AppStudio, and ideally make it attractive for collaborators. + make it usable outside the context of Konflux, and ideally make it attractive for collaborators. ## Implementation diff --git a/README.md b/README.md index 4086647a..c8a3bae1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Architecture of AppStudio +# Architecture of Konflux -This repository contains the technical and architecture documents for AppStudio. +This repository contains the technical and architecture documents for Konflux. User documentation is out of scope. ## Guide to Sections diff --git a/_config.yml b/_config.yml index e6f9fae2..c5a71cf8 100644 --- a/_config.yml +++ b/_config.yml @@ -1,5 +1,5 @@ remote_theme: vaibhavvikas/jekyll-theme-minimalistic -title: Architecture Of AppStudio +title: Architecture Of Konflux description: Technical documents about the Managed Developer Platform color-scheme: auto navigation: @@ -25,4 +25,4 @@ navigation: - name: Release Service link: /architecture/ref/release-service.html - name: Enterprise Contract - link: /architecture/ref/enterprise-contract.html \ No newline at end of file + link: /architecture/ref/enterprise-contract.html diff --git a/architecture/HAS/hybrid-application-service-api.md b/architecture/HAS/hybrid-application-service-api.md index b4b0acc9..7699dacc 100644 --- a/architecture/HAS/hybrid-application-service-api.md +++ b/architecture/HAS/hybrid-application-service-api.md @@ -2,7 +2,7 @@ ## Overview -The official Hybrid Application Service (HAS) APIs are listed in the AppStudio [API Reference](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#application). The APIs Specific to HAS are: +The official Hybrid Application Service (HAS) APIs are listed in the Konflux [API Reference](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#application). The APIs Specific to HAS are: * [Application](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#application) * [Component](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#component) diff --git a/architecture/HAS/hybrid-application-service-component-types.md b/architecture/HAS/hybrid-application-service-component-types.md index a53e91b1..3428d152 100644 --- a/architecture/HAS/hybrid-application-service-component-types.md +++ b/architecture/HAS/hybrid-application-service-component-types.md @@ -4,14 +4,14 @@ HAS supports a variety of user repositories for Components. User repositories ca ## Supported Runtimes -The following runtimes are supported by AppStudio: +The following runtimes are supported by Konflux: - NodeJS - Springboot - Quarkus - Python - Go -Repositories with Components that are not one of the supported runtime types, can still be imported into AppStudio, if the following conditions are met: +Repositories with Components that are not one of the supported runtime types, can still be imported into Konflux, if the following conditions are met: 1) The Component has a Dockerfile present 2) The Dockerfile can be detected 3) **If** a Devfile is present, the Devfile contains references for valid Kubernetes and Dockerfile components. See [below](#devfile-requirements) for specific Devfile requirements @@ -21,7 +21,7 @@ These Components will be listed as having a “Dockerfile” runtime. ## Detecting Components -Before a repository is added to an Application in AppStudio, if no Devfiles or Dockerfiles were specified for the Component resource, HAS will use alizer to attempt to detect the Components that exist within the repository. Each Component that corresponds to a supported runtime type (or Dockerfile type), will be detected. +Before a repository is added to an Application in Konflux, if no Devfiles or Dockerfiles were specified for the Component resource, HAS will use alizer to attempt to detect the Components that exist within the repository. Each Component that corresponds to a supported runtime type (or Dockerfile type), will be detected. If a runtime exists at the top level of the repository, HAS will treat the repository as a single Component, and will not attempt to detect Components below that level. @@ -30,10 +30,10 @@ If a runtime exists at the top level of the repository, HAS will treat the repos Some runtime types may have specific requirements in order to be detected by HAS: Quarkus -- If a .dockerignore file is present, make sure that a wildcard, *, entry is not present, as AppStudio builds the Application source as part of the Container build +- If a .dockerignore file is present, make sure that a wildcard, *, entry is not present, as Konflux builds the Application source as part of the Container build Python -- Pip is used to manage dependencies for AppStudio Python projects. Make sure that your project has a requirements.txt or a pyproject.toml file at the root. +- Pip is used to manage dependencies for Konflux Python projects. Make sure that your project has a requirements.txt or a pyproject.toml file at the root. NodeJS - HAS expects NodeJS based Components to have a package.json at the Component's base folder diff --git a/architecture/HAS/hybrid-application-service-crds.md b/architecture/HAS/hybrid-application-service-crds.md index 94bfb9fc..34db37a1 100644 --- a/architecture/HAS/hybrid-application-service-crds.md +++ b/architecture/HAS/hybrid-application-service-crds.md @@ -7,7 +7,7 @@ [ComponentDetectionQuery](hybrid-application-service-crds.md#componentdetectionquery) ## Application -The Application resource defines an Application in AppStudio. The fields in the resource are relatively bare, just the name of the resource (a UUID), an annotation with the application’s name, a description for the Application, and its git repository. +The Application resource defines an Application in Konflux. The fields in the resource are relatively bare, just the name of the resource (a UUID), an annotation with the application’s name, a description for the Application, and its git repository. When the resource is created, the `status.devfile` field is populated with the Application model for the app (a Devfile). When the Application resource is updated, or Components are added to the Application, the Application model in this resource is updated accordingly. @@ -53,7 +53,7 @@ When the resource is created, the `status.devfile` field is populated with the A ## Component -The Component resource defines an application’s Component in AppStudio. The fields in the resource contain the name of the resource, the component’s name, the Application it is linked to (referenced via a label), and the source for the Component (a git repository, container image, or external Devfile URL). +The Component resource defines an application’s Component in Konflux. The fields in the resource contain the name of the resource, the component’s name, the Application it is linked to (referenced via a label), and the source for the Component (a git repository, container image, or external Devfile URL). When the Component is created, the HAS controller retrieves the component’s Devfile from the specified source (a git repo, a container image, or an external URL). The Application resource for the Component’s Application also has its model updated to reference the Component (via its `status.devfile` field). The controller also adds labels for the Component name and Application CR name to the resource. diff --git a/architecture/HAS/hybrid-application-service-design.md b/architecture/HAS/hybrid-application-service-design.md index 2a9db698..2553ec07 100644 --- a/architecture/HAS/hybrid-application-service-design.md +++ b/architecture/HAS/hybrid-application-service-design.md @@ -67,7 +67,7 @@ The Devfile in Application and Component CRs are a source of truth for the HAS c ## Build Service Integration -For the Build Service integration, The HAS Component controller will create a webhook url during the Component creation process. A TriggerTemplate and an EventListener will be created as per the documentation AppStudio Build Service Architecture +For the Build Service integration, The HAS Component controller will create a webhook url during the Component creation process. A TriggerTemplate and an EventListener will be created as per the documentation Konflux Build Service Architecture The webhook URL will only be created with a user provided Git repository. If the user chooses to import from a Devfile Registry sample, the user would need to clone the sample and import it via HAC to enable webhooks for the Git repository. @@ -90,6 +90,6 @@ The GitOps repository stores the following information: 2. [Sample Generated GitOps Repo](https://github.com/maysunfaisal/application-sample-lK5Sb-lend-enjoy) - current version generated by HAS on Kubernetes 2. HAS Component specific information like Deployment, Service, Route, Ingress and other Kubernetes resources. -In the beginning, the GitOps repository will be stored under the private org https://github.com/redhat-appstudio-appdata that is owned by AppStudio. The user will not be able to access the data under that org directly. For each Application, a unique GitOps repository will be generated under that GitHub org for storing the GitOps repository specific data. For GitOps repository that is stored under that private org, the lifecycle of that repository will follow the lifecycle of the Application, i.e. when the Application is being deleted, the corresponding GitOps repository will be deleted automatically. +In the beginning, the GitOps repository will be stored under the private org https://github.com/redhat-appstudio-appdata that is owned by Konflux. The user will not be able to access the data under that org directly. For each Application, a unique GitOps repository will be generated under that GitHub org for storing the GitOps repository specific data. For GitOps repository that is stored under that private org, the lifecycle of that repository will follow the lifecycle of the Application, i.e. when the Application is being deleted, the corresponding GitOps repository will be deleted automatically. -In the future, the user can bring their own users repo to store those GitOps resources. By that time, AppStudio will need to support the user editing the GitOps resources directly. The lifecycle of the GitOps repository may not follow the lifecycle of the Application since it is a user owned resource. We may need to prompt the user for the option to delete the corresponding GitOps repository when the user deletes the Application, i.e. when the Application CR is deleted. +In the future, the user can bring their own users repo to store those GitOps resources. By that time, Konflux will need to support the user editing the GitOps resources directly. The lifecycle of the GitOps repository may not follow the lifecycle of the Application since it is a user owned resource. We may need to prompt the user for the option to delete the corresponding GitOps repository when the user deletes the Application, i.e. when the Application CR is deleted. diff --git a/architecture/HAS/hybrid-application-service-glossary.md b/architecture/HAS/hybrid-application-service-glossary.md index 7035f616..d5585edc 100644 --- a/architecture/HAS/hybrid-application-service-glossary.md +++ b/architecture/HAS/hybrid-application-service-glossary.md @@ -1,7 +1,7 @@ # Hybrid Application Service (HAS) Glossary ## Application -An Application in AppStudio, represented by the HAS Application custom resource. May contain one or more “components”. +An Application in Konflux, represented by the HAS Application custom resource. May contain one or more “components”. ## Application Model A Devfile representation of the Application, containing information about the HAS Application (e.g. its name, description, GitOps repo, etc), along with each Component that is part of the Application. The Application model contains the pointers to where the Components can be found. @@ -10,7 +10,7 @@ A Devfile representation of the Application, containing information about the HA The git repository where the Application model is stored (and available for later import). Specified when creating the HAS Application resource. Can be the same repository as the GitOps repository. The source of the child Components may either be contained within a folder under the Application model repository or it can be distributed in other repositories that contain the Component source code. ## Component -A single containerized Component, running as part of a HAS Application in AppStudio. Represented by the HAS Component custom resource. Each Component will contain a Devfile that contains information about how to build and deploy the Application in App Studio. +A single containerized Component, running as part of a HAS Application in Konflux. Represented by the HAS Component custom resource. Each Component will contain a Devfile that contains information about how to build and deploy the Application in App Studio. ## Devfile A yaml file (and corresponding specification) defining a workflow of a Component. It contains information on how to build, run, deploy and interact with the Component if the Devfile is on the Component level. A Devfile on the Application describes the composition of the Application. diff --git a/architecture/enterprise-contract.md b/architecture/enterprise-contract.md index c320c781..41c642e6 100644 --- a/architecture/enterprise-contract.md +++ b/architecture/enterprise-contract.md @@ -6,7 +6,7 @@ Overview -------- The Enterprise Contract's purpose is to ensure container images produced by -AppStudio meet certain clearly defined requirements before they are considered +Konflux meet certain clearly defined requirements before they are considered releasable. Should a container image not meet the requirements the Enterprise Contract will produce a list of the reasons why so they can be addressed as required to produce a releasable build. @@ -84,10 +84,10 @@ See also the related ### EC Policies -The reference set of policy rules for AppStudio is defined +The reference set of policy rules for Konflux is defined [here](https://github.com/enterprise-contract/ec-policies/) and documented [here](https://enterprise-contract.github.io/ec-policies/). It includes rules for a -range of different policies that are considered useful for AppStudio. +range of different policies that are considered useful for Konflux. There are Conftest bundles containing the latest version of these policies available in [quay.io @@ -100,7 +100,7 @@ Related Components ### Tekton Chains Tekton Chains is a dependency for EC since EC works by examining attestations -created by Tekton Chains when AppStudio build pipelines are running. +created by Tekton Chains when Konflux build pipelines are running. For more information on Tekton Chains refer to the [documentation](https://tekton.dev/docs/chains/), and the GitOps configuration @@ -108,11 +108,11 @@ For more information on Tekton Chains refer to the ### The Release Pipeline -The AppStudio Release Pipeline contains an instance of the EC Task which is used +The Konflux Release Pipeline contains an instance of the EC Task which is used to gate the release. If the EC task fails the release should be blocked. This functionality is handled by the Release Pipeline. -For more information, see [AppStudio Release Service +For more information, see [Konflux Release Service Bundles](https://github.com/redhat-appstudio/release-service-bundles). ### EC and Renovate Bot @@ -120,7 +120,7 @@ Bundles](https://github.com/redhat-appstudio/release-service-bundles). To verify that tasks used in the build pipeline are from known and trusted Tekton bundles, EC requires a list of those bundles. -AppStudio users can leverage the [Renovate +Konflux users can leverage the [Renovate Bot](https://github.com/renovatebot/renovate#readme) service to keep such Tekton bundle lists up to date. The service can be configured to run periodically, and provide pull requests with updated references. @@ -131,9 +131,9 @@ service or on-demand. Additional Resources -------------------- -- [AppStudio Documentation](https://redhat-appstudio.github.io/docs.appstudio.io) +- [Konflux Documentation](https://redhat-appstudio.github.io/docs.appstudio.io) - [Enterprise Contract Documentation](https://enterprise-contract.github.io/) -- [Architecture of AppStudio](https://redhat-appstudio.github.io/architecture/) +- [Architecture of Konflux](https://redhat-appstudio.github.io/architecture/) diff --git a/architecture/hybrid-application-service.md b/architecture/hybrid-application-service.md index eab6c5b5..563a7a85 100644 --- a/architecture/hybrid-application-service.md +++ b/architecture/hybrid-application-service.md @@ -1,6 +1,6 @@ # Hybrid Application Service (HAS) -Hybrid Application Service (HAS) provides an abstract way to define Applications and Components within the cloud. It also allows users to create new Applications and Components or import existing ones into AppStudio. HAS itself is a fully managed service with a set of predefined service types to provide out-of-the-box support. +Hybrid Application Service (HAS) provides an abstract way to define Applications and Components within the cloud. It also allows users to create new Applications and Components or import existing ones into Konflux. HAS itself is a fully managed service with a set of predefined service types to provide out-of-the-box support. ## Goals - Define an Application model that defines the Application and its containing Components @@ -15,7 +15,7 @@ Hybrid Application Service (HAS) provides an abstract way to define Applications ## Architecture Overview -To see how HAS fits into the AppStudio architecture, refer to the AppStudio [Application Context](./index.md#application-context). +To see how HAS fits into the Konflux architecture, refer to the Konflux [Application Context](./index.md#application-context). The diagram below shows the interaction between HAC and HAS services for the creation of Application and Component. diff --git a/architecture/image-controller.md b/architecture/image-controller.md index ed00e748..e19167c3 100644 --- a/architecture/image-controller.md +++ b/architecture/image-controller.md @@ -1,7 +1,7 @@ # Image Controller # Overview -Image controller sets up and manages container image repositories for an application's components. This enables greater component isolation within AppStudio where each component has its own image repository and secret for pushing images built via AppStudio. +Image controller sets up and manages container image repositories for an application's components. This enables greater component isolation within Konflux where each component has its own image repository and secret for pushing images built via Konflux. The image controller can perform three actions on image repositories by watching for either specific annotation changes or deletion events of a [Component CR](https://redhat-appstudio.github.io/architecture/ref/application-environment-api.html#component): @@ -12,7 +12,7 @@ The image controller can perform three actions on image repositories by watching - **Cleanup**: When a Component CR is requested to be deleted, image controller will remove component's image repository and robot account from the remote registry. The Kubernetes Secret will be removed along with the Component CR eventually due to the ownership established between them. # Dependencies -Image controller does not depend on other AppStudio services, but a remote image registry. AppStudio services are able to use the resources prepared by image controller, e.g. Build Service makes the Secret available to every build PipelineRun of a component for image push. +Image controller does not depend on other Konflux services, but a remote image registry. Konflux services are able to use the resources prepared by image controller, e.g. Build Service makes the Secret available to every build PipelineRun of a component for image push. # Interface Image controller uses annotations to interact with external services. diff --git a/architecture/index.md b/architecture/index.md index 4b2401e7..b0c13b69 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -1,7 +1,7 @@ -# AppStudio +# Konflux ## Overview -AppStudio is a platform for building integrated software that streamlines, consolidates, and secures the development lifecycle. +Konflux is a platform for building integrated software that streamlines, consolidates, and secures the development lifecycle. ### Goals @@ -47,9 +47,9 @@ AppStudio is a platform for building integrated software that streamlines, conso ## Application Context -The diagram below shows the services that make up AppStudio and their API resources. +The diagram below shows the services that make up Konflux and their API resources. -![](../diagrams/appstudio.drawio.svg) +![](../diagrams/konflux.drawio.svg) API resources in the first row (Application, Component) should primarilly be thought of as control-plane resources. Users supply these resources to indicate to the system what they want it to @@ -116,7 +116,7 @@ these resources. ## Service (Component) Context -Each service that makes up AppStudio is further explained in its own document. +Each service that makes up Konflux is further explained in its own document. - [Hybrid Application Service](./hybrid-application-service.md) - A workflow system that manages the definition of the users' Application and Components. diff --git a/architecture/integration-service.md b/architecture/integration-service.md index ce211b3d..dad4d2f3 100644 --- a/architecture/integration-service.md +++ b/architecture/integration-service.md @@ -18,7 +18,7 @@ The Integration service uses the pipeline, snapshot, and environment controllers ### High Level Workflow - When a build pipeline completes, Integration service creates a Snapshot CR representing a new collection of components that should be tested together. -- When Integration Service sees a new Snapshot CR (created either by itself or by a user), it coordinates deployment of the application for testing. It does this by creating new “ephemeral” AppStudio Environment CRs which trigger the GitOps Service to provision the ephemeral test environment. +- When Integration Service sees a new Snapshot CR (created either by itself or by a user), it coordinates deployment of the application for testing. It does this by creating new “ephemeral” Konflux Environment CRs which trigger the GitOps Service to provision the ephemeral test environment. - After the environment is ready and the application snapshot has been deployed to it, Integration Service tests and validates the application according to user-provided configuration. It does this by executing Tekton PipelineRuns against the ephemeral test Environment. - Finally, if any automatic ReleasePlans have been created by the user in the workspace, it will create a Release CR signalling intent to release the tested content, to be carried out by the [release-service](./release-service.md). @@ -132,7 +132,7 @@ Following the [annotation guidelines](https://docs.google.com/document/d/1gyXM3p “appstudio.openshift.io/component": “” “appstudio.openshift.io/application": “” ``` -The Integration service will copy the annotations and labels from the Build PipelineRun and append those to the Test PipelineRuns for traceability across the system per [Labels and Annotations for AppStudio pipelines](https://docs.google.com/document/d/1fJq4LDakLfcAPvOOoxxZNWJ_cuQ1ew9jfBjWa-fEGLE/edit#) and [AppStudio builds and tests PRs](https://docs.google.com/document/d/113XTplEWRM63aIzk7WwgLruUBu2O7xVy-Zd_U6yjYr0/edit#) +The Integration service will copy the annotations and labels from the Build PipelineRun and append those to the Test PipelineRuns for traceability across the system per [Labels and Annotations for Konflux pipelines](https://docs.google.com/document/d/1fJq4LDakLfcAPvOOoxxZNWJ_cuQ1ew9jfBjWa-fEGLE/edit#) and [Konflux builds and tests PRs](https://docs.google.com/document/d/113XTplEWRM63aIzk7WwgLruUBu2O7xVy-Zd_U6yjYr0/edit#) The "test.appstudio.openshift.io/optional" Label provides users an option whether the result of a pipelineRun created according to the IntegrationTestScenario will be taken into account when determining if the Snapshot has passed all required testing. In another word, the label is used to specify if an IntegrationTestScenario is allowed to fail. If the label is not defined in an IntegrationTestScenario, integration service will consider it as "false". ``` @@ -152,7 +152,7 @@ The Integration service will provide Tekton workspaces to the individual Pipelin #### Secrets -The Integration service needs secrets mounted so that the `Environment Provisioner` Task running in the workspace has the correct permissions to create AppStudio Application Environments resources within the Applications/Component’s namespace. +The Integration service needs secrets mounted so that the `Environment Provisioner` Task running in the workspace has the correct permissions to create Konflux Application Environments resources within the Applications/Component’s namespace. ## Detailed Workflow 1. Watch for Build PipelineRuns of `type: build` @@ -222,10 +222,10 @@ Integration service is getting specific information about the image that's being ## Appendix -- [AppStudio Promotion & Environment API](https://docs.google.com/document/d/14LaXAmQEW73kIr3a6TvPswT-zSdBsuaaxLF77HJ3gX4/edit#) +- [Konflux Promotion & Environment API](https://docs.google.com/document/d/14LaXAmQEW73kIr3a6TvPswT-zSdBsuaaxLF77HJ3gX4/edit#) - [v3 - Environment API draft: Component-scoped with native Snapshots](https://docs.google.com/document/d/1-_rWLgALd5pdSlqNNcQ5FSrD00fZb0l_exU-_FiL68o/edit#heading=h.vf66svd4o6xr) -- [AppStudio builds and tests PRs](https://docs.google.com/document/d/113XTplEWRM63aIzk7WwgLruUBu2O7xVy-Zd_U6yjYr0/edit#) -- [Labels and Annotations for AppStudio pipelines](https://docs.google.com/document/d/1fJq4LDakLfcAPvOOoxxZNWJ_cuQ1ew9jfBjWa-fEGLE/edit#) +- [Konflux builds and tests PRs](https://docs.google.com/document/d/113XTplEWRM63aIzk7WwgLruUBu2O7xVy-Zd_U6yjYr0/edit#) +- [Labels and Annotations for Konflux pipelines](https://docs.google.com/document/d/1fJq4LDakLfcAPvOOoxxZNWJ_cuQ1ew9jfBjWa-fEGLE/edit#) - [Implementation design and rules for pipeline customization](https://docs.google.com/document/d/1PXkpFHKrnq1Sg1giTgeXdYzNVf7CTRgwowykr7YPM2I/edit#) diff --git a/architecture/internal-services.md b/architecture/internal-services.md index 73c4ecba..03940d1a 100644 --- a/architecture/internal-services.md +++ b/architecture/internal-services.md @@ -20,7 +20,7 @@ The diagram below shows the interaction of the internal services controller and ## Terminology * **InternalRequest** - The custom resource that describes the internal service to trigger the internal job on. -* **Remote Cluster** - A **public**, AppStudio cluster residing outside a private network. +* **Remote Cluster** - A **public**, Konflux cluster residing outside a private network. * **Internal, Private Cluster** - A cluster that is not externally addressable but which has access to a private network. ## Resources diff --git a/architecture/jvm-build-service.md b/architecture/jvm-build-service.md index 11d306e1..63605ec1 100644 --- a/architecture/jvm-build-service.md +++ b/architecture/jvm-build-service.md @@ -14,7 +14,7 @@ JBS automates this process as much as possible, making it much less time-consumi ### Dependencies -JBS depends on Tekton, but is otherwise largely independent of the rest of AppStudio. Given the right configuration it can be deployed outside of AppStudio, which is mainly used for testing and development. +JBS depends on Tekton, but is otherwise largely independent of the rest of Konflux. Given the right configuration it can be deployed outside of Konflux, which is mainly used for testing and development. ## Architecture diff --git a/architecture/release-service.md b/architecture/release-service.md index e07a86f0..e1cbade1 100644 --- a/architecture/release-service.md +++ b/architecture/release-service.md @@ -26,7 +26,7 @@ The diagram below shows the interaction of the release service and other service The diagram below shows the flow of custom resources and the orchestration of pipelines by the release service. -![](../diagrams/release-service/hacbs-release-service-data-flow.jpg) +![](../diagrams/release-service/konflux-release-service-data-flow.jpg) ## Terminology diff --git a/diagrams/index.md b/diagrams/index.md index 38636750..b149888a 100644 --- a/diagrams/index.md +++ b/diagrams/index.md @@ -2,15 +2,15 @@ ## System Context -The diagram below shows the interaction of the AppStudio with other systems and environments. +The diagram below shows the interaction of the Konflux with other systems and environments. ## Application Context -![](../diagrams/appstudio.drawio.svg) +![](../diagrams/konflux.drawio.svg) ## Workspace Layout -![](../diagrams/appstudio-workspace-layout.drawio.svg) +![](../diagrams/konflux-workspace-layout.drawio.svg) ## Personal Data diff --git a/diagrams/appstudio-workspace-layout.drawio.svg b/diagrams/konflux-workspace-layout.drawio.svg similarity index 99% rename from diagrams/appstudio-workspace-layout.drawio.svg rename to diagrams/konflux-workspace-layout.drawio.svg index 9980b8ff..187319a6 100644 --- a/diagrams/appstudio-workspace-layout.drawio.svg +++ b/diagrams/konflux-workspace-layout.drawio.svg @@ -443,7 +443,7 @@ xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 228px; height: 1px; padding-top: 970px; margin-left: 691px;">
- AppStudio + Konflux
Build Service
@@ -453,7 +453,7 @@
- AppStudio... + Konflux... @@ -518,7 +518,7 @@ xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 228px; height: 1px; padding-top: 1040px; margin-left: 691px;">
- HACBS + Konflux
Integration Service @@ -526,7 +526,7 @@
- HACBS... + Konflux... @@ -1075,14 +1075,14 @@ xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 228px; height: 1px; padding-top: 1110px; margin-left: 691px;">
- HACBS + Konflux
Release Service
- HACBS... + Konflux... @@ -1109,14 +1109,14 @@
-
HACBS +
Konflux
JVM Build Service
- HACBS... + Konflux... diff --git a/diagrams/appstudio.drawio.svg b/diagrams/konflux.drawio.svg similarity index 100% rename from diagrams/appstudio.drawio.svg rename to diagrams/konflux.drawio.svg diff --git a/diagrams/personal-data.drawio.svg b/diagrams/personal-data.drawio.svg index fc72a734..2daeb005 100644 --- a/diagrams/personal-data.drawio.svg +++ b/diagrams/personal-data.drawio.svg @@ -1,4 +1,4 @@ -
GitHub
GitOps repositories for User's apps









GitHub...

Bring Your Own Compute
Owned and managed by User












Bring Your Own Compute...
Kubernetes cluster







Kubernetes cluster...
Control Plane (Dev Sandbox)

















































Control Plane (Dev Sandbox)...
Host Cluser




















Host Cluser...
Member Cluster











































Member Cluster...
Registration Service
Registration Ser...
Proxy
Proxy
Namespaces
Namespaces

Workspace "XYZ" namespace
Workspace "XYZ" namespace
Environment CR: "dev"
Environment CR: "dev"
Environment CR: "stage"
Environment CR: "stage"
Environment CR: "prod"
Environment CR: "prod"
ApplicationComponent CR:
"my-cool-app"
ApplicationComponent CR:...
ApplicationComponent CR:
"my-even-cooler-app"
ApplicationComponent CR:...
AppStudio
Build Service
AppStudio...
Pushes
Pushes
HAS Controller
HAS Controller
Manages
Manages
HACBS
Integration Service
HACBS...
Built-in Compute
Multi-tenant shared clusters
Owned and managed by Red Hat














Built-in Compute...

OSD cluster










OSD cluster...
Pulls
Pulls
Namespace: xyz-workspace-dev
Deployment: my-cool-app
Namespace: xyz-workspace-devDep...
Pulls
Pulls
Namespace: xyz-workspace-stage
Deployment: my-cool-app
Namespace: xyz-workspace-stageD...

Pipeline Service Compute
Owned and managed by Pipeline Service Team













Pipeline Service Compute...

OSD cluster









OSD cluster...
Pushes
Pushes
Namespace: xyz-workspace
PipelineRun CR: my-cool-app-build
Namespace: xyz-workspacePipelineRu...
Pipelines Operator
Pipelines Operator
Manages
Manages
HAC
HAC
Quay.io
Image repositories for User's apps









Quay.io...
Manages
Manages
Manages
Manages
Manages
Manages
Pulls
Pulls
ArgoCD
ArgoCD
Repo: github.com/redhat-appstudio-appdata/my-cool-app
Repo: github.com/redhat-appstudio-appd...
GitOps Controller
GitOps Controller
Pulls
Pulls
Namespace: xyz-workspace-prod
Deployment: my-cool-app
Namespace: xyz-workspace-prodDep...
Manages
Manages
HACBS
Release Service
HACBS...
Manages
Manages
HACBS
JVM Build Service
HACBS...
SPI Controller
SPI Controller
Defines
Defines
Defines
Defines
Defines
Defines
Tekton Results
Tekton Results
AWS RDS
AWS RDS
Red Hat SSO
Red Hat SSO
SSO data
SSO data
SSO data: Username, user ID, UUID
SSO data:...
user ID in workspace names
user ID in...
Amazon SNS
Amazon SNS
Eloqua
Eloqua
Hashicorp Vault (internal deployment)
Hashicorp Vault (...
Amazon CloudWatch
Amazon CloudWatch
Splunk
Splunk
Log archives
Log archiv...
AWS S3
AWS S3
Cluster logs from all clusters go to CloudWatch and Splunk. These contain username and IP addresses.
Cluster logs from...
User Credentials (OAUTH dance, or self-entered)
User Credentials (OAUTH...
Account management email messages
Account ma...
SMS message
SMS message
User-entered phone number (stored as a hash after SMS verification); workspace invitations (name, email address)
User-entered phone number...
User-provided GitHub repo paths contain usernames; stored in ApplicationComponent CRs and used by various controllers.
User-provided GitHub repo paths contain u...Text is not SVG - cannot display \ No newline at end of file +
GitHub
GitOps repositories for User's apps









GitHub...

Bring Your Own Compute
Owned and managed by User












Bring Your Own Compute...
Kubernetes cluster







Kubernetes cluster...
Control Plane (Dev Sandbox)

















































Control Plane (Dev Sandbox)...
Host Cluser




















Host Cluser...
Member Cluster











































Member Cluster...
Registration Service
Registration Ser...
Proxy
Proxy
Namespaces
Namespaces

Workspace "XYZ" namespace
Workspace "XYZ" namespace
Environment CR: "dev"
Environment CR: "dev"
Environment CR: "stage"
Environment CR: "stage"
Environment CR: "prod"
Environment CR: "prod"
ApplicationComponent CR:
"my-cool-app"
ApplicationComponent CR:...
ApplicationComponent CR:
"my-even-cooler-app"
ApplicationComponent CR:...
Konflux
Build Service
Konflux...
Pushes
Pushes
HAS Controller
HAS Controller
Manages
Manages
Konflux
Integration Service
Konflux...
Built-in Compute
Multi-tenant shared clusters
Owned and managed by Red Hat














Built-in Compute...

OSD cluster










OSD cluster...
Pulls
Pulls
Namespace: xyz-workspace-dev
Deployment: my-cool-app
Namespace: xyz-workspace-devDep...
Pulls
Pulls
Namespace: xyz-workspace-stage
Deployment: my-cool-app
Namespace: xyz-workspace-stageD...

Pipeline Service Compute
Owned and managed by Pipeline Service Team













Pipeline Service Compute...

OSD cluster









OSD cluster...
Pushes
Pushes
Namespace: xyz-workspace
PipelineRun CR: my-cool-app-build
Namespace: xyz-workspacePipelineRu...
Pipelines Operator
Pipelines Operator
Manages
Manages
HAC
HAC
Quay.io
Image repositories for User's apps









Quay.io...
Manages
Manages
Manages
Manages
Manages
Manages
Pulls
Pulls
ArgoCD
ArgoCD
Repo: github.com/redhat-appstudio-appdata/my-cool-app
Repo: github.com/redhat-appstudio-appd...
GitOps Controller
GitOps Controller
Pulls
Pulls
Namespace: xyz-workspace-prod
Deployment: my-cool-app
Namespace: xyz-workspace-prodDep...
Manages
Manages
Konflux
Release Service
Konflux...
Manages
Manages
Konflux
JVM Build Service
Konflux...
SPI Controller
SPI Controller
Defines
Defines
Defines
Defines
Defines
Defines
Tekton Results
Tekton Results
AWS RDS
AWS RDS
Red Hat SSO
Red Hat SSO
SSO data
SSO data
SSO data: Username, user ID, UUID
SSO data:...
user ID in workspace names
user ID in...
Amazon SNS
Amazon SNS
Eloqua
Eloqua
Hashicorp Vault (internal deployment)
Hashicorp Vault (...
Amazon CloudWatch
Amazon CloudWatch
Splunk
Splunk
Log archives
Log archiv...
AWS S3
AWS S3
Cluster logs from all clusters go to CloudWatch and Splunk. These contain username and IP addresses.
Cluster logs from...
User Credentials (OAUTH dance, or self-entered)
User Credentials (OAUTH...
Account management email messages
Account ma...
SMS message
SMS message
User-entered phone number (stored as a hash after SMS verification); workspace invitations (name, email address)
User-entered phone number...
User-provided GitHub repo paths contain usernames; stored in ApplicationComponent CRs and used by various controllers.
User-provided GitHub repo paths contain u...Text is not SVG - cannot display \ No newline at end of file diff --git a/diagrams/release-service/hacbs-release-service-data-flow.jpg b/diagrams/release-service/konflux-release-service-data-flow.jpg similarity index 100% rename from diagrams/release-service/hacbs-release-service-data-flow.jpg rename to diagrams/release-service/konflux-release-service-data-flow.jpg diff --git a/ref/index.md b/ref/index.md index 7b0f7394..fc7e63a3 100644 --- a/ref/index.md +++ b/ref/index.md @@ -1,6 +1,6 @@ # API Reference -## AppStudio +## Konflux - [Application and Environment API](application-environment-api.md): Hybrid Application Service (HAS) provides an abstract way to define applications within the cloud. Also includes shared APIs for defining and managing environments. - [Service Provider](service-provider.md): Responsible for providing a service-provider-neutral way of obtaining authentication tokens so that tools accessing the service provider do not have to deal with the intricacies of getting the access tokens from the different service providers. diff --git a/tools/security-tools.MD b/tools/security-tools.MD index e844d09b..7d11ee43 100644 --- a/tools/security-tools.MD +++ b/tools/security-tools.MD @@ -1,6 +1,6 @@ # Security Guild recommended tools -This document lists the available tools that we researched for performing linting, Static Code Analysis, and vulnerability scanning on different platforms and languages. The goal is to introduce one of more of these tools into AppStudio for customers to use. +This document lists the available tools that we researched for performing linting, Static Code Analysis, and vulnerability scanning on different platforms and languages. The goal is to introduce one of more of these tools into Konflux for customers to use. From our discussions in the Secure Engineering Guild, our current position is that we would encourage teams to use the tools highlighted in this list for consistency. But if a team finds a different tool that's a better fit-for-purpose, that is also fine. The ProdSec org also supports some tools, and some tools will be integrated into our product over time (taking the responsibility of implementation off of our teams). Where we have a recommendation, it makes sense to follow it if it fits your team/product's needs. Per our discussions with ProdSec, we should not use tools that could potentially "phone home," or any that could otherwise expose information about embargoed vulnerabilities, unless they have previously approved our particular use of the tool. @@ -17,24 +17,24 @@ $ golangci-lint run ``` #### Docker -**hadolint** - https://github.com/hadolint/hadolint -_Note: In order to lint Bash code inside a Dockerfile, it uses Shellcheck internally._ - +**hadolint** - https://github.com/hadolint/hadolint +_Note: In order to lint Bash code inside a Dockerfile, it uses Shellcheck internally._ + ``` Usage: -$ hadolint Dockerfile -(or) +$ hadolint Dockerfile +(or) $ docker run --rm -i ghcr.io/hadolint/hadolint < Dockerfile ``` ### Vulnerability Scanners -**clair** - https://github.com/quay/clair -- quay.io uses Clair internally and the project is officially under them. +**clair** - https://github.com/quay/clair +- quay.io uses Clair internally and the project is officially under them. - Check these [docs](https://quay.github.io/clair/howto/deployment.html) to understand the deployment models Clair currently uses. - For teams using quay.io as their container image registry, we enjoy the benefit of these scans via their website. You can check the results under the vulnerabilites tab of an image. -_Note: [clair-in-ci](https://quay.io/repository/redhat-appstudio/clair-in-ci) is a feature which includes security scanning via clair. It is enabled by default for any Pipelines created in AppStudio. A Tekton Task is available that can be used to run clair in your own Pipelines [here](https://github.com/redhat-appstudio/build-definitions/tree/main/task/clair-scan/)._ +_Note: [clair-in-ci](https://quay.io/repository/redhat-appstudio/clair-in-ci) is a feature which includes security scanning via clair. It is enabled by default for any Pipelines created in Konflux. A Tekton Task is available that can be used to run clair in your own Pipelines [here](https://github.com/redhat-appstudio/build-definitions/tree/main/task/clair-scan/)._ ### SAST Tools @@ -44,12 +44,12 @@ _Note: [clair-in-ci](https://quay.io/repository/redhat-appstudio/clair-in-ci) is **synk** - https://github.com/snyk/cli -_Note: AppStudio uses synk to perform static analysis. A Tekton Task is available that can be used to run synk in your own Pipelines [here](https://github.com/redhat-appstudio/build-definitions/blob/main/task/sast-snyk-check)._ +_Note: Konflux uses synk to perform static analysis. A Tekton Task is available that can be used to run synk in your own Pipelines [here](https://github.com/redhat-appstudio/build-definitions/blob/main/task/sast-snyk-check)._ **checkov** - https://github.com/bridgecrewio/checkov - Checkov uses a common command line interface to manage and analyze infrastructure as code (IaC) scan results across platforms such as Terraform, CloudFormation, Kubernetes, Helm, ARM Templates and Serverless framework. ([source](https://www.checkov.io/)) -- As mentioned above, checkov covers most cloud platforms / tools including Kubernetes / OpenShift. It enforces a bunch of best practices to be followed for every platform. +- As mentioned above, checkov covers most cloud platforms / tools including Kubernetes / OpenShift. It enforces a bunch of best practices to be followed for every platform. - It also integrates well with [kustomize](https://www.checkov.io/7.Scan%20Examples/Kustomize.html) - we could simply scan a kustomize directory, and it would check everything within that. -[kube-score](https://github.com/zegl/kube-score), [kubesec](https://github.com/controlplaneio/kubesec), [kubeconform](https://github.com/yannh/kubeconform), [kubelinter](https://github.com/stackrox/kube-linter) were some other tools that were explored. Teams are welcome to experiment with these or other tools if none of the above mentioned tools in the doc meet your requirements. But as mentioned earlier, beware of any security implications of using a tool. Checking with the ProdSec team on the approval status is a good first step when considering a new tool. +[kube-score](https://github.com/zegl/kube-score), [kubesec](https://github.com/controlplaneio/kubesec), [kubeconform](https://github.com/yannh/kubeconform), [kubelinter](https://github.com/stackrox/kube-linter) were some other tools that were explored. Teams are welcome to experiment with these or other tools if none of the above mentioned tools in the doc meet your requirements. But as mentioned earlier, beware of any security implications of using a tool. Checking with the ProdSec team on the approval status is a good first step when considering a new tool.