Configure a Dedicated Cloud Service for a Datastore
A dedicated cloud service is a Cassandra or PostgreSQL instance that the C3 Agentic AI Platform runs for one application or environment. When you start the service, the platform points the datastore of that application or environment at the new service: the key-value (KV) datastore for Cassandra, or the SQL datastore for PostgreSQL. Choose a dedicated service when an application or environment needs its own datastore with its own storage, CPU, and memory sizing.
On this page, you configure a dedicated Cassandra service or a dedicated containerized PostgreSQL service. For each service, you set the configuration, start the service, check its status, and remove it when you no longer need it.
Before you begin
Review the following requirements before you start:
- Permissions: To start a service, you need the
C3.ClusterAdminrole. For a service of your environment, theC3.EnvAdminrole is enough. For a service of one application, you can also run the steps in that application. Restarting an application needs an application administrator (C3.AppAdmin), and restarting all applications in an environment needs theC3.EnvAdminrole. - Console: Run every step in the C3 AI Console of the application or environment that the service serves. Run the steps of one procedure in the same Console session, because later steps use the variable that the first step creates.
- Cost: A dedicated service adds computing resources and increases cost.
Starting a dedicated service restarts C3 AI server nodes so that they use the new datastore. The application or environment is unavailable while its nodes restart. Plan the change for a maintenance window.
Configure a dedicated Cassandra service
Complete the following steps to configure a dedicated Cassandra service:
- Set the Cassandra service configuration
- Start the Cassandra service
- Check the Cassandra service status
- Remove the Cassandra service when you no longer need it
Set the Cassandra service configuration
Create a handle for the new service, then set its sizing. withRoleAndSeq() gives the service the next free ID for the current application, so you do not set an ID yourself. To create an environment-level service, run these steps in the C3 AI Console of the environment instead of an application.
The following script is an example sized for a large production load. Replace each value with the size your workload needs, and leave out any setting where the default fits:
var cassandra = CassandraDB.make().withRoleAndSeq();
var c = cassandra.config();
c = c.withField("heapSize", "12000M");
c = c.withField("storageSize", "1024Gi");
c = c.withField("ringSize", 3);
c = c.withField("cpuLimits", "8");
c = c.withField("cpuRequests", "8");
c = c.withField("memoryLimits", "64Gi");
c = c.withField("memoryRequests", "64Gi");
c.setConfig();The script creates an instance of the CassandraDB Type and stores its configuration with setConfig(). setConfig() writes the configuration for the application whose Console you run it in.
A pod is the running container that hosts Cassandra in Kubernetes. The following table describes each setting and when to change it:
| Setting | Default | Description | When to change it |
|---|---|---|---|
heapSize | 512M | Memory for the Cassandra Java heap | Raise it for large data loads. A value that is too low causes frequent garbage collection; a value that is too high causes long garbage collection pauses. |
storageSize | 30Gi | Size of the persistent volume that holds the Cassandra data files | Raise it to fit the data volume you expect to store. |
ringSize | 1 | Number of nodes in the Cassandra ring | Raise it to partition and replicate data across more nodes. |
storageClassName | Empty | Kubernetes StorageClass for the persistent volume | Leave it empty to use the cloud provider's default storage class. Set it only when you need a specific storage class. |
cpuLimits | 8 | Maximum CPU the Cassandra pod can use | Change it together with cpuRequests when you resize the service. |
cpuRequests | 8 | CPU reserved for the Cassandra pod | Match it to cpuLimits to reserve the full CPU allocation. |
memoryLimits | 64Gi | Maximum memory the Cassandra pod can use | Raise it when you raise heapSize. |
memoryRequests | 64Gi | Minimum memory reserved for the Cassandra pod | Match it to memoryLimits to reserve the full memory allocation. |
To learn more about storage classes, see Storage Classes in the Kubernetes documentation.
To review the configuration before you start the service, run the following code:
cassandra.config();
cassandra.config().allConfigOverrides();The first line returns the service configuration with the values you set. The second line returns the values set at each override level.
setConfig() only stores the configuration. The application or environment keeps using its current datastore until you start the service in the next step.
Start the Cassandra service
Start the service with ensureService(). This call deploys Cassandra with your configuration, points the KV datastore at the new service, and restarts C3 AI server nodes so that they use it. The new service starts empty. The platform does not copy existing data from the previous datastore.
Run the following code to start the service. ensureService() accepts its options as a plain object, as in this example, or as a CloudServiceStartSpec, as in the PostgreSQL procedure.
cassandra.ensureService({
waitForReady: true,
restartAllServers: true
});The call uses the following options:
waitForReady: Whentrue, the call returns after the service status isavailable, which means the platform can connect to the service.restartAllServers: Controls which C3 AI server nodes restart:true: Restarts every server node that uses the service. For a cluster-level service, that is all environments; for an environment-level service, all its applications; for an application-level service, the application. Choosetruefor an environment-level service so that every application in the environment uses the new datastore.false: Restarts only the application that the service belongs to.
Check the Cassandra service status
Run the following code to check the status of an application-level service:
CassandraDB.listForApp()[0].statusFor an environment-level service, use CassandraDB.listForEnv() instead. Both methods list the services of the current application or environment when you call them without an argument. The status is available when the service is running.
To send a request to the Cassandra service that the KV datastore uses, run the following code:
Cassandra.inst().ping()Cassandra.inst() returns the Cassandra connection of the current application, and ping() checks that the service responds.
To check that the application or environment can read data from the KV datastore, run the following code:
NormalizedTimeseries.fetch();The NormalizedTimeseries Type is stored in the KV datastore, so the call returns a fetch result when the datastore is running.
You can also view cloud services in C3 AI Studio. See View Cloud Services and Manage Resources.
Remove the Cassandra service
To remove a dedicated Cassandra service, terminate the application or environment that it serves. When you terminate the application or environment, the platform terminates its dedicated services and clears the datastore settings that point to them. Terminating the service on its own fails while an application's KV datastore still points to it. See Manage Environments and Applications in C3 AI Studio to learn how to terminate an application or environment.
Terminating the service keeps its stored data. To delete the data, contact C3 AI Operations.
Configure a dedicated PostgreSQL service
The C3 Agentic AI Platform supports two kinds of PostgreSQL service:
- Managed: Hosted by an external cloud provider. Managed is the default. To set up a managed PostgreSQL service, contact C3 AI Operations.
- Containerized: Hosted by C3 AI in the cluster. Choose this option when you want the platform to run PostgreSQL for the application or environment.
Complete the following steps to configure a containerized PostgreSQL service:
- Set the PostgreSQL service configuration
- Start the PostgreSQL service
- Check the PostgreSQL service status
- Remove the PostgreSQL service when you no longer need it
Set the PostgreSQL service configuration
Create a handle for the new service, then set its sizing. As with Cassandra, withRoleAndSeq() gives the service the next free ID. To create an environment-level service, run these steps in the C3 AI Console of the environment.
The following script is an example sized for a large production load. Replace each value with the size your workload needs, and leave out any setting where the default fits:
var pg = PostgresDB.make().withRoleAndSeq();
var c = pg.config();
c = c.withField("persistenceSize", "1024Gi");
c = c.withField("resourcesLimitsCpu", "8");
c = c.withField("resourcesRequestsCpu", "8");
c = c.withField("resourcesLimitsMemory", "64Gi");
c = c.withField("resourcesRequestsMemory", "64Gi");
c.setConfig();The script creates an instance of the PostgresDB Type and stores its configuration with setConfig(). setConfig() writes the configuration for the application whose Console you run it in.
The following table describes each setting and when to change it:
| Setting | Default | Description | When to change it |
|---|---|---|---|
persistenceSize | 100Gi | Size of the persistent volume that stores PostgreSQL data | Raise it to fit the data volume you expect to store. |
resourcesLimitsCpu | 400m | Maximum CPU the PostgreSQL pod can use | Raise it for heavy query or write loads. |
resourcesRequestsCpu | 400m | CPU reserved so that the pod can start and run reliably | Match it to resourcesLimitsCpu to reserve the full CPU allocation. |
resourcesLimitsMemory | 4Gi | Maximum memory the PostgreSQL pod can use | Raise it for large working sets. |
resourcesRequestsMemory | 4Gi | Memory reserved so that the pod can start and run reliably | Match it to resourcesLimitsMemory to reserve the full memory allocation. |
To review the configuration before you start the service, run the following code:
pg.config();
pg.config().allConfigOverrides();The first line returns the service configuration with the values you set. The second line returns the values set at each override level.
Start the PostgreSQL service
Start the service with ensureService() and the notManaged option. ensureService() deploys the service, points the SQL datastore at it, and restarts the application that the service belongs to. The new service starts empty, and the platform does not copy existing data from the previous datastore. notManaged: true selects the containerized service instead of a managed one.
Run the following code to start the service:
pg.ensureService(CloudServiceStartSpec.make({notManaged: true}));For an environment-level service, also restart every application in the environment so that each one uses the new datastore. Choose one of the following options:
Add
restartAllServers: trueto restart the applications as part of the start:JavaScriptpg.ensureService(CloudServiceStartSpec.make({notManaged: true, restartAllServers: true}));Run
C3.env().restartApps()later to restart the applications at a time you choose, for example in a maintenance window:JavaScriptC3.env().restartApps();
Check the PostgreSQL service status
Run the following code to check the status of an application-level service:
PostgresDB.listForApp()[0].statusFor an environment-level service, use PostgresDB.listForEnv() instead. The status is available when the service is running.
You can also view cloud services in C3 AI Studio. See View Cloud Services and Manage Resources.
Remove the PostgreSQL service
To remove a dedicated PostgreSQL service, terminate the application or environment that it serves. When you terminate the application or environment, the platform terminates its dedicated services and clears the datastore settings that point to them. Terminating the service on its own fails while an application's SQL datastore still points to it. See Manage Environments and Applications in C3 AI Studio to learn how to terminate an application or environment.
Terminating the service keeps its stored data. To delete the data, contact C3 AI Operations.