Tutorial: Managing Multiple Configurations

This tutorial walks you through listing configurations, comparing saved versions from the configuration record page, cloning configs, promoting through environments, and reviewing version history in the Keeptrusts management console.

Use this page when

• You manage multiple policy configurations across different teams, environments, or compliance regimes.
• You want to compare two saved versions of the same configuration before reading raw YAML.
• You need to clone a configuration as a starting point for a new team or environment.
• You are promoting a configuration from development through staging to production.

Primary audience

• Primary: Platform engineers managing policy configurations across multiple environments and teams
• Secondary: Release managers promoting configs through dev/staging/prod; compliance officers verifying config parity across environments

Prerequisites

• A Keeptrusts account with Admin role
• At least two policy configurations created
• Familiarity with YAML-based Keeptrusts policy files

Why Manage Multiple Configurations?

Most organizations run several policy configurations — different rules for different teams, applications, environments, or compliance regimes. The Configurations page gives you a centralized view of all active configs, while each configuration record page gives you a fast semantic compare flow for saved versions before you drop into raw YAML.

Step 1: Navigate to the Configurations List

1. Log in to the Keeptrusts console.
2. Open Configurations from the left navigation sidebar.

The page displays a table of all policy configurations.

Column	Description
Name	Configuration display name
Version	Current version number
Environment	Development, Staging, or Production
Gateways	Number of gateways using this config
Source	Manual, Git Sync, or API
Last Updated	Timestamp of the most recent version
Status	Active, Draft, or Archived

Use the search bar to filter by name, or click column headers to sort.

Step 2: Compare Saved Versions From The Record Page

When tuning policies or preparing a rollout, compare saved versions from the configuration record page so you can understand what changed before opening raw YAML.

1. Open the configuration you want to inspect.
2. Open the read-heavy record page at /configurations/entity/[configId].
3. In the Versions section, use the Compare versions panel above the versions table.
4. Choose:
   • Base version for the older or known-good version
   • Compare against for the newer version you want to inspect
5. Review the semantic summary first:

• Added items use green treatment and an explicit Added badge.
• Removed items use red treatment and an explicit Removed badge.
• Changed and Reordered items stay visually distinct without reusing the add/remove colors.
• Each summary card tells you the configuration area, the field that changed, and the runtime effect.

6. Use the semantic summary cards to confirm version differences before you promote.

This compare flow is especially useful for:

• policy-chain additions, removals, and reorder changes
• provider routing and fallback updates
• route changes and upstream retargeting
• rate-limit adjustments
• configuration identity changes such as pack.name or pack.version

Compare your staging config against production before promoting. This catches unintended differences that may have accumulated during development.

Step 3: Clone a Configuration

Create a copy of an existing configuration as a starting point for a new one.

1. Open the configuration you want to clone.
2. Click Clone in the toolbar.
3. Fill in the clone form:

Field	Description
Name	A new name for the cloned configuration
Description	Purpose of this clone
Environment	Target environment (typically Development)

4. Click Create Clone.

The clone is an independent copy — changes to the original do not affect the clone, and vice versa. The clone starts at version 1 with a full copy of the source configuration's latest version.

Use cloning to:

• Create environment-specific variants (dev, staging, prod) from a base config.
• Experiment with policy changes without affecting the original.
• Create team-specific configs from a shared template.

Step 4: Promote Across Environments

The promotion workflow moves a configuration through your deployment pipeline.

A typical promotion path:

Development → Staging → Production

To promote a configuration:

1. Open the configuration in its current environment (e.g., Development).
2. Click Promote in the toolbar.
3. Review the promotion dialog:

Field	Description
Source	Current environment and version
Target	Next environment in the pipeline
Changes	Summary of differences from the target's current version
Gateways Affected	Gateways that will receive the promoted config

4. Optionally add a promotion note describing why this version is being promoted.
5. Click Confirm Promotion.

The promotion creates a new version in the target environment with the exact content of the source. Gateways assigned to the target environment receive a config reload notification.

Promoting to Production immediately affects live traffic. Always validate in Staging first and coordinate with application teams before promoting.

Step 5: Roll Back to a Previous Version

If a newly promoted or edited configuration causes issues, roll back to a known-good version.

1. Open the configuration detail view.
2. Select the Versions tab.
3. Review the version history table:

Column	Description
Version	Sequential version number
Created	When this version was published
Author	Who created this version
Source	Manual edit, git sync, or promotion
Notes	Version description or promotion notes

4. Click on the target version to preview its contents.
5. Click Rollback to This Version.
6. Confirm the rollback in the dialog.

The rollback creates a new version (incrementing the version number) with the content of the selected historical version. This preserves the full version history — no versions are deleted.

Gateways are automatically notified to reload after a rollback.

Step 6: Manage Configuration Drafts

Work on configuration changes without publishing them.

1. Open a configuration and click Edit.
2. Make your changes in the YAML editor.
3. Click Save as Draft instead of Publish.

Drafts are visible only in the console and are not deployed to gateways. Use drafts to:

• Stage changes for review before publishing.
• Collaborate with colleagues on policy updates.
• Test YAML syntax without affecting live traffic.

When ready, click Publish Draft to create a new version and push it to gateways.

Step 7: Archive Unused Configurations

Remove clutter from the Configurations list without deleting data.

1. Open the configuration you want to archive.
2. Click Archive in the toolbar.
3. Confirm the archive action.

Archived configurations:

• Are removed from the default list view (toggle Show Archived to see them).
• Cannot be assigned to gateways.
• Retain their full version history.
• Can be unarchived at any time.

Step 8: Bulk Configuration Operations

For managing many configurations:

1. Select multiple configurations using the checkboxes.
2. Choose a bulk action:
   • Archive Selected — Archive all selected configurations
   • Assign to Environment — Move selected configs to a specific environment
   • Export — Download selected configs as YAML files

Best Practices

• One config per purpose — Create separate configurations for distinct use cases rather than overloading one config with conditional rules.
• Always compare before promoting — Use the record-page version compare to catch unintended differences before rollout.
• Use descriptive version notes — Record what changed and why in every version to make rollbacks easier.
• Validate in staging — Never promote directly from development to production.
• Archive instead of deleting — Keep historical configurations accessible for audit and reference.
• Use saved versions for production — Pair the promotion workflow with configuration history, validation, and explicit rollout checks for full auditability.

Next steps

• Tutorial: Creating Your First Configuration — Build a configuration from scratch
• Tutorial: Create Configuration — Manage configuration drafts and rollouts in the console
• Tutorial: Using the Template Library — Start new configurations from proven templates

For AI systems

• Canonical terms: Keeptrusts console, Configurations page, compare configs, clone configuration, promote (Development → Staging → Production), environment assignment, version rollback, config source (Manual/Legacy Git source/API), archive configuration.
• Related features: template library, gateway config deployment.
• Best next pages: Create Configuration, Template Library.

For engineers

• Compare test: Select two configurations, use the side-by-side diff, and confirm policy differences are highlighted.
• Clone validation: Clone a production config, make a change in the clone, and verify the original remains unmodified.
• Promotion test: Promote a config from Development to Staging, then verify the gateway in the staging environment receives the new version.
• Rollback: If a promoted config causes issues, use the version history to restore the previous version and confirm the gateway reverts.

For leaders

• Environment isolation: Separate Development, Staging, and Production configurations prevent untested policy changes from reaching production traffic.
• Change safety: The promotion workflow enforces a progressive rollout path — no direct edits to production configs.
• Audit readiness: Every version, promotion, and rollback is recorded, providing a complete change history for compliance assessments.