diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md new file mode 100644 index 0000000000..16eb6a88e5 --- /dev/null +++ b/_partials/_devops-cli-get-started.md @@ -0,0 +1,237 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +$CLI_LONG is a command-line interface that you use to manage $CLOUD_LONG resources +including VPCs, services, read replicas, and related infrastructure. $CLI_LONG calls $REST_LONG to communicate with +$CLOUD_LONG. + +This page shows you how to install and set up secure authentication for $CLI_LONG, then create your first +service. + +## Prerequisites + + + + +## Install and configure $CLI_LONG + + + +1. **Install $CLI_LONG** + + Use the terminal to install the $CLI_SHORT: + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo os=any dist=any bash + sudo apt-get install tiger-cli + ``` + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo os=rpm_any dist=rpm_any bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + brew install --cask timescale/tap/tiger-cli + ``` + + + + + + ```shell + curl -fsSL https://tiger-cli-releases.s3.amazonaws.com/install/install.sh | sh + ``` + + + + + +1. **Set up API credentials** + + 1. Log $CLI_LONG into your $ACCOUNT_LONG: + + ```shell + tiger auth login + ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. + + 1. Log $CLI_LONG into your $ACCOUNT_LONG + + ```shell + tiger auth login + ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Login, then click `Authorize`. + + 1. Select a $PROJECT_LONG. + + ```terminaloutput + Auth URL is: https://console.cloud.timescale.com/oauth/authorize?client_id=lotsOfURLstuff + Opening browser for authentication... + Select a project: + + > 1. Tiger Project (tgrproject) + 2. YourCompany (Company wide project) (cpnproject) + 3. YourCompany Department (dptproject) + + Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit + ``` + If only one $PROJECT_SHORT is associated with your $ACCOUNT_SHORT, this step is not shown. + + Where possible, $CLI_LONG stores your authentication information in the system keychain/credential manager. + If that fails, the key is stored in `~/.config/tiger/api-key` with restricted file permissions (600). + $CLI_LONG stores your configuration in `~/.config/tiger/config.yaml`. + +1. **Test your authenticated connection to $CLOUD_LONG by listing services** + + ```bash + tiger service list + ``` + + This call returns something like: + - No services: + ```terminaloutput + 🏜️ No services found! Your project is looking a bit empty. + 🚀 Ready to get started? Create your first service with: tiger service create + ``` + - One or more services: + + ```terminaloutput + ┌────────────┬─────────────────────┬────────┬─────────────┬──────────────┬──────────────────┐ + │ SERVICE ID │ NAME │ STATUS │ TYPE │ REGION │ CREATED │ + ├────────────┼─────────────────────┼────────┼─────────────┼──────────────┼──────────────────┤ + │ tgrservice │ tiger-agent-service │ READY │ TIMESCALEDB │ eu-central-1 │ 2025-09-25 16:09 │ + └────────────┴─────────────────────┴────────┴─────────────┴──────────────┴──────────────────┘ + ``` + + + + +## Create your first service + +Create a new $SERVICE_LONG using $CLI_LONG: + + + +1. **Submit a service creation request** + ```shell + tiger service create + ``` + $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or + read replication. You see something like: + ```terminaloutput + 🚀 Creating service 'db-11111' (auto-generated name)... + ✅ Service creation request accepted! + 📋 Service ID: happyservice + 🔐 Password saved to system keyring for automatic authentication + 🎯 Set service 'happyservice' as default service. + ⏳ Waiting for service to be ready (wait timeout: 30m0s)... + ⏳ Service status: QUEUED... + 🎉 Service is ready and running! + ``` + This $SERVICE_SHORT is set as default by the $CLI_SHORT. + +1. **Check the $CLI_SHORT configuration** + ```shell + tiger config show + ``` + You see something like: + ```terminaloutput + api_url: https://console.cloud.timescale.com/public/api/v1 + console_url: https://console.cloud.timescale.com + gateway_url: https://console.cloud.timescale.com/api + docs_mcp: true + docs_mcp_url: https://mcp.tigerdata.com/docs + project_id: tgrproject + service_id: tgrservice + output: table + analytics: true + password_storage: keyring + debug: false + config_dir: /Users//.config/tiger + ``` + + + +And that is it, you are ready to use $CLI_LONG to manage your $SERVICE_SHORTs in $CLOUD_LONG. + +## Commands + +You can use the following commands with $CLI_LONG. For more information on each command, use the `-h` flag. For example: +`tiger auth login -h` + +| Command | Subcommand | Description | +|---------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| auth | | Manage authentication and the credentials for your $ACCOUNT_LONG | +| | login | Create an authenticated connection to your $ACCOUNT_LONG | +| | logout | Remove the credentials used to create authenticated connections to $CLOUD_LONG | +| | whoami | Show information about the current user | +| version | | Show information about the currently installed version of $CLI_LONG | +| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | +| config | | Manage your $CLI_LONG configuration | +| | show | Show the current configuration | +| | unset `` | Clear the value of a configuration parameter. For example, `tiger config unset debug` | +| | reset | Reset the configuration to the defaults. This also logs you out from the current $PROJECT_LONG | +| service | | Manage the $SERVICE_LONGs in this $PROJECT_SHORT | +| | create `--addons=` | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible addons are:
  • time-series: with the Timescaledb and Timescaledb Toolkit extensions
  • ai: with the Timescaledb, Timescaledb Toolkit, vector and vectorscale extensions
  • free: free services have fixed compute of 0.25 CPU, 1 GiB RAM, and up to 500mb storage.
  • none: vanilla Postgres
