From 91ee1df2c5a45624db42597cfbbf5bf656cf4484 Mon Sep 17 00:00:00 2001 From: Daniel Grimm Date: Wed, 4 Dec 2024 15:50:56 +0100 Subject: [PATCH] Create IstioRevisionTag documentation Signed-off-by: Daniel Grimm --- api/v1alpha1/istiorevisiontags_types.go | 6 +- .../sailoperator.clusterserviceversion.yaml | 12 +- .../sailoperator.io_istiorevisiontags.yaml | 10 +- .../sailoperator.io_istiorevisiontags.yaml | 10 +- chart/values.yaml | 2 +- docs/README.md | 206 +++++++++++++++++- docs/api-reference/sailoperator.io.md | 6 +- enhancements/SEP2-revision-tags.md | 4 +- 8 files changed, 229 insertions(+), 27 deletions(-) diff --git a/api/v1alpha1/istiorevisiontags_types.go b/api/v1alpha1/istiorevisiontags_types.go index 8d2788564..cb1a13ee7 100644 --- a/api/v1alpha1/istiorevisiontags_types.go +++ b/api/v1alpha1/istiorevisiontags_types.go @@ -31,7 +31,7 @@ type IstioRevisionTagSpec struct { TargetRef IstioRevisionTagTargetReference `json:"targetRef"` } -// IstioRevisionTagTargetReference can reference either Istio or IstioRevision objects in the cluster. +// IstioRevisionTagTargetReference can reference either Istio or IstioRevision objects in the cluster. In the case of referencing an Istio object, the Sail Operator will automatically update the reference to the Istio object's Active Revision. type IstioRevisionTagTargetReference struct { // Kind is the kind of the target resource. // @@ -181,7 +181,7 @@ const ( // +kubebuilder:printcolumn:name="Revision",type="string",JSONPath=".status.istioRevision",description="The IstioRevision this object is referencing." // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp",description="The age of the object" -// IstioRevisionTag references a Istio or IstioRevision object and serves as an alias for sidecar injection. +// IstioRevisionTag references an Istio or IstioRevision object and serves as an alias for sidecar injection. It can be used to manage stable revision tags without having to use istioctl or helm directly. See https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels for more information on the concept. type IstioRevisionTag struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -192,7 +192,7 @@ type IstioRevisionTag struct { // +kubebuilder:object:root=true -// IstioRevisionList contains a list of IstioRevision +// IstioRevisionTagList contains a list of IstioRevisionTags type IstioRevisionTagList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` diff --git a/bundle/manifests/sailoperator.clusterserviceversion.yaml b/bundle/manifests/sailoperator.clusterserviceversion.yaml index 5e80c45f0..8e3e03c36 100644 --- a/bundle/manifests/sailoperator.clusterserviceversion.yaml +++ b/bundle/manifests/sailoperator.clusterserviceversion.yaml @@ -33,8 +33,8 @@ metadata: ] capabilities: Seamless Upgrades categories: OpenShift Optional, Integration & Delivery, Networking, Security - containerImage: quay.io/maistra-dev/sail-operator:0.2-latest - createdAt: "2024-12-04T05:04:50Z" + containerImage: registry.gitlab.com/dgrimm/istio/sail-operator:dgn + createdAt: "2024-12-06T12:46:23Z" description: Experimental operator for installing Istio service mesh features.operators.openshift.io/cnf: "false" features.operators.openshift.io/cni: "true" @@ -225,8 +225,10 @@ spec: displayName: Helm Values path: values version: v1alpha1 - - description: IstioRevisionTag references a Istio or IstioRevision object and - serves as an alias for sidecar injection. + - description: IstioRevisionTag references an Istio or IstioRevision object and + serves as an alias for sidecar injection. It can be used to manage stable + revision tags without having to use istioctl or helm directly. See https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels + for more information on the concept. displayName: Istio Revision Tag kind: IstioRevisionTag name: istiorevisiontags.sailoperator.io @@ -659,7 +661,7 @@ spec: - --zap-log-level=info command: - /sail-operator - image: quay.io/maistra-dev/sail-operator:0.2-latest + image: registry.gitlab.com/dgrimm/istio/sail-operator:dgn livenessProbe: httpGet: path: /healthz diff --git a/bundle/manifests/sailoperator.io_istiorevisiontags.yaml b/bundle/manifests/sailoperator.io_istiorevisiontags.yaml index 90db7a5a2..7c84d6021 100644 --- a/bundle/manifests/sailoperator.io_istiorevisiontags.yaml +++ b/bundle/manifests/sailoperator.io_istiorevisiontags.yaml @@ -38,8 +38,10 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: IstioRevisionTag references a Istio or IstioRevision object and - serves as an alias for sidecar injection. + description: IstioRevisionTag references an Istio or IstioRevision object + and serves as an alias for sidecar injection. It can be used to manage stable + revision tags without having to use istioctl or helm directly. See https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels + for more information on the concept. properties: apiVersion: description: |- @@ -63,7 +65,9 @@ spec: properties: targetRef: description: IstioRevisionTagTargetReference can reference either - Istio or IstioRevision objects in the cluster. + Istio or IstioRevision objects in the cluster. In the case of referencing + an Istio object, the Sail Operator will automatically update the + reference to the Istio object's Active Revision. properties: kind: description: Kind is the kind of the target resource. diff --git a/chart/crds/sailoperator.io_istiorevisiontags.yaml b/chart/crds/sailoperator.io_istiorevisiontags.yaml index 3c4866eb1..07635ed4d 100644 --- a/chart/crds/sailoperator.io_istiorevisiontags.yaml +++ b/chart/crds/sailoperator.io_istiorevisiontags.yaml @@ -38,8 +38,10 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: IstioRevisionTag references a Istio or IstioRevision object and - serves as an alias for sidecar injection. + description: IstioRevisionTag references an Istio or IstioRevision object + and serves as an alias for sidecar injection. It can be used to manage stable + revision tags without having to use istioctl or helm directly. See https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels + for more information on the concept. properties: apiVersion: description: |- @@ -63,7 +65,9 @@ spec: properties: targetRef: description: IstioRevisionTagTargetReference can reference either - Istio or IstioRevision objects in the cluster. + Istio or IstioRevision objects in the cluster. In the case of referencing + an Istio object, the Sail Operator will automatically update the + reference to the Istio object's Active Revision. properties: kind: description: Kind is the kind of the target resource. diff --git a/chart/values.yaml b/chart/values.yaml index 86cd0327f..2422f38b5 100644 --- a/chart/values.yaml +++ b/chart/values.yaml @@ -48,7 +48,7 @@ csv: features.operators.openshift.io/cnf: "false" features.operators.openshift.io/cni: "true" features.operators.openshift.io/csi: "false" -image: quay.io/maistra-dev/sail-operator:0.2-latest +image: registry.gitlab.com/dgrimm/istio/sail-operator:dgn # We're commenting out the imagePullPolicy to use k8s defaults # imagePullPolicy: Always proxy: diff --git a/docs/README.md b/docs/README.md index e879a7dc6..e6193ef46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,10 @@ - [Concepts](#concepts) - [Istio resource](#istio-resource) - [IstioRevision resource](#istiorevision-resource) + - [IstioRevisionTag resource](#istiorevisiontag-resource) - [IstioCNI resource](#istiocni-resource) + - [Resource Status](#resource-status) + - [InUse Detection](#inuse-detection) - [API Reference documentation](#api-reference-documentation) - [Getting Started](#getting-started) - [Installation on OpenShift](#installation-on-openshift) @@ -96,6 +99,24 @@ The `IstioRevision` is the lowest-level API the Sail Operator provides, and it i You can think of the relationship between the `Istio` and `IstioRevision` resource as similar to the one between Kubernetes' `ReplicaSet` and `Pod`: a `ReplicaSet` can be created by users and results in the automatic creation of `Pods`, which will trigger the instantiation of your containers. Similarly, users create an `Istio` resource which instructs the operator to create a matching `IstioRevision`, which then in turn triggers the creation of the Istio control plane. To do that, the Sail Operator will copy all of your relevant configuration from the `Istio` resource to the `IstioRevision` resource. +### IstioRevisionTag resource +The `IstioRevisionTag` resource represents a *Stable Revision Tag*, which functions as an alias for Istio control plane revisions. With a stable tag `prod`, you can e.g. use the label `istio.io/rev=prod` to inject proxies into your workloads. When you perform an upgrade to a control plane with a new revision name, you can simply update your tag to point to the new revision, instead of having to re-label your workloads and namespaces. Also see the [Stable Revision Tags](https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels) section of Istio's [Canary Upgrades documentation](https://istio.io/latest/docs/setup/upgrade/canary/) for more details. + +In Istio, stable revision tags are usually created using `istioctl`, but if you're using the Sail Operator, you can use the `IstioRevisionTag` resource, which comes with an additional feature: instead of just being able to reference an `IstioRevision`, you can also reference an `Istio` resource. When you now update your control plane and the underlying `IstioRevision` changes, the Sail Operator will update your revision tag for you. You only need to restart your deployments to re-inject the new proxies. + +```yaml +apiVersion: sailoperator.io/v1alpha1 +kind: IstioRevisionTag +metadata: + name: default +spec: + targetRef: + kind: Istio # can be either Istio or IstioRevision + name: prod # the name of the Istio/IstioRevision resource +``` + +As you can see in the YAML above, `IstioRevisionTag` really only has one field in its spec: `targetRef`. With this field, you can reference an `Istio` or `IstioRevision` resource. So after deploying this, you will be able to use both the `istio.io/rev=default` and also `istio-injection=enabled` labels to inject proxies into your workloads. The `istio-injection` label can only be used for revisions named `default` - and this tag is called `default`. + ### IstioCNI resource The lifecycle of Istio's CNI plugin is managed separately when using Sail Operator. To install it, you can create an `IstioCNI` resource. The `IstioCNI` resource is a cluster-wide resource as it will install a `DaemonSet` that will be operating on all nodes of your cluster. You can select a version by setting the `spec.version` field, as you can see in the sample below. To update the CNI plugin, just change the `version` field to the version you want to install. Just like the `Istio` resource, it also has a `values` field that exposes all of the options provided in the `istio-cni` chart: @@ -114,6 +135,21 @@ spec: - kube-system ``` +### Resource Status +All of the Sail Operator API resources have a `status` subresource that contains information about their current state in the Kubernetes cluster. + +#### Conditions +All resources have a `Ready` condition which is set to `true` as soon as all child resource have been created and are deemed Ready by their respective controllers. To see additional conditions for each of the resources, check the [API reference documentation](https://github.com/istio-ecosystem/sail-operator/tree/main/docs/api-reference/sailoperator.io.md). + +#### InUse Detection +The Sail Operator uses InUse detection to determine whether an object is referenced. This is currently present on all resources apart from `IstioCNI`. On the `Istio` resource, it is a counter as it only aggregates the `InUse` conditions on its child `IstioRevisions`. + +|API |Type |Name|Description +|------------------|------------|----|------------------------------------------- +|Istio |Counter |Status.Revisions.InUse|Aggregates across all child `IstioRevisions`. +|IstioRevision |Condition |Status.Conditions[type="InUse']|Set to `true` if the `IstioRevision` is referenced by a namespace, workload or `IstioRevisionTag`. +|IstioRevisionTag |Condition |Status.Conditions[type="InUse']|Set to `true` if the `IstioRevisionTag` is referenced by a namespace or workload. + ## API Reference documentation The Sail Operator API reference documentation can be found [here](https://github.com/istio-ecosystem/sail-operator/tree/main/docs/api-reference/sailoperator.io.md). @@ -276,7 +312,7 @@ Steps: NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE default 1 1 0 default Healthy v1.22.5 23s ``` - Note: `IN USE` field shows as 0, as `Istio` is yet installed. + Note: `IN USE` field shows as 0, as `Istio` has just been installed and there are no workloads using it. 4. Create namespace `bookinfo` and deploy bookinfo application. @@ -294,7 +330,7 @@ Steps: NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE default 1 1 1 default Healthy v1.22.5 115s ``` - Note: `IN USE` field shows as 1, after application being deployed. + Note: `IN USE` field shows as 1, as the namespace label and the injected proxies reference the IstioRevision. 6. Perform the update of the control plane by changing the version in the Istio resource. @@ -364,7 +400,7 @@ Steps: NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE default 1 1 0 default-v1-22-5 Healthy v1.22.5 52s ``` - Note: `IN USE` field shows as 0, as `Istio` is yet installed. + Note: `IN USE` field shows as 0, as the control plane has just been installed and there are no workloads using it. 4. Get the `IstioRevision` name. @@ -413,11 +449,11 @@ Steps: 10. Verify the `Istio` and `IstioRevision` resources. There will be a new revision created with the new version. ```console - $ kubectl get istio -n istio-system + $ kubectl get istio NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE default 2 2 1 default-v1-23-2 Healthy v1.23.2 9m23s - $ kubectl get istiorevision -n istio-system + $ kubectl get istiorevision NAME TYPE READY STATUS IN USE VERSION AGE default-v1-22-5 Local True Healthy True v1.22.5 10m default-v1-23-2 Local True Healthy False v1.23.2 66s @@ -446,7 +482,7 @@ Steps: ``` The existing workload sidecars will continue to run and will remain connected to the old control plane instance. They will not be replaced with a new version until the pods are deleted and recreated. -14. Delete all the pods in the `bookinfo` namespace. +14. Restart all Deplyments in the `bookinfo` namespace. ```bash kubectl rollout restart deployment -n bookinfo @@ -459,7 +495,163 @@ Steps: ``` The column `VERSION` should match the updated control plane version. -16. Confirm the old control plane and revision deletion. +16. Confirm the deletion of the old control plane and IstioRevision. + + ```console + $ kubectl get pods -n istio-system + NAME READY STATUS RESTARTS AGE + istiod-default-v1-23-2-7495cdc7bf-v8t4g 1/1 Running 0 4m40s + + $ kubectl get istio + NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE + default 1 1 1 default-v1-23-2 Healthy v1.23.2 5m + + $ kubectl get istiorevision + NAME TYPE READY STATUS IN USE VERSION AGE + default-v1-23-2 Local True Healthy True v1.23.2 5m31s + ``` + The old `IstioRevision` resource and the old control plane will be deleted when the grace period specified in the `Istio` resource field `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds` expires. + +#### Example using the RevisionBased strategy and an IstioRevisionTag + +Prerequisites: +* Sail Operator is installed. +* `istioctl` is [installed](common/install-istioctl-tool.md). + +Steps: + +1. Create the `istio-system` namespace. + + ```bash + kubectl create namespace istio-system + ``` + +2. Create the `Istio` and `IstioRevisionTag` resources. + + ```bash + cat <