docs: updating the documentation for Extension Servers and adding an …

…example extension server (#3788)

* Updating the documentation for Extension Servers and adding an example
extension server.

Signed-off-by: Lior Okman <[email protected]>

* Make the docs linter happy

Signed-off-by: Lior Okman <[email protected]>

* Add license headers to every new source file, and make the yaml linter
ignore the extension-server chart

Signed-off-by: Lior Okman <[email protected]>

* Add the boilerplate license for generated files.

Signed-off-by: Lior Okman <[email protected]>

---------

Signed-off-by: Lior Okman <[email protected]>

examples/extension-server/.gitignore

@@ -0,0 +1 @@
+bin

examples/extension-server/Makefile

@@ -0,0 +1,30 @@
+tools.dir = tools
+tools.bindir = tools/bin
+tools.srcdir = tools/src
+
+tools/controller-gen     = $(tools.bindir)/controller-gen
+$(tools.bindir)/%: $(tools.srcdir)/%/pin.go $(tools.srcdir)/%/go.mod
+	cd $(<D) && GOOS= GOARCH= go build -o $(abspath $@) $$(sed -En 's,^import _ "(.*)".*,\1,p' pin.go)
+
+build: generate manifests
+	mkdir -p bin
+	CGO_ENABLED=0 go build -o bin/extension-server ./cmd/extension-server
+
+image: build
+	docker build -t extension-server:latest -f tools/docker/extension-server/Dockerfile .
+
+manifests: $(tools/controller-gen)
+	$(tools/controller-gen) crd:allowDangerousTypes=true paths="./..." output:crd:artifacts:config=charts/extension-server/crds/generated
+
+generate: $(tools/controller-gen)
+	$(tools/controller-gen) object:headerFile="$(tools.dir)/boilerplate.generatego.txt",year=2024 paths="{./api/...}"
+
+tools.clean: # Remove all tools
+	@$(LOG_TARGET)
+	rm -rf $(tools.bindir)
+
+clean: tools.clean
+	rm -fr bin
+
+
+.PHONY: build image manifests generate tools.clean clean

examples/extension-server/api/doc.go

@@ -0,0 +1,6 @@
+// Copyright Envoy Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package api

examples/extension-server/api/v1alpha1/doc.go

@@ -0,0 +1,8 @@
+// Copyright Envoy Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+// +kubebuilder:object:generate=true
+// +groupName=example.extensions.io
+package v1alpha1

examples/extension-server/api/v1alpha1/groupversion_info.go

@@ -0,0 +1,25 @@
+// Copyright Envoy Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/scheme"
+)
+
+const GroupName = "example.extensions.io"
+
+var (
+
+	// GroupVersion is group version used to register these objects
+	GroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha1"}
+
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
+
+	// AddToScheme adds the types in this group-version to the given scheme.
+	AddToScheme = SchemeBuilder.AddToScheme
+)

examples/extension-server/api/v1alpha1/listenercontext_types.go

@@ -0,0 +1,42 @@
+// Copyright Envoy Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	gwapiv1a2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
+)
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+//
+// ListenerContext provides an example extension policy context resource.
+type ListenerContextExample struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec ListenerContextExampleSpec `json:"spec"`
+}
+
+type ListenerContextExampleSpec struct {
+	TargetRefs []gwapiv1a2.LocalPolicyTargetReferenceWithSectionName `json:"targetRefs"`
+
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+// +kubebuilder:object:root=true
+//
+// ListenerContextList contains a list of ListenerContext resources.
+type ListenerContextExampleList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ListenerContextExample `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&ListenerContextExample{}, &ListenerContextExampleList{})
+}

examples/extension-server/charts/extension-server/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

examples/extension-server/charts/extension-server/Chart.yaml

@@ -0,0 +1,24 @@
+apiVersion: v2
+name: extension-server
+description: A minimal chart to install the example extension-server for Envoy Gateway
+
+# A chart can be either an 'application' or a 'library' chart.
+#
+# Application charts are a collection of templates that can be packaged into versioned archives
+# to be deployed.
+#
+# Library charts provide useful utilities or functions for the chart developer. They're included as
+# a dependency of application charts to inject those utilities and functions into the rendering
+# pipeline. Library charts do not define any templates and therefore cannot be deployed.
+type: application
+
+# This is the chart version. This version number should be incremented each time you make changes
+# to the chart and its templates, including the app version.
+# Versions are expected to follow Semantic Versioning (https://semver.org/)
+version: 0.1.0
+
+# This is the version number of the application being deployed. This version number should be
+# incremented each time you make changes to the application. Versions are not expected to
+# follow Semantic Versioning. They should reflect the version the application is using.
+# It is recommended to use it with quotes.
+appVersion: "0.0.1"

examples/extension-server/charts/extension-server/crds/generated/example.extensions.io_listenercontextexamples.yaml

@@ -0,0 +1,112 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.15.0
+  name: listenercontextexamples.example.extensions.io
+spec:
+  group: example.extensions.io
+  names:
+    kind: ListenerContextExample
+    listKind: ListenerContextExampleList
+    plural: listenercontextexamples
+    singular: listenercontextexample
+  scope: Namespaced
+  versions:
+  - name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: ListenerContext provides an example extension policy context
+          resource.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            properties:
+              password:
+                type: string
+              targetRefs:
+                items:
+                  description: |-
+                    LocalPolicyTargetReferenceWithSectionName identifies an API object to apply a
+                    direct policy to. This should be used as part of Policy resources that can
+                    target single resources. For more information on how this policy attachment
+                    mode works, and a sample Policy resource, refer to the policy attachment
+                    documentation for Gateway API.
+
+
+                    Note: This should only be used for direct policy attachment when references
+                    to SectionName are actually needed. In all other cases,
+                    LocalPolicyTargetReference should be used.
+                  properties:
+                    group:
+                      description: Group is the group of the target resource.
+                      maxLength: 253
+                      pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+                      type: string
+                    kind:
+                      description: Kind is kind of the target resource.
+                      maxLength: 63
+                      minLength: 1
+                      pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
+                      type: string
+                    name:
+                      description: Name is the name of the target resource.
+                      maxLength: 253
+                      minLength: 1
+                      type: string
+                    sectionName:
+                      description: |-
+                        SectionName is the name of a section within the target resource. When
+                        unspecified, this targetRef targets the entire resource. In the following
+                        resources, SectionName is interpreted as the following:
+
+
+                        * Gateway: Listener name
+                        * HTTPRoute: HTTPRouteRule name
+                        * Service: Port name
+
+
+                        If a SectionName is specified, but does not exist on the targeted object,
+                        the Policy must fail to attach, and the policy implementation should record
+                        a `ResolvedRefs` or similar Condition in the Policy's status.
+                      maxLength: 253
+                      minLength: 1
+                      pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+                      type: string
+                  required:
+                  - group
+                  - kind
+                  - name
+                  type: object
+                type: array
+              username:
+                type: string
+            required:
+            - password
+            - targetRefs
+            - username
+            type: object
+        required:
+        - spec
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}

examples/extension-server/charts/extension-server/templates/NOTES.txt

@@ -0,0 +1 @@
+The example extension server is now deployed.