From 0089f79ee3f37847b0832df5633a6dedf9197417 Mon Sep 17 00:00:00 2001 From: April M Date: Sun, 10 Aug 2025 09:03:40 -0700 Subject: [PATCH 1/6] pcu group note --- docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index de59221..7c68288 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -54,10 +54,12 @@ astra db create **DATABASE_NAME** --vector ---- ==== -[NOTE] +[IMPORTANT] ==== -You cannot create {db-classic} databases with the {product}. +* **{db-classic} databases**: You cannot create {db-classic} databases with the {product}. However, you can use the {product} to <> about existing {db-classic} databases. + +* **PCU groups**: For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} to create databases] because the {product} doesn't support PCU group assignment with database creation. ==== Running `astra db create` without any options deploys the database in an available *Free* region and uses `default_keyspace` as the name for the default keyspace. From 12427942cb214446be1d48ddfe37603e93cf9693 Mon Sep 17 00:00:00 2001 From: April M Date: Sun, 10 Aug 2025 11:41:40 -0700 Subject: [PATCH 2/6] attributes --- docs-src/astra-cli-core/antora.yml | 28 +++++++++------- .../modules/ROOT/pages/getting-started.adoc | 2 +- .../modules/ROOT/pages/managing.adoc | 32 +++++++++---------- 3 files changed, 34 insertions(+), 28 deletions(-) diff --git a/docs-src/astra-cli-core/antora.yml b/docs-src/astra-cli-core/antora.yml index 7e50f45..00147f0 100644 --- a/docs-src/astra-cli-core/antora.yml +++ b/docs-src/astra-cli-core/antora.yml @@ -8,19 +8,25 @@ nav: asciidoc: attributes: + # General attributes + company: 'DataStax' + support-url: 'https://support.datastax.com' + # Other product attributes + cass-reg: 'Apache Cassandra(R)' + cass: 'Apache Cassandra' + cass-short: 'Cassandra' + # Astra DB attributes + astra-db: 'Astra DB' + astra: 'Astra' product: 'Astra CLI' product-version: '0.6' - astra: 'Astra' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' db-classic: 'Classic' - astra-api: 'Data API' - url-astra: 'https://astra.datastax.com' - link-astra-portal: '{url-astra}[{astra_ui}^]' - py-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$python-client/astrapy' - ts-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$typescript-client' - java-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$java-client' - cass-short: 'Cassandra' - scb-long: Secure Connect Bundle (SCB) - scb-cap: Secure Connect Bundle - scb: SCB + astra-stream: 'Astra Streaming' + astra-ui: 'Astra Portal' + astra-url: 'https://astra.datastax.com' + astra-ui-link: '{astra-url}[{astra-ui}^]' + scb: 'Secure Connect Bundle (SCB)' + scb-short: 'SCB' + scb-brief: 'Secure Connect Bundle' \ No newline at end of file diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc index 7bd7fa6..baff8a7 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc @@ -11,7 +11,7 @@ To configure the {product}: * xref:ROOT:installation.adoc[Install the {product}]. -* You must have an active {url-astra}[Astra account^]. +* You must have an active {astra-url}[Astra account^]. * [[get-credentials]]You must have an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] that is assigned a _role_ with adequate _permissions_ to perform the tasks you'd like to accomplish with the {product}. diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index 7c68288..c69efce 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -523,11 +523,11 @@ You cannot load vector data into a non-vector collection. ===== -- -Use an {astra}-hosted provider:: +Use an Astra-hosted provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either {astra}-hosted or external. +Embedding provider integrations are either Astra-hosted or external. [source,bash,subs="+quotes"] ---- @@ -542,7 +542,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the {astra}-hosted embedding provider. +* `**PROVIDER_NAME**`: The name of the Astra-hosted embedding provider. * `**MODEL_NAME**`: The name of the embedding model that you want to use to generate embeddings. * (Optional) `**DIMENSION**`: The number of dimensions that you want the generated vectors to have. You can only set the dimensions if the chosen model supports a range of dimensions. @@ -576,7 +576,7 @@ Use an external provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either {astra}-hosted or external. +Embedding provider integrations are either Astra-hosted or external. To use an external embedding provider, you must add an xref:astra-db-serverless:databases:embedding-generation.adoc#supported-embedding-providers[embedding provider integration] to your {astra_db} organization, and then you can select that embedding provider when you create a collection. @@ -594,7 +594,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the {astra}-hosted embedding provider. +* `**PROVIDER_NAME**`: The name of the Astra-hosted embedding provider. * `**MODEL_NAME**`: The name of the embedding model that you want to use to generate embeddings. * (Optional) `**PROVIDER_KEY_NAME**`: The name of the provider key that you want to use to authenticate with the external embedding provider. * (Optional) `**DIMENSION**`: The number of dimensions that you want the generated vectors to have. @@ -2956,7 +2956,7 @@ token@cqlsh> Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. The first time you use the `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} installation directory (`~/.astra/cqlsh-astra`). -The {product} also downloads the {scb-long} for each database you connect to and stores the {scb} zip files in the `~/.astra/scb` directory. +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. [NOTE] ====== @@ -3315,7 +3315,7 @@ To resume the current operation, re-run it with the same settings, and add the f [NOTE] ==== The first time you use one of the `astra db load`, `astra db unload`, or `astra db count` commands, the {product} downloads and installs the `dsbulk` utility to the {product} installation directory (`~/.astra/dsbulk-*`). -The {product} also downloads the {scb-long} for each database you connect to and stores the {scb} zip files in the `~/.astra/scb` directory. +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. ==== === `db load` options @@ -4229,11 +4229,11 @@ astra streaming list-cdc cdc-demo-tenant After you enable CDC on your {db-serverless} database, you can xref:astra-db-serverless:databases:change-data-capture.adoc#connect-a-sink[connect a sink]. -== Download the {scb-cap} +== Download the {scb-brief} The xref:astra-db-serverless:drivers:secure-connect-bundle.adoc[] is a zip file containing security credentials and certificates required for secure mutual TLS (mTLS) connection to your database. -Use the `astra db download-scb` command to download the {scb-long} for a database: +Use the `astra db download-scb` command to download the {scb} for a database: [source,bash,subs="+quotes"] ---- @@ -4250,15 +4250,15 @@ astra db download-scb **DATABASE_ID** -r **REGION_NAME** ==== The `-r **REGION_NAME**` option is required for <>. -If your database is configured with multiple regions, replace `**REGION_NAME**` with the name of the region you want to download the {scb} for. +If your database is configured with multiple regions, replace `**REGION_NAME**` with the name of the region you want to download the {scb-short} for. -By default, the {product} downloads the {scb} to the directory where you run the command and saves the file with the following naming pattern: `scb_**DATABASE-ID**_**REGION-NAME**.zip`. +By default, the {product} downloads the {scb-short} to the directory where you run the command and saves the file with the following naming pattern: `scb_**DATABASE-ID**_**REGION-NAME**.zip`. [WARNING] ==== -Treat the {scb} the same way you would any other sensitive values, such as passwords or tokens. +Treat the {scb-short} the same way you would any other sensitive values, such as passwords or tokens. -The {scb} contains sensitive information that establishes a connection to your database, including key pairs and certificates. +The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== === `db download-scb` options @@ -4317,7 +4317,7 @@ OPTIONS ---- ==== -Use the `-r` / `--region` option to download the {scb} for a specific region: +Use the `-r` / `--region` option to download the {scb-short} for a specific region: [source,bash,subs="+quotes"] ---- @@ -4339,7 +4339,7 @@ Use the `astra db list-regions` command to get a list of the region names where For more information, see <>. ==== -Use the `-f` / `--output-file` option to download the {scb} to a specific location and filename: +Use the `-f` / `--output-file` option to download the {scb-short} to a specific location and filename: [source,bash,subs="+quotes"] ---- @@ -4402,7 +4402,7 @@ ASTRA_ORG_TOKEN="AstraCS:FZm..." ==== The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to Astra. -The {scb} contains sensitive information that establishes a connection to your database, including key pairs and certificates. +The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== === `db create-dotenv` options From 08d67ff5d6faf23cdaf5705b72829b22ca20c5b4 Mon Sep 17 00:00:00 2001 From: April M Date: Sun, 10 Aug 2025 12:04:10 -0700 Subject: [PATCH 3/6] multi-region limitation for PCU-only --- .../modules/ROOT/pages/managing.adoc | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index c69efce..5dc7f61 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -2268,10 +2268,16 @@ For more information, see xref:astra-db-serverless:databases:manage-regions.adoc [IMPORTANT] ==== -Multi-region databases are a premium feature. +* **Premium feature**: Multi-region databases are a premium feature. Each region added to a database increases the database's costs. This includes a one-time data replication fee for the new region, and charges for replicating data to all database regions. For more information, see xref:astra-db-serverless:administration:subscription-plans.adoc[]. + +* **Status change**: The database enters *Maintenance* status while provisioning and replicating data to the new region. +While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. +However, *Maintenance* status doesn't impact reads and writes. + +* **PCU groups**: For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} to add regions] because the {product} doesn't support PCU group assignment when adding a region. ==== Use the `astra db create-region` command to add a region to a database: @@ -2306,15 +2312,6 @@ For more information, see xref:astra-db-serverless:databases:regions.adoc[]. ==== //// -[NOTE] -==== -The database enters *Maintenance* status while provisioning and replicating data to the new region. - -While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. - -*Maintenance* status doesn't impact reads and writes. -==== - Use the `astra db list-regions` command to list the regions where a database is deployed: [source,bash,subs="+quotes"] From ebe8574222a9b7fd2d163e02b91f0936838954e7 Mon Sep 17 00:00:00 2001 From: "April I. Murphy" <36110273+aimurphy@users.noreply.github.com> Date: Wed, 13 Aug 2025 07:26:05 -0700 Subject: [PATCH 4/6] edit programmatic support for PCU only --- docs-src/astra-cli-core/antora.yml | 1 + docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs-src/astra-cli-core/antora.yml b/docs-src/astra-cli-core/antora.yml index 00147f0..9eca67d 100644 --- a/docs-src/astra-cli-core/antora.yml +++ b/docs-src/astra-cli-core/antora.yml @@ -23,6 +23,7 @@ asciidoc: db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' db-classic: 'Classic' + devops-api: 'DevOps API' astra-stream: 'Astra Streaming' astra-ui: 'Astra Portal' astra-url: 'https://astra.datastax.com' diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index 5dc7f61..ba9aefa 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -59,7 +59,7 @@ astra db create **DATABASE_NAME** --vector * **{db-classic} databases**: You cannot create {db-classic} databases with the {product}. However, you can use the {product} to <> about existing {db-classic} databases. -* **PCU groups**: For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} to create databases] because the {product} doesn't support PCU group assignment with database creation. +* **PCU groups**: For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} or {devops-api} to create databases] because the {product} doesn't support PCU group assignment with database creation. ==== Running `astra db create` without any options deploys the database in an available *Free* region and uses `default_keyspace` as the name for the default keyspace. @@ -2277,7 +2277,7 @@ For more information, see xref:astra-db-serverless:administration:subscription-p While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. However, *Maintenance* status doesn't impact reads and writes. -* **PCU groups**: For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} to add regions] because the {product} doesn't support PCU group assignment when adding a region. +* **PCU groups**: For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} or {devops-api} to add regions] because the {product} doesn't support PCU group assignment when adding a region. ==== Use the `astra db create-region` command to add a region to a database: From a3083f0ac5e9af17d28553ef2395baade734c2ec Mon Sep 17 00:00:00 2001 From: April M Date: Wed, 27 Aug 2025 14:06:27 -0700 Subject: [PATCH 5/6] apply product-short attribute --- docs-src/astra-cli-core/antora.yml | 2 +- .../modules/ROOT/pages/administration.adoc | 26 +++---- .../ROOT/pages/astra-streaming-cli.adoc | 2 +- .../modules/ROOT/pages/getting-started.adoc | 8 +-- .../modules/ROOT/pages/index.adoc | 6 +- .../modules/ROOT/pages/installation.adoc | 2 +- .../modules/ROOT/pages/managing.adoc | 68 +++++-------------- 7 files changed, 39 insertions(+), 75 deletions(-) diff --git a/docs-src/astra-cli-core/antora.yml b/docs-src/astra-cli-core/antora.yml index 9eca67d..3ff9fd8 100644 --- a/docs-src/astra-cli-core/antora.yml +++ b/docs-src/astra-cli-core/antora.yml @@ -17,8 +17,8 @@ asciidoc: cass-short: 'Cassandra' # Astra DB attributes astra-db: 'Astra DB' - astra: 'Astra' product: 'Astra CLI' + product-short: 'Astra' product-version: '0.6' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/administration.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/administration.adoc index 492c7b3..aba8197 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/administration.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/administration.adoc @@ -1,11 +1,11 @@ -= Manage your Astra organization with the {product} -:navtitle: Manage Astra administration += Manage your {product-short} organization with the {product} +:navtitle: Manage {product-short} administration -Use the {product} to manage your Astra organization. +Use the {product} to manage your {product-short} organization. == Get organization details -Use the `astra org` command to get information about the current Astra organization: +Use the `astra org` command to get information about the current {product-short} organization: [source,bash] ---- @@ -49,7 +49,7 @@ SYNOPSIS == List users -Use the `astra user list` command to list all users in your Astra organization: +Use the `astra user list` command to list all users in your {product-short} organization: [source,bash] ---- @@ -113,7 +113,7 @@ OPTIONS == Add a user -Use the `astra user invite` command to invite a new user to your Astra organization: +Use the `astra user invite` command to invite a new user to your {product-short} organization: [source,bash,subs="+quotes"] ---- @@ -218,7 +218,7 @@ astra user invite alice@example.com -r "Organization Administrator" == Get user details -Use the `astra user get` or `astra user describe` command to get information about a specific user in your Astra organization: +Use the `astra user get` or `astra user describe` command to get information about a specific user in your {product-short} organization: [source,bash,subs="+quotes"] ---- @@ -358,7 +358,7 @@ The user can still access their personal {astra_db} account, if they have access If your organization uses SSO, make sure that you also remove the user from your IdP, if necessary. ==== -Use the `astra user delete` command to remove a user or revoke their invitation from your Astra organization: +Use the `astra user delete` command to remove a user or revoke their invitation from your {product-short} organization: [source,bash,subs="+quotes"] ---- @@ -427,7 +427,7 @@ OPTIONS [#list-roles] == List roles -Use the `astra role list` command to list all xref:astra-db-serverless:administration:manage-database-access.adoc#default-roles[default roles] and xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom roles] in your Astra organization: +Use the `astra role list` command to list all xref:astra-db-serverless:administration:manage-database-access.adoc#default-roles[default roles] and xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom roles] in your {product-short} organization: [source,bash] ---- @@ -505,7 +505,7 @@ OPTIONS == Get role details -Use the `astra role get` or `astra role describe` command to get information about a specific role in your Astra organization: +Use the `astra role get` or `astra role describe` command to get information about a specific role in your {product-short} organization: [source,bash,subs="+quotes"] ---- @@ -680,7 +680,7 @@ OPTIONS [#list-tokens] == Get a list of tokens -Use the `astra token list` command to list all of the application tokens in your Astra organization: +Use the `astra token list` command to list all of the application tokens in your {product-short} organization: [source,bash] ---- @@ -741,7 +741,7 @@ OPTIONS == Create an application token -Use the `astra token create` command to create a new application token in your Astra organization: +Use the `astra token create` command to create a new application token in your {product-short} organization: [source,bash,subs="+quotes"] ---- @@ -875,7 +875,7 @@ OPTIONS Application tokens never expire. ==== -Use the `astra token delete` or `astra token revoke` command to delete an application token from your Astra organization: +Use the `astra token delete` or `astra token revoke` command to delete an application token from your {product-short} organization: [source,bash,subs="+quotes"] ---- diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/astra-streaming-cli.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/astra-streaming-cli.adoc index e4d488a..4ec7488 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/astra-streaming-cli.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/astra-streaming-cli.adoc @@ -1080,7 +1080,7 @@ ASTRA_STREAMING_WEBSOCKET_URL="wss://pulsar-aws-useast2.streaming.datastax.com:8 [WARNING] ==== -The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to Astra. +The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to {product-short}. The {scb} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc index baff8a7..7b72a70 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc @@ -11,20 +11,20 @@ To configure the {product}: * xref:ROOT:installation.adoc[Install the {product}]. -* You must have an active {astra-url}[Astra account^]. +* You must have an active {astra-url}[{product-short} account^]. * [[get-credentials]]You must have an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] that is assigned a _role_ with adequate _permissions_ to perform the tasks you'd like to accomplish with the {product}. -** *Non-production organizations*: If your Astra organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. +** *Non-production organizations*: If your {product-short} organization has no databases or streaming tenants that handle sensitive information, you can grant your application token the `Organization Administrator` role to try out all of the {product} features. -** *Production organizations*: If you're using Astra in production, {company} recommends that you use a xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum xref:astra-db-serverless:administration:manage-database-access.adoc#about-permissions[permissions] required to perform the required tasks with the {product}. +** *Production organizations*: If you're using {product-short} in production, {company} recommends that you use a xref:astra-db-serverless:administration:manage-database-access.adoc#custom-roles[custom role] to grant your application token the bare minimum xref:astra-db-serverless:administration:manage-database-access.adoc#about-permissions[permissions] required to perform the required tasks with the {product}. * If you plan to manage an {astra_db} database that has restricted public access, then you must xref:astra-db-serverless:administration:manage-database-ip-access-list.adoc#add-ip-access-list-entries[add your IP address to the database's access list]. [#initialize] == Initialize the {product} -After installation, initialize the {product} and connect it to an existing Astra account. +After installation, initialize the {product} and connect it to an existing {product-short} account. . Use the `astra setup` command to initialize the {product} with your xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token]: + diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/index.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/index.adoc index 9b6cdd1..121220d 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/index.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/index.adoc @@ -1,10 +1,10 @@ = {product} :page-layout: landing -The {product} is a free utility that you can use to create and manage Astra resources. -You can use the {product} to perform common platform tasks for {astra_db} and {astra_stream} from the command line or with automation to control your Astra resources at scale. +The {product} is a free utility that you can use to create and manage {product-short} resources. +You can use the {product} to perform common platform tasks for {astra_db} and {astra_stream} from the command line or with automation to control your {product-short} resources at scale. -To make it even easier to integrate Astra into your applications and workflows, the {product} provides seamless integration with the following external tools: +To make it even easier to integrate {product-short} into your applications and workflows, the {product} provides seamless integration with the following external tools: * DSBulk * cqlsh diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/installation.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/installation.adoc index 30b474e..05aa0d4 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/installation.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/installation.adoc @@ -1,5 +1,5 @@ = Install or update the {product} -:description: {product} makes it easier to integrate Astra into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. +:description: {product} makes it easier to integrate {product-short} into your applications and workflows by letting you perform common platform tasks for {astra_db} and {astra_stream} from the command line. Install the {product} to create and manage {astra_db} databases and {astra_stream} tenants from the command line. diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index ba9aefa..3541e85 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -13,6 +13,11 @@ You can use `**DATABASE_NAME**` instead of `**DATABASE_ID**` in all `astra db` c == Create a database +The {product} can create only {db-serverless} and {db-serverless-vector} on on-demand (non-PCU) capacity. +It cannot create {db-classic} databases; however, you can use the {product} to <> about your existing {db-classic} databases. + +For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} or {devops-api} to create databases] because the {product} doesn't support PCU group assignment with database creation. + Use the `astra db create` command to create a new {db-serverless} database: [source,bash,subs="+quotes"] @@ -54,14 +59,6 @@ astra db create **DATABASE_NAME** --vector ---- ==== -[IMPORTANT] -==== -* **{db-classic} databases**: You cannot create {db-classic} databases with the {product}. -However, you can use the {product} to <> about existing {db-classic} databases. - -* **PCU groups**: For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} or {devops-api} to create databases] because the {product} doesn't support PCU group assignment with database creation. -==== - Running `astra db create` without any options deploys the database in an available *Free* region and uses `default_keyspace` as the name for the default keyspace. If the database already exists but is currently xref:astra-db-serverless:databases:database-statuses.adoc[hibernated], the `astra db create` command <> the database. @@ -523,11 +520,11 @@ You cannot load vector data into a non-vector collection. ===== -- -Use an Astra-hosted provider:: +Use an {product-short}-hosted provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either Astra-hosted or external. +Embedding provider integrations are either {product-short}-hosted or external. [source,bash,subs="+quotes"] ---- @@ -542,7 +539,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the Astra-hosted embedding provider. +* `**PROVIDER_NAME**`: The name of the {product-short}-hosted embedding provider. * `**MODEL_NAME**`: The name of the embedding model that you want to use to generate embeddings. * (Optional) `**DIMENSION**`: The number of dimensions that you want the generated vectors to have. You can only set the dimensions if the chosen model supports a range of dimensions. @@ -576,7 +573,7 @@ Use an external provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either Astra-hosted or external. +Embedding provider integrations are either {product-short}-hosted or external. To use an external embedding provider, you must add an xref:astra-db-serverless:databases:embedding-generation.adoc#supported-embedding-providers[embedding provider integration] to your {astra_db} organization, and then you can select that embedding provider when you create a collection. @@ -594,7 +591,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the Astra-hosted embedding provider. +* `**PROVIDER_NAME**`: The name of the {product-short}-hosted embedding provider. * `**MODEL_NAME**`: The name of the embedding model that you want to use to generate embeddings. * (Optional) `**PROVIDER_KEY_NAME**`: The name of the provider key that you want to use to authenticate with the external embedding provider. * (Optional) `**DIMENSION**`: The number of dimensions that you want the generated vectors to have. @@ -2262,43 +2259,19 @@ OPTIONS [#configure-multiple-regions] == Configure multiple regions -You can configure a database to replicate data across multiple regions. -Some benefits of multi-region databases include better data locality and higher availability for multi-region application architectures. -For more information, see xref:astra-db-serverless:databases:manage-regions.adoc[]. - -[IMPORTANT] -==== -* **Premium feature**: Multi-region databases are a premium feature. -Each region added to a database increases the database's costs. -This includes a one-time data replication fee for the new region, and charges for replicating data to all database regions. -For more information, see xref:astra-db-serverless:administration:subscription-plans.adoc[]. - -* **Status change**: The database enters *Maintenance* status while provisioning and replicating data to the new region. -While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. -However, *Maintenance* status doesn't impact reads and writes. - -* **PCU groups**: For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} or {devops-api} to add regions] because the {product} doesn't support PCU group assignment when adding a region. -==== - -Use the `astra db create-region` command to add a region to a database: +Use the `astra db create-region` command to deploy a database to an additional region: [source,bash,subs="+quotes"] ---- astra db create-region **DATABASE_ID** -r **REGION** ---- -Replace `**REGION**` with the region you want to add to your database. -The following restrictions apply: +The database enters *Maintenance* status while provisioning and replicating data to the new region. +Some functions are limited while in *Maintenance* status. -* You can add only one region at a time. +For more information, including requirements and costs for additional regions, see xref:astra-db-serverless:databases:manage-regions.adoc[]. -* You cannot select a region that the database already uses. - -* You must select a region in the same cloud provider as the database's other regions. -Multi-region databases cannot span multiple cloud providers. - -* For {db-serverless-vector} databases, you must select a region that supports that database type. -For more information, see xref:astra-db-serverless:databases:regions.adoc[]. +For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} or {devops-api} to add regions] because the {product} doesn't support PCU group assignment when adding a region. //// // TODO: The command is not working as expected. Must investigate and figure out why it is reporting the following error: [ERROR] UNAVAILABLE: Database 'my_serverless_db' has been found but operation cannot be processed due to invalid state (ACTIVE) expected (ACTIVE) @@ -2350,15 +2323,6 @@ astra db delete-region **DATABASE_ID** -r **REGION** ---- ==== -[NOTE] -==== -The database enters *Maintenance* status while deleting the region. - -While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. - -*Maintenance* status doesn't impact reads and writes. -==== - [IMPORTANT] ==== You cannot remove the primary (default) region, which is the first region selected when you created the database. @@ -4397,7 +4361,7 @@ ASTRA_ORG_TOKEN="AstraCS:FZm..." [WARNING] ==== -The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to Astra. +The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to {product-short}. The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== From d3703dc1fffb18843fb1ec006ac46f15c4bc7885 Mon Sep 17 00:00:00 2001 From: "April I. Murphy" <36110273+aimurphy@users.noreply.github.com> Date: Wed, 10 Sep 2025 17:46:57 -0700 Subject: [PATCH 6/6] Apply suggestions from code review --- docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index ec24e6c..47ec724 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -16,7 +16,7 @@ You can use `**DATABASE_NAME**` instead of `**DATABASE_ID**` in all `astra db` c The {product} can create {db-serverless} and {db-serverless-vector} databases with on-demand (non-PCU) capacity only. It cannot create {db-classic} databases; however, you can use the {product} to <> about your existing {db-classic} databases. -For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} or {devops-api} to create databases] because the {product} doesn't support PCU group assignment with database creation. +If your organization requires that new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} or {devops-api} to create databases] because the {product} doesn't support PCU group assignment with database creation. Use the `astra db create` command to create a new {db-serverless} database: @@ -2156,7 +2156,7 @@ astra db create-region **DATABASE_ID** -r **REGION** The database enters *Maintenance* status while provisioning and replicating data to the new region. Some functions are limited while in *Maintenance* status. -For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} or {devops-api} to add regions] because the {product} doesn't support PCU group assignment when adding a region. +If your organization requires use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} or {devops-api} to add regions] because the {product} doesn't support PCU group assignment when adding a region. For more information, including requirements and costs for additional regions, see xref:astra-db-serverless:databases:manage-regions.adoc[].