Merge branch '763-topology-service-config' into 'main'

Add Topology Service configuration types

See merge request https://gitlab.com/gitlab-org/gitlab-shell/-/merge_requests/1382

Merged-by: Igor Drozdov <idrozdov@gitlab.com>
Approved-by: Igor Drozdov <idrozdov@gitlab.com>
Co-authored-by: Vasilii Iakliushin <viakliushin@gitlab.com>

Author: 2 people

config.yml.example

@@ -128,3 +128,35 @@ pat:
   enabled: true
   # Configure which PAT scopes are allowable to generate using an SSH key
   # allowed_scopes: [read_repository]
+
+# Topology Service configuration for GitLab Cells routing.
+# This enables routing SSH requests to the appropriate cell in a multi-cell deployment.
+# See: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/topology_service/
+#
+# topology_service:
+#   # Enable Topology Service integration
+#   enabled: false
+#
+#   # gRPC address of the Topology Service
+#   address: "topology.gitlab.com:443"
+#
+#   # ClassifyType to use when querying for cell routing.
+#   # Options: first_cell, session_prefix, cell_id
+#   classify_type: "first_cell"
+#
+#   # Timeout for Topology Service requests. Defaults to 5s.
+#   timeout: 5s
+#
+#   # TLS configuration for secure connections
+#   tls:
+#     # Enable TLS (recommended for production)
+#     enabled: true
+#     # Path to CA certificate file for server verification
+#     ca_file: "/etc/gitlab/ssl/topology-ca.crt"
+#     # Client certificate for mTLS (if required by Topology Service)
+#     # cert_file: "/etc/gitlab/ssl/client.crt"
+#     # key_file: "/etc/gitlab/ssl/client.key"
+#     # Expected server name for TLS verification
+#     # server_name: "topology.gitlab.com"
+#     # Skip TLS verification (development only, not recommended for production)
+#     # insecure_skip_verify: false

internal/config/config.go

@@ -4,6 +4,7 @@
 package config
 
 import (
+	"fmt"
 	"net/url"
 	"os"
 	"path"
@@ -16,6 +17,7 @@ import (
 	"gitlab.com/gitlab-org/gitlab-shell/v14/client"
 	"gitlab.com/gitlab-org/gitlab-shell/v14/internal/gitaly"
 	"gitlab.com/gitlab-org/gitlab-shell/v14/internal/metrics"
+	"gitlab.com/gitlab-org/gitlab-shell/v14/internal/topology"
 )
 
 const (
@@ -97,6 +99,9 @@ type Config struct {
 	LFSConfig      LFSConfig          `yaml:"lfs"`
 	PATConfig      PATConfig          `yaml:"pat"`
 
+	// TopologyService contains Topology Service client configuration for Cells routing.
+	TopologyService topology.Config `yaml:"topology_service"`
+
 	httpClient     *client.HTTPClient
 	httpClientErr  error
 	httpClientOnce sync.Once
@@ -242,6 +247,10 @@ func newFromFile(path string) (*Config, error) {
 		cfg.LogFile = filepath.Join(cfg.RootDir, cfg.LogFile)
 	}
 
+	if err := cfg.TopologyService.Validate(); err != nil {
+		return nil, fmt.Errorf("invalid topology_service config: %w", err)
+	}
+
 	return cfg, nil
 }
 

internal/config/config_test.go

@@ -104,3 +104,67 @@ func TestYAMLDuration(t *testing.T) {
 		})
 	}
 }
