Configuration

Icepack is configured through environment variables. Defaults are read from icepack.config.CompactionConfig unless a component has a separate runtime default.

API

Variable	Config path	Default	Required	Description
ICEPACK_MAX_CONCURRENT_JOBS	max_workers	2	no	Maximum concurrent in-process maintenance workers per API replica.
ICEPACK_TABLE_CACHE_REFRESH_SECONDS	table_cache_refresh_seconds	300	no	Table inventory refresh cadence in seconds.

API / Worker

Variable	Config path	Default	Required	Description
ICEPACK_DRAIN_MODE	drain_mode	false	no	When true/on, the API rejects new maintenance submissions and the worker avoids stale-claim recovery.
ICEPACK_POSTGRES_HEALTH_CHECK_TIMEOUT_SECONDS	postgres.health_check_timeout_seconds	2.0	no	Maximum seconds readiness waits for a pool connection and SELECT 1 probe.
ICEPACK_POSTGRES_MAX_CONNECTIONS	postgres.max_connections	20	no	Maximum PostgreSQL pool connections.
ICEPACK_POSTGRES_MIN_CONNECTIONS	postgres.min_connections	4	no	Minimum PostgreSQL pool connections.
ICEPACK_SOCKET_TIMEOUT_MS	spark.socket_timeout_ms	7200000	no	Spark Thrift socket read timeout in milliseconds.
ICEPACK_TABLE_CACHE_STALENESS_SECONDS	table_cache_staleness_seconds	2x ICEPACK_TABLE_CACHE_REFRESH_SECONDS	no	Maximum table-cache age before readiness fails.

API / Worker / CLI

Variable	Config path	Default	Required	Description
ICEPACK_CATALOG	spark.catalog	lakehouse_dev	no	Iceberg catalog name used in Spark SQL statements.
ICEPACK_SPARK_HOST	spark.host	kyuubi-maintenance.data-platform.us-east-1.test-dataops.fetchrewards.com	no	Spark Thrift Server / Kyuubi hostname.
ICEPACK_SPARK_PORT	spark.port	10009	no	Spark Thrift Server / Kyuubi port.

API / Worker / Health Sync

Variable	Config path	Default	Required	Description
AWS_REGION	aws_region	us-east-1	no	AWS region used for Glue and S3 API calls.
ICEPACK_GLUE_CATALOG	glue_catalog_name	lakehouse_dev	no	Glue catalog name used by metadata inspectors for direct Iceberg metadata access.
ICEPACK_ICEBERG_GO_INSPECTOR_PATH	iceberg_go_inspector_path	/usr/local/bin/icepack-iceberg-inspector	no	Path to the bundled iceberg-go metadata inspector helper.
ICEPACK_ICEBERG_GO_INSPECTOR_TIMEOUT_SECONDS	iceberg_go_inspector_timeout_seconds	120	no	Maximum seconds to wait for the iceberg-go metadata inspector helper.
ICEPACK_METADATA_INSPECTOR	metadata_inspector	pyiceberg	no	Metadata inspector backend for table health: pyiceberg or iceberg-go.
ICEPACK_POLARIS_CATALOG	polaris.catalog_name	glue_dev	no	Polaris REST catalog name.
ICEPACK_POLARIS_CLIENT_ID	polaris.client_id	unset	no	OAuth2 client ID for Polaris REST catalog access.
ICEPACK_POLARIS_CLIENT_SECRET	polaris.client_secret	unset	yes	OAuth2 client secret for Polaris REST catalog access.
ICEPACK_POLARIS_URI	polaris.uri	unset	no	Polaris REST catalog URI. Empty falls back to Glue.
ICEPACK_POSTGRES_DATABASE	postgres.database	icepack	no	PostgreSQL database name.
ICEPACK_POSTGRES_HOST	postgres.host	localhost	no	PostgreSQL hostname.
ICEPACK_POSTGRES_PASSWORD	postgres.password	required	yes	PostgreSQL password.
ICEPACK_POSTGRES_PORT	postgres.port	5432	no	PostgreSQL port.
ICEPACK_POSTGRES_USER	postgres.user	icepack	no	PostgreSQL username.

API / Worker / Orchestrator

Variable	Config path	Default	Required	Description
ICEPACK_ENVIRONMENT	-	unknown	no	Deployment environment label attached to Icepack operational metrics.

Health Sync

Variable	Config path	Default	Required	Description
ICEPACK_HEALTH_SYNC_CONCURRENCY	health_sync_concurrency	10	no	Maximum concurrent table metadata inspections for health sync.
ICEPACK_HEALTH_SYNC_DATABASES	health_sync_databases	all	no	Comma-separated databases to sync health for. Empty means all databases.
ICEPACK_MIMIR_ENDPOINT	mimir_endpoint	unset	no	OTLP gRPC endpoint for Mimir metrics push. Empty disables push.

Orchestrator

Variable	Config path	Default	Required	Description
ICEPACK_API_URL	-	http://icepack-api.icepack.svc.cluster.local:443	no	Icepack API base URL used for table health checks and job submission.
ICEPACK_DRY_RUN	-	false	no	When true, logs orchestration decisions without submitting maintenance jobs.
ICEPACK_HEALTH_CONCURRENCY	-	10	no	Maximum concurrent health check requests during orchestration.
ICEPACK_MAX_SUBMIT	-	3	no	Maximum total maintenance jobs submitted by one orchestrator run.
ICEPACK_POLL_INTERVAL	-	30	no	Seconds between job status polls while the orchestrator waits for submitted jobs.
ICEPACK_SLACK_WEBHOOK_URL	-	unset	no	Slack incoming webhook URL for orchestrator summaries. Optional.

Orchestrator, API

Variable	Config path	Default	Required	Description
ICEPACK_INCLUDE_DATABASES	include_databases	unset	no	Comma-separated database allowlist. The orchestrator maintains only these databases; the API also surfaces it on GET /tables so the UI greys out databases outside the allowlist.
ICEPACK_MAINTENANCE_CADENCE_HOURS	-	24	no	Global minimum hours between automated maintenance runs for one table.
ICEPACK_OPT_IN_MODE	-	false	no	Orchestrator enrollment mode. When false (opt-out, the default), every table in the database allowlist is maintained unless it sets icepack.maintenance_enabled=false or compaction_skip=true. When true (opt-in), only tables with icepack.maintenance_enabled=true are maintained.

Worker / Orchestrator

Variable	Config path	Default	Required	Description
OTEL_EXPORTER_OTLP_ENDPOINT	-	unset	no	OTLP endpoint used by ephemeral worker and orchestrator pods for push metrics. Leave unset to disable.