Customization Overview
Summary
You can customize the Keymate platform at three levels: platform-wide defaults, Tenant-specific overrides, and environment-specific overrides. This layered approach allows you to maintain a consistent base configuration while tailoring behavior per Tenant, per environment, or per component — without modifying platform source code.
This page describes what can be customized, at which level, and how the override model works.
Why It Exists
Every enterprise has different requirements. One Tenant may need a specific identity federation setup, another may require custom authorization policies, and a third may need different resource limits for a high-traffic environment. A rigid, one-size-fits-all configuration would force workarounds and shadow configurations.
Keymate's customization model provides controlled flexibility: you change what you need through supported configuration surfaces, and the platform merges your overrides with the base defaults.
Where It Fits in Keymate
Customization applies after the platform is deployed (see Helm-Based Installation or GitOps-Based Installation) and throughout the operational lifecycle. It connects to:
- Tenant Onboarding — each new Tenant can receive Tenant-specific configuration
- Multi-Environment Management — each environment (dev, staging, production) can have its own overrides
- Runtime — scaling and performance tuning is a form of customization
Boundaries
This page covers:
- Customization levels (platform, Tenant, environment)
- What categories of settings can be customized
- How the override model works (base + layers)
- The relationship between Helm values, GitOps configuration, and runtime settings
This page does not cover:
- Specific configuration keys and their allowed values (deployment-specific)
- Authorization policy authoring (see Concepts — Policy Model)
- Identity provider realm configuration (see Integrations)
How It Works
Three Customization Levels
The platform applies configuration in layers, from broadest to most specific:
Each level can override the previous one. If no override is set, the parent level's value applies.
| Level | Scope | Example |
|---|---|---|
| Platform | All Tenants, all environments | Default replica counts, base resource limits, shared feature flags |
| Tenant | One Tenant, all its environments | Tenant-specific domain, identity federation, custom branding |
| Environment | One Tenant, one environment | Production-specific scaling, dev-only debug settings |
What Can Be Customized
| Category | Examples | Level |
|---|---|---|
| Component enablement | Enable or disable optional components (e.g., observability platform, specific integrations) | Platform, Tenant |
| Resource allocation | CPU requests/limits, memory, replica counts, storage sizes | Platform, Environment |
| Identity configuration | Authentication flows, federation settings, session policies, branding | Tenant |
| Authorization model | Policy structure, role definitions, relationship model | Tenant |
| Networking | Domain names, TLS settings, ingress rules | Tenant, Environment |
| Feature flags | Enable or disable platform features per Tenant or environment | Platform, Tenant, Environment |
| Observability | Telemetry export destinations, alert rules, dashboard configuration | Platform, Environment |
| Scaling | Horizontal pod autoscaler settings, minimum/maximum replicas | Environment |
Override Model
The override model follows a clear priority: environment overrides Tenant, Tenant overrides platform defaults.
When the platform starts a component, it merges all applicable configuration layers. Only the fields you explicitly override change — everything else inherits from the parent level.
Customization by Deployment Path
| Deployment path | How customization works |
|---|---|
| Helm | Override values through Helm values files. Use separate files per Tenant and environment, passed to helm install or helm upgrade via -f flags |
| GitOps | Override values are stored in the GitOps repository. Directory or file-based separation per Tenant and environment. ArgoCD applies the merged result |
Both paths use the same configuration model — the difference is how you store and apply the overrides.
Example Scenario
Scenario
Acme Corp has two Tenants on their Keymate platform: an internal HR division and an external customer-facing API. The HR division needs SAML federation with their corporate identity provider. The API Tenant needs higher replica counts in production due to traffic volume.
Input
- Actor: Platform Engineer
- Tenants:
hr-division,api-platform - Requirements: SAML federation for HR, higher scaling for API production
Expected Outcome
- Platform defaults apply to both Tenants (base resource limits, shared feature flags)
- HR division Tenant override adds SAML federation configuration
- API platform Tenant override sets higher base replica counts
- API platform production environment override further increases replicas and enables autoscaling
- Neither Tenant can see or affect the other's configuration
Common Misunderstandings
- "I need to modify platform source code to customize behavior." All customization happens through configuration surfaces (Helm values, GitOps files, platform settings). You do not need to change source code.
- "Tenant overrides affect other Tenants." Each Tenant's configuration is isolated. An override for one Tenant has no effect on any other Tenant.
- "I must override everything." You only override what needs to differ from the defaults. Unset fields inherit from the parent level automatically.
- "Helm and GitOps customization are incompatible." Both use the same configuration model. Migrating from Helm to GitOps (or vice versa) does not require reconfiguring the platform — only how overrides are stored and applied changes.
Avoid overriding platform defaults at the environment level unless necessary. The more overrides per environment, the harder it is to maintain consistency and troubleshoot issues. Override at the broadest applicable level.
Design Notes
- The layered override model is intentionally simple: platform → Tenant → environment. The inheritance chain never goes deeper than three levels.
- All configuration is declarative. The platform reads the merged configuration at startup or when a sync triggers — there are no imperative "set this value" commands.
- The platform enforces customization boundaries. Tenants cannot override platform-level security settings, and environment overrides cannot break Tenant isolation.
Document your customization decisions. Keep a record of what was overridden and why, especially at the Tenant and environment levels. This makes troubleshooting easier when behavior differs between environments.