Deploying Services

This guide provides a comprehensive overview of the lifecycle of a managed service in Codesphere. It covers the practical steps for deploying, configuring, maintaining, and eventually deleting services.

Deploying Managed Services

Deploying a managed service can be done through the Codesphere UI or the public API.

A managed service can either be an independent deployment or integrated into the landscape lifecycle. This guide will cover how to deploy an independent service. For information on how to deploy services as part of a landscape, refer to the Managed Services in Landscapes section.

UI

1. Navigate: Go to the Managed Services tab.

2. Select: Choose the desired service-provider from the catalog. Services are marked with categories (e.g., Database, Cache). In this example we choose PostgreSQL. Click "Start Setup"

3. Configure: A configuration modal will appear. Set the initial parameters. You can leave non-required parameters at their default values and update them later if needed. Some parameters (like User name in this PostgreSQL example) have specific requirements. Hover over the "Info"-Icon to learn more. Click "Define Secrets" to proceed.

4. Secrets: Most services require secrets. Generate them on your machine and enter them here. Codesphere will not show you these secrets again after this step, so make sure to save them securely. If you lose them, you will need to reset the secrets which will cause downtime for the service. Click "Create Service" to proceed.

5. Deploy: After clicking "Deploy", Codesphere will begin provisioning the resources. Switch to the Managed Services tab in the left sidebar to monitor the progress. Status indicators will update as the service goes from Creating to Synchronized. Use the events log to get more details on the provisioning process. If there are any issues during deployment, the events log will provide insights into what went wrong and how to fix it.

API

You can create a managed service using the POST /managed-services endpoint.

curl -X POST "<your-codesphere-instance-url>/api/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 123,
    "name": "my-postgres-db",
    "provider": {
      "name": "postgresql",
      "version": "15"
    },
    "plan": {
      "id": 1,
      "parameters": {
        "storage": 10
      }
    },
    "config": {
      "max_connections": "100"
    },
    "secrets": {
      "password": "secure-password",
      "username": "admin"
    },
    "backups": {
      "enabled": true,
      "intervalH": 24,
      "deleteRetentionDays": 7,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/"
      },
      "secrets": {
        "accessKey": "YOUR_S3_ACCESS_KEY",
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Parameters:

• teamId (integer, required): The ID of the team where the service will be created.
• name (string, required): A unique name for your service.
• provider (object, required):
  • name: The name of the service provider (e.g., postgresql, redis).
  • version: The version tag (e.g., 15).
• plan (object, required):
  • id: The plan ID.
  • parameters: Plan-specific parameters (e.g., storage size in GB).
• secrets (object): Key-value pairs of secret service credentials.
• backups (object): Configure automated backups. For providers that support it. See the Managed Service Backups guide for details.
• recoverFrom (object): Automatically bootstrap the instance via a backup point in time object or a specific backup. Requires backups config and secrets. See the Managed Service Backups guide.

Refer to the API Documentation for complete schema details.

info

API endpoints are available for all lifecycle operations including deployment, configuration updates, pausing, and deletion.

info

Deployment times vary by service. Complex databases may take a few minutes to become fully operational.

What's Next?

Once your service is up and running, proceed to the Connecting to Services guide to learn how to access your database or object storage from your workspace.

Update / Configure

You can modify the configuration of a running service to adapt to changing requirements.

UI

1. Locate: Find the deployed service you want to update.
2. Open Settings: Click on the gear icon in the right of the table row to open the service details view.
3. Modify: Navigate to the Configuration tab and click Edit Configuration. This will enable editing configurable parameters. Note that not every option that was available in the creation-flow will be available for update. If you need to change a parameter that is not editable, you will need to delete and re-create the service with the desired configuration.
4. Apply: Click Save to apply changes. The service Status will change from Synchronized to Updating while the changes are being applied. Once complete, it will return to Synchronized. Check the event log for more details on the update process.

API

You can update a managed service using the PATCH /managed-services/{id} endpoint.

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "max_connections": "200"
    },
    "plan": {
      "id": 2,
      "parameters": {
        "storage": 20
      }
    },
    "secrets": {
      "password": "new-secure-password"
    },
    "backups": {
      "enabled": true,
      "intervalH": 12,
      "deleteRetentionDays": 30,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/"
      },
      "secrets": {
        "accessKey": "YOUR_S3_ACCESS_KEY",
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Parameters:

• id (string, path parameter): The UUID of the managed service to update.
• config (object, optional): Configuration updates.
• plan (object, optional):
  • id: The new plan ID.
  • parameters: Updated plan parameters (e.g., storage).
• secrets (object, optional): Updated secrets.
• backups (object, optional): Automated backup configurations.
• name (string, optional): New name for the service.
• pause (boolean, optional): Set to true to pause the service.

Refer to the API Documentation for complete schema details.

warning

Some configuration updates may trigger a restart of the service, causing brief downtime.

Pause

Codesphere allows you to pause certain managed services when they are not in active use. This is ideal for development environments or prototypes.

How it Works

Not every service supports pausing. If a service can be paused, you will see the option under the services capabilities. Capabilities can be viewed using the public API's GET providers endpoint.

• Pause: Takes the service offline and releases the compute resources (CPU & RAM). The service status changes to Paused or Stopped.
• Resume: Re-provisions the compute resources and brings the service back online.

Landscapes will automatically pause their own services when they are torn down.

UI

Currently, pausing Managed Services is only supported via the Public API. Use the API tab for instructions.

API

You can pause a managed service by updating its pause property to true using the PATCH /managed-services/{id} endpoint.

Pause Service:

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pause": true
  }'