All services have Tiger features such as Tiger Storage, Security, Monitoring and compliance. If you do not use the `addons` flag, the default service is `time-series`. | +| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | +| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | +| | fork `` | Fork of an existing database service. Key features are:
  • Timing options: `--now`, `--last-snapshot`, `--to-timestamp`
  • Resource configuration: `--cpu`, `--memory`
  • Naming: `--name ` . Defaults to {source-service-name}-fork
  • Wait behavior: `--no-wait`, `--wait-timeout`
  • Default service: `--no-set-default`
| +| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | +| | update-password `` | Update the password for a $SERVICE_SHORT | +| db | | Database operations and management | +| | connect `` | Connect to a $SERVICE_SHORT | +| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | +| | test-connection `` | Test the connectivity to a $SERVICE_SHORT | +| mcp | | Manage the $MCP_LONG | +| | start | Start the $MCP_LONG. This is the same as `tiger mcp start stdio` | +| | start `stdio` \| `http` | Start the $MCP_LONG with stdio or HTTP transport | + +## Flags + +You can use the following global flags with $CLI_LONG: + +| Flag | Default | Description | +|--|-----------------|-----------------------------------------------------------------------| +| --analytics | `true` | Set to `false` to disable usage analytics | +| --config-dir string | `.config/tiger` | Set the directory that holds `config.yaml` | +| --debug | No debugging | Enable debug logging | +| -o, --output string | table | Set the output format. Options are `json`, `yaml`, or `table` | +| --password-storage string | keyring | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | +| --project-id string | - | Set the $PROJECT_LONG to manage | +| --service-id string | - | Set the $SERVICE_LONG to manage | + + + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md new file mode 100644 index 0000000000..fdf27c3062 --- /dev/null +++ b/_partials/_devops-rest-api-get-started.md @@ -0,0 +1,157 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +[$REST_LONG][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources +including VPCs, $SERVICE_SHORTs, and read replicas. + +This page shows you how to set up secure authentication for the $REST_LONG and create your first $SERVICE_SHORT. + +## Prerequisites + + + +* Install [curl][curl]. + + +## Configure secure authentication + +$REST_LONG uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +proper authentication headers. + + + +1. **Set up API credentials** + + 1. In $CONSOLE, copy your [project ID][get-project-id] and store it securely using an environment variable: + + ```bash + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + + 1. [Create your client credentials][create-client-credentials] and store them securely using environment variables: + + ```bash + export TIGERDATA_ACCESS_KEY="Public key" + export TIGERDATA_SECRET_KEY="Secret key" + ``` + +1. **Configure the API endpoint** + + Set the base URL in your environment: + + ```bash + export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + ``` + +1. **Test your authenticated connection to $REST_LONG by listing the $SERVICE_SHORTs in the current $PROJECT_LONG** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` + + This call returns something like: + - No $SERVICE_SHORTs: + ```terminaloutput + []% + ``` + - One or more $SERVICE_SHORTs: + + ```terminaloutput + [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", + "region_code":"eu-central-1","service_type":"TIMESCALEDB", + "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", + "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", + "port":12345}}] + ``` + + + + +## Create your first $SERVICE_LONG + +Create a new $SERVICE_SHORT using the $REST_LONG: + + + +1. **Create a $SERVICE_SHORT using the POST endpoint** + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + }' + ``` + $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or + read replication. You see something like: + ```terminaloutput + { + "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", + "region_code":"us-east-1", "service_type":"TIMESCALEDB", + "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", + "resources":[{"id":"101240", + "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"PROD"}, + "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, + "initial_password":"very-secret", + "ha_replicas":{"sync_replica_count":0,"replica_count":1} + } + ``` + +1. **Save `service_id` from the response to a variable** + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="service_id-from-response" + ``` + +1. **Check the configuration for the $SERVICE_SHORT** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` + You see something like: + ```terminaloutput + {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service","region_code":"us-east-1", + "service_type":"TIMESCALEDB","created":"2025-09-30T12:08:54.438785Z","paused":false,"status":"READY", + "resources":[{"id":"102879","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"ohhhh.yeahhhhh.tsdb.cloud.timescale.com","port":33867}, + "ha_replicas":{"sync_replica_count":0,"replica_count":1}} + ``` + + + +And that is it, you are ready to use the [$REST_LONG][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + +## Security best practices + +Follow these security guidelines when working with the $REST_LONG: + +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Never commit credentials to version control systems + +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + +- **Data protection** + - Use secure storage for service connection strings and passwords + - Implement proper backup and recovery procedures for created services + - Follow data residency requirements for your region + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/_partials/_prereqs-cloud-account-only.md b/_partials/_prereqs-cloud-account-only.md new file mode 100644 index 0000000000..bebd9d9f60 --- /dev/null +++ b/_partials/_prereqs-cloud-account-only.md @@ -0,0 +1,5 @@ +To follow the steps on this page: + +* Create a target [$ACCOUNT_LONG][create-account]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-cloud-account \ No newline at end of file diff --git a/api/api-reference.md b/api/api-reference.md new file mode 100644 index 0000000000..d682b84a4d --- /dev/null +++ b/api/api-reference.md @@ -0,0 +1,849 @@ +--- +title: Tiger Cloud REST API reference +excerpt: A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. +tags: [REST] +products: [cloud] +--- + +# $REST_LONG reference + +A comprehensive RESTful API for managing $CLOUD_LONG resources including VPCs, services, and read replicas. + +## Overview + +**API Version:** 1.0.0 +**Base URL:** `https://console.cloud.timescale.com/public/api/v1` + +## Authentication + +The $REST_LONG uses HTTP Basic Authentication. Include your access key and secret key in the Authorization header. + +### Basic Authentication +```http +Authorization: Basic +``` + +### Example +```bash +# Using cURL +curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project_id}/services" \ + -H "Authorization: Basic $(echo -n 'your_access_key:your_secret_key' | base64)" +``` + +## Service Management + +You use this endpoint to create and manage the following Tiger Postgres services: + +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions + +### List All Services + +```http +GET /projects/{project_id}/services +``` + +Retrieve all services within a project. + +**Response:** `200 OK` +```json +[ + { + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "my-production-db", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "status": "READY", + "created": "2024-01-15T10:30:00Z", + "paused": false, + "resources": [ + { + "id": "resource-1", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "gp2" + } + } + ], + "endpoint": { + "host": "my-service.com", + "port": 5432 + } + } +] +``` + +### Create a Service + +```http +POST /projects/{project_id}/services +``` + +Create a new Tiger Postgres service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "test-2", + "service_type": "TIMESCALEDB", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:46:46.265680278Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 + }, + "initial_password": "oamv8ch9t4ar2j8g" +} +``` + +**Service Types:** +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions + +### Get a Service + +```http +GET /projects/{project_id}/services/{service_id} +``` + +Retrieve details of a specific service. + +**Response:** `200 OK` +```json +{ + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:46:46.26568Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "metadata": { + "environment": "DEV" + }, + "endpoint": { + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 + } +} +``` + +**Service Status:** +- `QUEUED`: Service creation is queued +- `DELETING`: Service is being deleted +- `CONFIGURING`: Service is being configured +- `READY`: Service is ready for use +- `DELETED`: Service has been deleted +- `UNSTABLE`: Service is in an unstable state +- `PAUSING`: Service is being paused +- `PAUSED`: Service is paused +- `RESUMING`: Service is being resumed +- `UPGRADING`: Service is being upgraded +- `OPTIMIZING`: Service is being optimized + +### Delete a Service + +```http +DELETE /projects/{project_id}/services/{service_id} +``` + +Delete a specific service. This is an asynchronous operation. + +**Response:** `202 Accepted` + +### Resize a Service + +```http +POST /projects/{project_id}/services/{service_id}/resize +``` + +Change CPU and memory allocation for a service. + +**Request Body:** +```json +{ + "cpu_millis": 2000, + "memory_gbs": 8 +} +``` + +**Response:** `202 Accepted` + +### Update Service Password + +```http +POST /projects/{project_id}/services/{service_id}/updatePassword +``` + +Set a new master password for the service. + +**Request Body:** +```json +{ + "password": "a-very-secure-new-password" +} +``` + +**Response:** `204 No Content` + +### Set Service Environment + +```http +POST /projects/{project_id}/services/{service_id}/setEnvironment +``` + +Set the environment type for the service. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Environment Values:** +- `PROD`: Production environment +- `DEV`: Development environment + +**Response:** `200 OK` +```json +{ + "message": "Environment set successfully" +} +``` + +### Configure High Availability + +```http +POST /projects/{project_id}/services/{service_id}/setHA +``` + +Change the HA configuration for a service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "replica_count": 1 +} +``` + +**Response:** `202 Accepted` + +### Connection Pooler Management + +#### Enable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/enablePooler +``` + +Activate the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` + +#### Disable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/disablePooler +``` + +Deactivate the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} + +### Fork a Service + +```http +POST /projects/{project_id}/services/{service_id}/forkService +``` + +Create a new, independent service by taking a snapshot of an existing one. + +**Request Body:** +```json +{ + "name": "fork-test2", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "otewd3pem2", + "project_id": "jz22xtzemv", + "name": "fork-test2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:54:09.53380732Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100929", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "forked_from": { + "project_id": "jz22xtzemv", + "service_id": "p7zm9wqqii", + "is_standby": false + }, + "initial_password": "ph33bl5juuri5gem" +} +``` + +## Read Replica Sets + +Manage read replicas for improved read performance. + +### List Read Replica Sets + +```http +GET /projects/{project_id}/services/{service_id}/replicaSets +``` + +Retrieve all read replica sets associated with a primary service. + +**Response:** `200 OK` +```json +[ + { + "id": "l5alxb3s2g", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4, + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38448 + }, + "connection_pooler": { + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38543 + } + }, + "metadata": { + "environment": "DEV" + } + } +] +``` + +**Replica Set Status:** +- `creating`: Replica set is being created +- `active`: Replica set is active and ready +- `resizing`: Replica set is being resized +- `deleting`: Replica set is being deleted +- `error`: Replica set encountered an error + +### Create a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets +``` + +Create a new read replica set. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "replica-set-test2", + "cpu_millis": 1000, + "memory_gbs": 4, + "nodes": 1 +} +``` + +**Response:** `202 Accepted` +```json +{ + "id": "dsldm715t2", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +### Delete a Read Replica Set + +```http +DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} +``` + +Delete a specific read replica set. This is an asynchronous operation. + +**Response:** `202 Accepted` + +### Resize a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize +``` + +Change resource allocation for a read replica set. This operation is async. + +**Request Body:** +```json +{ + "cpu_millis": 500, + "memory_gbs": 2, + "nodes": 2 +} +``` + +**Response:** `202 Accepted` +```json +{ + "message": "Replica set resize request accepted" +} +``` + +### Read Replica Set Connection Pooler + +#### Enable Replica Set Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler +``` + +Activate the connection pooler for a read replica set. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` + +#### Disable Replica Set Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler +``` + +Deactivate the connection pooler for a read replica set. + +**Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} +``` + +### Set Replica Set Environment + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment +``` + +Set the environment type for a read replica set. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Response:** `200 OK` +```json +{ + "message": "Environment set successfully" +} +``` + +## VPC Management + +Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. + +### List All VPCs + +```http +GET /projects/{project_id}/vpcs +``` + +List all Virtual Private Clouds in a project. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" + } +] +``` + +### Create a VPC + +```http +POST /projects/{project_id}/vpcs +``` + +Create a new VPC. + +**Request Body:** +```json +{ + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Get a VPC + +```http +GET /projects/{project_id}/vpcs/{vpc_id} +``` + +Retrieve details of a specific VPC. + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Rename a VPC + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/rename +``` + +Update the name of a specific VPC. + +**Request Body:** +```json +{ + "name": "my-renamed-vpc" +} +``` + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-renamed-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Delete a VPC + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id} +``` + +Delete a specific VPC. + +**Response:** `204 No Content` + +## VPC Peering + +Manage peering connections between VPCs across different accounts and regions. + +### List VPC Peerings + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Retrieve all VPC peering connections for a given VPC. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "active", + "error_message": null + } +] +``` + +### Create VPC Peering + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Create a new VPC peering connection. + +**Request Body:** +```json +{ + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "pending" +} +``` + +### Get VPC Peering + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Retrieve details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Delete a specific VPC peering connection. + +**Response:** `204 No Content` + +## Service VPC Operations + +### Attach Service to VPC + +```http +POST /projects/{project_id}/services/{service_id}/attachToVPC +``` + +Associate a service with a VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +### Detach Service from VPC + +```http +POST /projects/{project_id}/services/{service_id}/detachFromVPC +``` + +Disassociate a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +## Data Models + +### VPC Object +```json +{ + "id": "string", + "name": "string", + "cidr": "string", + "region_code": "string" +} +``` + +### Service Object +```json +{ + "service_id": "string", + "project_id": "string", + "name": "string", + "region_code": "string", + "service_type": "TIMESCALEDB|POSTGRES|VECTOR", + "created": "2024-01-15T10:30:00Z", + "initial_password": "string", + "paused": false, + "status": "READY|CONFIGURING|QUEUED|...", + "resources": [ + { + "id": "string", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "string" + } + } + ], + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +### Peering Object +```json +{ + "id": "string", + "peer_account_id": "string", + "peer_region_code": "string", + "peer_vpc_id": "string", + "provisioned_id": "string", + "status": "string", + "error_message": "string" +} +``` + +### Read Replica Set Object + +```json +{ + "id": "string", + "name": "string", + "status": "creating|active|resizing|deleting|error", + "nodes": 2, + "cpu_millis": 1000, + "memory_gbs": 4, + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +## Error Handling + +Tiger Cloud REST API uses standard HTTP status codes and returns error details in JSON format. + +### Error Response Format +```json +{ + "code": "ERROR_CODE", + "message": "Human-readable error description" +} +``` + +### Common Error Codes +- `400 Bad Request`: Invalid request parameters or malformed JSON +- `401 Unauthorized`: Missing or invalid authentication credentials +- `403 Forbidden`: Insufficient permissions for the requested operation +- `404 Not Found`: Requested resource does not exist +- `409 Conflict`: Request conflicts with current resource state +- `500 Internal Server Error`: Unexpected server error + +### Example Error Response +```json +{ + "code": "INVALID_REQUEST", + "message": "The service_type field is required" +} +``` diff --git a/api/page-index/page-index.js b/api/page-index/page-index.js index 5a9152cc77..5b1bb90c25 100644 --- a/api/page-index/page-index.js +++ b/api/page-index/page-index.js @@ -617,6 +617,12 @@ module.exports = [ description: "An overview of what different tags represent in the API section of TigerData Documentation.", }, + { + title: "Tiger Cloud REST API", + href: "api-reference", + description: + "A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas.", + }, { title: "Glossary", href: "glossary", diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md new file mode 100644 index 0000000000..1258de6b64 --- /dev/null +++ b/getting-started/get-started-devops-as-code.md @@ -0,0 +1,41 @@ +--- +title: "DevOps as code with Tiger" +excerpt: "Configure secure authentication and manage the resources in your Tiger project using REST, the cli or MCP." +keywords: + - authentication + - service creation + - API setup + - security +tags: + - setup + - security + - services + - authentication +--- + + +import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; +import CLIGS from "versionContent/_partials/_devops-cli-get-started.mdx"; + + +# DevOps as code with $CLOUD_LONG + +$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, $CLI commands, and +MCP commands that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs +programmatically. + + + + + + + + + + + + + + + + diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 08356efc97..08862cd8b9 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -15,15 +15,20 @@ module.exports = [ title: "Start coding with TigerData", href: "start-coding-with-timescale", excerpt: - "Integrate Tiger Cloud with your app using your preferred programming language", + "Integrate Tiger with your app using your preferred programming language", }, { - title: "Create a Tiger Cloud service", + title: "Create a Tiger service", href: "services", - excerpt: "Create a Tiger Cloud service and connect to it", + excerpt: "Create a Tiger service and connect to it", }, { - title: "Run your queries from Tiger Cloud Console", + title: "DevOps as code with Tiger", + href: "get-started-devops-as-code", + excerpt: "Set up secure authentication for the Tiger REST API and create your first service", + }, + { + title: "Run your queries from Tiger Console", href: "run-queries-from-console", excerpt: "Run your queries securely from inside Tiger Cloud Console", }, diff --git a/integrations/find-connection-details.md b/integrations/find-connection-details.md index 7df2ce0722..2f46815a00 100644 --- a/integrations/find-connection-details.md +++ b/integrations/find-connection-details.md @@ -41,7 +41,7 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON -1. **Retreive your project ID**: +1. **Retrieve your project ID**: In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Copy` next to the project ID. ![Retrive the project id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-project-id.png) @@ -53,6 +53,31 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON +## Create client credentials + +You use client credentials to obtain access tokens outside of the user context. + +To retrieve the connection details for your $CLOUD_LONG project for programmatic usage +such as Terraform or the [$CLOUD_LONG REST API][rest-api-reference]: + + + +1. **Open the settings for your project**: + + In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Project settings`. + +1. **Create client credentials**: + + 1. Click `Create credentials`, then copy `Public key` and `Secret key` locally. + + ![Retrive the service id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-client-credentials.png) + + This is the only time you see the `Secret key`. After this, only the `Public key` is visible in this page. + + 1. Click `Done`. + + + @@ -73,3 +98,6 @@ In the `Services` page of the $MST_CONSOLE_LONG, click the service you want to c [console-services]: https://console.cloud.timescale.com/dashboard/services [postgres-config]: https://www.postgresql.org/docs/current/runtime-config-file-locations.html +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials \ No newline at end of file