> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Customizing values
> Configure and customize your applications using inputs and per-installation overrides
Inputs let you customize how an application deploys without modifying its underlying source. Akua provides a wizard-driven editor that lets you configure applications, manage changes, and control how updates roll out to installations.
For most customers, the dashboard's wizard is all you need. For advanced edits — patching individual fields, adding sidecars, overriding what the schema doesn't expose — see [Customize an installation via git](/installs/install-repo). Both surfaces edit the same underlying state: the wizard writes to your installation's `inputs.yaml`, and accepted repository changes update that same state.
## Understanding inputs
Inputs are YAML configuration that drive how an application is rendered for a specific installation. They control everything from resource allocations and scaling behavior to application-specific settings and networking configuration.
When you customize inputs, Akua:
* Writes the change to the installation's `inputs.yaml`
* Re-renders the deployment manifests against the package's composition logic
* Validates inputs against the package's input schema when available
* Commits the new render to the installation's [package repository](/installs/repositories)
The wizard and repository review path are two views over the same state. UI edits and accepted repository changes converge on the same `inputs.yaml`.
## Multi-source configuration
Many applications combine multiple package sources — for example, a web application with a database, cache, and monitoring stack. Akua's editor provides a tabbed interface where you configure each source independently while applying all changes in a single transaction.
### Using the multi-source editor
When editing inputs for products or installations with multiple sources:
1. **Switch between sources** using the tabs at the top of the editor
2. **Edit each source** independently in YAML or form view
3. **Track modifications** with visual indicators (orange dots) on tabs that have been changed
4. **Apply all changes** at once with the "Apply All" button
The editor shows:
* **Modified badge** - Count of sources with unsaved changes
* **Source tabs** - All sources displayed as switchable tabs
* **YAML/Form toggle** - Switch between raw YAML and guided form interface
* **Diff highlighting** - See exactly what differs from defaults
The form view provides a structured interface when the package exposes a JSON Schema. Use YAML view for advanced configurations or sources that don't expose a schema.
## Package defaults and install inputs
Akua distinguishes between **Package version defaults** (the install contract shared by Products, Offers, and direct installs) and **install-level inputs** (per-installation customization). Understanding this distinction is crucial for managing updates effectively.
### Package version defaults
Package version defaults define the starting configuration for future installations. When you publish a new Package version:
1. **Package version created** - The new configuration becomes the default for new installs that select it
2. **Existing installs unchanged** - Current installs continue running on their selected Package version
3. **New installs use updated inputs** - Future installations get the new defaults when their Product, Offer, or direct install selects that version
4. **Manual rollout required** - You control when existing installs move to the new version
**Use Package version defaults when:**
* Setting default configuration for all customers
* Preparing new features or settings
* Testing changes before wide rollout
* Managing staged installs
### Direct install inputs
Direct installations select a Package version without a Product or Offer wrapper. When you update inputs for a direct install:
1. **`inputs.yaml` updated immediately** - Changes are written to the installation's repository
2. **Re-rendered** - The new configuration is rendered into the installation's `manifests/`
3. **Application redeploys** - The new configuration is applied to your cluster after the render succeeds
4. **Single installation affected** - Only this specific install changes
**Use direct install inputs when:**
* Configuring customer-specific installations
* Making one-off customizations
* Testing configurations for specific environments
* Managing independent installs
### Product-based install overrides
Product-based installations support **per-install input overrides** that layer on top of Package version defaults. When you customize inputs for a product-based install:
1. **Overrides stored separately** - Your customizations are saved as install-specific overrides
2. **Package defaults preserved** - The selected Package version remains unchanged
3. **Inputs merged automatically** - Package version defaults + install overrides are merged into `inputs.yaml`
4. **Updates persist** - Overrides survive Package version updates
5. **Application redeploys** - The new merged configuration is applied to your cluster
**Use product-based install overrides when:**
* Customizing installations for specific customers (custom domains, branding, resource limits)
* Enabling customer-specific features or toggles
* Adjusting configurations per environment (production vs staging)
* Maintaining customer settings across Package version updates
Install overrides always take precedence over Package version defaults. When an installation moves to a newer Package version, customer overrides are automatically merged with the new defaults, ensuring customizations persist.
## Input layering and merging
Akua uses a layered approach to merge inputs from multiple sources, ensuring predictable and maintainable configurations.
### Merge order
Inputs are merged in the following order (later layers override earlier ones):
1. **Upstream defaults** - Defaults defined in the package's source
2. **Package version defaults** - Defaults configured in the selected Package version
3. **Install overrides** - Customer-specific overrides for product-based installs
4. **Install metadata** - System-generated values like the installation ID, which is available in your package's composition logic via the install's metadata context
### Deep merging
Akua performs deep merging of nested objects:
```yaml theme={null}
# Package version defaults
database:
host: "prod-db.example.com"
port: 5432
ssl: true
# Install override
database:
host: "customer-db.example.com"
# Final merged result
database:
host: "customer-db.example.com" # Overridden
port: 5432 # From Package version
ssl: true # From Package version
```
Arrays are replaced entirely rather than merged:
```yaml theme={null}
# Package version defaults
features:
- "basic"
- "standard"
# Install override
features:
- "basic"
- "premium"
# Final merged result
features:
- "basic" # Completely replaced
- "premium" # Not merged
```
When customizing inputs, you only need to specify the keys you want to override. All other Package version defaults are automatically included in the merged configuration.
## Version management and rollouts
When you publish a new Package version, existing installations are not updated automatically. This gives you precise control over when and how updates roll out to your customers.
### The update workflow
```mermaid theme={null}
flowchart TB
A[Update Package defaults] --> B[New Package version]
B --> C{Choose rollout strategy}
C -->|Single install| D[Update one installation]
C -->|Bulk update| E[Update all installations]
D --> F[Installation updated]
E --> F
```
### Viewing available updates
Each product installation shows its current Package version and whether updates are available:
* **Current version badge** - Shows the Package version currently deployed
* **Latest version badge** - Shows the newest available Package version
* **Update available indicator** - Orange badge when install is behind latest
### Rolling out to a single install
To update a specific installation:
1. Navigate to the product's installations list
2. Click **Update** on the installation row
3. Review the change (current Package version → latest Package version)
4. Confirm the update
The installation updates to the latest Package version immediately. Use this approach for:
* Testing updates with a pilot customer
* Staggered rollouts across customers
* Customer-requested upgrades
* Selective deployment strategies
### Rolling out to all installs
To update all installations at once:
1. Navigate to the product details page
2. Click **Update All Installs** in the installations section
3. Review the update scope (shows count of installations)
4. Confirm the bulk update
All installations update to the latest Package version simultaneously. Use this approach for:
* Security patches requiring immediate deployment
* Critical bug fixes
* Coordinated feature releases
* Simplified version management
Bulk updates execute in parallel but you can monitor each installation's progress individually. Failed updates don't block others from completing.
## Editing inputs
### For products
1. Navigate to your product details page
2. Click the **Values** button in the header
3. Configure each source using the tabbed interface:
* Switch between sources using tabs
* Edit in YAML or form view
* Track changes with modification indicators
4. Click **Apply All** to save changes
This creates a new Package version for the Product to sell. Existing installations continue running the previous version until you choose to update them.
### For product-based installations
1. Navigate to the installation details page (must not be the product owner)
2. Click the **Values** button in the header
3. Configure each source using the tabbed interface
* You'll see merged inputs (Package version defaults + any existing overrides)
* Changes are stored as install-specific overrides
4. Click **Apply All** to save changes
This creates install overrides that layer on top of Package version defaults and triggers an immediate redeployment with the merged configuration.
Product owners cannot edit inputs for product-based installations directly (this would affect all customers). They must update the product instead. Only customers (non-owners) can create install-specific overrides.
### For direct installations
1. Navigate to the installation details page
2. Click the **Values** button in the header
3. Configure each source using the tabbed interface
4. Click **Apply All** to save changes
This updates the installation's `inputs.yaml` and triggers an immediate redeployment with the new configuration.
Changes to direct installations and product-based install overrides take effect immediately. Review configurations carefully before applying.
## Status tracking
Akua provides real-time status indicators during input updates:
| Status | Description |
| ---------------- | ----------------------------------------------------------------- |
| **Saving...** | Writing updated inputs to the installation repository |
| **Packaging...** | Rendering the new configuration into the installation's manifests |
| **Deploying...** | Applying changes to your cluster (direct installs only) |
Progress appears on the Values button, allowing you to monitor the update without blocking other work.
## Best practices
### Version control strategy
* **Update Package versions first** - Make package changes before rolling out to installs
* **Test with single install** - Verify configuration with one customer before bulk updates
* **Use semantic versioning** - Akua automatically versions packages; treat major updates carefully
* **Document changes** - Keep notes on what changed in each version
### Multi-source configuration
* **Configure all sources together** - Use the multi-source editor to apply changes atomically
* **Review modifications** - Check the modified sources count before applying
* **Validate YAML syntax** - The editor warns about syntax errors before applying
* **Use form view for structure** - Form view prevents common YAML formatting mistakes
### Rollout management
* **Pilot test updates** - Start with a single installation for new configurations
* **Stagger large rollouts** - Consider updating installations in batches for large products
* **Monitor after updates** - Check installation health after rolling out changes
* **Keep previous versions** - Don't delete old Package versions until all installs are migrated
### Install overrides
* **Minimize overrides** - Only override inputs that truly need to be customer-specific
* **Use Package version defaults** - Set sensible defaults in the Package version for common configurations
* **Document overrides** - Keep notes on why specific inputs were overridden for each customer
* **Test Package version updates** - Verify that Package version changes merge correctly with install overrides
* **Review periodically** - Check if overrides are still necessary as Package version defaults evolve
### Security considerations
* **Never commit secrets** - Use environment variables and secret management for sensitive data
* **Review inputs before applying** - Especially when using form view which may expose all fields
* **Limit who can update** - Package version defaults affect future customers and rollouts; restrict access appropriately
* **Audit changes** - Every input change is a commit in the installation repository — use git history to track who changed what and when
## Common scenarios
Update CPU and memory limits to scale applications. For products, publish a Package version with new defaults and roll out to installations that need more resources. For direct installs, update inputs directly.
Many packages use feature flags in inputs. Enable features in a new Package version, then selectively update installations as customers opt in.
Use direct installations for environment-specific installs (dev, staging, production). Each can have different inputs while sharing the same base package.
Update database URLs or connection parameters by editing inputs. For products, create a new Package version with updated defaults. For direct installs, update directly to reconfigure immediately.
Adjust replica counts, autoscaling settings, and resource requests. Test with a single installation first, then roll out to others once validated.
Use per-install input overrides for product-based installations when customers need unique configurations. Navigate to the installation details page and edit inputs to create customer-specific overrides for custom domains, resource limits, feature toggles, or any other settings. These overrides layer on top of Package version defaults and persist across version updates, giving you the benefits of centralized package management while supporting customer-specific customizations.
## Troubleshooting
### Changes not applying
If input changes don't take effect:
* **Check syntax** - Ensure YAML is valid with proper indentation
* **Review status** - Wait for "Packaging..." status to complete
* **Verify rollout** - For products, ensure you've updated the installations
* **Check logs** - View application logs for deployment errors in the installation details page
### Schema validation errors
If the form view shows validation errors:
* **Check required fields** - Some inputs must be provided
* **Verify data types** - Ensure numbers, strings, and booleans match schema
* **Switch to YAML** - Use YAML view for complex configurations
* **Consult package docs** - Review the package's documentation for input requirements
### Installation not updating
If an installation doesn't update after rollout:
* **Review version** - Verify the installation is pointing to the new Package version
* **Check status** - Look for errors in the installation details page
* **Check deployment** - Ensure the application is deploying successfully
## Related topics
Create and manage products with configurable inputs.
Install applications on your infrastructure.
How Akua generates packages.
How commit history maps to installs.