+
+func TestTopologyServiceConfig(t *testing.T) {
+	t.Run("default test config has topology_service disabled", func(t *testing.T) {
+		testRoot := testhelper.PrepareTestRootDir(t)
+		cfg, err := NewFromDir(testRoot)
+		require.NoError(t, err)
+		require.False(t, cfg.TopologyService.Enabled)
+	})
+
+	t.Run("parses full topology_service configuration from YAML", func(t *testing.T) {
+		yamlData := `
+topology_service:
+  enabled: true
+  address: "topology.example.com:443"
+  classify_type: "first_cell"
+  timeout: 10s
+  tls:
+    enabled: true
+    ca_file: "/path/to/ca.crt"
+    cert_file: "/path/to/cert.crt"
+    key_file: "/path/to/key.pem"
+    server_name: "topology.example.com"
+    insecure_skip_verify: true
+`
+		var cfg Config
+		require.NoError(t, yaml.Unmarshal([]byte(yamlData), &cfg))
+
+		ts := cfg.TopologyService
+		require.True(t, ts.Enabled)
+		require.Equal(t, "topology.example.com:443", ts.Address)
+		require.Equal(t, "first_cell", ts.ClassifyType)
+		require.Equal(t, 10*time.Second, ts.Timeout)
+		require.True(t, ts.TLS.Enabled)
+		require.Equal(t, "/path/to/ca.crt", ts.TLS.CAFile)
+		require.Equal(t, "/path/to/cert.crt", ts.TLS.CertFile)
+		require.Equal(t, "/path/to/key.pem", ts.TLS.KeyFile)
+		require.Equal(t, "topology.example.com", ts.TLS.ServerName)
+		require.True(t, ts.TLS.InsecureSkipVerify)
+	})
+}
+
+func TestTopologyServiceConfigValidation(t *testing.T) {
+	t.Run("newFromFile rejects invalid topology config", func(t *testing.T) {
+		// Create a temporary directory with an invalid config
+		tmpDir := t.TempDir()
+		configPath := tmpDir + "/config.yml"
+		secretPath := tmpDir + "/.gitlab_shell_secret"
+
+		// Write secret file
+		require.NoError(t, os.WriteFile(secretPath, []byte("test-secret"), 0o600))
+
+		// Write config with enabled topology but missing address
+		invalidConfig := `
+topology_service:
+  enabled: true
+`
+		require.NoError(t, os.WriteFile(configPath, []byte(invalidConfig), 0o600))
+
+		_, err := NewFromDir(tmpDir)
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "invalid topology_service config")
+		require.Contains(t, err.Error(), "address is required")
+	})
+}

internal/testhelper/testdata/testroot/config.yml

@@ -2,3 +2,7 @@ sshd:
   grace_period: 10
   client_alive_interval: 1m
   proxy_header_timeout: 500ms
+
+# Topology service disabled by default in tests
+topology_service:
+  enabled: false

internal/topology/config.go

