Skip to main content

Configuration Stores

Configuration Stores let administrators curate named collections of configuration properties that extensions can read at runtime. This keeps cluster endpoints, credentials, tuning parameters, and similar values out of extension bundles and environment files, and gives a single place to review, edit, and rotate them.

The feature is reached from the Configuration item in the left navigation. This page is distinct from the Configuration Reference, which documents Symphony's own server-side configuration files.

How Configuration Is Organised​

Configuration is organised as a three-level hierarchy:

  • Store — a named backend that holds configuration. A store is either built into Symphony or delegates to an external secrets backend (see Store Types).
  • Collection — a named group of key/value properties within a store. A collection usually corresponds to a logical scope, such as the config for one HDFS cluster or one replication target.
  • Property — a single key / value pair. Both sides are plain strings.

Stores and collections appear in the tree on the left of the Configuration page. Selecting a collection shows its properties in a table on the right. Property values are masked by default — click the eye icon on any row to reveal a single value. Local collections are editable in this table; collections backed by an external store are read-only and resolve their values from the backend at request time (see Read-only collections).

Store Types​

When you create a store you choose its type. All five store types are supported.

TypeWhat it storesTypical use
Cirata Symphony (built-in)Property values are held locally, inside Symphony's own storage.Non-secret configuration, development, or deployments that do not use an external secrets manager.
HashiCorp VaultReferences into a Vault KV v2 secrets engine. Needs a client token and the Vault address.Environments already using Vault for secret management.
AWS Secrets ManagerReferences into AWS Secrets Manager secrets. Needs region and AWS credentials.AWS deployments.
Google Secret ManagerReferences into Google Secret Manager secrets. Needs a project ID and a service-account JSON key.GCP deployments.
Azure Key VaultReferences into an Azure Key Vault secret. Needs the vault URL and a service-principal credential.Azure deployments.

HashiCorp Vault​

