Skip to content

Commit c03f3de

Browse files
jgwestjgwest
committed
Add Environment API introduction doc
1 parent f03d178 commit c03f3de

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎docs/environment-api/introduction.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Konflux Environment API Quick Start
2+
3+
Written by Jonathan West (@jgwest) on February 1st, 2024.
4+
5+
## Konflux Environment API
6+
7+
The Red Hat product/project that this is attached to has had many names: AppStudio, RHTAP (Red Hat Trusted Application Pipeline), Konflux, and more.
8+
- In the linked resources, you will see many of these names (mostly AppStudio). They all refer to the same code, but a succession of project/product names.
9+
- For the purposes of this document, I will use 'Konflux', the latest name, as of this writing, February 2024.
10+
- However, the code/API referenced in this document has been deprecated, will no longer be used, and will be removed from the Konflux project.
11+
12+
For more information on the Environment API, see this [long, detailed document I wrote](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/environment-api/environment-api-proposal-v3.md) which details the final cross-organization agreement on how this API would work within Konflux.
13+
14+
## Big Picture
15+
16+
- You define an `Application`. (e.g. `bank-loan-app`)
17+
- **NOTE**: ZERO relation to Argo CD's Application custom resource (CR)/concept, put this out of your mind here in this context. They just happen share a name 😀
18+
- In this document, I'll use "Argo CD Application" when I specifically mean that.
19+
- You define `Components`, which are the child components of that Application (e.g. `frontend` in Node, `backend` in Java, `database` in PSQL)
20+
- You define `Environment`s, which are the K8s clusters that you wish to deploy that Application to (only K8s clusters are supported)
21+
- e.g. `test`, `staging`, `prod-eu`, `prod-us`
22+
- A DAG, e.g. dev -> test -> staging -> prod. Can be single or multiple children (for example, see last deployment in this example.)
23+
- ![Relationships between resources](Stages.png)
24+
25+
- You define a `Snapshot`, which is a particular version of your Application (and specifically, of its constituent Components). (e.g. `bank-loan-app-v2-(commit id)`)
26+
- The actual deployment of a Snapshot (specific version of an Application) to an Environment (specific k8s cluster) is performed via a `SnapshotEnvironmentBinding`
27+
- `SnapshotEnvironmentBinding` defines *(Application, Snapshot, Environment)* tuple
28+
- tuple: Application A, of version S, should be deployed to Environment E
29+
- Finally, `SnapshotEnvironmentBinding` is translated (reconciled, via K8s controller) into 1 or more Argo CD Application
30+
- Thus, all of these abstractions **ultimately boil down into Argo CD Application CRs** (custom resources) deploying to K8s clusters.
31+
32+
33+
34+
#### Relationships between the concepts:
35+
![Relationships between resources](Relationships.png)
36+
- `Binding` seen in the image is just a `SnapshotEnvironmentBinding` (using shorter name in the diagram)
37+
38+
39+
40+
## Central Konflux Concepts
41+
42+
All concepts mentioned have a corresponding CR (Kubernetes custom resource) of the same name. I use the two interchangeably, here.
43+
44+
#### Application
45+
- NOTE: This does not refer to an Argo CD Application, neither the CR nor the overall concept. It is entirely different.
46+
- When the API was defined I pushed to have them use a different, non-conflicting name, but was outvoted. 😀
47+
- When thinking of an Application in the context of this document, it is best to put the Argo CD Application concept/CR entirely out of your mind. They are not compatible or related in any way.
48+
- An `Application` is composed of 1 or more `Component`s
49+
- Applications are the atomic unit of deployment:
50+
- All Components of an Application are deployed together.
51+
- Components cannot be deployed outside of an Application.
52+
- Example: If you're a bank that gives loans to customers, your Application might be 'loan-app', and your components might be 'front-end', 'backend', 'database'.
53+
- Application and Component are both CRs.
54+
- [Application CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/application_types.go#L27)
55+
56+
#### Component
57+
- A `Component` is a single container running as part of an `Application`.
58+
- A Component has a single, mandatory Application as a parent.
59+
- Components are not shared between different Applications.
60+
- Each Component is a single container/container image.
61+
- Example: a bank might have a 'loan-app' Application, whose job is to provide bank loans. The Components of that Application might be:
62+
- Application 'loan-app'
63+
- Component 'frontend': React frontend, served into the browser via a lightweight HTTP server
64+
- Component 'backend': Java backend application
65+
- Component 'database': Postgresql image
66+
- Application and Component are both CRs.
67+
- [Component CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/component_types.go#L75)
68+
69+
70+
## Central Environment API Concepts, building on on top of Konflux concepts
71+
72+
All concepts mentioned have a corresponding CR of the same name. I use the two interchangeably, here.
73+
74+
#### Environment
75+
- One or more `Application`s can be deployed to an `Environment`.
76+
- An Environment is just a CR describing credentials for deploying to a target K8s cluster.
77+
- Example Environments: 'staging K8s cluster NA', 'production K8s cluster NA', 'staging K8s cluster EU', 'dev K8s cluster AU', etc.
78+
- Environments form a directed acyclic graph (DAG), which describes the order in which a new version of an Application is promoted between environments.
79+
- For example: dev NA -> test NA -> staging NA -> prod NA
80+
- See diagram above.
81+
- Example workflow:
82+
- Snapshot 'v2' of an Application would first be tested on Environment 'dev NA' (North America)
83+
- Once it passes some integration tests, Snapshot 'v2' would be promoted to run on Environment 'test NA'
84+
- Next, once successful, v2 would be promoted to 'staging NA' Environment.
85+
- And so on, dev -> test -> staging, along the DAG.
86+
- [API description](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/api.md#environment)
87+
- [Environment CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/environment_types.go#L24)
88+
89+
#### Snapshot
90+
- `Application`s are deployed to `Environments` via `Snapshot`s.
91+
- `Snapshot` represent a single, atomic version of an Application.
92+
- A Snapshot is only useful in the context of the Application it references: a Snapshot is not shared between multiple Applications.
93+
- A Snapshot is a set of container images, one for each component of an Application.
94+
- If an Application has 3 components, the Snapshot will have 3 container images.
95+
- Example Snapshot:
96+
- Application: loan-app
97+
- Component 'frontend': `quay.io/my-bank/loan-app-frontend:(version, git commit id, or date built, for example)`
98+
- Component 'backend': `quay.io/my-bank/loan-app-backend:(version, git commit id or date built, for example)`
99+
- Component 'database': `postgres:16.1`
100+
- Snapshots can be annotated with additional information, for example, whether or not the Snapshot passed integration tests (thus making the Snapshot ready for promotion to next child in the DAG).
101+
- This ensures a particular version of an Application has necessarily been tested with a particular set of constituent container images
102+
- Snapshots are not shared between different Applications. A Snapshot will have a single Application as a mandatory parent.
103+
- [API description](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/api.md#snapshot)
104+
- [Snapshot CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/snapshot_types.go#L25)
105+
106+
#### SnapshotEnvironmentBinding
107+
- This is the CR/concept that performs the actual deployment of everything described above. This is where the 'rubber meets the road'.
108+
- Behind the scenes, a single `SnapshotEnvironmentBinding` is reconciled into X corresponding Argo CD Applications, where X is the number of components of the Snapshot (Application).
109+
- Describes what Application/Snapshot (version) should be deployed to which Environment.
110+
- A SnapshotEnvironmentBinding (SEB) binds the following into a concrete deployment:
111+
- Application
112+
- Environment
113+
- Snapshot
114+
- tuple: Application A, of version S, should be deployed to Environment E
115+
116+
- Example SnapshotEnvironmentBinding:
117+
- We want to deploy (snapshot) 'v2' of our Application to 'staging' Environment, and 'v1' (snapshot) to 'production' Environment.
118+
- That would look like this:
119+
- SEB 'loan-app-staging':
120+
- application: loan-app
121+
- environment: staging
122+
- snapshot: v2
123+
- SEB 'loan-app-production':
124+
- application: loan-app
125+
- environment: production
126+
- snapshot: v1
127+
- In this example, the `SnapshotEnvironmentBinding` controller would reconcile the above into 6 Argo CD Applications:
128+
- 'loan-app-staging' would become:
129+
- Argo CD Application 'loan-app-staging-frontend': deploy v2 of 'frontend' component to staging
130+
- Argo CD Application 'loan-app-staging-backend': deploy v2 of 'backend' component to staging
131+
- Argo CD Application 'loan-app-staging-database': deploy v2 of 'database' component to staging
132+
- 'loan-app-prod' would become:
133+
- Argo CD Application 'loan-app-prod-frontend': deploy v1 of 'frontend' component to prod
134+
- Argo CD Application 'loan-app-prod-backend': deploy v1 of 'backend' component to prod
135+
- Argo CD Application 'loan-app-prod-database': deploy v1 of 'database' component to prod
136+
- [API description](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/api.md#snapshotenvironmentbinding)
137+
- [SnapshotEnvironmentBinding CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/snapshotenvironmentbinding_types.go#L33)
138+
139+
140+
#### PromotionRun
141+
- A single use CR which will promote a particular Application/Snapshot to a particular Environment
142+
- For example: I could use a `PromotionRun` to promote Snapshot 'loan-app-v2' from 'staging NA' to 'prod NA'
143+
- [API description](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/promotionrun_types.go#L24)
144+
- [PromotionRun CR code](https://github.com/redhat-appstudio/application-api/blob/18f545e48a03cbc6df71fb0468dac9aa66209c4c/api/v1alpha1/promotionrun_types.go#L24)
145+
146+
## Similarity to others: Kargo
147+
148+
From my cursory look at Kargo,the Konflux Environment API is somewhat similar to Kargo (probably because we're working in the same problem space), but with Kargo having more support for advanced use cases.
149+
150+
#### For example, API similarities:
151+
- Konflux `Environment` CR => Kargo `Stage` CR
152+
- Both are a DAG of K8s clusters, with promotion between, and customizable logic to trigger.
153+
- Konflux `Snapshot` CR => Kargo `Freight` CR
154+
- `Snapshot` is just a set of container images, while `Freight` is container images but can ALSO be other resources (e.g. helm chart versions)
155+
- Konflux `PromotionRun` CR => `Promotion` CR
156+
- Both are a CR which manually triggers a promotion between environments.
157+
- Custom Konflux controllers => `Warehouse` CR
158+
- Konflux has custom controllers that enable specific, supported workflows, implemented by other Konflux teams. These custom controllers produce `Snapshot`. In contrast, Konflux has the `Warehouse` concept, which generalizes the concept into a CR.
159+
- _(N/A)_ => `PromotionPolicy` CR / `Verification` CR
160+
- No specific equivalent in Konflux, but only because we never had specfic requirement requests, here. The Kargo concepts appear sound and would fit right in.
161+
162+
## External Resources
163+
164+
[Environment API CR descriptions and concepts](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/api.md#gitops-service-app-studio-environment-apis)
165+
166+
[Konflux Application/Component/Environment Go APIs live here](https://github.com/redhat-appstudio/application-api/tree/main/api/v1alpha1)
167+
168+
[K8s controllers that implement the Environment API live here](https://github.com/redhat-appstudio/managed-gitops/tree/main/appstudio-controller/controllers/appstudio.redhat.com)
169+
170+
See this [long, detailed document](https://github.com/redhat-appstudio/managed-gitops/blob/main/docs/environment-api/environment-api-proposal-v3.md) which details the final agreement on how this API would work within Konflux.

0 commit comments

Comments
 (0)