Resume Service:

curl -X PATCH "<your-codesphere-instance-url>/api/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pause": false
  }'

Data Persistence

For Codesphere-managed services like Managed Storage or Object Store, your data stays safe during a pause. The persistent volume (disk) associated with the service is not deleted. When you resume the service, it re-attaches to the same volume, ensuring all your data is preserved.

Landscape-based and Custom Providers

This behavior currently applies to standalone managed services. For services integrated into landscape lifecycles or custom service providers, data persistence during pause depends on the specific implementation.

tip

Pausing services that are not in use is a great way to optimize your resource usage and costs.

Backups

Codesphere supports automated backups and point-in-time recovery for specific managed service providers (such as PostgreSQL and Babelfish). This allows you to securely store your data in an external S3-compatible service.

For complete instructions on configuring automated backups, running manual backups, and recovering a service from a previous point in time or backup ID, please refer to the dedicated Managed Service Backups guide.

Delete Managed Services

Deleting a service calls the deletion endpoint of a Managed Service backend. For Managed Services offered by Codesphere, this removes any resources associated with said service.

When you trigger a deletion, the behavior depends on whether backups are enabled for the service.

If backups are enabled: Codesphere performs a soft delete — the service is marked with a deletedAt timestamp, enters the Deleting state, and the reconciler schedules a final backup before the provider deletion proceeds. If backups are not enabled: Vault secrets are cleaned up and the delete request is sent to the provider immediately. No soft delete occurs.

Deletion Flow (backups enabled)

1. Soft delete: The service is marked with a deletedAt timestamp. The service status changes to Deleting.
2. Final backup: The reconciler schedules a final backup. It waits for this backup to be confirmed before sending the delete request to the provider.
3. Provider deletion: Once the final backup is confirmed, the reconciler sends the delete request to the provider backend, which removes compute resources and persistent data.
4. Retention period: The soft-deleted service record remains in the database for the duration configured by deleteRetentionDays after the deletion was initiated. During this window, you can still see the service by checking "Show recently Deleted" in the service table. After the retention period expires, the record is permanently hard-deleted and no longer visible.

Deletion Flow (backups not enabled)

1. Immediate deletion: When you trigger deletion, vault secrets are cleaned up and the delete request is sent to the provider immediately. The service is removed without a soft delete phase.

UI

1. Navigate: Go to the service table page.
2. Delete: Find the "Delete" button under the 3-dots menu.
3. Confirm: You will be asked to confirm the action, by typing the name of the service.

API

You can delete a managed service using the DELETE /managed-services/{id} endpoint.

curl -X DELETE "<your-codesphere-api-endpoint>/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Parameters:

• id (string, path parameter): The UUID of the managed service to delete.

Refer to the API Documentation for complete schema details.

warning

Deleting a managed service is permanent. It removes both the compute resources and the persistent data volume. This action cannot be undone. You can see recently deleted services by checking the "Show recently Deleted" checkbox, but they cannot be recovered.