A HashiCorp store points at a Vault instance using its Address (e.g. http://vault.internal:8200) and a Client Token with read/list access to the KV v2 engine. Two optional fields are also accepted:

  • KV Mount — the mount path of the KV v2 engine. Defaults to secret.
  • Namespace — Vault Enterprise namespace. Two stores on different namespaces resolve disjoint trees even when they share an address and token.

Symphony validates the token against auth/token/lookup-self when the store is created, so misconfigured stores are rejected at create time.

Collection names map directly to Vault paths under the KV mount: a collection named app/db-config resolves to secret/data/app/db-config.

AWS Secrets Manager​

An AWS store needs the Region (e.g. us-east-1), an Access Key ID, and a Secret Access Key. A Session Token is required only when using temporary STS credentials. Symphony validates the credentials with sts:GetCallerIdentity at create time — a default-allowed action — so credential errors surface immediately even for tokens that don't yet have Secrets Manager permissions.

Each collection maps to one secret in AWS Secrets Manager, addressed by name. The secret's value is expected to be a JSON object whose keys become the collection's properties:

{ "host": "db.example.com", "port": "5432", "user": "symphony" }

A secret whose value is plain text (not JSON) is surfaced as a single property whose key matches the collection name — useful for secrets that hold a single token. The IAM principal needs secretsmanager:GetSecretValue for resolve and secretsmanager:ListSecrets for the Browse picker in the Add Collection drawer.

Google Secret Manager​

A GCP store needs the Project ID (e.g. my-gcp-project) and a Service Account JSON key — the full contents of a key file generated for a service account that has at least roles/secretmanager.viewer on the project (covers both list and access). Symphony validates the credentials by attempting a one-page list at create time, so credential errors surface immediately.

Each collection maps to one secret in Secret Manager, addressed by short name (the resolver expands it to projects/<project>/secrets/<name>/versions/latest). The secret's value is expected to be a JSON object whose keys become the collection's properties:

{ "host": "db.example.com", "port": "5432", "user": "symphony" }

A secret whose value is plain text (not JSON) is surfaced as a single property whose key matches the collection name — same fallback as the AWS resolver.

The Browse picker uses GCP's standard list-filter syntax (name:prefix*), so typing a prefix in the collection name field narrows the listing.

Azure Key Vault​

An Azure store needs the Vault URL (e.g. https://my-vault.vault.azure.net) and a service-principal credential: Tenant ID, Client ID, Client Secret. The principal needs at least the Get and List data-plane permissions on the vault — granted via either the legacy access policies or the Key Vault Secrets User Azure RBAC role. Symphony validates the credentials with a one-page list at create time.

Each collection maps to one secret in the Key Vault, addressed by name. Azure Key Vault secret names accept only alphanumerics and hyphens ([a-zA-Z0-9-]+); collections that include other characters cannot be represented in this backend, and the Azure API will reject them. The secret value is expected to be a JSON object whose keys become the collection's properties:

{ "host": "db.example.com", "port": "5432", "user": "symphony" }

A secret whose value is plain text (not JSON) is surfaced as a single property whose key matches the collection name.

The Browse picker lists every secret in the vault and filters client-side by the typed prefix — Azure Key Vault has no server-side name filter.

Creating a Store​

  1. Open the Configuration page from the left navigation.
  2. Click Add Store.
  3. Enter a Name for the store.
  4. Choose a Store Type. If you pick an external type, fill in the required connection properties.
  5. (External stores) Click Test Connection to probe the backend with the entered credentials. Symphony runs the type's validate probe (Vault: lookup-self; AWS: sts:GetCallerIdentity; GCP / Azure: a one-page list) and reports success or the underlying error inline.
  6. Optionally add Notes.
  7. Click Create. Symphony validates the credentials again, encrypts the connection properties (see Credential storage), and writes the store record.

Editing a Store​

Open the store from the tree and click Edit. The drawer pre-fills the name and notes. The store type cannot be changed after creation. Connection properties show empty: leave them all blank to update only name or notes; fill in every required field to rotate the credentials, which re-seals the entire envelope.

Creating a Collection​

  1. Click Add Collection at the top of the tree, or use the + on a store row to pre-select that store.
  2. Choose the Store that should hold the collection. This is pre-selected if you opened the drawer from the + affordance.
  3. Enter a Name for the collection.
    • For local stores this is a free-text label.
    • For external stores the field is a Browse picker — Symphony lists the secrets available in the backend so you can pick one. You can still type a name that does not yet exist if you are about to create the secret in the backend.
  4. Optionally add Notes.
  5. Click Create.

Add Collection is disabled until at least one store exists; create a store first.

Adding Properties (local collections)​

Local collections own their values directly. Properties can be added one at a time in the properties table, or imported from a file. External collections do not use this flow — see Read-only collections.

Manual Entry​

With a collection selected, use the Add Property row in the properties table to enter a key and value. Changes are held locally until you click Save Changes.

Import​

The Import button on a collection reads a file from disk and appends the parsed properties to the collection's existing list. It does not replace existing entries. If you want to replace, delete the existing rows first. Imports are not saved automatically — review the appended rows and then click Save Changes.

Two file formats are supported.

CSV​

One property per line, key,value:

fs.defaultFS,hdfs://nn:8020
dfs.replication,3

A leading header row of key,value or name,value is automatically skipped. Surrounding quotes on the key or value are stripped. The first comma on each line separates the key from the value; further commas are kept as part of the value, so "a","x,y,z" produces a single property with value x,y,z.

Hadoop XML​

Hadoop *-site.xml files (for example core-site.xml, hdfs-site.xml, hive-site.xml) can be imported directly. The file must use <configuration> as the root element and list properties using the standard <property><name>…</name><value>…</value></property> shape:

<?xml version="1.0"?>
<configuration>
  <property>
    <name>fs.defaultFS</name>
    <value>hdfs://nn:8020</value>
  </property>
  <property>
    <name>dfs.replication</name>
    <value>3</value>
  </property>
</configuration>

Hadoop's <final>, <description>, and <source> elements are ignored. A property with a missing or empty <value> is imported with an empty string. Properties missing a <name> are skipped. Duplicate names are preserved in order — if you want last-wins semantics, remove the earlier entries manually after import.

Import Errors​

Invalid files are rejected and reported in an alert above the properties table. Common failures:

  • The file is not valid XML — the file could not be parsed. Check for truncation or stray characters.
  • Expected a Hadoop configuration file with a <configuration> root element — the XML parses but uses a different root. Confirm the file is a Hadoop site config, not a different XML format.
  • No <property> entries with a <name> were found in the file — the file is valid XML but has no importable properties.
  • Could not read "…" — the browser could not read the bytes of the file. This most often affects files kept in cloud-synced folders (Google Drive File Stream, OneDrive, iCloud) whose contents are not present locally. Mark the file for offline use, or copy it to a local folder, and try again.

Read-only collections (external stores)​

When the selected collection lives in an external store, the properties table renders as read-only: a "Read-only" chip appears in the header and the Add / Remove / Save / Cancel / Import affordances are hidden. The values are fetched from the backend each time the collection is opened. To change a value, edit the underlying secret in the backend store; the next open of the collection in Symphony will reflect the change.

Property values are masked by default. Use the per-row eye icon to reveal a single value.

Exporting a Collection​

Click Export CSV on a collection to download its current properties as a CSV file named <collection>-properties.csv. XML export is not currently supported — CSV is a lossless export for the data held in the collection, since properties are stored as flat key/value pairs regardless of the original import format.

Credential storage​

Connection properties for external stores (Vault tokens, AWS / GCP / Azure credentials) are encrypted with AES-256-GCM before they are written to Symphony's storage. A leaked store record reveals only ciphertext; the master key never leaves the Symphony process. See Security § Configuration Store Credential Sealing for the full threat model and rotation considerations.

Stores created on older builds — before sealing landed — are re-sealed automatically the first time the Configuration page loads them; no operator action is required.

Editing and Deleting​

  • Editing a property (local collections only) — click a cell in the properties table to edit it. Changes are held locally and take effect after Save Changes.
  • Reverting (local collections only) — Cancel discards local changes and reloads the collection from the server.
  • Editing a store — use the Edit button on the store's detail panel. See Editing a Store.
  • Deleting a collection — use the Delete button in the collection's header. The deletion cannot be undone. For external collections, this only removes Symphony's reference; the secret in the backend store is not touched.
  • Deleting a store — use the Delete Store button on the store's detail panel. If the store still holds collections, the button reads Delete Store and N Collection(s) and the confirmation prompt warns that those collections will be deleted alongside the store. Deletion cannot be undone.

See Also​

  • Configuration Reference — Symphony's own server-side configuration files (a distinct topic).
  • Security — how Symphony authenticates users and protects service-to-service traffic.