egctl x translate (#1047)

* egctl x translate * add an `experimental` subcommand called `translate` allowing users to observe the translated xds output when gateway api resources are inputted * this should help users understand the mapping between gatewapi resources and xds resources which will help with #24 and #31 Signed-off-by: Arko Dasgupta <arko@tetrate.io> * fix and docs Signed-off-by: Arko Dasgupta <arko@tetrate.io> * license Signed-off-by: Arko Dasgupta <arko@tetrate.io> * lint Signed-off-by: Arko Dasgupta <arko@tetrate.io> * more lint Signed-off-by: Arko Dasgupta <arko@tetrate.io> * more lint Signed-off-by: Arko Dasgupta <arko@tetrate.io> * test Signed-off-by: Arko Dasgupta <arko@tetrate.io> * lint Signed-off-by: Arko Dasgupta <arko@tetrate.io> * rename file to skip yaml validation Signed-off-by: Arko Dasgupta <arko@tetrate.io> --------- Signed-off-by: Arko Dasgupta <arko@tetrate.io>
envoyproxy · Feb 20, 2023 · e43c5ba · e43c5ba
1 parent d6b4402
commit e43c5ba
Show file tree

Hide file tree

Showing 14 changed files with 929 additions and 53 deletions.
diff --git a/cmd/egctl/main.go b/cmd/egctl/main.go
@@ -30,6 +30,7 @@ func rootCommand() *cobra.Command {
 	}
 
 	rootCmd.AddCommand(egctl.NewVersionCommand())
+	rootCmd.AddCommand(egctl.NewExperimentalCommand())
 
 	return rootCmd
 }
diff --git a/docs/latest/design/egctl.md b/docs/latest/design/egctl.md
@@ -34,11 +34,12 @@ If you need help, run `egctl help` from the terminal window.
 
 The following table includes short descriptions and the general syntax for all the `egctl` operations:
 
-| Operation | Syntax                           | Description                                                                 |
-| --------- | -------------------------------- | --------------------------------------------------------------------------- |
-| `version` | `egctl version`                  | Prints out build version information.                                       |
-| `config`  | `egctl config ENTITY`            | Retrieve information about proxy configuration from envoy proxy and gateway |
-| `analyze` | `egctl analyze`                  | Analyze EG configuration and print validation messages                      |
+| Operation     | Syntax                           | Description                                                                          |
+| --------------| -------------------------------- | -------------------------------------------------------------------------------------|
+| `version`     | `egctl version`                  | Prints out build version information.                                                |
+| `config`      | `egctl config ENTITY`            | Retrieve information about proxy configuration from envoy proxy and gateway          |
+| `analyze`     | `egctl analyze`                  | Analyze EG configuration and print validation messages                               |
+| `experimental`| `egctl experimental`             | Subcommand for experimental features. These do not guarantee backwards compatibility |
 
 ## Examples
 

