diff --git a/README.md b/README.md index 2c91c5286..f13e0df58 100644 --- a/README.md +++ b/README.md @@ -13,25 +13,27 @@ The Sail Operator manages the lifecycle of your [Istio](https://istio.io) contro We have a weekly call every Thursday at 4PM CET / 10AM EST to discuss current progress and future plans. To add it to your Google Calendar, you can [subscribe to the Sail Operator calendar](https://calendar.google.com/calendar/u/0?cid=MDRhNzBkZjUwNmI5ZjFlMTAyYmUzZDhiZTFlNDA3ZjRlMjcwZjAzNmY4NDFkZTA1MmYzYzczYjk3OTU4ZGI2MUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t). ## User Documentation + This document aims to provide an overview of the project and some information for contributors. For information on how to use the operator, take a look at the [User Documentation](docs/README.adoc). ## Table of Contents - [How it works](#how-it-works) - [Getting Started](#getting-started) - - [Deploying the operator from source](#deploying-the-operator-from-source) - - [Deploying the operator by using Helm charts](#deploying-the-operator-by-using-helm-charts) - - [Deploying the Istio Control Plane](#deploying-the-istio-control-plane) - - [Undeploying the operator](#undeploying-the-operator) + - [Deploying the operator from source](#deploying-the-operator-from-source) + - [Deploying the operator by using Helm charts](#deploying-the-operator-by-using-helm-charts) + - [Deploying the Istio Control Plane](#deploying-the-istio-control-plane) + - [Undeploying the operator](#undeploying-the-operator) - [Development](#development) - - [Repository Setup](#repository-setup) - - [Test It Out](#test-it-out) - - [Modifying the API definitions](#modifying-the-api-definitions) - - [Writing Tests](#writing-tests) - - [Integration Tests](#integration-tests) - - [End-to-End Tests](#end-to-end-tests) - - [Vendor-specific changes](#vendor-specific-changes) - - [Developing on macOS](#developing-on-macos) + - [Repository Setup](#repository-setup) + - [Test It Out](#test-it-out) + - [Modifying the API definitions](#modifying-the-api-definitions) + - [Writing Tests](#writing-tests) + - [Integration Tests](#integration-tests) + - [End-to-End Tests](#end-to-end-tests) + - [Vendor-specific changes](#vendor-specific-changes) + - [Developing on macOS](#developing-on-macos) + - [Synchronization with Istio](#synchronization-with-istio) - [Release process](#release-process) - [Versioning and Support Policy](#versioning-and-support-policy) - [Community Support and Contributing](#community-support-and-contributing) @@ -85,7 +87,7 @@ spec: meshConfig: trustDomain: example.com trustDomainAliases: - - example.net + - example.net ``` ## Getting Started @@ -210,6 +212,7 @@ kubectl get ztunnel default For other deployment options, refer to the [docs](docs) directory. ### Undeploying the operator + Undeploy the operator from the cluster: ```sh @@ -305,6 +308,10 @@ As you might know, the Sail Operator project serves as the community upstream fo There are some considerations that you need to take into account while trying to develop, debug and work on macOS and specially if you are using Podman instead on Docker. Please take a look into this [documentation](/docs/macos/develop-on-macos.adoc) for macOS specifics. +### Synchronization with Istio + +This repo uses a few different workflows to stay in sync with [Istio](github.com/istio/istio). See [SYNC](./SYNC.md) for more detail. + #### versions.yaml The name of the versions.yaml file can be overwritten using the VERSIONS_YAML_FILE environment variable. This way, downstream vendors can point to a custom list of supported versions. Note that this file should be located in the `pkg/istioversion` directory, with the default value being `versions.yaml`. @@ -335,9 +342,11 @@ When running multiple Istio components (control plane, IstioCNI, ZTunnel), each > The first stable 1.0 release did not follow this versioning strategy but subsequent releases will. ## Community Support and Contributing + Please refer to the [CONTRIBUTING-SAIL-PROJECT.md](CONTRIBUTING.md) file for more information on how to contribute to the Sail Operator project. This file contains all the information you need to get started with contributing to the project. ## AI Agents for Development + If you're using AI coding assistants like Claude, GitHub Copilot, or Cursor, check out our [AI Agents Guide](docs/ai/ai-agents-guide.adoc) for information on how to configure these tools to understand Sail Operator patterns and best practices. ## Sail Enhancement Proposal @@ -347,6 +356,7 @@ SEP documents are used to propose and discuss non-trivial features or epics and SEP documents are stored in the [enhancements](enhancements) directory of the Sail Operator repository in Markdown format. If you want to create a SEP, be sure to check out the [SEP template](enhancements/SEP0-template.md). ## Issue management + Please refer to the [ISSUE-MANAGEMENT.md](ISSUE-MANAGEMENT.md) file for more information on how to report bugs and feature requests to the Sail Operator team. If you found a bug in Istio, please refer to the [Istio GitHub repository](BUGS-AND-FEATURE-REQUESTS.md) diff --git a/SYNC.md b/SYNC.md new file mode 100644 index 000000000..a8b333948 --- /dev/null +++ b/SYNC.md @@ -0,0 +1,121 @@ +# Sync Jobs + +This document describes the automated workflows that keep the Sail Operator in sync with upstream Istio and its dependencies. + +## Overview + +The Sail Operator uses several scheduled GitHub Actions workflows to track upstream Istio releases, update Go dependencies, manage end-of-life versions, and publish operator images. All automated PRs are created by the [Istio Automator](https://github.com/istio/test-infra/tree/master/tools/automator) tool running inside the `registry.istio.io/testing/build-tools` container. + +```mermaid +flowchart TB + subgraph upstream["Upstream Sources"] + istio_repo["istio/istio
(releases + source)"] + eol_api["endoflife.date API"] + tools_repos["Tool repos
(operator-sdk, Helm,
controller-runtime, etc.)"] + gw_api["kubernetes-sigs/
gateway-api"] + end + + subgraph gha["GitHub Actions (istio-ecosystem/sail-operator)"] + update_deps["Update Dependencies
(daily)"] + update_eol["Update EOL Versions
(daily)"] + nightly["Nightly Build
(daily)"] + vtb["Versions-Triggered Build
(on versions.yaml change)"] + clean["Clean Nightlies
(daily)"] + end + + subgraph artifacts["Published Artifacts"] + quay["quay.io
operator images"] + operatorhub["OpenShift
OperatorHub"] + end + + istio_repo --> update_deps + tools_repos --> update_deps + gw_api --> update_deps + eol_api --> update_eol + + update_deps -->|"updates versions.yaml"| vtb + vtb --> quay + nightly --> quay + nightly --> operatorhub + clean --> operatorhub +``` + +## Workflows + +### 1. Update Dependencies + +The primary sync job. It runs against `main` and each active release branch (`release-1.28`, `release-1.29`, `release-1.30`), creating separate PRs for each. PRs are labeled `auto-merge` and are merged automatically by `istio-testing` once CI passes. If a PR fails due to a merge conflict or test failure, manual intervention is required to resolve the issue before it can merge. + +**Workflow:** [update-deps.yaml](.github/workflows/update-deps.yaml) + +**Schedule:** Daily + +**Example PR:** [#1899](https://github.com/istio-ecosystem/sail-operator/pull/1899) + +**What it updates:** + +| Category | Details | +| --- | --- | +| **Istio Go modules** | `istio.io/istio` and `istio.io/client-go` pulled from the upstream branch (`master` for main, release branch for release branches). Skipped on release branches (`TOOLS_ONLY=true`). | +| **Istio versions** | Runs `make update-istio` (via `hack/update-istio.sh`) to detect new stable Istio releases and pre-release builds, adding them to `pkg/istioversion/versions.yaml`. Skipped on release branches. | +| **Istio sample manifests** | Downloads latest `helloworld`, `httpbin`, `sleep`, and `tcp-echo` samples from the upstream Istio repo into `tests/e2e/samples/`. These samples are used in e2e testing and by downloading them to the repo ahead of time we avoid having Github as a failure point for the tests. | +| **Tool versions** | Updates operator-sdk, Helm, controller-tools, controller-runtime, opm, OLM, gitleaks, runme, misspell, and KIND node image to their latest releases. On release branches, updates are pinned to the current minor version (patch-only). | +| **Gateway API CRDs** | Downloads the latest `experimental-install.yaml` from `kubernetes-sigs/gateway-api`. The Gateway API CRDs are used in e2e testing and by downloading them to the repo ahead of time we avoid having Github as a failure point for the tests. | +| **Istio build-tools image** | Updates the container image tag used by the `update-deps` and `update-eol-versions` workflows themselves. | +| **Documentation** | Runs `hack/update-istio-in-docs.sh` to update Istio version variables in `.adoc` files under `docs/`. | +| **Common files** | Runs `make update-common` to sync shared build scripts and tooling from `istio/common-files`. | + +After all updates, the script runs `make gen` to regenerate CRDs, manifests, and generated code. + +**Branch behavior:** + +- **Main**: Full update including Istio modules, new Istio versions, tools, and samples. +- **Release branches**: Tools-only updates with versions pinned to the current minor (`PIN_MINOR=true`, `TOOLS_ONLY=true`). No new Istio versions are added and Istio Go modules are not updated. + +### 2. Update Istio Versions + +Called by the update-deps workflow (not a standalone workflow), this script performs two types of Istio version tracking: + +- **Stable releases:** Queries the GitHub releases API for `istio/istio`, compares against versions in `versions.yaml`, and adds new patch releases when found. Updates the `vX.Y-latest` alias to point to the newest patch. +- **Pre-release (dev) builds:** Checks the upstream branch for new commits, waits for build artifacts to appear on GCS (`istio-build/dev/`), and updates the dev version entry with the new commit hash, version string, and chart URLs. Updates the `master` alias accordingly. + +### 3. Update EOL Versions + +Marks Istio versions as end-of-life when they are no longer supported upstream. Unlike update-deps, these PRs are **not** auto-merged and require manual review. + +**Workflow:** [update-eol-versions.yaml](.github/workflows/update-eol-versions.yaml) + +**Schedule:** Daily + +**Example PR:** [#1821](https://github.com/istio-ecosystem/sail-operator/pull/1821) + +### 4. Versions-Triggered Build + +This workflow fires whenever the versions file changes on `main` (typically from a merged update-deps PR). It builds and pushes a new operator image to `quay.io` using `make docker-buildx`, ensuring a fresh image is available immediately after version updates land. + +**Workflow:** [versions-triggered-build.yaml](.github/workflows/versions-triggered-build.yaml) + +**Trigger:** Push to `main` that modifies `pkg/istioversion/versions.yaml` + +### 5. Nightly Image Build + +Builds and publishes a nightly operator image to + +1. [quay.io](https://quay.io/repository/sail-dev/sail-operator) +2. [OpenShift OperatorHub](https://github.com/redhat-openshift-ecosystem/community-operators-prod/tree/main/operators/sailoperator) + +**Workflow:** [nightly-images.yaml](.github/workflows/nightly-images.yaml) + +**Schedule:** Daily + +**Example PR:** [community-operators-prod#9564](https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/9564) + +### 6. Clean Nightly Images + +Removes nightly OLM bundle releases older than 2 weeks from the [community-operators-prod](https://github.com/redhat-openshift-ecosystem/community-operators-prod/tree/main/operators/sailoperator) repo to avoid unbounded growth of nightly entries. + +**Workflow:** [clean-nightly-images.yaml](.github/workflows/clean-nightly-images.yaml) + +**Schedule:** Daily + +**Example PR:** [community-operators-prod#9401](https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/9401)