Merge branch 'liqotech:master' into unpeering_force

Author: giuliafalaschi

docs/conf.py

@@ -167,6 +167,33 @@ def generate_version() -> str:
         version = x.json()['tag_name']
     return version
 
+def generate_argocd_manifest() -> str:
+    return f"""```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: liqo-app
+  namespace: argocd
+spec:
+  project: default # Place here your project name
+  source:
+    chart: liqo
+    repoURL: https://helm.liqo.io/
+    targetRevision: {generate_version()}
+    helm:
+      releaseName: liqo
+      values: |
+        HERE_YOUR_VALUES_FILE
+  destination:
+    server: "https://kubernetes.default.svc" # Place here your destination cluster
+    namespace: liqo
+  syncPolicy:
+    syncOptions:
+      - CreateNamespace=true
+      - ServerSideApply=true
+```
+"""
+
 # generate_link_to_repo generates a link to the repository for the given file, according to the current version of the documentation.
 def generate_link_to_repo(text: str, file_path: str) -> str:
     version = generate_version()
@@ -237,6 +264,7 @@ def generate_liqoctl_version_warning() -> str:
 html_context = {
     'generate_clone_example': generate_clone_example,
     'generate_clone_example_tf': generate_clone_example_tf,
+    'generate_argocd_manifest': generate_argocd_manifest,
     'generate_liqoctl_install': generate_liqoctl_install,
     'generate_link_to_repo': generate_link_to_repo,
     'generate_helm_install': generate_helm_install,

docs/installation/install.md

@@ -543,26 +543,72 @@ liqoctl info --get network.podcidr
 
 ## ArgoCD
 
-### Annotations
+[ArgoCD](https://argo-cd.readthedocs.io/en/stable/) is a GitOps continuous delivery tool designed for Kubernetes.
+**Liqo supports installation and configuration with ArgoCD** via a declarative approach.
 
-When using ArgoCD to install Liqo, we recommend to set the following values:
+The following is an example of ArgoCD application installing the [Liqo Helm chart](#install-with-helm).
 
-```yaml
-common:
-  globalAnnotations:
-    argocd.argoproj.io/ignore-resource-updates: "true"
-    argocd.argoproj.io/sync-options: Delete=true
-    argocd.argoproj.io/sync-wave: 10
-    argocd.argoproj.io/compare-options: IgnoreExtraneous  
+{{ env.config.html_context.generate_argocd_manifest() }}
+
+In the previous example, you should define the values to configure your Liqo installation.
+You can generate a template of the `spec.source.helm.values` field via `liqoctl`:
+
+```bash
+liqoctl install <provider> [flags] --only-output-values
 ```
 
-This instruments Liqo to add some **argocd annotations** to the resources it creates.
-These annotations allow to:
+The previous command produces a pre-configured `values.yaml` file in the working directory, which you can customize and place in the `spec.source.helm.values` field of the ArgoCD application manifest.
+
+Check the [ArgoCD documentation](https://argo-cd.readthedocs.io/en/latest/user-guide/helm/) for further info about how to install a Helm Chart via ArgoCD.
+
+### Ensure clean Liqo removal with ArgoCD
+
+When Liqo is installed via ArgoCD, to ensure the clean removal of all the Liqo resources during the uninstallation process, some configurations need to be applied to the ArgoCD `Application` manifest.
+
+Depending on the version of ArgoCD you are running or the enabled [resource tracking strategy](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking), you should add the following to your `spec.source.helm.values` field:
+
+* When [ArgoCD tracks resources by label](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking/#tracking-kubernetes-resources-by-label) (default of **ArgoCD v2.X**)
+
+  ```yaml
+  common:
+    globalLabels:
+      app.kubernetes.io/instance: ARGOCD_APP_NAME
+    globalAnnotations:
+      argocd.argoproj.io/ignore-resource-updates: "true"
+      argocd.argoproj.io/sync-wave: 10
+      argocd.argoproj.io/compare-options: IgnoreExtraneous
+      argocd.argoproj.io/sync-options: Prune=false
+  ```
+
+  Where **ARGOCD_APP_NAME** should be replaced with the name of your ArgoCD application.
+
+* When [ArgoCD tracks resources by annotation](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking/#tracking-kubernetes-resources-by-annotation) (default of **ArgoCD >= v3.X**)
+
+  ```yaml
+  common:
+    globalAnnotations:
+      argocd.argoproj.io/tracking-id: ARGOCD_APP_NAME:${group}/${kind}:${namespace}/${name}
+      argocd.argoproj.io/ignore-resource-updates: "true"
+      argocd.argoproj.io/sync-wave: 10
+      argocd.argoproj.io/compare-options: IgnoreExtraneous
+      argocd.argoproj.io/sync-options: Prune=false
+  ```
+
+  Where **ARGOCD_APP_NAME** should be replaced with the name of your ArgoCD application.
+
+  The `${group}`, `${kind}`, `${namespace}` and `${name}` fields are replaced at runtime with the values of the object where annotation is applied.
+
+The above instruments Liqo to add some **argocd annotations and labels** to the resources it creates.
+Those fields and labels have the following meaning:
 
-* **argocd.argoproj.io/ignore-resource-updates: "true"**: This allows ArgoCD to ignore updates on resources created by other resources (like a *Pod* and its *Deployment*), which are managed by ArgoCD.
-* **argocd.argoproj.io/sync-options: Delete=true**: Allows ArgoCD to delete resources created by Liqo controllers.
-* **argocd.argoproj.io/sync-wave: 10**: This allows ArgoCD to wait resources deletion before deleting the Liqo controllers.
-* **argocd.argoproj.io/compare-options: IgnoreExtraneous**: This allows ArgoCD to ignore resources created by Liqo controllers.
+* labels:
+  * **app.kubernetes.io/instance: ARGOCD_APP_NAME**: when ArgoCD tracks resource by label, it tells ArgoCD to track the resource
+* annotations:
+  * **argocd.argoproj.io/tracking-id: ARGOCD_APP_NAME:${group}/${kind}:${namespace}/${name}**: when ArgoCD tracks resource by annotation, it tells ArgoCD to track the annotated resource
+  * **argocd.argoproj.io/ignore-resource-updates: "true"**: allows ArgoCD to ignore updates on resources created by other resources (like a *Pod* and its *Deployment*), which are managed by ArgoCD.
+  * **argocd.argoproj.io/sync-wave: 10**: allows ArgoCD to wait resources deletion before deleting the Liqo controllers.
+  * **argocd.argoproj.io/compare-options: IgnoreExtraneous**: allows ArgoCD to ignore resources created by Liqo controllers when the sync status is determined.
+  * **argocd.argoproj.io/sync-options: Prune=false**: prevents ArgoCD from deleting the resources managed by the Liqo controllers.
 
 ## CNIs
 

pkg/utils/resource/suite_test.go

@@ -0,0 +1,28 @@
+// Copyright 2019-2025 The Liqo Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package resource
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+func TestUtils(t *testing.T) {
+	defer GinkgoRecover()
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Test Resource Utils")
+}

pkg/utils/resource/wrapper_test.go

@@ -0,0 +1,120 @@
+// Copyright 2019-2025 The Liqo Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package resource
+
+import (
+	"context"
+	"fmt"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes/scheme"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/client/fake"
+)
+
+var _ = Describe("CreateOrUpdate Wrapper", func() {
+	var (
+		ctx context.Context
+		cl  client.Client
+		obj client.Object = &appsv1.Deployment{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:        "testname",
+				Namespace:   "testns",
+				Labels:      map[string]string{"existing": "label"},
+				Annotations: map[string]string{"existing": "annotation"},
+			},
+			Spec: appsv1.DeploymentSpec{
+				Replicas: func() *int32 { i := int32(1); return &i }(),
+				Selector: &metav1.LabelSelector{
+					MatchLabels: map[string]string{"app": "testapp"},
+				},
+				Template: corev1.PodTemplateSpec{
+					ObjectMeta: metav1.ObjectMeta{
+						Labels: map[string]string{"app": "testapp"},
+					},
+					Spec: corev1.PodSpec{
+						Containers: []corev1.Container{
+							{
+								Name:  "testcontainer",
+								Image: "testimage",
+							},
+						},
+					},
+				},
+			},
+		}
+	)
+
+	BeforeEach(func() {
+		ctx = context.TODO()
+		cl = fake.NewClientBuilder().WithScheme(scheme.Scheme).Build()
+	})
+
+	AfterEach(func() {
+		SetGlobalLabels(nil)
+		SetGlobalAnnotations(nil)
+	})
+
+	It("should inject global labels and annotations with variable replacement", func() {
+		SetGlobalLabels(map[string]string{
+			"app":           "liqo:${namespace}-${name}:${kind}-${group}",
+			"env":           "test",
+			"namespace-var": "${namespace}",
+		})
+		SetGlobalAnnotations(map[string]string{
+			"anno": "liqo:${namespace}-${name}:${kind}-${group}",
+		})
+
+		mutateFn := func() error {
+			// Simulate mutation logic
+			return nil
+		}
+
+		newObj := obj.DeepCopyObject().(client.Object)
+
+		_, err := CreateOrUpdate(ctx, cl, newObj, mutateFn)
+		Expect(err).ToNot(HaveOccurred())
+
+		groupKind, _, _ := cl.Scheme().ObjectKinds(newObj)
+		expectedReplacedString := fmt.Sprintf("liqo:%s-%s:%s-%s",
+			newObj.GetNamespace(),
+			newObj.GetName(),
+			groupKind[0].Kind,
+			groupKind[0].Group,
+		)
+
+		labels := newObj.GetLabels()
+		// Check that existing labels are preserved
+		for k, v := range obj.GetLabels() {
+			Expect(labels).To(HaveKeyWithValue(k, v))
+		}
+		Expect(labels).To(HaveKeyWithValue("app", expectedReplacedString))
+		Expect(labels).To(HaveKeyWithValue("env", "test"))
+		Expect(labels).To(HaveKeyWithValue("namespace-var", newObj.GetNamespace()))
+
+		annotations := newObj.GetAnnotations()
+		Expect(annotations).To(HaveKeyWithValue("anno", expectedReplacedString))
+	})
+
+	It("should not panic if no global labels/annotations are set", func() {
+		mutateFn := func() error { return nil }
+		_, err := CreateOrUpdate(ctx, cl, obj, mutateFn)
+		Expect(err).ToNot(HaveOccurred())
+	})
+})

pkg/utils/resource/wrappers.go

@@ -16,11 +16,17 @@ package resource
 
 import (
 	"context"
+	"fmt"
+	"strings"
 
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
 )
 
+var knownVariables = []string{"namespace", "name", "kind", "group"}
+
 // CreateOrUpdate is a wrapper around controllerutil.CreateOrUpdate that automatically adds global labels and annotations.
 // It takes the same parameters as controllerutil.CreateOrUpdate plus an optional list of additional labels to merge.
 func CreateOrUpdate(ctx context.Context, c client.Client, obj client.Object,
@@ -32,13 +38,19 @@ func CreateOrUpdate(ctx context.Context, c client.Client, obj client.Object,
 			return err
 		}
 
+		// Build the variables map from the object to replace variables in global labels and annotations.
+		variablesMap, err := buildVariablesMap(obj, c.Scheme())
+		if err != nil {
+			return fmt.Errorf("unable replace variable in global labels and annotations: %w", err)
+		}
+
 		// Then add global labels and any additional labels
 		if obj.GetLabels() == nil {
 			obj.SetLabels(make(map[string]string))
 		}
 		labels := obj.GetLabels()
 		for k, v := range GetGlobalLabels() {
-			labels[k] = v
+			labels[k] = replaceVariables(v, variablesMap)
 		}
 		obj.SetLabels(labels)
 
@@ -48,7 +60,7 @@ func CreateOrUpdate(ctx context.Context, c client.Client, obj client.Object,
 		}
 		annotations := obj.GetAnnotations()
 		for k, v := range GetGlobalAnnotations() {
-			annotations[k] = v
+			annotations[k] = replaceVariables(v, variablesMap)
 		}
 		obj.SetAnnotations(annotations)
 
@@ -57,3 +69,42 @@ func CreateOrUpdate(ctx context.Context, c client.Client, obj client.Object,
 
 	return controllerutil.CreateOrUpdate(ctx, c, obj, wrappedMutateFn)
 }
+
+func getVar(variable string, obj client.Object, kind schema.GroupVersionKind) string {
+	switch variable {
+	case "namespace":
+		return obj.GetNamespace()
+	case "name":
+		return obj.GetName()
+	case "kind":
+		return kind.Kind
+	case "group":
+		return kind.Group
+	}
+
+	return ""
+}
+
+func buildVariablesMap(obj client.Object, scheme *runtime.Scheme) (map[string]string, error) {
+	variables := make(map[string]string)
+	groupKind, _, err := scheme.ObjectKinds(obj)
+
+	if err != nil {
+		return nil, fmt.Errorf("unable to retrieve object kind: %w", err)
+	}
+
+	for _, variable := range knownVariables {
+		variables[variable] = getVar(variable, obj, groupKind[0])
+	}
+	return variables, nil
+}
+
+// replaceVariables replace the variables in the given string with the corresponding values in the object.
+func replaceVariables(s string, variablesMap map[string]string) string {
+	// Replace the variables in the string with the corresponding values in the object
+	for varName, varValue := range variablesMap {
+		s = strings.ReplaceAll(s, "${"+varName+"}", varValue)
+	}
+
+	return s
+}