OSSM-13581: Add ARCHITECTURE.md documenting high-level system design by jewertow · Pull Request #2035 · istio-ecosystem/sail-operator

jewertow · 2026-06-25T17:53:23Z

No description provided.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

codecov · 2026-06-25T18:08:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.81%. Comparing base (147fde9) to head (cc78f3f).
⚠️ Report is 46 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2035      +/-   ##
==========================================
+ Coverage   76.57%   76.81%   +0.23%     
==========================================
  Files          58       58              
  Lines        3181     3222      +41     
==========================================
+ Hits         2436     2475      +39     
- Misses        608      609       +1     
- Partials      137      138       +1

Flag	Coverage Δ
integration-tests	`69.53% <ø> (-0.76%)`	⬇️
unit-tests	`53.16% <ø> (+0.60%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

FilipB

This is great, it would be nice to have some automation which would keep this up to date.

FilipB · 2026-06-26T07:00:05Z

+sail-operator/
+├── api/                    # CRD type definitions
+│   ├── v1/                 # Stable API group (Istio, IstioRevision, IstioRevisionTag, IstioCNI)
+│   └── v1alpha1/           # Experimental API group (ZTunnel)


Ztunnel is already in v1 too

Good point, thanks! Done.

FilipB · 2026-06-26T07:04:26Z

+├── controllers/            # Kubernetes controller implementations
+│   ├── istio/              # Top-level Istio CR controller
+│   ├── istiorevision/      # Revision lifecycle via Helm charts
+│   ├── istiorevisiontag/   # Revision traffic routing


Revision traffic routing might be a bit confusing?

I totally agree. I changed the description to "Revision tag management".

FilipB · 2026-06-26T07:06:08Z

+├── enhancements/           # Sail Enhancement Proposals (SEPs)
+├── docs/                   # Documentation
+├── common/                 # Shared Makefile infrastructure (from istio/common-files)
+├── ossm/                   # OpenShift Service Mesh downstream code


Do we want to include this to upstream doc when the dir is not there?

Sorry... I started in midstream, and this is leftover from the previous source code. I removed it.

FilipB · 2026-06-26T07:06:52Z

+## Project Structure
+
+```
+sail-operator/


nit: maybe sort it alphabetically so it matches order visible in GH UI

I agree. Done.

FilipB · 2026-06-26T08:32:48Z

+Profile overlay (default, openshift, demo, ambient, etc.)
+        │
+        ▼
+Image digest injection (from config.properties)


Do we want to include this? I don't think an user can touch config.properties right?

Yes, users do not touch it, but the diagram is for an agent, so I think it's valuable information. Could we leave it as is?

Sounds good.

Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

mkolesnik · 2026-07-02T06:33:30Z

+```
+                          ┌─────────────────────────────────────────────┐
+                          │              Kubernetes API                 │
+                          └───────────────────┬─────────────────────────┘
+                                              │
+                          ┌───────────────────▼─────────────────────────┐
+                          │           Sail Operator (Manager)           │
+                          │                                             │
+                          │  ┌──────────┐  ┌───────────┐  ┌─────────┐  │
+                          │  │  Istio   │  │ IstioCNI  │  │ ZTunnel │  │
+                          │  │Controller│  │Controller │  │Controller│  │
+                          │  └────┬─────┘  └─────┬─────┘  └────┬────┘  │
+                          │       │              │              │       │
+                          │  ┌────▼─────────┐    │              │       │
+                          │  │IstioRevision │    │              │       │
+                          │  │  Controller  │    │              │       │
+                          │  └────┬─────────┘    │              │       │
+                          │       │              │              │       │
+                          │  ┌────▼──────────────▼──────────────▼────┐  │
+                          │  │          Helm ChartManager            │  │
+                          │  │  (install/upgrade embedded charts)    │  │
+                          │  └────┬─────────────────────────────────┘  │
+                          │       │                                     │
+                          └───────┼─────────────────────────────────────┘
+                                  │
+                          ┌───────▼─────────────────────────────────────┐
+                          │         Deployed Istio Components           │
+                          │  (istiod, CNI DaemonSet, ZTunnel, gateways) │
+                          └─────────────────────────────────────────────┘
+```


This is misaligned..
Also you can use something like mermaid to generate an svg diagram (supported by GH) - not just here

FilipB · 2026-07-02T08:12:09Z

LGTM, not approving so others can review too.

sridhargaddam · 2026-07-06T19:11:36Z

+Chart defaults (values.yaml from embedded chart)
+        │
+        ▼
+Profile overlay (default, openshift, demo, ambient, etc.)


The "Image digest injection" comes before "ApplyProfilesAndPlatform"
See

sail-operator/pkg/revision/values.go

Line 41 in f53307f

// apply image digests from configuration, if not already set by user

Also, there is an additional step where we apply the vendor specific defaults.

sail-operator/pkg/revision/values.go

Line 45 in f53307f

userValues, err := istiovalues.ApplyIstioVendorDefaults(version, userValues)

fjglira

it looks good to me, adding a hold label until comments from others reviewers are addressed

fjglira · 2026-09-17T11:39:45Z

Hey @jewertow can we check the latest comment to see if we can merge the PR

jewertow and others added 2 commits June 25, 2026 19:46

Add ARCHITECTURE.md documenting high-level system design

5aff33d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

Remove specific versions from ARCHITECTURE.md to avoid staleness

bac5f46

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

jewertow requested a review from a team as a code owner June 25, 2026 17:53

jewertow requested a review from fjglira June 25, 2026 17:53

istio-testing added the size/L label Jun 25, 2026

FilipB reviewed Jun 26, 2026

View reviewed changes

jewertow and others added 4 commits July 1, 2026 20:24

Include ZTunnel in stable APIs

a31325e

Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

Fix istiorevisiontag description

5715f7e

Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

Remove ossm from the project structure

fff17bd

Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

Sort project structure alphabetically in ARCHITECTURE.md

cc78f3f

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Jacek Ewertowski <jacek.ewertowski1@gmail.com>

jewertow requested a review from FilipB July 1, 2026 18:48

mkolesnik reviewed Jul 2, 2026

View reviewed changes

sridhargaddam reviewed Jul 6, 2026

View reviewed changes

fjglira added the do-not-merge/hold label Jul 9, 2026

fjglira approved these changes Jul 9, 2026

View reviewed changes

Conversation

jewertow commented Jun 25, 2026

Uh oh!

codecov Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

FilipB left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FilipB commented Jul 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fjglira left a comment

Choose a reason for hiding this comment

Uh oh!

fjglira commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Jun 25, 2026 •

edited

Loading