@@ -0,0 +1,124 @@
+// Package topology provides a client for interacting with the GitLab Cells Topology Service.
+//
+// The Topology Service is a gRPC server that provides cell routing information for
+// requests related to specific records (projects, groups, etc.) in a GitLab Cells
+// architecture.
+//
+// Configuration is done via the topology_service section in config.yml:
+//
+//	topology_service:
+//	  enabled: true
+//	  address: "topology.gitlab.com:443"
+//	  classify_type: "first_cell"
+//	  tls:
+//	    enabled: true
+//	    ca_file: "/path/to/ca.crt"
+//
+// For more details, see:
+//   - https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/topology_service/
+//   - https://gitlab.com/gitlab-org/cells/topology-service
+package topology
+
+import (
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+)
+
+// ValidClassifyTypes contains the list of valid classify_type values.
+// These correspond to the ClassifyType enum in the Topology Service proto.
+var ValidClassifyTypes = []string{"first_cell", "session_prefix", "cell_id"}
+
+// DefaultTimeout is the default timeout for Topology Service requests.
+const DefaultTimeout = 5 * time.Second
+
+// Config contains Topology Service client configuration settings.
+type Config struct {
+	// Enabled indicates whether Topology Service integration is enabled.
+	Enabled bool `yaml:"enabled"`
+
+	// Address is the gRPC address of the Topology Service (e.g., "topology.gitlab.com:443").
+	Address string `yaml:"address"`
+
+	// ClassifyType specifies which ClassifyType to use when querying the service.
+	// Valid values: "first_cell", "session_prefix", "cell_id".
+	// Default: "first_cell" (applied at runtime when empty).
+	ClassifyType string `yaml:"classify_type"`
+
+	// Timeout is the maximum duration to wait for a response from the Topology Service.
+	// Default: 5s (when zero).
+	Timeout time.Duration `yaml:"timeout"`
+
+	// TLS contains TLS configuration for secure connections.
+	TLS TLSConfig `yaml:"tls"`
+}
+
+// TLSConfig contains TLS settings for the Topology Service connection.
+type TLSConfig struct {
+	// Enabled indicates whether TLS should be used for the connection.
+	Enabled bool `yaml:"enabled"`
+
+	// CAFile is the path to the CA certificate file for server verification.
+	// If empty, system CA certificates will be used.
+	CAFile string `yaml:"ca_file"`
+
+	// CertFile is the path to the client certificate file (for mTLS).
+	// Must be provided together with KeyFile.
+	CertFile string `yaml:"cert_file"`
+
+	// KeyFile is the path to the client key file (for mTLS).
+	// Must be provided together with CertFile.
+	KeyFile string `yaml:"key_file"`
+
+	// ServerName is the expected server name for TLS verification.
+	// If empty, the hostname from Address will be used.
+	ServerName string `yaml:"server_name"`
+
+	// InsecureSkipVerify skips TLS certificate verification.
+	// WARNING: This should only be used for development/testing.
+	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`
+}
+
+// Validate validates the Topology Service configuration.
+func (c *Config) Validate() error {
+	if !c.Enabled {
+		return nil
+	}
+
+	if c.Address == "" {
+		return errors.New("topology_service.address is required when enabled")
+	}
+
+	if !strings.Contains(c.Address, ":") {
+		return errors.New("topology_service.address must be in host:port format")
+	}
+
+	if c.ClassifyType != "" && !slices.Contains(ValidClassifyTypes, c.ClassifyType) {
+		return fmt.Errorf("invalid topology_service.classify_type: %q, must be one of %v", c.ClassifyType, ValidClassifyTypes)
+	}
+
+	if err := c.TLS.Validate(); err != nil {
+		return fmt.Errorf("topology_service.tls: %w", err)
+	}
+
+	return nil
+}
+
+// Validate validates the TLS configuration.
+func (c *TLSConfig) Validate() error {
+	if !c.Enabled {
+		return nil
+	}
+
+	// Check that both cert and key are provided together for mTLS
+	hasCert := c.CertFile != ""
+	hasKey := c.KeyFile != ""
+
+	if hasCert != hasKey {
+		return errors.New("both cert_file and key_file must be provided for mTLS")
+	}
+
+	return nil
+}

internal/topology/config_test.go

@@ -0,0 +1,100 @@
+package topology
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestConfigValidate(t *testing.T) {
+	t.Run("disabled config is always valid", func(t *testing.T) {
+		require.NoError(t, (&Config{Enabled: false}).Validate())
+		require.NoError(t, (&Config{Enabled: false, Address: ""}).Validate())
+	})
+
+	t.Run("enabled config requires address", func(t *testing.T) {
+		err := (&Config{Enabled: true}).Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "address is required")
+	})
+
+	t.Run("enabled config requires address in host:port format", func(t *testing.T) {
+		err := (&Config{Enabled: true, Address: "localhost"}).Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "must be in host:port format")
+	})
+
+	t.Run("enabled config with address is valid", func(t *testing.T) {
+		cfg := &Config{Enabled: true, Address: "localhost:8080"}
+		require.NoError(t, cfg.Validate())
+	})
+
+	t.Run("enabled config with TLS is valid", func(t *testing.T) {
+		cfg := &Config{
+			Enabled: true,
+			Address: "topology.gitlab.com:443",
+			TLS:     TLSConfig{Enabled: true, CAFile: "/path/to/ca.crt"},
+		}
+		require.NoError(t, cfg.Validate())
+	})
+
+	t.Run("invalid classify_type fails", func(t *testing.T) {
+		cfg := &Config{Enabled: true, Address: "localhost:8080", ClassifyType: "invalid_type"}
+		err := cfg.Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "invalid topology_service.classify_type")
+	})
+
+	t.Run("valid classify_types succeed", func(t *testing.T) {
+		for _, ct := range []string{"first_cell", "session_prefix", "cell_id", ""} {
+			cfg := &Config{Enabled: true, Address: "localhost:8080", ClassifyType: ct}
+			require.NoError(t, cfg.Validate(), "classify_type=%q should be valid", ct)
+		}
+	})
+}
+
+func TestTLSConfigValidate(t *testing.T) {
+	t.Run("disabled TLS is always valid", func(t *testing.T) {
+		require.NoError(t, (&TLSConfig{Enabled: false}).Validate())
+	})
+
+	t.Run("enabled TLS without CA uses system CAs", func(t *testing.T) {
+		require.NoError(t, (&TLSConfig{Enabled: true}).Validate())
+	})
+
+	t.Run("mTLS requires both cert and key", func(t *testing.T) {
+		err := (&TLSConfig{Enabled: true, CertFile: "/cert.crt"}).Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "both cert_file and key_file must be provided")
+
+		err = (&TLSConfig{Enabled: true, KeyFile: "/key.pem"}).Validate()
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "both cert_file and key_file must be provided")
+	})
+
+	t.Run("mTLS with both cert and key is valid", func(t *testing.T) {
+		cfg := &TLSConfig{Enabled: true, CertFile: "/cert.crt", KeyFile: "/key.pem"}
+		require.NoError(t, cfg.Validate())
+	})
+
+	t.Run("full mTLS config is valid", func(t *testing.T) {
+		cfg := &TLSConfig{
+			Enabled:    true,
+			CAFile:     "/ca.crt",
+			CertFile:   "/cert.crt",
+			KeyFile:    "/key.pem",
+			ServerName: "topology.gitlab.com",
+		}
+		require.NoError(t, cfg.Validate())
+	})
+}
+
+func TestValidClassifyTypes(t *testing.T) {
+	expected := []string{"first_cell", "session_prefix", "cell_id"}
+	require.Equal(t, expected, ValidClassifyTypes)
+}
+
+func TestDefaultTimeout(t *testing.T) {
+	require.Equal(t, 5*time.Second, DefaultTimeout)
+}