feat: enable specification of environment variables (#165)

Allow specifying env variables for an extension in its metadata.

Related to cloudnative-pg/cloudnative-pg#10372
Closes #162

Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
Co-authored-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Co-authored-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>

Author: 3 people

dagger/maintenance/catalogs.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"path/filepath"
 	"slices"
+	"sort"
 
 	"go.yaml.in/yaml/v3"
 
@@ -22,13 +23,19 @@ type ImageVolumeSource struct {
 	PullPolicy string `yaml:"pullPolicy,omitempty"`
 }
 
+type ExtensionEnvVar struct {
+	Name  string `yaml:"name"`
+	Value string `yaml:"value"`
+}
+
 type ExtensionConfiguration struct {
 	Name                 string            `yaml:"name"`
 	ImageVolumeSource    ImageVolumeSource `yaml:"image"`
 	ExtensionControlPath []string          `yaml:"extension_control_path,omitempty"`
 	DynamicLibraryPath   []string          `yaml:"dynamic_library_path,omitempty"`
 	LdLibraryPath        []string          `yaml:"ld_library_path,omitempty"`
 	BinPath              []string          `yaml:"bin_path,omitempty"`
+	Env                  []ExtensionEnvVar `yaml:"env,omitempty"`
 }
 
 type ImageCatalog struct {
@@ -111,3 +118,14 @@ func writeCatalogToDir(catalog *ImageCatalog, outDir *dagger.Directory) (*dagger
 
 	return outDir.WithNewFile(outName, buf.String()), nil
 }
+
+func envMapToSlice(env map[string]string) []ExtensionEnvVar {
+	result := make([]ExtensionEnvVar, 0, len(env))
+	for name, value := range env {
+		result = append(result, ExtensionEnvVar{Name: name, Value: value})
+	}
+	sort.Slice(result, func(i, j int) bool {
+		return result[i].Name < result[j].Name
+	})
+	return result
+}

dagger/maintenance/main.go

@@ -515,6 +515,7 @@ func (m *Maintenance) GenerateCatalogs(
 					DynamicLibraryPath:   metadata.DynamicLibraryPath,
 					LdLibraryPath:        metadata.LdLibraryPath,
 					BinPath:              metadata.BinPath,
+					Env:                  envMapToSlice(metadata.Env),
 				}
 
 				img.Extensions = append(img.Extensions, extensionsConfig)

dagger/maintenance/parse.go

@@ -25,19 +25,20 @@ type extensionVersion struct {
 type versionMap map[string]map[string]extensionVersion
 
 type extensionMetadata struct {
-	Name                   string     `hcl:"name" cty:"name"`
-	SQLName                string     `hcl:"sql_name" cty:"sql_name"`
-	ImageName              string     `hcl:"image_name" cty:"image_name"`
-	SharedPreloadLibraries []string   `hcl:"shared_preload_libraries" cty:"shared_preload_libraries"`
-	ExtensionControlPath   []string   `hcl:"extension_control_path" cty:"extension_control_path"`
-	DynamicLibraryPath     []string   `hcl:"dynamic_library_path" cty:"dynamic_library_path"`
-	LdLibraryPath          []string   `hcl:"ld_library_path" cty:"ld_library_path"`
-	BinPath                []string   `hcl:"bin_path" cty:"bin_path"`
-	AutoUpdateOsLibs       bool       `hcl:"auto_update_os_libs" cty:"auto_update_os_libs"`
-	RequiredExtensions     []string   `hcl:"required_extensions" cty:"required_extensions"`
-	CreateExtension        bool       `hcl:"create_extension" cty:"create_extension"`
-	Versions               versionMap `hcl:"versions" cty:"versions"`
-	Remain                 hcl.Body   `hcl:",remain"`
+	Name                   string            `hcl:"name" cty:"name"`
+	SQLName                string            `hcl:"sql_name" cty:"sql_name"`
+	ImageName              string            `hcl:"image_name" cty:"image_name"`
+	SharedPreloadLibraries []string          `hcl:"shared_preload_libraries" cty:"shared_preload_libraries"`
+	ExtensionControlPath   []string          `hcl:"extension_control_path" cty:"extension_control_path"`
+	DynamicLibraryPath     []string          `hcl:"dynamic_library_path" cty:"dynamic_library_path"`
+	LdLibraryPath          []string          `hcl:"ld_library_path" cty:"ld_library_path"`
+	BinPath                []string          `hcl:"bin_path" cty:"bin_path"`
+	Env                    map[string]string `hcl:"env" cty:"env"`
+	AutoUpdateOsLibs       bool              `hcl:"auto_update_os_libs" cty:"auto_update_os_libs"`
+	RequiredExtensions     []string          `hcl:"required_extensions" cty:"required_extensions"`
+	CreateExtension        bool              `hcl:"create_extension" cty:"create_extension"`
+	Versions               versionMap        `hcl:"versions" cty:"versions"`
+	Remain                 hcl.Body          `hcl:",remain"`
 }
 
 const (

dagger/maintenance/testingvalues.go

@@ -109,6 +109,7 @@ func generateExtensionConfiguration(metadata *extensionMetadata, extensionImage
 		DynamicLibraryPath:   metadata.DynamicLibraryPath,
 		LdLibraryPath:        metadata.LdLibraryPath,
 		BinPath:              metadata.BinPath,
+		Env:                  envMapToSlice(metadata.Env),
 	}, nil
 }
 

pg-crash/metadata.hcl

@@ -10,6 +10,7 @@ metadata = {
   dynamic_library_path     = []
   ld_library_path          = []
   bin_path                 = []
+  env                      = {}
   auto_update_os_libs      = false
   required_extensions      = []
   create_extension         = false

pgaudit/metadata.hcl

@@ -8,6 +8,7 @@ metadata = {
   dynamic_library_path     = []
   ld_library_path          = []
   bin_path                 = []
+  env                      = {}
   auto_update_os_libs      = false
   required_extensions      = []
   create_extension         = true

pgvector/metadata.hcl

@@ -8,6 +8,7 @@ metadata = {
   dynamic_library_path     = []
   ld_library_path          = []
   bin_path                 = []
+  env                      = {}
   auto_update_os_libs      = false
   required_extensions      = []
   create_extension         = true

postgis/metadata.hcl

@@ -9,6 +9,7 @@ metadata = {
   dynamic_library_path     = []
   ld_library_path          = ["system"]
   bin_path                 = []
+  env                      = {}
   auto_update_os_libs      = true
   required_extensions      = []
   create_extension         = true

templates/metadata.hcl.tmpl

@@ -58,6 +58,29 @@ metadata = {
   # Postgres process. Used in tests and to generate image catalogs.
   bin_path                 = []
 
+  # TODO: Remove this comment block after customizing the file.
+  # `env`: Optional map of environment variables to be injected into the
+  # PostgreSQL process for this extension.
+  #
+  # NOTE: Both HCL and the CNPG operator use `${...}` for placeholder
+  # expansion. In both systems, `$${...}` is the escape that produces a
+  # literal `${...}` in the output (`$$` without a following `{` is kept
+  # as-is).
+  #
+  # 1. CNPG Placeholders: Use `$${...}` to pass a placeholder through HCL
+  #    to the operator, which then expands it.
+  #    Example: { "LIB_PATH" = "$${image_root}/lib" }
+  #    HCL output: ${image_root}/lib -> Operator expands to the mount path
+  #
+  # 2. Literal `${...}`: Use `$$${...}` so that HCL produces `$${...}`,
+  #    which the operator then treats as a literal `${...}`.
+  #    Example: { "TOKEN_FORMAT" = "$$${value}" }
+  #    HCL output: $${value} -> Operator produces literal: ${value}
+  #
+  # 3. Static Values: No special escaping needed.
+  #    Example: { "DEBUG" = "true" }
+  env = {}
+
   # TODO: Remove this comment block after customizing the file.
   # `auto_update_os_libs`: set to true to allow the maintenance tooling
   # to update OS libraries automatically; look at the `postgis` example.