diff --git a/docs/latest/user/egctl.md b/docs/latest/user/egctl.md
@@ -0,0 +1,251 @@
+# egctl
+
+`egctl` is a command line tool to provide additional functionality for Envoy Gateway users.
+
+## egctl experimental translate
+
+This subcommand allows users to translate from an input configuration type to an output configuration type.
+
+In the below example, we will translate the Kubernetes resources (including the Gateway API resources) into xDS
+resources.
+
+```
+cat <<EOF >> gateway-api-config.yaml
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: GatewayClass
+metadata:
+  name: eg
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: Gateway
+metadata:
+  name: eg
+  namespace: default
+spec:
+  gatewayClassName: eg
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: default 
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: backend
+  namespace: default
+  labels:
+    app: backend
+    service: backend
+spec:
+  clusterIP: "1.1.1.1"
+  type: ClusterIP
+  ports:
+    - name: http
+      port: 3000
+      targetPort: 3000
+      protocol: TCP
+  selector:
+    app: backend
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: HTTPRoute
+metadata:
+  name: backend
+  namespace: default
+spec:
+  parentRefs:
+    - name: eg
+  hostnames:
+    - "www.example.com"
+  rules:
+    - backendRefs:
+        - group: ""
+          kind: Service
+          name: backend
+          port: 3000
+          weight: 1
+      matches:
+        - path:
+            type: PathPrefix
+            value: /
+EOF
+```
+
+```
+egctl x translate --from gateway-api --to xds -f gateway-api-config.yaml
+
+xDS
+
+Key: default-eg
+
+Bootstrap:
+admin:
+  access_log:
+  - name: envoy.access_loggers.file
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
+      path: /dev/null
+  address:
+    socket_address:
+      address: 127.0.0.1
+      port_value: 19000
+dynamic_resources:
+  cds_config:
+    resource_api_version: V3
+    api_config_source:
+      api_type: DELTA_GRPC
+      transport_api_version: V3
+      grpc_services:
+      - envoy_grpc:
+          cluster_name: xds_cluster
+      set_node_on_first_message_only: true
+  lds_config:
+    resource_api_version: V3
+    api_config_source:
+      api_type: DELTA_GRPC
+      transport_api_version: V3
+      grpc_services:
+      - envoy_grpc:
+          cluster_name: xds_cluster
+      set_node_on_first_message_only: true
+static_resources:
+  clusters:
+  - connect_timeout: 1s
+    load_assignment:
+      cluster_name: xds_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: envoy-gateway
+                port_value: 18000
+    typed_extension_protocol_options:
+      "envoy.extensions.upstreams.http.v3.HttpProtocolOptions":
+         "@type": "type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions"
+         "explicit_http_config":
+           "http2_protocol_options": {}
+    name: xds_cluster
+    type: STRICT_DNS
+    transport_socket:
+      name: envoy.transport_sockets.tls
+      typed_config:
+        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
+        common_tls_context:
+          tls_params:
+            tls_maximum_protocol_version: TLSv1_3
+          tls_certificate_sds_secret_configs:
+          - name: xds_certificate
+            sds_config:
+              path_config_source:
+                path: "/sds/xds-certificate.json"
+              resource_api_version: V3
+          validation_context_sds_secret_config:
+            name: xds_trusted_ca
+            sds_config:
+              path_config_source:
+                path: "/sds/xds-trusted-ca.json"
+              resource_api_version: V3
+layered_runtime:
+  layers:
+    - name: runtime-0
+      rtds_layer:
+        rtds_config:
+          resource_api_version: V3
+          api_config_source:
+            transport_api_version: V3
+            api_type: DELTA_GRPC
+            grpc_services:
+              envoy_grpc:
+                cluster_name: xds_cluster
+        name: runtime-0
+
+Listeners:
+- accessLog:
+  - filter:
+      responseFlagFilter:
+        flags:
+        - NR
+    name: envoy.access_loggers.file
+    typedConfig:
+      '@type': type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
+      path: /dev/stdout
+  address:
+    socketAddress:
+      address: 0.0.0.0
+      portValue: 10080
+  defaultFilterChain:
+    filters:
+    - name: envoy.filters.network.http_connection_manager
+      typedConfig:
+        '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+        accessLog:
+        - name: envoy.access_loggers.file
+          typedConfig:
+            '@type': type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
+            path: /dev/stdout
+        httpFilters:
+        - name: envoy.filters.http.router
+          typedConfig:
+            '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+        rds:
+          configSource:
+            apiConfigSource:
+              apiType: DELTA_GRPC
+              grpcServices:
+              - envoyGrpc:
+                  clusterName: xds_cluster
+              setNodeOnFirstMessageOnly: true
+              transportApiVersion: V3
+            resourceApiVersion: V3
+          routeConfigName: default-eg-http
+        statPrefix: http
+        upgradeConfigs:
+        - upgradeType: websocket
+        useRemoteAddress: true
+  name: default-eg-http
+
+Routes:
+- name: default-eg-http
+  virtualHosts:
+  - domains:
+    - '*'
+    name: default-eg-http
+    routes:
+    - match:
+        headers:
+        - name: :authority
+          stringMatch:
+            exact: www.example.com
+        prefix: /
+      route:
+        cluster: default-backend-rule-0-match-0-www.example.com
+
+Clusters:
+- commonLbConfig:
+    localityWeightedLbConfig: {}
+  connectTimeout: 5s
+  dnsLookupFamily: V4_ONLY
+  loadAssignment:
+    clusterName: default-backend-rule-0-match-0-www.example.com
+    endpoints:
+    - lbEndpoints:
+      - endpoint:
+          address:
+            socketAddress:
+              address: 1.1.1.1
+              portValue: 3000
+        loadBalancingWeight: 1
+      loadBalancingWeight: 1
+      locality: {}
+  name: default-backend-rule-0-match-0-www.example.com
+  outlierDetection: {}
+  type: STATIC
+```  
diff --git a/docs/latest/user_docs.rst b/docs/latest/user_docs.rst
@@ -20,3 +20,4 @@ Learn how to deploy, use, and operate Envoy Gateway.
   user/grpc-routing
   user/authn
   user/rate-limit
+  user/egctl
diff --git a/internal/cmd/egctl/experimental.go b/internal/cmd/egctl/experimental.go
@@ -0,0 +1,23 @@
+// 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 egctl
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewExperimentalCommand() *cobra.Command {
+
+	experimentalCommand := &cobra.Command{
+		Use:     "experimental",
+		Aliases: []string{"x"},
+		Short:   "Experimental features",
+	}
+
+	experimentalCommand.AddCommand(NewTranslateCommand())
+
+	return experimentalCommand
+}
diff --git a/internal/cmd/egctl/testdata/in/from-gateway-api-to-xds.yaml b/internal/cmd/egctl/testdata/in/from-gateway-api-to-xds.yaml
@@ -0,0 +1,64 @@
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: GatewayClass
+metadata:
+  name: eg
+spec:
+  controllerName: gateway.envoyproxy.io/gatewayclass-controller
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: Gateway
+metadata:
+  name: eg
+  namespace: default
+spec:
+  gatewayClassName: eg
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: default 
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: backend
+  namespace: default
+  labels:
+    app: backend
+    service: backend
+spec:
+  clusterIP: "1.1.1.1"
+  type: ClusterIP
+  ports:
+    - name: http
+      port: 3000
+      targetPort: 3000
+      protocol: TCP
+  selector:
+    app: backend
+---
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: HTTPRoute
+metadata:
+  name: backend
+  namespace: default
+spec:
+  parentRefs:
+    - name: eg
+  hostnames:
+    - "www.example.com"
+  rules:
+    - backendRefs:
+        - group: ""
+          kind: Service
+          name: backend
+          port: 3000
+          weight: 1
+      matches:
+        - path:
+            type: PathPrefix
+            value: /