From bbdd988715e7986d68ebf11a7b98d1abbc511fed Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 21 Aug 2025 15:35:46 +0200 Subject: [PATCH 01/24] chore: add first files. --- api/api-reference.md | 831 ++++++++++++++++++ getting-started/get-started-devops-as-code.md | 225 +++++ 2 files changed, 1056 insertions(+) create mode 100644 api/api-reference.md create mode 100644 getting-started/get-started-devops-as-code.md diff --git a/api/api-reference.md b/api/api-reference.md new file mode 100644 index 0000000000..952a21e838 --- /dev/null +++ b/api/api-reference.md @@ -0,0 +1,831 @@ +# TigerData Cloud API Reference + +A comprehensive RESTful API for managing TigerData Cloud Platform resources including VPCs, services, and read replicas. + +## Overview + +**API Version:** 1.0.0 +**Base URL:** `https://api.tigerdata.com/public/v1` +**Development URL:** `https://console.dev.timescale.com/public/api/v1` +**Local Development URL:** `http://localhost:8080/public/api/v1` + +## Authentication + +The TigerData Cloud API 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://api.tigerdata.com/public/v1/projects/{project_id}/services" \ + -H "Authorization: Basic $(echo -n 'your_access_key:your_secret_key' | base64)" +``` + +### Error Responses +- **401 Unauthorized:** Invalid or missing credentials +- **403 Forbidden:** Insufficient permissions + +## Common Parameters + +### Path Parameters +- `project_id` (string): The unique identifier of the project (e.g., "rp1pz7uyae") +- `service_id` (string): The unique identifier of the service (e.g., "d1k5vk7hf2") +- `vpc_id` (string): The unique identifier of the VPC (e.g., "1234567890") +- `replica_set_id` (string): The unique identifier of the read replica set (e.g., "alb8jicdpr") +- `peering_id` (string): The unique identifier of the VPC peering connection (e.g., "1234567890") + +## VPC Management + +Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. + +### List All VPCs + +```http +GET /projects/{project_id}/vpcs +``` + +Lists 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": "google-europe-west1" + } +] +``` + +### Create a VPC + +```http +POST /projects/{project_id}/vpcs +``` + +Creates a new Virtual Private Cloud. + +**Request Body:** +```json +{ + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid request parameters + +### Get a VPC + +```http +GET /projects/{project_id}/vpcs/{vpc_id} +``` + +Retrieves details of a specific VPC. + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Error Responses:** +- `404 Not Found`: VPC not found + +### Rename a VPC + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/rename +``` + +Updates 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": "google-europe-west1" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid request parameters +- `404 Not Found`: VPC not found + +### Delete a VPC + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id} +``` + +Deletes a specific VPC. + +**Response:** `204 No Content` + +**Error Responses:** +- `404 Not Found`: VPC not found + +## VPC Peering + +Manage peering connections between VPCs across different accounts and regions. + +### List VPC Peerings + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Retrieves all VPC peering connections for a given VPC. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-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 +``` + +Creates a new VPC peering connection. + +**Request Body:** +```json +{ + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-1", + "peer_vpc_id": "1234567890" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "pending" +} +``` + +### Get VPC Peering + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Retrieves details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Deletes a specific VPC peering connection. + +**Response:** `204 No Content` + +## Service Management + +Manage database services including TimescaleDB, PostgreSQL, and Vector databases. + +### List All Services + +```http +GET /projects/{project_id}/services +``` + +Retrieves all services within a project. + +**Response:** `200 OK` +```json +[ + { + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "service_type": "TIMESCALEDB", + "status": "READY", + "created": "2024-01-15T10:30:00Z", + "initial_password": "a-very-secure-initial-password", + "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 +``` + +Creates a new database service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "my-production-db", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "service_type": "TIMESCALEDB", + "status": "QUEUED", + "created": "2024-01-15T10:30:00Z", + "initial_password": "a-very-secure-initial-password" +} +``` + +**Service Types:** +- `TIMESCALEDB`: TimescaleDB service +- `POSTGRES`: PostgreSQL service +- `VECTOR`: Vector database service + +**Error Responses:** +- `400 Bad Request`: Invalid service configuration + +### Get a Service + +```http +GET /projects/{project_id}/services/{service_id} +``` + +Retrieves details of a specific service. + +**Response:** `200 OK` +```json +{ + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "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" + } + } + ], + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "my-service.com", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "pooler.my-service.com", + "port": 5432 + } + } +} +``` + +**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} +``` + +Deletes a specific service. This is an asynchronous operation. + +**Response:** `202 Accepted` + +**Error Responses:** +- `404 Not Found`: Service not found + +### Resize a Service + +```http +POST /projects/{project_id}/services/{service_id}/resize +``` + +Changes 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 +``` + +Sets 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 +``` + +Sets the environment type for the service. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Environment Values:** +- `PROD`: Production environment +- `DEV`: Development environment + +**Response:** `200 OK` +```json +{ + "message": "Action completed successfully." +} +``` + +### Configure High Availability + +```http +POST /projects/{project_id}/services/{service_id}/setHA +``` + +Changes the HA configuration for a service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "sync_replica_count": 1, + "replica_count": 2 +} +``` + +**Response:** `202 Accepted` + +### Connection Pooler Management + +#### Enable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/enablePooler +``` + +Activates the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Action completed successfully." +} +``` + +#### Disable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/disablePooler +``` + +Deactivates the connection pooler for a service. + +**Response:** `200 OK` + +### Service VPC Operations + +#### Attach Service to VPC + +```http +POST /projects/{project_id}/services/{service_id}/attachToVPC +``` + +Associates a service with a VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +**Error Responses:** +- `409 Conflict`: Service already attached to a VPC + +#### Detach Service from VPC + +```http +POST /projects/{project_id}/services/{service_id}/detachFromVPC +``` + +Disassociates a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +### Fork a Service + +```http +POST /projects/{project_id}/services/{service_id}/forkService +``` + +Creates a new, independent service by taking a snapshot of an existing one. + +**Request Body:** +```json +{ + "name": "forked-customer-db" +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "new-service-id", + "name": "forked-customer-db", + "forked_from": { + "project_id": "rp1pz7uyae", + "service_id": "d1k5vk7hf2", + "is_standby": false + }, + "status": "CONFIGURING" +} +``` + +## Read Replica Sets + +Manage read replicas for improved read performance and geographical distribution. + +### List Read Replica Sets + +```http +GET /projects/{project_id}/services/{service_id}/replicaSets +``` + +Retrieves all read replica sets associated with a primary service. + +**Response:** `200 OK` +```json +[ + { + "id": "alb8jicdpr", + "name": "reporting-replica-1", + "status": "active", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5, + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "replica.my-service.com", + "port": 5432 + } + } +] +``` + +**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 +``` + +Creates a new read replica set. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "my-reporting-replica", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5 +} +``` + +**Response:** `202 Accepted` +```json +{ + "id": "alb8jicdpr", + "name": "my-reporting-replica", + "status": "creating", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5 +} +``` + +### Delete a Read Replica Set + +```http +DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} +``` + +Deletes 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 +``` + +Changes resource allocation for a read replica set. + +**Request Body:** +```json +{ + "cpu_millis": 500, + "memory_gbs": 1.0, + "nodes": 3 +} +``` + +**Response:** `202 Accepted` + +### Read Replica Connection Pooler + +#### Enable Replica Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler +``` + +Activates the connection pooler for a read replica set. + +**Response:** `200 OK` + +#### Disable Replica Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler +``` + +Deactivates the connection pooler for a read replica set. + +**Response:** `200 OK` + +### Set Replica Environment + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment +``` + +Sets the environment type for a read replica set. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Response:** `200 OK` + +## 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": 250, + "memory_gbs": 0.5, + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +## Error Handling + +The 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" +} +``` + +## Rate Limiting + +The API implements rate limiting to ensure fair usage: + +- **Development Environment**: More lenient rate limits for testing +- **Production Environment**: Strict rate limits for stability +- **Local Development**: No rate limits applied + +When rate limits are exceeded, the API returns `429 Too Many Requests` with retry information in the response headers. + +## Support and Contact + +For API support and questions: +- **Support**: [TigerData Support](https://www.tigerdata.com/contact) +- **License**: [Terms of Service](https://www.tigerdata.com/legal/terms) +- **Documentation**: This API reference follows the OpenAPI 3.0.3 specification \ No newline at end of file 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..df696d561a --- /dev/null +++ b/getting-started/get-started-devops-as-code.md @@ -0,0 +1,225 @@ +--- +title: "Set up TigerData Cloud API and create your first service" +excerpt: "Configure secure authentication and create a new database service using the TigerData Cloud API" +keywords: + - authentication + - service creation + - API setup + - security +tags: + - setup + - security + - services + - authentication +--- + +# Set up TigerData Cloud API and create your first service + +Set up secure authentication for the TigerData Cloud API and create your first database service. This procedure covers credential configuration, security best practices, and service creation using the RESTful API. + +## Prerequisites + +Complete the following prerequisites before setting up the API: + +- Valid TigerData Cloud account with API access +- Project ID from your TigerData Cloud console +- API access key and secret key with appropriate permissions +- Command-line tool (cURL, HTTPie, or programming language with HTTP client) +- OpenAPI specification file for reference +- Network connectivity to TigerData Cloud API endpoints + +## Configure secure authentication + +The TigerData Cloud API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. + +### Set up API credentials + +1. Obtain your API credentials from the TigerData Cloud console: + - Access key: Your unique API identifier + - Secret key: Your private authentication token + - Project ID: The identifier for your TigerData project + +2. Store credentials securely using environment variables: + ```bash + export TIGERDATA_ACCESS_KEY="your-access-key" + export TIGERDATA_SECRET_KEY="your-secret-key" + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + +3. Verify credential format: + - Access key format: Alphanumeric string (typically 10-20 characters) + - Secret key format: Base64-encoded string (typically 40-60 characters) + - Project ID format: Alphanumeric string starting with project prefix + +### Configure API endpoint + +Set the appropriate API base URL for your environment: + +```bash +# Development environment (recommended for testing) +export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" + +# Production environment +export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + +# Local development (if running local server) +export API_BASE_URL="http://localhost:8080/public/api/v1" +``` + +## Test API connection + +Verify your authentication setup and API connectivity before creating resources. + +### Perform health check + +Test the API connection using a simple health check request: + +```bash +curl -X GET "${API_BASE_URL}/healthcheck" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" +``` + +Expected response: +```json +{ + "status": "healthy", + "timestamp": "2024-01-15T10:30:00Z" +} +``` + +### Validate authentication + +Test authentication by listing existing services: + +```bash +curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" +``` + +Successful authentication returns a JSON array of services (may be empty for new projects). + +## Create your first service + +Create a new database service using the TigerData Cloud API with secure configuration. + +### Prepare service configuration + +1. Define the service creation payload in JSON format: + ```json + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + ``` + +2. Save the configuration to a file for reuse: + ```bash + cat > service-config.json << 'EOF' + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + EOF + ``` + +### Submit service creation request + +1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` + +2. Save the service ID from the response: + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="extracted-service-id-from-response" + ``` + +The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. + +### Monitor service creation progress + +1. Check service status periodically: + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + +2. Wait for status to change from `CONFIGURING` to `READY`: + - `QUEUED`: Service creation request is queued + - `CONFIGURING`: Service is being provisioned + - `READY`: Service is available for use + - `UNSTABLE`: Service encountered issues during creation + +Service creation typically completes within 5-10 minutes depending on the configuration. + +## Security best practices + +Follow these security guidelines when working with the TigerData Cloud API: + +### Credential management +- Store API credentials as environment variables, not in code +- Use credential rotation policies for production environments +- Limit credential scope to minimum required permissions +- Never commit credentials to version control systems + +### Network security +- Use HTTPS endpoints exclusively for API communication +- Implement proper certificate validation in your HTTP clients +- Consider IP allowlisting for production API access +- Monitor API access logs for suspicious activity + +### Access control +- Create dedicated service accounts for automated API access +- Use principle of least privilege for API key permissions +- Regularly audit and review API access patterns +- Implement proper session management for interactive applications + +### Data protection +- Encrypt sensitive data before API transmission when applicable +- 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 + +## Alternative implementation using API explorer + +The TigerData Cloud project includes a command-line API explorer tool that simplifies API interactions: + +### Using the API explorer + +1. Navigate to the API explorer directory: + ```bash + cd api_explorer + ``` + +2. Configure the environment interactively: + ```bash + go run . config setup + ``` + +3. Test the connection: + ```bash + go run . health + ``` + +4. Create a service using the simplified command: + ```bash + go run . service create + ``` + +The API explorer automatically handles authentication, request formatting, and response parsing, making it ideal for development and testing workflows. + +Your TigerData Cloud API is now configured securely, and you have successfully created your first database service. The service provides a managed TimescaleDB instance with the specified resources and configuration. \ No newline at end of file From a48e482ccf516fce6a66bef4c2630fa320a0a6f1 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 25 Aug 2025 09:57:36 +0200 Subject: [PATCH 02/24] chore: first draft of the REST API docs --- api/api-reference.md | 11 +- api/page-index/page-index.js | 6 + getting-started/get-started-devops-as-code.md | 307 ++++++++---------- getting-started/page-index/page-index.js | 5 + 4 files changed, 159 insertions(+), 170 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index 952a21e838..e100eb85a0 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -1,6 +1,13 @@ -# TigerData Cloud API Reference +--- +title: Tiger Cloud API reference +excerpt: A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. +tags: [REST] +products: [cloud] +--- -A comprehensive RESTful API for managing TigerData Cloud Platform resources including VPCs, services, and read replicas. +# Tiger Cloud API reference + +A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. ## Overview diff --git a/api/page-index/page-index.js b/api/page-index/page-index.js index 049f79920a..f2c4411d9f 100644 --- a/api/page-index/page-index.js +++ b/api/page-index/page-index.js @@ -587,6 +587,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: "Compression (Old API, replaced by Hypercore)", href: "compression", diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index df696d561a..6ddc27b4aa 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,6 +1,6 @@ --- -title: "Set up TigerData Cloud API and create your first service" -excerpt: "Configure secure authentication and create a new database service using the TigerData Cloud API" +title: "Set up Tiger Cloud REST API and create your first service" +excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication - service creation @@ -13,111 +13,106 @@ tags: - authentication --- -# Set up TigerData Cloud API and create your first service +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; -Set up secure authentication for the TigerData Cloud API and create your first database service. This procedure covers credential configuration, security best practices, and service creation using the RESTful API. +# Get started with Tiger Cloud REST API -## Prerequisites - -Complete the following prerequisites before setting up the API: - -- Valid TigerData Cloud account with API access -- Project ID from your TigerData Cloud console -- API access key and secret key with appropriate permissions -- Command-line tool (cURL, HTTPie, or programming language with HTTP client) -- OpenAPI specification file for reference -- Network connectivity to TigerData Cloud API endpoints - -## Configure secure authentication - -The TigerData Cloud API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. - -### Set up API credentials - -1. Obtain your API credentials from the TigerData Cloud console: - - Access key: Your unique API identifier - - Secret key: Your private authentication token - - Project ID: The identifier for your TigerData project - -2. Store credentials securely using environment variables: - ```bash - export TIGERDATA_ACCESS_KEY="your-access-key" - export TIGERDATA_SECRET_KEY="your-secret-key" - export TIGERDATA_PROJECT_ID="your-project-id" - ``` - -3. Verify credential format: - - Access key format: Alphanumeric string (typically 10-20 characters) - - Secret key format: Base64-encoded string (typically 40-60 characters) - - Project ID format: Alphanumeric string starting with project prefix - -### Configure API endpoint - -Set the appropriate API base URL for your environment: +[Tiger Cloud REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read +replicas. -```bash -# Development environment (recommended for testing) -export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" +This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. -# Production environment -export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" - -# Local development (if running local server) -export API_BASE_URL="http://localhost:8080/public/api/v1" -``` - -## Test API connection - -Verify your authentication setup and API connectivity before creating resources. - -### Perform health check - -Test the API connection using a simple health check request: - -```bash -curl -X GET "${API_BASE_URL}/healthcheck" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" -``` +## Prerequisites -Expected response: -```json -{ - "status": "healthy", - "timestamp": "2024-01-15T10:30:00Z" -} -``` + -### Validate authentication +- An [API access key and secret key][rest-api-credentials] +- A Command-line tool for REST calls +- Network connectivity to Tiger Cloud REST API endpoints -Test authentication by listing existing services: +## Configure secure authentication -```bash -curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" -``` +Tiger Cloud REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +proper authentication headers. + + + +1. **Set up API credentials** + + 1. Obtain your API credentials from the TigerData Cloud console: + - Access key: Your unique API identifier + - Secret key: Your private authentication token + - Project ID: The identifier for your TigerData project + + 2. Store credentials securely using environment variables: + ```bash + export TIGERDATA_ACCESS_KEY="your-access-key" + export TIGERDATA_SECRET_KEY="your-secret-key" + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + + 3. Verify credential format: + - Access key format: Alphanumeric string (typically 10-20 characters) + - Secret key format: Base64-encoded string (typically 40-60 characters) + - Project ID format: Alphanumeric string starting with project prefix + +1. **Configure API endpoint** + + Set the appropriate API base URL for your environment: + + ```bash + # Development environment (recommended for testing) + export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" + + # Production environment + export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + + # Local development (if running local server) + export API_BASE_URL="http://localhost:8080/public/api/v1" + ``` + +1. **Test API connection** + + Verify your authentication setup and API connectivity before creating resources. + +1. **Perform health check** + + Test the API connection using a simple health check request: + + ```bash + curl -X GET "${API_BASE_URL}/healthcheck" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" + ``` + + Expected response: + ```json + { + "status": "healthy", + "timestamp": "2024-01-15T10:30:00Z" + } + ``` + +1. **Validate authentication** + + Test authentication by listing existing services: + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + + Successful authentication returns a JSON array of services (may be empty for new projects). ## Create your first service -Create a new database service using the TigerData Cloud API with secure configuration. - -### Prepare service configuration +Create a new database service using the Tiger Cloud REST API with secure configuration. -1. Define the service creation payload in JSON format: - ```json - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - ``` + -2. Save the configuration to a file for reuse: +1. **Define the service creation payload in a JSON file** ```bash cat > service-config.json << 'EOF' { @@ -131,95 +126,71 @@ Create a new database service using the TigerData Cloud API with secure configur EOF ``` -### Submit service creation request - -1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - -2. Save the service ID from the response: - ```bash - # Extract service_id from the JSON response - export SERVICE_ID="extracted-service-id-from-response" - ``` +1. **Submit service creation request** -The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. + 1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` -### Monitor service creation progress + 2. Save the service ID from the response: + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="extracted-service-id-from-response" + ``` -1. Check service status periodically: - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" - ``` + The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. -2. Wait for status to change from `CONFIGURING` to `READY`: - - `QUEUED`: Service creation request is queued - - `CONFIGURING`: Service is being provisioned - - `READY`: Service is available for use - - `UNSTABLE`: Service encountered issues during creation +1. **Monitor service creation progress** -Service creation typically completes within 5-10 minutes depending on the configuration. + 1. Check service status periodically: + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` -## Security best practices + 2. Wait for status to change from `CONFIGURING` to `READY`: + - `QUEUED`: Service creation request is queued + - `CONFIGURING`: Service is being provisioned + - `READY`: Service is available for use + - `UNSTABLE`: Service encountered issues during creation -Follow these security guidelines when working with the TigerData Cloud API: + Service creation typically completes within 5-10 minutes depending on the configuration. -### Credential management -- Store API credentials as environment variables, not in code -- Use credential rotation policies for production environments -- Limit credential scope to minimum required permissions -- Never commit credentials to version control systems + -### Network security -- Use HTTPS endpoints exclusively for API communication -- Implement proper certificate validation in your HTTP clients -- Consider IP allowlisting for production API access -- Monitor API access logs for suspicious activity - -### Access control -- Create dedicated service accounts for automated API access -- Use principle of least privilege for API key permissions -- Regularly audit and review API access patterns -- Implement proper session management for interactive applications +## Security best practices -### Data protection -- Encrypt sensitive data before API transmission when applicable -- 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 +Follow these security guidelines when working with the Tiger Cloud REST API: -## Alternative implementation using API explorer +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Limit credential scope to minimum required permissions + - Never commit credentials to version control systems -The TigerData Cloud project includes a command-line API explorer tool that simplifies API interactions: +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + - Consider IP allowlisting for production API access + - Monitor API access logs for suspicious activity -### Using the API explorer +- **Access control** + - Create dedicated service accounts for automated API access + - Use principle of least privilege for API key permissions + - Regularly audit and review API access patterns + - Implement proper session management for interactive applications -1. Navigate to the API explorer directory: - ```bash - cd api_explorer - ``` - -2. Configure the environment interactively: - ```bash - go run . config setup - ``` - -3. Test the connection: - ```bash - go run . health - ``` - -4. Create a service using the simplified command: - ```bash - go run . service create - ``` +- **Data protection** + - Encrypt sensitive data before API transmission when applicable + - 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 -The API explorer automatically handles authentication, request formatting, and response parsing, making it ideal for development and testing workflows. -Your TigerData Cloud API is now configured securely, and you have successfully created your first database service. The service provides a managed TimescaleDB instance with the specified resources and configuration. \ No newline at end of file +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 08356efc97..8c52c4857a 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -22,6 +22,11 @@ module.exports = [ href: "services", excerpt: "Create a Tiger Cloud service and connect to it", }, + { + title: "Get started with Tiger Cloud REST API", + href: "get-started-devops-as-code", + excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", + }, { title: "Run your queries from Tiger Cloud Console", href: "run-queries-from-console", From 496846a8b19ceb758b6a0ef5cda3e59034b0c8c0 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 27 Aug 2025 14:17:44 +0200 Subject: [PATCH 03/24] chore: update and test. --- _partials/_prereqs-cloud-account-only.md | 5 ++ getting-started/get-started-devops-as-code.md | 51 +++++++------------ integrations/find-connection-details.md | 30 ++++++++++- 3 files changed, 52 insertions(+), 34 deletions(-) create mode 100644 _partials/_prereqs-cloud-account-only.md diff --git a/_partials/_prereqs-cloud-account-only.md b/_partials/_prereqs-cloud-account-only.md new file mode 100644 index 0000000000..9d31734690 --- /dev/null +++ b/_partials/_prereqs-cloud-account-only.md @@ -0,0 +1,5 @@ +To follow the steps on this page: + +* Create a target [$CLOUD_LONG account][create-account]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-cloud-account \ No newline at end of file diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 6ddc27b4aa..f453883df7 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,69 +13,52 @@ tags: - authentication --- -import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; # Get started with Tiger Cloud REST API -[Tiger Cloud REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read +[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. ## Prerequisites - - -- An [API access key and secret key][rest-api-credentials] + - A Command-line tool for REST calls - Network connectivity to Tiger Cloud REST API endpoints ## Configure secure authentication -Tiger Cloud REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +$CLOUD_LONG REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. 1. **Set up API credentials** - 1. Obtain your API credentials from the TigerData Cloud console: - - Access key: Your unique API identifier - - Secret key: Your private authentication token - - Project ID: The identifier for your TigerData project - - 2. Store credentials securely using environment variables: + 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: + ```bash - export TIGERDATA_ACCESS_KEY="your-access-key" - export TIGERDATA_SECRET_KEY="your-secret-key" export TIGERDATA_PROJECT_ID="your-project-id" ``` - 3. Verify credential format: - - Access key format: Alphanumeric string (typically 10-20 characters) - - Secret key format: Base64-encoded string (typically 40-60 characters) - - Project ID format: Alphanumeric string starting with project prefix + 1. In $CONSOLE [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 API endpoint** - Set the appropriate API base URL for your environment: + Set the API base URL for your environment: ```bash - # Development environment (recommended for testing) - export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" - - # Production environment export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" - - # Local development (if running local server) - export API_BASE_URL="http://localhost:8080/public/api/v1" ``` -1. **Test API connection** - - Verify your authentication setup and API connectivity before creating resources. - -1. **Perform health check** +1. **Perform health check and test your connection to $CLOUD_LONG REST API** Test the API connection using a simple health check request: @@ -118,7 +101,7 @@ Create a new database service using the Tiger Cloud REST API with secure configu { "name": "my-first-service", "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", + "region_code": "us-east-1", "replica_count": 1, "cpu_millis": 1000, "memory_gbs": 4 @@ -193,4 +176,6 @@ Follow these security guidelines when working with the Tiger Cloud REST API: [rest-api-reference]: /api/:currentVersion:/api-reference/ -[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file +[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 \ No newline at end of file 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 From 0aa622e534a41a726fb5bed81700fc877249ced8 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 27 Aug 2025 14:24:18 +0200 Subject: [PATCH 04/24] chore: update and test. --- getting-started/get-started-devops-as-code.md | 12 +++++++----- getting-started/page-index/page-index.js | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index f453883df7..aa85e6a578 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,5 +1,5 @@ --- -title: "Set up Tiger Cloud REST API and create your first service" +title: "DevOps with Tiger Cloud REST API" excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication @@ -15,7 +15,7 @@ tags: import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -# Get started with Tiger Cloud REST API +# DevOps with Tiger Cloud REST API [$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. @@ -25,8 +25,9 @@ This page shows you how to set up secure authentication for the TigerData Cloud ## Prerequisites -- A Command-line tool for REST calls -- Network connectivity to Tiger Cloud REST API endpoints + +* Install [curl][curl]. + ## Configure secure authentication @@ -178,4 +179,5 @@ Follow these security guidelines when working with the Tiger Cloud REST API: [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 \ No newline at end of file +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 8c52c4857a..a8681649f7 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -23,7 +23,7 @@ module.exports = [ excerpt: "Create a Tiger Cloud service and connect to it", }, { - title: "Get started with Tiger Cloud REST API", + title: "DevOps with Tiger Cloud REST API", href: "get-started-devops-as-code", excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", }, From 20a0a27ba0b7506fce205405fce4067d99c850e9 Mon Sep 17 00:00:00 2001 From: josesahad Date: Fri, 5 Sep 2025 11:53:56 +0200 Subject: [PATCH 05/24] Fix spec. Better examples and documentation --- api/api-reference.md | 684 +++++++++++++++++++++---------------------- 1 file changed, 341 insertions(+), 343 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index e100eb85a0..0cfc44914e 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -12,9 +12,7 @@ A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, s ## Overview **API Version:** 1.0.0 -**Base URL:** `https://api.tigerdata.com/public/v1` -**Development URL:** `https://console.dev.timescale.com/public/api/v1` -**Local Development URL:** `http://localhost:8080/public/api/v1` +**Base URL:** `https://console.cloud.timescale.com/public/api/v1` ## Authentication @@ -28,214 +26,10 @@ Authorization: Basic ### Example ```bash # Using cURL -curl -X GET "https://api.tigerdata.com/public/v1/projects/{project_id}/services" \ +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)" ``` -### Error Responses -- **401 Unauthorized:** Invalid or missing credentials -- **403 Forbidden:** Insufficient permissions - -## Common Parameters - -### Path Parameters -- `project_id` (string): The unique identifier of the project (e.g., "rp1pz7uyae") -- `service_id` (string): The unique identifier of the service (e.g., "d1k5vk7hf2") -- `vpc_id` (string): The unique identifier of the VPC (e.g., "1234567890") -- `replica_set_id` (string): The unique identifier of the read replica set (e.g., "alb8jicdpr") -- `peering_id` (string): The unique identifier of the VPC peering connection (e.g., "1234567890") - -## VPC Management - -Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. - -### List All VPCs - -```http -GET /projects/{project_id}/vpcs -``` - -Lists 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": "google-europe-west1" - } -] -``` - -### Create a VPC - -```http -POST /projects/{project_id}/vpcs -``` - -Creates a new Virtual Private Cloud. - -**Request Body:** -```json -{ - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Response:** `201 Created` -```json -{ - "id": "1234567890", - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Error Responses:** -- `400 Bad Request`: Invalid request parameters - -### Get a VPC - -```http -GET /projects/{project_id}/vpcs/{vpc_id} -``` - -Retrieves details of a specific VPC. - -**Response:** `200 OK` -```json -{ - "id": "1234567890", - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Error Responses:** -- `404 Not Found`: VPC not found - -### Rename a VPC - -```http -POST /projects/{project_id}/vpcs/{vpc_id}/rename -``` - -Updates 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": "google-europe-west1" -} -``` - -**Error Responses:** -- `400 Bad Request`: Invalid request parameters -- `404 Not Found`: VPC not found - -### Delete a VPC - -```http -DELETE /projects/{project_id}/vpcs/{vpc_id} -``` - -Deletes a specific VPC. - -**Response:** `204 No Content` - -**Error Responses:** -- `404 Not Found`: VPC not found - -## VPC Peering - -Manage peering connections between VPCs across different accounts and regions. - -### List VPC Peerings - -```http -GET /projects/{project_id}/vpcs/{vpc_id}/peerings -``` - -Retrieves all VPC peering connections for a given VPC. - -**Response:** `200 OK` -```json -[ - { - "id": "1234567890", - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-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 -``` - -Creates a new VPC peering connection. - -**Request Body:** -```json -{ - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-1", - "peer_vpc_id": "1234567890" -} -``` - -**Response:** `201 Created` -```json -{ - "id": "1234567890", - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-1", - "peer_vpc_id": "1234567890", - "provisioned_id": "1234567890", - "status": "pending" -} -``` - -### Get VPC Peering - -```http -GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} -``` - -Retrieves details of a specific VPC peering connection. - -### Delete VPC Peering - -```http -DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} -``` - -Deletes a specific VPC peering connection. - -**Response:** `204 No Content` - ## Service Management Manage database services including TimescaleDB, PostgreSQL, and Vector databases. @@ -252,14 +46,13 @@ Retrieves all services within a project. ```json [ { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", "name": "my-production-db", - "region_code": "google-europe-west1", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", "status": "READY", "created": "2024-01-15T10:30:00Z", - "initial_password": "a-very-secure-initial-password", "paused": false, "resources": [ { @@ -290,10 +83,9 @@ Creates a new database service. This is an asynchronous operation. **Request Body:** ```json { - "name": "my-production-db", + "name": "test-2", "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", - "replica_count": 1, + "region_code": "eu-central-1", "cpu_millis": 1000, "memory_gbs": 4 } @@ -302,14 +94,32 @@ Creates a new database service. This is an asynchronous operation. **Response:** `202 Accepted` ```json { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", - "name": "my-production-db", - "region_code": "google-europe-west1", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", - "status": "QUEUED", - "created": "2024-01-15T10:30:00Z", - "initial_password": "a-very-secure-initial-password" + "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" } ``` @@ -318,9 +128,6 @@ Creates a new database service. This is an asynchronous operation. - `POSTGRES`: PostgreSQL service - `VECTOR`: Vector database service -**Error Responses:** -- `400 Bad Request`: Invalid service configuration - ### Get a Service ```http @@ -332,36 +139,30 @@ Retrieves details of a specific service. **Response:** `200 OK` ```json { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", - "name": "my-production-db", - "region_code": "google-europe-west1", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", - "status": "READY", - "created": "2024-01-15T10:30:00Z", + "created": "2025-09-04T20:46:46.26568Z", "paused": false, + "status": "READY", "resources": [ - { - "id": "resource-1", - "spec": { - "cpu_millis": 1000, - "memory_gbs": 4, - "volume_type": "gp2" + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } } - } ], "metadata": { - "environment": "PROD" + "environment": "DEV" }, "endpoint": { - "host": "my-service.com", - "port": 5432 - }, - "connection_pooler": { - "endpoint": { - "host": "pooler.my-service.com", - "port": 5432 - } + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 } } ``` @@ -389,9 +190,6 @@ Deletes a specific service. This is an asynchronous operation. **Response:** `202 Accepted` -**Error Responses:** -- `404 Not Found`: Service not found - ### Resize a Service ```http @@ -449,7 +247,7 @@ Sets the environment type for the service. **Response:** `200 OK` ```json { - "message": "Action completed successfully." + "message": "Environment set successfully" } ``` @@ -464,8 +262,7 @@ Changes the HA configuration for a service. This is an asynchronous operation. **Request Body:** ```json { - "sync_replica_count": 1, - "replica_count": 2 + "replica_count": 1 } ``` @@ -484,7 +281,7 @@ Activates the connection pooler for a service. **Response:** `200 OK` ```json { - "message": "Action completed successfully." + "message": "Connection pooler enabled successfully" } ``` @@ -497,45 +294,10 @@ POST /projects/{project_id}/services/{service_id}/disablePooler Deactivates the connection pooler for a service. **Response:** `200 OK` - -### Service VPC Operations - -#### Attach Service to VPC - -```http -POST /projects/{project_id}/services/{service_id}/attachToVPC -``` - -Associates a service with a VPC. - -**Request Body:** ```json { - "vpc_id": "1234567890" + "message": "Connection pooler disabled successfully" } -``` - -**Response:** `202 Accepted` - -**Error Responses:** -- `409 Conflict`: Service already attached to a VPC - -#### Detach Service from VPC - -```http -POST /projects/{project_id}/services/{service_id}/detachFromVPC -``` - -Disassociates a service from its VPC. - -**Request Body:** -```json -{ - "vpc_id": "1234567890" -} -``` - -**Response:** `202 Accepted` ### Fork a Service @@ -548,27 +310,46 @@ Creates a new, independent service by taking a snapshot of an existing one. **Request Body:** ```json { - "name": "forked-customer-db" + "name": "fork-test2", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 } ``` **Response:** `202 Accepted` ```json { - "service_id": "new-service-id", - "name": "forked-customer-db", - "forked_from": { - "project_id": "rp1pz7uyae", - "service_id": "d1k5vk7hf2", - "is_standby": false - }, - "status": "CONFIGURING" + "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 and geographical distribution. +Manage read replicas for improved read performance. ### List Read Replica Sets @@ -582,18 +363,18 @@ Retrieves all read replica sets associated with a primary service. ```json [ { - "id": "alb8jicdpr", - "name": "reporting-replica-1", + "id": "dsldm715t2", + "name": "replica-set-test", "status": "active", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5, + "nodes": 1, + "cpu_millis": 500, + "memory_gbs": 2, "metadata": { "environment": "PROD" }, "endpoint": { - "host": "replica.my-service.com", - "port": 5432 + "host": "jz22xtzemv.dsldm715t2.tsdb.cloud.timescale.com", + "port": 39680 } } ] @@ -617,22 +398,22 @@ Creates a new read replica set. This is an asynchronous operation. **Request Body:** ```json { - "name": "my-reporting-replica", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5 + "name": "replica-set-test2", + "cpu_millis": 1000, + "memory_gbs": 4, + "nodes": 1 } ``` **Response:** `202 Accepted` ```json { - "id": "alb8jicdpr", - "name": "my-reporting-replica", - "status": "creating", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5 + "id": "dsldm715t2", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4 } ``` @@ -652,22 +433,27 @@ Deletes a specific read replica set. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize ``` -Changes resource allocation for a read replica set. +Changes resource allocation for a read replica set. This operation is async. **Request Body:** ```json { "cpu_millis": 500, - "memory_gbs": 1.0, - "nodes": 3 + "memory_gbs": 2, + "nodes": 2 } ``` **Response:** `202 Accepted` +```json +{ + "message": "Replica set resize request accepted" +} +``` -### Read Replica Connection Pooler +### Read Replica Set Connection Pooler -#### Enable Replica Pooler +#### Enable Replica Set Pooler ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler @@ -676,8 +462,13 @@ POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/e Activates the connection pooler for a read replica set. **Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` -#### Disable Replica Pooler +#### Disable Replica Set Pooler ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler @@ -686,8 +477,13 @@ POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/d Deactivates the connection pooler for a read replica set. **Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} +``` -### Set Replica Environment +### Set Replica Set Environment ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment @@ -703,6 +499,225 @@ Sets the environment type for a read replica set. ``` **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 +``` + +Lists 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 +``` + +Creates 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} +``` + +Retrieves 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 +``` + +Updates 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} +``` + +Deletes 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 +``` + +Retrieves 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 +``` + +Creates 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} +``` + +Retrieves details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Deletes 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 +``` + +Associates 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 +``` + +Disassociates a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` ## Data Models @@ -774,8 +789,8 @@ Sets the environment type for a read replica set. "name": "string", "status": "creating|active|resizing|deleting|error", "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5, + "cpu_millis": 1000, + "memory_gbs": 4, "metadata": { "environment": "PROD|DEV" }, @@ -819,20 +834,3 @@ The API uses standard HTTP status codes and returns error details in JSON format "message": "The service_type field is required" } ``` - -## Rate Limiting - -The API implements rate limiting to ensure fair usage: - -- **Development Environment**: More lenient rate limits for testing -- **Production Environment**: Strict rate limits for stability -- **Local Development**: No rate limits applied - -When rate limits are exceeded, the API returns `429 Too Many Requests` with retry information in the response headers. - -## Support and Contact - -For API support and questions: -- **Support**: [TigerData Support](https://www.tigerdata.com/contact) -- **License**: [Terms of Service](https://www.tigerdata.com/legal/terms) -- **Documentation**: This API reference follows the OpenAPI 3.0.3 specification \ No newline at end of file From 2f12d32ff4fff27c77b0a539a8585de5df75180a Mon Sep 17 00:00:00 2001 From: josesahad Date: Fri, 5 Sep 2025 13:00:57 +0200 Subject: [PATCH 06/24] Fix replica set retrieval docs --- api/api-reference.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index 0cfc44914e..b6f8db3dc3 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -363,18 +363,24 @@ Retrieves all read replica sets associated with a primary service. ```json [ { - "id": "dsldm715t2", - "name": "replica-set-test", + "id": "l5alxb3s2g", + "name": "replica-set-test2", "status": "active", "nodes": 1, - "cpu_millis": 500, - "memory_gbs": 2, - "metadata": { - "environment": "PROD" - }, + "cpu_millis": 1000, + "memory_gbs": 4, "endpoint": { - "host": "jz22xtzemv.dsldm715t2.tsdb.cloud.timescale.com", - "port": 39680 + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38448 + }, + "connection_pooler": { + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38543 + } + }, + "metadata": { + "environment": "DEV" } } ] From 81b21fcf7ef32815dad1c0e464477d5736ae657b Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 9 Sep 2025 11:21:28 +0100 Subject: [PATCH 07/24] chore: few small updates. --- api/api-reference.md | 79 +++++++++------- getting-started/get-started-devops-as-code.md | 94 ++++++++++--------- 2 files changed, 95 insertions(+), 78 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index b6f8db3dc3..7dbea75899 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -1,11 +1,11 @@ --- -title: Tiger Cloud API reference +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] --- -# Tiger Cloud API reference +# Tiger Cloud REST API reference A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. @@ -32,7 +32,12 @@ curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project ## Service Management -Manage database services including TimescaleDB, PostgreSQL, and Vector databases. +You use this endpoint to create and manage the following Tiger Posgres 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 @@ -40,7 +45,7 @@ Manage database services including TimescaleDB, PostgreSQL, and Vector databases GET /projects/{project_id}/services ``` -Retrieves all services within a project. +Retrieve all services within a project. **Response:** `200 OK` ```json @@ -78,7 +83,7 @@ Retrieves all services within a project. POST /projects/{project_id}/services ``` -Creates a new database service. This is an asynchronous operation. +Create a new Tiger Postgres service. This is an asynchronous operation. **Request Body:** ```json @@ -124,9 +129,10 @@ Creates a new database service. This is an asynchronous operation. ``` **Service Types:** -- `TIMESCALEDB`: TimescaleDB service -- `POSTGRES`: PostgreSQL service -- `VECTOR`: Vector database service +- `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 @@ -134,7 +140,7 @@ Creates a new database service. This is an asynchronous operation. GET /projects/{project_id}/services/{service_id} ``` -Retrieves details of a specific service. +Retrieve details of a specific service. **Response:** `200 OK` ```json @@ -186,7 +192,7 @@ Retrieves details of a specific service. DELETE /projects/{project_id}/services/{service_id} ``` -Deletes a specific service. This is an asynchronous operation. +Delete a specific service. This is an asynchronous operation. **Response:** `202 Accepted` @@ -196,7 +202,7 @@ Deletes a specific service. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/resize ``` -Changes CPU and memory allocation for a service. +Change CPU and memory allocation for a service. **Request Body:** ```json @@ -214,7 +220,7 @@ Changes CPU and memory allocation for a service. POST /projects/{project_id}/services/{service_id}/updatePassword ``` -Sets a new master password for the service. +Set a new master password for the service. **Request Body:** ```json @@ -231,7 +237,7 @@ Sets a new master password for the service. POST /projects/{project_id}/services/{service_id}/setEnvironment ``` -Sets the environment type for the service. +Set the environment type for the service. **Request Body:** ```json @@ -257,7 +263,7 @@ Sets the environment type for the service. POST /projects/{project_id}/services/{service_id}/setHA ``` -Changes the HA configuration for a service. This is an asynchronous operation. +Change the HA configuration for a service. This is an asynchronous operation. **Request Body:** ```json @@ -276,7 +282,7 @@ Changes the HA configuration for a service. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/enablePooler ``` -Activates the connection pooler for a service. +Activate the connection pooler for a service. **Response:** `200 OK` ```json @@ -291,7 +297,7 @@ Activates the connection pooler for a service. POST /projects/{project_id}/services/{service_id}/disablePooler ``` -Deactivates the connection pooler for a service. +Deactivate the connection pooler for a service. **Response:** `200 OK` ```json @@ -305,7 +311,7 @@ Deactivates the connection pooler for a service. POST /projects/{project_id}/services/{service_id}/forkService ``` -Creates a new, independent service by taking a snapshot of an existing one. +Create a new, independent service by taking a snapshot of an existing one. **Request Body:** ```json @@ -357,7 +363,7 @@ Manage read replicas for improved read performance. GET /projects/{project_id}/services/{service_id}/replicaSets ``` -Retrieves all read replica sets associated with a primary service. +Retrieve all read replica sets associated with a primary service. **Response:** `200 OK` ```json @@ -399,7 +405,7 @@ Retrieves all read replica sets associated with a primary service. POST /projects/{project_id}/services/{service_id}/replicaSets ``` -Creates a new read replica set. This is an asynchronous operation. +Create a new read replica set. This is an asynchronous operation. **Request Body:** ```json @@ -429,7 +435,7 @@ Creates a new read replica set. This is an asynchronous operation. DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} ``` -Deletes a specific read replica set. This is an asynchronous operation. +Delete a specific read replica set. This is an asynchronous operation. **Response:** `202 Accepted` @@ -439,7 +445,7 @@ Deletes a specific read replica set. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize ``` -Changes resource allocation for a read replica set. This operation is async. +Change resource allocation for a read replica set. This operation is async. **Request Body:** ```json @@ -465,7 +471,7 @@ Changes resource allocation for a read replica set. This operation is async. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler ``` -Activates the connection pooler for a read replica set. +Activate the connection pooler for a read replica set. **Response:** `200 OK` ```json @@ -480,7 +486,7 @@ Activates the connection pooler for a read replica set. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler ``` -Deactivates the connection pooler for a read replica set. +Deactivate the connection pooler for a read replica set. **Response:** `200 OK` ```json @@ -495,7 +501,7 @@ Deactivates the connection pooler for a read replica set. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment ``` -Sets the environment type for a read replica set. +Set the environment type for a read replica set. **Request Body:** ```json @@ -521,7 +527,7 @@ Virtual Private Clouds (VPCs) provide network isolation for your TigerData servi GET /projects/{project_id}/vpcs ``` -Lists all Virtual Private Clouds in a project. +List all Virtual Private Clouds in a project. **Response:** `200 OK` ```json @@ -541,7 +547,7 @@ Lists all Virtual Private Clouds in a project. POST /projects/{project_id}/vpcs ``` -Creates a new VPC. +Create a new VPC. **Request Body:** ```json @@ -568,7 +574,7 @@ Creates a new VPC. GET /projects/{project_id}/vpcs/{vpc_id} ``` -Retrieves details of a specific VPC. +Retrieve details of a specific VPC. **Response:** `200 OK` ```json @@ -586,7 +592,7 @@ Retrieves details of a specific VPC. POST /projects/{project_id}/vpcs/{vpc_id}/rename ``` -Updates the name of a specific VPC. +Update the name of a specific VPC. **Request Body:** ```json @@ -611,7 +617,7 @@ Updates the name of a specific VPC. DELETE /projects/{project_id}/vpcs/{vpc_id} ``` -Deletes a specific VPC. +Delete a specific VPC. **Response:** `204 No Content` @@ -625,7 +631,7 @@ Manage peering connections between VPCs across different accounts and regions. GET /projects/{project_id}/vpcs/{vpc_id}/peerings ``` -Retrieves all VPC peering connections for a given VPC. +Retrieve all VPC peering connections for a given VPC. **Response:** `200 OK` ```json @@ -648,7 +654,7 @@ Retrieves all VPC peering connections for a given VPC. POST /projects/{project_id}/vpcs/{vpc_id}/peerings ``` -Creates a new VPC peering connection. +Create a new VPC peering connection. **Request Body:** ```json @@ -677,7 +683,7 @@ Creates a new VPC peering connection. GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} ``` -Retrieves details of a specific VPC peering connection. +Retrieve details of a specific VPC peering connection. ### Delete VPC Peering @@ -685,7 +691,7 @@ Retrieves details of a specific VPC peering connection. DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} ``` -Deletes a specific VPC peering connection. +Delete a specific VPC peering connection. **Response:** `204 No Content` @@ -697,7 +703,7 @@ Deletes a specific VPC peering connection. POST /projects/{project_id}/services/{service_id}/attachToVPC ``` -Associates a service with a VPC. +Associate a service with a VPC. **Request Body:** ```json @@ -714,7 +720,7 @@ Associates a service with a VPC. POST /projects/{project_id}/services/{service_id}/detachFromVPC ``` -Disassociates a service from its VPC. +Disassociate a service from its VPC. **Request Body:** ```json @@ -789,6 +795,7 @@ Disassociates a service from its VPC. ``` ### Read Replica Set Object + ```json { "id": "string", @@ -815,7 +822,7 @@ Disassociates a service from its VPC. ## Error Handling -The API uses standard HTTP status codes and returns error details in JSON format. +Tiger Cloud REST API uses standard HTTP status codes and returns error details in JSON format. ### Error Response Format ```json diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index aa85e6a578..d5b48450a9 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -59,36 +59,32 @@ proper authentication headers. export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" ``` -1. **Perform health check and test your connection to $CLOUD_LONG REST API** - - Test the API connection using a simple health check request: - - ```bash - curl -X GET "${API_BASE_URL}/healthcheck" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" - ``` - - Expected response: - ```json - { - "status": "healthy", - "timestamp": "2024-01-15T10:30:00Z" - } - ``` - -1. **Validate authentication** - - Test authentication by listing existing services: - +1. **Test your authenticated connection to $CLOUD_LONG REST API by listing services** + ```bash curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ -H "Content-Type: application/json" ``` + This call returns something like: + - No services: + ```terminaloutput + []% + ``` + - One or more services: + + ```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}}] + ``` + -Successful authentication returns a JSON array of services (may be empty for new projects). ## Create your first service @@ -119,34 +115,48 @@ Create a new database service using the Tiger Cloud REST API with secure configu -H "Content-Type: application/json" \ -d @service-config.json ``` - - 2. Save the service ID from the response: - ```bash - # Extract service_id from the JSON response - export SERVICE_ID="extracted-service-id-from-response" + $CLOUD_LONG creates a production environment for you. 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} + } ``` + - The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. - -1. **Monitor service creation progress** - - 1. Check service status periodically: + 2. Save `service_id` from the response to a variable: ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" + # Extract service_id from the JSON response + export SERVICE_ID="service_id-from-response" ``` - 2. Wait for status to change from `CONFIGURING` to `READY`: - - `QUEUED`: Service creation request is queued - - `CONFIGURING`: Service is being provisioned - - `READY`: Service is available for use - - `UNSTABLE`: Service encountered issues during creation - - Service creation typically completes within 5-10 minutes depending on the configuration. +1. **Change the environment from production to development** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d '{"environment": "DEV"}' + ``` + You see something like: + ```terminaloutput + { + "message": "Environment set successfully" + } + ``` +And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + ## Security best practices Follow these security guidelines when working with the Tiger Cloud REST API: From 39a62ae1a36511ecdc91a736d8da7afba38a764c Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 9 Sep 2025 12:02:59 +0100 Subject: [PATCH 08/24] chore: few small updates. --- getting-started/get-started-devops-as-code.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index d5b48450a9..8df4ac02c7 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -51,9 +51,9 @@ proper authentication headers. export TIGERDATA_SECRET_KEY="Secret key" ``` -1. **Configure API endpoint** +1. **Configure the API endpoint** - Set the API base URL for your environment: + Set the base URL in your environment: ```bash export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" From 3238fefa5628ec9bfe9e4b8f3e9bc36c54dc4d5d Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 11 Sep 2025 10:57:08 +0100 Subject: [PATCH 09/24] chore: change title to give space for the CLI --- getting-started/get-started-devops-as-code.md | 4 ++-- getting-started/page-index/page-index.js | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 8df4ac02c7..a7882b458a 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,5 +1,5 @@ --- -title: "DevOps with Tiger Cloud REST API" +title: "DevOps as code with Tiger Cloud" excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication @@ -15,7 +15,7 @@ tags: import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -# DevOps with Tiger Cloud REST API +# DevOps as code with Tiger Cloud [$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index a8681649f7..501845fbd7 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -23,7 +23,7 @@ module.exports = [ excerpt: "Create a Tiger Cloud service and connect to it", }, { - title: "DevOps with Tiger Cloud REST API", + title: "DevOps as code with Tiger Cloud", href: "get-started-devops-as-code", excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", }, From d77f5549f303e40e13e1d61b24a94f09ead74a2c Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 29 Sep 2025 12:16:45 +0200 Subject: [PATCH 10/24] chore: commit for pull from latest. --- _partials/_devops-cli-get-started.md | 217 ++++++++++++++++++ _partials/_devops-rest-api-get-started.md | 176 ++++++++++++++ getting-started/get-started-devops-as-code.md | 178 ++------------ 3 files changed, 407 insertions(+), 164 deletions(-) create mode 100644 _partials/_devops-cli-get-started.md create mode 100644 _partials/_devops-rest-api-get-started.md diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md new file mode 100644 index 0000000000..343e117115 --- /dev/null +++ b/_partials/_devops-cli-get-started.md @@ -0,0 +1,217 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +is a command-line interface for managing TigerData Cloud Platform resources. + +$CLOUD_LONG Cli is a command-line interface that you use to manage $CLOUD_LONG resources +including VPCs, services, read replicas, and related infrastructure. + +This page shows you how to install and set up secure authentication for the $CLOUD_LONG Cli, then create your first +service. + +## Prerequisites + + + + +## Install and configure secure authentication + + + + +1. **Install the CLI** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +3. +4. **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. In $CONSOLE [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 $CLOUD_LONG REST API by listing services** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + + This call returns something like: + - No services: + ```terminaloutput + []% + ``` + - One or more services: + + ```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 + +Create a new database service using the Tiger Cloud REST API with secure configuration. + + + +1. **Define the service creation payload in a JSON file** + ```bash + cat > service-config.json << 'EOF' + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + EOF + ``` + +1. **Submit service creation request** + + 1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` + $CLOUD_LONG creates a production environment for you. 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} + } + ``` + + +2. 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. **Change the environment from production to development** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d '{"environment": "DEV"}' + ``` +You see something like: + ```terminaloutput + { + "message": "Environment set successfully" + } + ``` + + + +And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + +## Security best practices + +Follow these security guidelines when working with the Tiger Cloud REST API: + +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Limit credential scope to minimum required permissions + - Never commit credentials to version control systems + +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + - Consider IP allowlisting for production API access + - Monitor API access logs for suspicious activity + +- **Access control** + - Create dedicated service accounts for automated API access + - Use principle of least privilege for API key permissions + - Regularly audit and review API access patterns + - Implement proper session management for interactive applications + +- **Data protection** + - Encrypt sensitive data before API transmission when applicable + - 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/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md new file mode 100644 index 0000000000..2759080bac --- /dev/null +++ b/_partials/_devops-rest-api-get-started.md @@ -0,0 +1,176 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources +including VPCs, services, and read replicas. + +This page shows you how to set up secure authentication for the $CLOUD_LONG REST API and create your first service. + +## Prerequisites + + + +* Install [curl][curl]. + + +## Configure secure authentication + +$CLOUD_LONG REST API 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. In $CONSOLE [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 $CLOUD_LONG REST API by listing services** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + + This call returns something like: + - No services: + ```terminaloutput + []% + ``` + - One or more services: + + ```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 + +Create a new database service using the Tiger Cloud REST API with secure configuration. + + + +1. **Define the service creation payload in a JSON file** + ```bash + cat > service-config.json << 'EOF' + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + EOF + ``` + +1. **Submit service creation request** + + 1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` + $CLOUD_LONG creates a production environment for you. 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} + } + ``` + + +2. 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. **Change the environment from production to development** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d '{"environment": "DEV"}' + ``` +You see something like: + ```terminaloutput + { + "message": "Environment set successfully" + } + ``` + + + +And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + +## Security best practices + +Follow these security guidelines when working with the Tiger Cloud REST API: + +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Limit credential scope to minimum required permissions + - Never commit credentials to version control systems + +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + - Consider IP allowlisting for production API access + - Monitor API access logs for suspicious activity + +- **Access control** + - Create dedicated service accounts for automated API access + - Use principle of least privilege for API key permissions + - Regularly audit and review API access patterns + - Implement proper session management for interactive applications + +- **Data protection** + - Encrypt sensitive data before API transmission when applicable + - 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/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index a7882b458a..88b1038ecf 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,181 +13,31 @@ tags: - authentication --- -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -# DevOps as code with Tiger Cloud - -[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read -replicas. - -This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. - -## Prerequisites - - - -* Install [curl][curl]. - - -## Configure secure authentication - -$CLOUD_LONG REST API 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. In $CONSOLE [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" - ``` +import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; +import CLIGS from "versionContent/_partials/_devops-cli-get-started.mdx"; -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 $CLOUD_LONG REST API by listing services** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" - ``` - - This call returns something like: - - No services: - ```terminaloutput - []% - ``` - - One or more services: - - ```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 - -Create a new database service using the Tiger Cloud REST API with secure configuration. - - - -1. **Define the service creation payload in a JSON file** - ```bash - cat > service-config.json << 'EOF' - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - EOF - ``` - -1. **Submit service creation request** - - 1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - $CLOUD_LONG creates a production environment for you. 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} - } - ``` - - - 2. 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. **Change the environment from production to development** +# DevOps as code with Tiger Cloud - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d '{"environment": "DEV"}' - ``` - You see something like: - ```terminaloutput - { - "message": "Environment set successfully" - } - ``` +$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, CLI commands, and +MCP endpoints that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONG +programmatically. - + -And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your -$SERVICE_SHORTs in $CLOUD_LONG. + -## Security best practices + -Follow these security guidelines when working with the Tiger Cloud REST API: + -- **Credential management** - - Store API credentials as environment variables, not in code - - Use credential rotation policies for production environments - - Limit credential scope to minimum required permissions - - Never commit credentials to version control systems + -- **Network security** - - Use HTTPS endpoints exclusively for API communication - - Implement proper certificate validation in your HTTP clients - - Consider IP allowlisting for production API access - - Monitor API access logs for suspicious activity + -- **Access control** - - Create dedicated service accounts for automated API access - - Use principle of least privilege for API key permissions - - Regularly audit and review API access patterns - - Implement proper session management for interactive applications + -- **Data protection** - - Encrypt sensitive data before API transmission when applicable - - 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 From cd7314990170b48c630096cdbdf10f6e3a8c8dd9 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 29 Sep 2025 16:32:04 +0200 Subject: [PATCH 11/24] chore: cli docs. --- _partials/_devops-cli-get-started.md | 310 +++++++++--------- _partials/_devops-rest-api-get-started.md | 14 +- api/api-reference.md | 8 +- getting-started/get-started-devops-as-code.md | 4 +- 4 files changed, 168 insertions(+), 168 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 343e117115..f9845c206c 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -1,11 +1,10 @@ import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -is a command-line interface for managing TigerData Cloud Platform resources. +$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. -$CLOUD_LONG Cli is a command-line interface that you use to manage $CLOUD_LONG resources -including VPCs, services, read replicas, and related infrastructure. - -This page shows you how to install and set up secure authentication for the $CLOUD_LONG Cli, then create your first +This page shows you how to install and set up secure authentication for $CLI_LONG, then create your first service. ## Prerequisites @@ -13,98 +12,101 @@ service. -## Install and configure secure authentication - - - - -1. **Install the CLI** - - - - - - - - - - - +## 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 bash + sudo apt-get install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo bash + sudo apt-get install tiger-cli + ``` + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo bash + sudo yum install tiger-cli + ``` + + + + + + ```shell + curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo 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 + ``` - -3. -4. **Set up API credentials** + - 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: + + +1. **Set up API credentials** - ```bash - export TIGERDATA_PROJECT_ID="your-project-id" + 1. Log $CLI_LONG into your $CLOUD_LONG account + + ```shell + tiger auth login ``` + $CLI_LONG opens $CONSOLE_SHORT in your browser. Login, then click `Authorize`. - 1. In $CONSOLE [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. Select a $PROJECT_LONG. -1. **Test your authenticated connection to $CLOUD_LONG REST API by listing services** + $CLI_LONG stores your authentication information locally in `~/.config/tiger/config.yaml`. + +1. **Test your authenticated connection to $CLOUD_LONG by listing services** ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" + 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":"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}}] + ┌────────────┬─────────────────────┬────────┬─────────────┬──────────────┬──────────────────┐ + │ SERVICE ID │ NAME │ STATUS │ TYPE │ REGION │ CREATED │ + ├────────────┼─────────────────────┼────────┼─────────────┼──────────────┼──────────────────┤ + │ tgrservice │ tiger-agent-service │ READY │ TIMESCALEDB │ eu-central-1 │ 2025-09-25 16:09 │ + └────────────┴─────────────────────┴────────┴─────────────┴──────────────┴──────────────────┘ ``` @@ -112,102 +114,100 @@ service. ## Create your first service -Create a new database service using the Tiger Cloud REST API with secure configuration. +Create a new $SERVICE_LONG using $CLI_LONG with a secure configuration: -1. **Define the service creation payload in a JSON file** - ```bash - cat > service-config.json << 'EOF' - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - EOF +1. **Submit a service creation request** + ```shell + tiger service create + ``` + $CLOUD_LONG creates a `#dev` environment for you. 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 status: QUEUED... + ⏳ Service status: QUEUED... + ⏳ Service status: QUEUED... + 🎉 Service is ready and running! ``` + The $SERVICE_SHORT configuration is stored by the $CLI_SHORT and this $SERVICE_SHORT is set as default. -1. **Submit service creation request** - - 1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - $CLOUD_LONG creates a production environment for you. 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} - } - ``` - - -2. 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 $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 ``` -1. **Change the environment from production to development** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d '{"environment": "DEV"}' - ``` -You see something like: - ```terminaloutput - { - "message": "Environment set successfully" - } - ``` -And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your -$SERVICE_SHORTs in $CLOUD_LONG. - -## Security best practices - -Follow these security guidelines when working with the Tiger Cloud REST API: - -- **Credential management** - - Store API credentials as environment variables, not in code - - Use credential rotation policies for production environments - - Limit credential scope to minimum required permissions - - Never commit credentials to version control systems - -- **Network security** - - Use HTTPS endpoints exclusively for API communication - - Implement proper certificate validation in your HTTP clients - - Consider IP allowlisting for production API access - - Monitor API access logs for suspicious activity - -- **Access control** - - Create dedicated service accounts for automated API access - - Use principle of least privilege for API key permissions - - Regularly audit and review API access patterns - - Implement proper session management for interactive applications +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 $CLOUD_LONG account | +| | login | Create an authenticated connection to your $CLOUD_LONG account | +| | 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 | +| config | | Manage your $CLI_LONG configuration | +| | show | Show the current configuration | +| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | +| | 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 | +| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | +| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | +| | create | Create a new $SERVICE_SHORT in this $PROJECT_SHORT | +| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | +| | update-password `` | Update the password for a $SERVICE_SHORT | +| db | | Database operations and management | +| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | +| | connect `` | Connect to a $SERVICE_SHORT | +| | test-connection `` | Test the connectivity to a $SERVICE_SHORT | +| mcp | | Manage the $MCP_LONG | +| | start | Start the $MCP_LONG | +| | 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. | -- **Data protection** - - Encrypt sensitive data before API transmission when applicable - - 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/ diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index 2759080bac..1ff96a48d4 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -1,9 +1,9 @@ import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources +[$REST_LONG][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources including VPCs, services, and read replicas. -This page shows you how to set up secure authentication for the $CLOUD_LONG REST API and create your first service. +This page shows you how to set up secure authentication for the $REST_LONG and create your first service. ## Prerequisites @@ -14,7 +14,7 @@ This page shows you how to set up secure authentication for the $CLOUD_LONG REST ## Configure secure authentication -$CLOUD_LONG REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +$REST_LONG uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. @@ -42,7 +42,7 @@ proper authentication headers. export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" ``` -1. **Test your authenticated connection to $CLOUD_LONG REST API by listing services** +1. **Test your authenticated connection to $REST_LONG by listing services** ```bash curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ @@ -71,7 +71,7 @@ proper authentication headers. ## Create your first service -Create a new database service using the Tiger Cloud REST API with secure configuration. +Create a new database service using the $REST_LONG with secure configuration. @@ -137,12 +137,12 @@ You see something like: -And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your +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 Tiger Cloud REST API: +Follow these security guidelines when working with the $REST_LONG: - **Credential management** - Store API credentials as environment variables, not in code diff --git a/api/api-reference.md b/api/api-reference.md index 7dbea75899..d682b84a4d 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -5,9 +5,9 @@ tags: [REST] products: [cloud] --- -# Tiger Cloud REST API reference +# $REST_LONG reference -A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. +A comprehensive RESTful API for managing $CLOUD_LONG resources including VPCs, services, and read replicas. ## Overview @@ -16,7 +16,7 @@ A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, s ## Authentication -The TigerData Cloud API uses HTTP Basic Authentication. Include your access key and secret key in the Authorization header. +The $REST_LONG uses HTTP Basic Authentication. Include your access key and secret key in the Authorization header. ### Basic Authentication ```http @@ -32,7 +32,7 @@ curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project ## Service Management -You use this endpoint to create and manage the following Tiger Posgres services: +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 diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 88b1038ecf..d4adfaeff2 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -26,13 +26,13 @@ programmatically. - + - + From 6c2480335a4d3068aa2cbcfff44ca9457efef81d Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Tue, 30 Sep 2025 12:04:27 +0200 Subject: [PATCH 12/24] Apply suggestions from code review Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox --- _partials/_devops-cli-get-started.md | 4 ++-- _partials/_devops-rest-api-get-started.md | 11 +++++++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index f9845c206c..250f4ac75a 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -24,7 +24,7 @@ service. ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo bash + 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 ``` @@ -41,7 +41,7 @@ service. ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo bash + 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 ``` diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index 1ff96a48d4..170dfcf2c6 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -96,7 +96,14 @@ Create a new database service using the $REST_LONG with secure configuration. curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ -H "Content-Type: application/json" \ - -d @service-config.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 production environment for you. You see something like: ```terminaloutput @@ -123,7 +130,7 @@ Create a new database service using the $REST_LONG with secure configuration. 1. **Change the environment from production to development** ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}"/setEnvironment \ -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ -H "Content-Type: application/json" \ -d '{"environment": "DEV"}' From a45b764332a4b5dfaa12cd138ac2ffe5ea548276 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 30 Sep 2025 14:30:14 +0200 Subject: [PATCH 13/24] chore: updates on review. --- _partials/_devops-cli-get-started.md | 57 +++++------ _partials/_devops-rest-api-get-started.md | 113 +++++++++------------- _partials/_prereqs-cloud-account-only.md | 2 +- 3 files changed, 74 insertions(+), 98 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 250f4ac75a..1b4914c4a4 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -76,7 +76,7 @@ service. 1. **Set up API credentials** - 1. Log $CLI_LONG into your $CLOUD_LONG account + 1. Log $CLI_LONG into your $ACCOUNT_LONG ```shell tiger auth login @@ -85,7 +85,11 @@ service. 1. Select a $PROJECT_LONG. - $CLI_LONG stores your authentication information locally in `~/.config/tiger/config.yaml`. + 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** @@ -114,7 +118,7 @@ service. ## Create your first service -Create a new $SERVICE_LONG using $CLI_LONG with a secure configuration: +Create a new $SERVICE_LONG using $CLI_LONG: @@ -122,7 +126,8 @@ Create a new $SERVICE_LONG using $CLI_LONG with a secure configuration: ```shell tiger service create ``` - $CLOUD_LONG creates a `#dev` environment for you. You see something like: + $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! @@ -131,12 +136,9 @@ Create a new $SERVICE_LONG using $CLI_LONG with a secure configuration: 🎯 Set service 'happyservice' as default service. ⏳ Waiting for service to be ready (wait timeout: 30m0s)... ⏳ Service status: QUEUED... - ⏳ Service status: QUEUED... - ⏳ Service status: QUEUED... - ⏳ Service status: QUEUED... 🎉 Service is ready and running! ``` - The $SERVICE_SHORT configuration is stored by the $CLI_SHORT and this $SERVICE_SHORT is set as default. + This $SERVICE_SHORT is set as default by the $CLI_SHORT. 1. **Check the $CLI_SHORT configuration** ```shell @@ -144,21 +146,20 @@ Create a new $SERVICE_LONG using $CLI_LONG with a secure configuration: ``` 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 + 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. @@ -170,8 +171,8 @@ You can use the following commands with $CLI_LONG. For more information on each | Command | Subcommand | Description | |---------|----------------------------------|------------------------------------------------------------------------------------------------| -| auth | | Manage authentication and the credentials for your $CLOUD_LONG account | -| | login | Create an authenticated connection to your $CLOUD_LONG account | +| 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 | @@ -181,17 +182,17 @@ You can use the following commands with $CLI_LONG. For more information on each | | 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 | -| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | -| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | -| | create | Create a new $SERVICE_SHORT in this $PROJECT_SHORT | -| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | +| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | +| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | +| | create | Create a new $SERVICE_SHORT in this $PROJECT_SHORT | +| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | | | update-password `` | Update the password for a $SERVICE_SHORT | | db | | Database operations and management | | | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | | | connect `` | Connect to a $SERVICE_SHORT | | | test-connection `` | Test the connectivity to a $SERVICE_SHORT | | mcp | | Manage the $MCP_LONG | -| | start | Start 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 diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index 170dfcf2c6..e44dd82262 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -1,9 +1,9 @@ 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, services, and read replicas. +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. +This page shows you how to set up secure authentication for the $REST_LONG and create your first $SERVICE_SHORT. ## Prerequisites @@ -42,20 +42,20 @@ proper authentication headers. export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" ``` -1. **Test your authenticated connection to $REST_LONG by listing services** +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" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ -H "Content-Type: application/json" ``` This call returns something like: - - No services: + - No $SERVICE_SHORTs: ```terminaloutput []% ``` - - One or more services: + - One or more $SERVICE_SHORTs: ```terminaloutput [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", @@ -69,77 +69,62 @@ proper authentication headers. -## Create your first service +## Create your first $SERVICE_LONG -Create a new database service using the $REST_LONG with secure configuration. +Create a new $SERVICE_SHORT using the $REST_LONG: -1. **Define the service creation payload in a JSON file** +1. **Create a $SERVICE_SHORT using the POST endpoint** ```bash - cat > service-config.json << 'EOF' + 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 { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - EOF + "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. **Submit service creation request** - - 1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -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 production environment for you. 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} - } - ``` - - -2. Save `service_id` from the response to a variable: +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. **Change the environment from production to development** +1. **Check the configuration for the ** ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}"/setEnvironment \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d '{"environment": "DEV"}' + 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 - { - "message": "Environment set successfully" - } + {"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}} ``` @@ -154,28 +139,18 @@ 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 - - Limit credential scope to minimum required permissions - Never commit credentials to version control systems - **Network security** - Use HTTPS endpoints exclusively for API communication - Implement proper certificate validation in your HTTP clients - Consider IP allowlisting for production API access - - Monitor API access logs for suspicious activity - -- **Access control** - - Create dedicated service accounts for automated API access - - Use principle of least privilege for API key permissions - - Regularly audit and review API access patterns - - Implement proper session management for interactive applications - **Data protection** - - Encrypt sensitive data before API transmission when applicable - 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 diff --git a/_partials/_prereqs-cloud-account-only.md b/_partials/_prereqs-cloud-account-only.md index 9d31734690..bebd9d9f60 100644 --- a/_partials/_prereqs-cloud-account-only.md +++ b/_partials/_prereqs-cloud-account-only.md @@ -1,5 +1,5 @@ To follow the steps on this page: -* Create a target [$CLOUD_LONG account][create-account]. +* Create a target [$ACCOUNT_LONG][create-account]. [create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-cloud-account \ No newline at end of file From 1fac0458db3a2edfb58b64dc2b62b9faf2a4208f Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 30 Sep 2025 15:32:25 +0200 Subject: [PATCH 14/24] chore: updates on review. --- _partials/_devops-rest-api-get-started.md | 158 ++++++++++++++++ getting-started/get-started-devops-as-code.md | 179 +----------------- 2 files changed, 162 insertions(+), 175 deletions(-) create mode 100644 _partials/_devops-rest-api-get-started.md diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md new file mode 100644 index 0000000000..e44dd82262 --- /dev/null +++ b/_partials/_devops-rest-api-get-started.md @@ -0,0 +1,158 @@ +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. In $CONSOLE [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 ** + + ```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 + - Consider IP allowlisting for production API access + +- **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/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index a7882b458a..53b841e78f 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,181 +13,10 @@ tags: - authentication --- -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; +import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; -# DevOps as code with Tiger Cloud +# DevOps as code with $CLOUD_LONG -[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read -replicas. + -This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. - -## Prerequisites - - - -* Install [curl][curl]. - - -## Configure secure authentication - -$CLOUD_LONG REST API 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. In $CONSOLE [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 $CLOUD_LONG REST API by listing services** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" - ``` - - This call returns something like: - - No services: - ```terminaloutput - []% - ``` - - One or more services: - - ```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 - -Create a new database service using the Tiger Cloud REST API with secure configuration. - - - -1. **Define the service creation payload in a JSON file** - ```bash - cat > service-config.json << 'EOF' - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - EOF - ``` - -1. **Submit service creation request** - - 1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - $CLOUD_LONG creates a production environment for you. 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} - } - ``` - - - 2. 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. **Change the environment from production to development** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d '{"environment": "DEV"}' - ``` - You see something like: - ```terminaloutput - { - "message": "Environment set successfully" - } - ``` - - - -And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your -$SERVICE_SHORTs in $CLOUD_LONG. - -## Security best practices - -Follow these security guidelines when working with the Tiger Cloud REST API: - -- **Credential management** - - Store API credentials as environment variables, not in code - - Use credential rotation policies for production environments - - Limit credential scope to minimum required permissions - - Never commit credentials to version control systems - -- **Network security** - - Use HTTPS endpoints exclusively for API communication - - Implement proper certificate validation in your HTTP clients - - Consider IP allowlisting for production API access - - Monitor API access logs for suspicious activity - -- **Access control** - - Create dedicated service accounts for automated API access - - Use principle of least privilege for API key permissions - - Regularly audit and review API access patterns - - Implement proper session management for interactive applications - -- **Data protection** - - Encrypt sensitive data before API transmission when applicable - - 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 +[rest-api-reference]: /api/:currentVersion:/api-reference/ \ No newline at end of file From 9519e9036268f2b1e7ba8753c50b596abbf04c9f Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Wed, 1 Oct 2025 11:29:52 +0200 Subject: [PATCH 15/24] Apply suggestion from @nathanjcochran Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox --- _partials/_devops-cli-get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 1b4914c4a4..1eebdcf963 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -33,7 +33,7 @@ service. ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.deb.sh | sudo bash + 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 ``` From acd6526ebc3d90e998b7ebfbc575f2f2d2269e35 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Wed, 1 Oct 2025 11:30:20 +0200 Subject: [PATCH 16/24] Apply suggestion from @nathanjcochran Co-authored-by: Nathan Cochran Signed-off-by: Iain Cox --- _partials/_devops-cli-get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 1eebdcf963..405df928d6 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -50,7 +50,7 @@ service. ```shell - curl -s https://packagecloud.io/install/repositories/timescale/tiger-cli/script.rpm.sh | sudo bash + 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 ``` From 14e1e1f4d7d5df02a837efe9b18e9b63311062bb Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 1 Oct 2025 11:41:21 +0200 Subject: [PATCH 17/24] chore: updates on review. --- _partials/_devops-rest-api-get-started.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index e44dd82262..c8afeb0898 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -111,7 +111,7 @@ Create a new $SERVICE_SHORT using the $REST_LONG: export SERVICE_ID="service_id-from-response" ``` -1. **Check the configuration for the ** +1. **Check the configuration for the $SERVICE_SHORT** ```bash curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ @@ -144,7 +144,6 @@ Follow these security guidelines when working with the $REST_LONG: - **Network security** - Use HTTPS endpoints exclusively for API communication - Implement proper certificate validation in your HTTP clients - - Consider IP allowlisting for production API access - **Data protection** - Use secure storage for service connection strings and passwords From 64eaeb2b8435698a8b376bb52a5f0d72079f3205 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Thu, 2 Oct 2025 14:38:05 +0200 Subject: [PATCH 18/24] Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox --- _partials/_devops-cli-get-started.md | 18 +++++++++--------- _partials/_devops-rest-api-get-started.md | 8 ++++---- getting-started/get-started-devops-as-code.md | 4 ++-- getting-started/page-index/page-index.js | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index 405df928d6..a9e4ed8b84 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -16,9 +16,9 @@ service. -1. ** Install $CLI_LONG** +1. **Install $CLI_LONG** - Use the Terminal to install the $CLI_SHORT: + Use the terminal to install the $CLI_SHORT: @@ -76,12 +76,12 @@ service. 1. **Set up API credentials** - 1. Log $CLI_LONG into your $ACCOUNT_LONG + 1. Log $CLI_LONG into your $ACCOUNT_LONG: ```shell tiger auth login ``` - $CLI_LONG opens $CONSOLE_SHORT in your browser. Login, then click `Authorize`. + $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. 1. Select a $PROJECT_LONG. @@ -127,7 +127,7 @@ Create a new $SERVICE_LONG using $CLI_LONG: 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: + read replication. You see something like: ```terminaloutput 🚀 Creating service 'db-11111' (auto-generated name)... ✅ Service creation request accepted! @@ -193,7 +193,7 @@ You can use the following commands with $CLI_LONG. For more information on each | | 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. | +| | start `stdio` \| `http` | Start the $MCP_LONG with stdio or HTTP transport | ## Flags @@ -201,13 +201,13 @@ You can use the following global flags with $CLI_LONG: | Flag | Default | Description | |--|-----------------|-----------------------------------------------------------------------| -| --analytics | `true` | Set to `false` to disable usage analytics. | +| --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. | +| --project-id string | - | Set the $PROJECT_LONG to manage | +| --service-id string | - | Set the $SERVICE_LONG to manage | diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index c8afeb0898..55514a38fb 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -21,7 +21,7 @@ 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: + 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" @@ -90,7 +90,7 @@ Create a new $SERVICE_SHORT using the $REST_LONG: }' ``` $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or - read-replication. You see something like: + read replication. You see something like: ```terminaloutput { "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", @@ -105,7 +105,7 @@ Create a new $SERVICE_SHORT using the $REST_LONG: } ``` -1. Save `service_id` from the response to a variable: +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" @@ -118,7 +118,7 @@ Create a new $SERVICE_SHORT using the $REST_LONG: -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ -H "Content-Type: application/json" ``` -You see something like: + 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", diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index e0c717db95..c21618bf38 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -21,7 +21,7 @@ import CLIGS from "versionContent/_partials/_devops-cli-get-started.mdx"; # DevOps as code with Tiger Cloud $COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, CLI commands, and -MCP endpoints that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONG +MCP endpoints that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs programmatically. @@ -32,7 +32,7 @@ programmatically. - + diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 501845fbd7..e1c700faea 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -25,7 +25,7 @@ module.exports = [ { title: "DevOps as code with Tiger Cloud", href: "get-started-devops-as-code", - excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", + excerpt: "Set up secure authentication for the Tiger REST API and create your first service", }, { title: "Run your queries from Tiger Cloud Console", From 2245ca6e144619a6de9b81798234e9a5f4c2d01d Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 2 Oct 2025 14:45:09 +0200 Subject: [PATCH 19/24] chore: updates on review. --- _partials/_devops-rest-api-get-started.md | 2 +- getting-started/get-started-devops-as-code.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md index 55514a38fb..fdf27c3062 100644 --- a/_partials/_devops-rest-api-get-started.md +++ b/_partials/_devops-rest-api-get-started.md @@ -27,7 +27,7 @@ proper authentication headers. export TIGERDATA_PROJECT_ID="your-project-id" ``` - 1. In $CONSOLE [create your client credentials][create-client-credentials] and store them securely using environment variables: + 1. [Create your client credentials][create-client-credentials] and store them securely using environment variables: ```bash export TIGERDATA_ACCESS_KEY="Public key" diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index c21618bf38..382448ea57 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,6 +1,6 @@ --- title: "DevOps as code with Tiger Cloud" -excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" +excerpt: "Configure secure authentication and manage the resources in your Tiger project using REST, the Cli or MCP." keywords: - authentication - service creation @@ -24,7 +24,7 @@ $COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This incl MCP endpoints that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs programmatically. - + From 5180505aa3673a9f53c175a9a5c5d44a39d6eb57 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 2 Oct 2025 14:51:20 +0200 Subject: [PATCH 20/24] chore: updates on review. --- getting-started/page-index/page-index.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index e1c700faea..08862cd8b9 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -15,20 +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: "DevOps as code with Tiger Cloud", + 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 Cloud Console", + title: "Run your queries from Tiger Console", href: "run-queries-from-console", excerpt: "Run your queries securely from inside Tiger Cloud Console", }, From 8ef16b7ff1ca85690ffc92db475e2a80816d7fbb Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 2 Oct 2025 14:55:40 +0200 Subject: [PATCH 21/24] chore: updates on review. --- getting-started/get-started-devops-as-code.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 382448ea57..1258de6b64 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,6 +1,6 @@ --- -title: "DevOps as code with Tiger Cloud" -excerpt: "Configure secure authentication and manage the resources in your Tiger project using REST, the Cli or MCP." +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 @@ -18,10 +18,10 @@ 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 Tiger Cloud +# DevOps as code with $CLOUD_LONG -$COMPANY supplies a clean, programmatic control layer for $CLOUD_LONG. This includes RESTful APIs, CLI commands, and -MCP endpoints that let humans, machines, and AI agents easily provision, configure, and manage $SERVICE_LONGs +$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. From 1344101de6618102a1d7427ff317dd7bee138d30 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 2 Oct 2025 17:04:37 +0200 Subject: [PATCH 22/24] chore: updates on review. --- _partials/_devops-cli-get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index a9e4ed8b84..f73e0429ee 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -184,7 +184,7 @@ You can use the following commands with $CLI_LONG. For more information on each | service | | Manage the $SERVICE_LONGs in this $PROJECT_SHORT | | | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | | | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | -| | create | Create a new $SERVICE_SHORT in this $PROJECT_SHORT | +| | create --addons=time-series \| ai \| none | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible flavors are:
  • time-series: with the Timescaledb and Timescaledb Toolkit extensions
  • ai: with the Timescaledb, Timescaledb Toolkit, vector and vectorscale extensions
  • 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`. | | | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | | | update-password `` | Update the password for a $SERVICE_SHORT | | db | | Database operations and management | From b6b978a1c0ec8872126bbb126b87d579051d1a7d Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 2 Oct 2025 17:23:05 +0200 Subject: [PATCH 23/24] chore: updates on review. --- _partials/_devops-cli-get-started.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index f73e0429ee..b2489092f9 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -83,14 +83,32 @@ service. ``` $CLI_LONG opens $CONSOLE_SHORT in your browser. Log in, then click `Authorize`. - 1. Select a $PROJECT_LONG. + 1. Log $CLI_LONG into your $ACCOUNT_LONG - If only one $PROJECT_SHORT is associated with your $ACCOUNT_SHORT, this step is not shown. + ```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. + 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 From ef3b49244c83088b3bb7c3c1451e9324dad7e3ef Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Fri, 3 Oct 2025 12:10:40 +0200 Subject: [PATCH 24/24] chore: add fork and free. --- _partials/_devops-cli-get-started.md | 51 ++++++++++++++-------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/_partials/_devops-cli-get-started.md b/_partials/_devops-cli-get-started.md index b2489092f9..16eb6a88e5 100644 --- a/_partials/_devops-cli-get-started.md +++ b/_partials/_devops-cli-get-started.md @@ -187,31 +187,32 @@ And that is it, you are ready to use $CLI_LONG to manage your $SERVICE_SHORTs in 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 | -| config | | Manage your $CLI_LONG configuration | -| | show | Show the current configuration | -| | set `` `` | Set a specific value in your configuration. For example, `tiger config set debug true` | -| | 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 | -| | describe `` | Show detailed information about a specific $SERVICE_SHORT in this $PROJECT_SHORT | -| | list | List all the $SERVICE_SHORTs in this $PROJECT_SHORT | -| | create --addons=time-series \| ai \| none | Create a new $SERVICE_SHORT in this $PROJECT_SHORT. Possible flavors are:
  • time-series: with the Timescaledb and Timescaledb Toolkit extensions
  • ai: with the Timescaledb, Timescaledb Toolkit, vector and vectorscale extensions
  • 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`. | -| | delete `` | Delete a $SERVICE_SHORT from this $PROJECT_SHORT | -| | update-password `` | Update the password for a $SERVICE_SHORT | -| db | | Database operations and management | -| | connection-string `` | Retrieve the connection string for a $SERVICE_SHORT | -| | connect `` | Connect to 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 | +| 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