Create IstioRevisionTag documentation

Signed-off-by: Daniel Grimm <[email protected]>

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"`

bundle/manifests/sailoperator.clusterserviceversion.yaml

@@ -34,7 +34,7 @@ metadata:
     capabilities: Seamless Upgrades
     categories: OpenShift Optional, Integration & Delivery, Networking, Security
     containerImage: quay.io/maistra-dev/sail-operator:0.2-latest
-    createdAt: "2024-12-06T08:47:58Z"
+    createdAt: "2024-12-06T13:21:29Z"
     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

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.

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.

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 <<EOF | kubectl apply -f-
+    apiVersion: sailoperator.io/v1alpha1
+    kind: Istio
+    metadata:
+      name: default
+    spec:
+      namespace: istio-system
+      updateStrategy:
+        type: RevisionBased
+        inactiveRevisionDeletionGracePeriodSeconds: 30
+      version: v1.22.5
+    ---
+    apiVersion: sailoperator.io/v1alpha1
+    kind: IstioRevisionTag
+    metadata:
+      name: default
+    spec:
+      targetRef:
+        kind: Istio
+        name: default
+    EOF
+    ```
+
+3. Confirm the control plane is installed and is using the desired version.
+
+    ```console
+    $ kubectl get istio
+    NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
+    default   1           1       1        default-v1-22-5   Healthy   v1.22.5   52s
+    ```
+    Note: `IN USE` field shows as 1, even though no workloads are using the control plane. This is because the `IstioRevisionTag` is referencing it.
+
+4. Inspect the `IstioRevisionTag`.
+
+    ```console
+    $ kubectl get istiorevisiontags
+    NAME      STATUS                    IN USE   REVISION          AGE
+    default   NotReferencedByAnything   False    default-v1-22-5   52s
+    ```
+
+5. Create `bookinfo` namespace and label it to mark it for injection.
+
+    ```bash
+    kubectl create namespace bookinfo
+    kubectl label namespace bookinfo istio-injection=enabled
+    ```
+
+6. Deploy bookinfo application.
+
+    ```bash
+    kubectl apply -n bookinfo -f https://raw.githubusercontent.com/istio/istio/release-1.22/samples/bookinfo/platform/kube/bookinfo.yaml
+    ```
+
+7. Review the `IstioRevisionTag` resource after application deployment.
+
+    ```console
+    $ kubectl get istiorevisiontag
+    NAME      STATUS    IN USE   REVISION          AGE
+    default   Healthy   True     default-v1-22-5   2m46s
+    ```
+    Note: `IN USE` field shows 'True', as the tag is now referenced by both active workloads and the bookinfo namespace.
+
+8. Confirm that the proxy version matches the control plane version.
+
+    ```bash
+    istioctl proxy-status 
+    ```
+    The column `VERSION` should match the control plane version.
+
+9. Update the control plane to a new version.
+
+    ```bash
+    kubectl patch istio default -n istio-system --type='merge' -p '{"spec":{"version":"v1.23.2"}}'
+    ```
+
+10. Verify the `Istio`, `IstioRevision` and `IstioRevisionTag` resources. There will be a new revision created with the new version.
+
+    ```console
+    $ 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
+    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   True    v1.23.2   66s
+
+    $ kubectl get istiorevisiontag
+    NAME      STATUS    IN USE   REVISION          AGE
+    default   Healthy   True     default-v1-23-2   10m44s
+    ```
+    Now, both our IstioRevisions and the IstioRevisionTag are considered in use. The old revision default-v1-22-5 because it is being used by proxies, the new revision default-v1-23-2 because it is referenced by the tag, and lastly the tag because it is referenced by the bookinfo namespace.
+
+11. Confirm there are two control plane pods running, one for each revision.
+
+    ```console
+    $ kubectl get pods -n istio-system
+    NAME                                      READY   STATUS    RESTARTS   AGE
+    istiod-default-v1-22-5-c98fd9675-r7bfw    1/1     Running   0          10m
+    istiod-default-v1-23-2-7495cdc7bf-v8t4g   1/1     Running   0          113s
+    ```
+
+12. Confirm the proxy sidecar version remains the same:
+
+    ```bash
+    istioctl proxy-status 
+    ```
+    The column `VERSION` should still match the old control plane version.
+
+13. Restart all the Deployments in the `bookinfo` namespace.
+
+    ```bash
+    kubectl rollout restart deployment -n bookinfo
+    ```
+
+14. Confirm the new version is used in the sidecars.
+
+    ```bash
+    istioctl proxy-status 
+    ```
+    The column `VERSION` should match the updated control plane version.
+
+16. Confirm the deletion of the old control plane and IstioRevision.
 
     ```console
     $ kubectl get pods -n istio-system

docs/api-reference/sailoperator.io.md

@@ -885,7 +885,7 @@ _Appears in:_
 
 
 
-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.
 
 
 
@@ -969,7 +969,7 @@ _Appears in:_
 
 
 
-IstioRevisionList contains a list of IstioRevision
+IstioRevisionTagList contains a list of IstioRevisionTags
 
 
 
@@ -1025,7 +1025,7 @@ _Appears in:_
 
 
 
-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.