Merge pull request #20 from viccuad/cap-kubernetes

Extend unit tests and document kubernetes capability

internal/cel/library/kubernetes.go

@@ -11,12 +11,86 @@ import (
 	"github.com/kubewarden/policy-sdk-go/pkg/capabilities/kubernetes"
 )
 
-type kubernetesLib struct{}
-
+// Kubernetes returns a cel.EnvOption to configure CEL-namespaced Kubernetes
+// host-callback Kubewarden functions.
+//
+// # Kubernetes.ListResourcesByNamespace
+//
+// This CEL function returns all the Kubernetes resources in a specific Kubernetes namespace,
+// filtered via the options in ListResourcesByNamespaceRequest{}. See the Go
+// SDK for more information on ListResourcesByNamespaceRequest{}.
+// Usage in CEL:
+//
+// k8s.listResourcesByNamespace(ListResourcesByNamespaceRequest{Namespace: <string>}) ->
+//
+//	map(key, value) where:
+//	  key is a <string> "items"
+//	  value is a <list<object>> matching GroupVersionKind from "github.com/kubewarden/k8s-objects"
+//
+// Example:
+//
+//	 kw.k8s.listResourcesByNamespace(ListResourcesByNamespaceRequest{Namespace: 'default'}).items[0]
+//	 returns:
+//	{
+//	  Kind: "Pod",
+//	  Metadata: {
+//	    Name:      "nginx",
+//	    Namespace: "default",
+//	  },
+//	}
+//
+// # Kubernetes.ListAllResources
+//
+// This CEL function returns all the Kubernetes resources,
+// filtered via the options in ListAllResourcesRequest{}. See the Go
+// SDK for more information on ListAllResourcesRequest{}.
+// Usage in CEL:
+//
+//	k8s.listAllResources(ListAllResourcesRequest{Kind: <string>}) ->
+//	  map(key, value) where:
+//	  key is a <string> "items"
+//	  value is a <list<object>> matching GroupVersionKind from "github.com/kubewarden/k8s-objects"
+//
+// Example:
+//
+//	kw.k8s.listAllResources(listAllResourcesRequest{Kind: 'Pod'}).items[0]
+//	 returns:
+//	{
+//	  Kind: "Pod",
+//	  Metadata: {
+//	    Name:      "nginx",
+//	    Namespace: "default",
+//	  },
+//	}
+//
+// # Kubernetes.getResource
+//
+// This CEL function returns a specific Kubernetes resources,
+// selected via the options in getResourceRequest{}. See the Go
+// SDK for more information on getResourceRequest{}.
+// Usage in CEL:
+//
+//	k8s.getResource(getResourceRequest{Kind: <string>}) ->
+//	  <object> matching GroupVersionKind from "github.com/kubewarden/k8s-objects"
+//
+// Example:
+//
+// kw.k8s.getResource(getResourceRequest{Kind: 'Pod'})
+// returns:
+//
+//	{
+//	  Kind: "Pod",
+//	  Metadata: {
+//	    Name:      "nginx",
+//	    Namespace: "default",
+//	  },
+//	}
 func Kubernetes() cel.EnvOption {
 	return cel.Lib(kubernetesLib{})
 }
 
+type kubernetesLib struct{}
+
 // LibraryName implements the SingletonLibrary interface method.
 func (kubernetesLib) LibraryName() string {
 	return "kw.k8s"

internal/cel/library/kubernetes_test.go

@@ -1,6 +1,7 @@
 package library
 
 import (
+	"fmt"
 	"reflect"
 	"testing"
 
@@ -98,3 +99,49 @@ func TestKubernetes(t *testing.T) {
 		})
 	}
 }
+
+func TestKubernetesHostFailure(t *testing.T) {
+	tests := []struct {
+		name        string
+		expression  string
+		errorString string
+	}{
+		{
+			"kw.k8s.listAllResources host failure",
+			"kw.k8s.listAllResources(ListAllResourcesRequest{Kind: 'Pod'})",
+			"cannot list all Kubernetes resources: hostcallback error",
+		},
+		{
+			"kw.k8s.listResourcesByNamespace host failure",
+			"kw.k8s.listResourcesByNamespace(ListResourcesByNamespaceRequest{Namespace: 'default'})",
+			"cannot list Kubernetes resources by namespace: hostcallback error",
+		},
+		{
+			"kw.k8s.getResource host failure",
+			"kw.k8s.getResource(GetResourceRequest{Kind: 'Pod'}).metadata.name",
+			"cannot get Kubernetes resource: hostcallback error",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var err error
+
+			host.Client = capabilities.NewFailingMockWapcClient(fmt.Errorf("hostcallback error"))
+
+			env, err := cel.NewEnv(
+				Kubernetes(),
+			)
+			require.NoError(t, err)
+
+			ast, issues := env.Compile(test.expression)
+			require.Empty(t, issues)
+
+			prog, err := env.Program(ast)
+			require.NoError(t, err)
+
+			_, _, err = prog.Eval(map[string]interface{}{})
+			require.Error(t, err)
+			require.Equal(t, test.errorString, err.Error())
+		})
+	}
+}