feat(aigw): point to example config instead of bundling one (envoyproxy#1235)

**Description**

We can dramatically clarify `aigw run` docs now that you can
auto-generate a configuration with ENV variables.

This removes the bundled example config, and points to the examples
directory instead, which allows people to discover more features and
have a simpler doc experience.

**Related Issues/PRs (if applicable)**


envoyproxy#1233 (comment)

---------

Signed-off-by: Adrian Cole <[email protected]>
Co-authored-by: Takeshi Yoneda <[email protected]>

Author: codefromthecrypt

cmd/aigw/ai-gateway-default-resources.yaml

@@ -72,13 +72,10 @@ func TestReadConfig(t *testing.T) {
 		})
 	}
 
-	t.Run("Default config uses 0.0.0.0 IP for Ollama when no env vars", func(t *testing.T) {
-		t.Setenv("OPENAI_API_KEY", "")
-		t.Setenv("OPENAI_BASE_URL", "")
-		config, err := readConfig("")
-		require.NoError(t, err)
-		require.Contains(t, config, "address: 0.0.0.0")
-		require.Contains(t, config, "port: 11434")
+	t.Run("error when file and no OPENAI_API_KEY", func(t *testing.T) {
+		_, err := readConfig("")
+		require.Error(t, err)
+		require.EqualError(t, err, "you must supply at least OPENAI_API_KEY or a config file path")
 	})
 
 	t.Run("error when file does not exist", func(t *testing.T) {

cmd/aigw/config_test.go

@@ -36,12 +36,19 @@ type (
 	}
 	// cmdRun corresponds to `aigw run` command.
 	cmdRun struct {
-		Debug       bool   `help:"Enable debug logging emitted to stderr."`
-		Path        string `arg:"" name:"path" optional:"" help:"Path to the AI Gateway configuration yaml file. Optional. When this is not given, aigw runs the default configuration. Use --show-default to check the default configuration's behavior" type:"path"`
-		ShowDefault bool   `help:"Show the default configuration, and exit."`
+		Debug bool   `help:"Enable debug logging emitted to stderr."`
+		Path  string `arg:"" name:"path" optional:"" help:"Path to the AI Gateway configuration yaml file. Optional when at least OPENAI_API_KEY is set." type:"path"`
 	}
 )
 
+// Validate is called by Kong after parsing to validate the cmdRun arguments.
+func (c *cmdRun) Validate() error {
+	if c.Path == "" && os.Getenv("OPENAI_API_KEY") == "" {
+		return fmt.Errorf("you must supply at least OPENAI_API_KEY or a config file path")
+	}
+	return nil
+}
+
 type (
 	subCmdFn[T any] func(context.Context, T, io.Writer, io.Writer) error
 	translateFn     subCmdFn[cmdTranslate]

cmd/aigw/main.go

@@ -21,6 +21,7 @@ func Test_doMain(t *testing.T) {
 	tests := []struct {
 		name         string
 		args         []string
+		env          map[string]string
 		tf           translateFn
 		rf           runFn
 		expOut       string
@@ -105,8 +106,15 @@ Flags:
 			expPanicCode: ptr.To(0),
 		},
 		{
-			name: "run no arg",
+			name:         "run no arg",
+			args:         []string{"run"},
+			rf:           func(context.Context, cmdRun, runOpts, io.Writer, io.Writer) error { return nil },
+			expPanicCode: ptr.To(80),
+		},
+		{
+			name: "run with OpenAI env",
 			args: []string{"run"},
+			env:  map[string]string{"OPENAI_API_KEY": "dummy-key"},
 			rf:   func(context.Context, cmdRun, runOpts, io.Writer, io.Writer) error { return nil },
 		},
 		{
@@ -118,40 +126,32 @@ Flags:
 Run the AI Gateway locally for given configuration.
 
 Arguments:
-  [<path>]    Path to the AI Gateway configuration yaml file. Optional.
-              When this is not given, aigw runs the default configuration.
-              Use --show-default to check the default configuration's behavior
+  [<path>]    Path to the AI Gateway configuration yaml file. Optional when at
+              least OPENAI_API_KEY is set.
 
 Flags:
-  -h, --help            Show context-sensitive help.
+  -h, --help     Show context-sensitive help.
 
-      --debug           Enable debug logging emitted to stderr.
-      --show-default    Show the default configuration, and exit.
+      --debug    Enable debug logging emitted to stderr.
 `,
 			expPanicCode: ptr.To(0),
 		},
-		{
-			name: "run show default",
-			args: []string{"run", "--show-default"},
-			rf: func(_ context.Context, c cmdRun, _ runOpts, _, _ io.Writer) error {
-				require.True(t, c.ShowDefault)
-				return nil
-			},
-		},
 		{
 			name: "run with path",
 			args: []string{"run", "./path"},
 			rf: func(_ context.Context, c cmdRun, _ runOpts, _, _ io.Writer) error {
 				abs, err := filepath.Abs("./path")
 				require.NoError(t, err)
 				require.Equal(t, abs, c.Path)
-				require.False(t, c.ShowDefault)
 				return nil
 			},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
+			for k, v := range tt.env {
+				t.Setenv(k, v)
+			}
 			out := &bytes.Buffer{}
 			if tt.expPanicCode != nil {
 				require.PanicsWithValue(t, *tt.expPanicCode, func() {

cmd/aigw/main_test.go

@@ -9,6 +9,7 @@ import (
 	"bytes"
 	"context"
 	_ "embed"
+	"errors"
 	"fmt"
 	"io"
 	"log/slog"
@@ -39,18 +40,11 @@ import (
 	"github.com/envoyproxy/ai-gateway/internal/filterapi"
 )
 
-var (
-	// This is the default configuration for the AI Gateway when <path> parameter is not given.
-	//
-	//go:embed ai-gateway-default-resources.yaml
-	aiGatewayDefaultResources string
-
-	// This is the template for the Envoy Gateway configuration where PLACEHOLDER_TMPDIR will be replaced with the temporary
-	// directory where the resources are written to.
-	//
-	//go:embed envoy-gateway-config.yaml
-	envoyGatewayConfigTemplate string
-)
+// This is the template for the Envoy Gateway configuration where PLACEHOLDER_TMPDIR will be replaced with the temporary
+// directory where the resources are written to.
+//
+//go:embed envoy-gateway-config.yaml
+var envoyGatewayConfigTemplate string
 
 const (
 	substitutionEnvAnnotationPrefix  = "substitution.aigw.run/env/"
@@ -96,13 +90,6 @@ func run(ctx context.Context, c cmdRun, o runOpts, stdout, stderr io.Writer) err
 		stderr = io.Discard
 	}
 	stderrLogger := slog.New(slog.NewTextHandler(stderr, &slog.HandlerOptions{}))
-	if c.ShowDefault {
-		_, err := stdout.Write([]byte(aiGatewayDefaultResources))
-		if err != nil {
-			panic(fmt.Sprintf("BUG: failed to write default resources: %v", err))
-		}
-		return nil
-	}
 
 	// First, we need to create the self-signed certificates used for communication between the EG and Envoy.
 	// Certificates will be placed at /tmp/envoy-gateway/certs, which is currently is not configurable:
@@ -248,21 +235,18 @@ func pollEnvoyReadiness(ctx context.Context, l *slog.Logger, addr string, interv
 	}
 }
 
-// readConfig reads and returns the configuration as a string from the specified path,
-// substituting environment variables similar to envsubst. If the path is empty and
-// OPENAI_API_KEY is set, it generates the configuration from OpenAI environment variables.
-// If the path is empty and no OPENAI_API_KEY is set, it returns the default configuration.
-// An error is returned if the file cannot be read or if config generation fails.
+// readConfig returns the configuration as a string from the given path,
+// substituting environment variables. If OPENAI_API_KEY is set, it generates
+// the config from OpenAI environment variables. Otherwise, it returns an error.
 func readConfig(path string) (string, error) {
-	if path == "" {
-		if os.Getenv("OPENAI_API_KEY") != "" {
-			config, err := envgen.GenerateOpenAIConfig()
-			if err != nil {
-				return "", fmt.Errorf("error generating OpenAI config: %w", err)
-			}
-			return config, nil
+	if os.Getenv("OPENAI_API_KEY") != "" {
+		config, err := envgen.GenerateOpenAIConfig()
+		if err != nil {
+			return "", fmt.Errorf("error generating OpenAI config: %w", err)
 		}
-		return aiGatewayDefaultResources, nil
+		return config, nil
+	} else if path == "" {
+		return "", errors.New("you must supply at least OPENAI_API_KEY or a config file path")
 	}
 	configBytes, err := envsubst.ReadFile(path)
 	if err != nil {