Best Practices for Managing Controller Services

Modified on Thu, 11 Dec, 2025 at 9:35 PM

Controller services are central to reliable Clockspring deployments. Following these practices helps avoid configuration drift, keeps environments consistent, and reduces surprises when promoting flows or updating shared services.

1. Reuse controller services instead of cloning them

If multiple processors need the same configuration, reference a single controller service.
Cloned services drift over time and make updates harder.

Examples of configs that should never be duplicated:

Database connection pools
SSL context services
OAuth/JWT token providers
Record readers/writers
Cache services

2. Use clear, descriptive names

Names should describe what the service does and which environment it applies to.

Good:

DBCP_Postgres_Prod
SSL_Internal_CA
OAuth_GCPServiceAcct

Avoid ambiguous labels like DBCP1, CacheTest, or ssl_new.

3. Choose the correct scope before creating the service

Controller services inherit downward. They do not inherit upward or sideways.

Before creating a new service, decide:

Does this need to be available everywhere? → create at Root Canvas
Is this specific to one flow or use case? → create inside that Process Group

Fixing scope after the fact is more work than planning it.

4. Use parameters for environment-specific differences

Instead of hardcoding differences in each controller service (URLs, usernames, passwords, API tokens), use parameters. This keeps services identical across environments while letting the parameter context provide environment-specific values.

Common things to parameterize:

Database hostnames and ports
API endpoints
Basic auth credentials
OAuth client IDs and secrets
File paths for certificates

Parameters + controller services is the cleanest promotion model.

5. Understand the blast radius before modifying a service

Changing a controller service affects every processor referencing it.
Clockspring shows the exact list in the Referencing Components panel (see image).

When modifying:

Check the referencing components list
Confirm you’re not about to break sibling or parent flows
Avoid modifying at peak times
Use parameterized values so you can rotate credentials with minimal disruption

High-risk changes include:

SSL truststore/keystore rotation
Database credential changes
Token provider configuration changes
Driver changes

6. Version and migrate controller services intentionally

Clockspring Registry and manual exports both support including controller services, but you must decide when they come along.

Two important points:

Registry versioning:
Controller services in the same process group as your versioned flow are included automatically.
Manual download/export:
Clockspring will ask whether you want to include controller services.
If you exclude them, the destination environment must already have matching services, or processors will show as invalid.

Be consistent. Decide whether controller services should travel with the flow or be maintained separately at the environment level.

7. Avoid embedding credentials in processor properties

Use controller services or parameters for authentication.