From 1de3853006826099148b07a34057b7aa459d3252 Mon Sep 17 00:00:00 2001 From: Kurtis Van Gent <31518063+kurtisvg@users.noreply.github.com> Date: Wed, 22 Jan 2025 09:57:06 -0700 Subject: [PATCH] chore: move sources documentation to docsite (#225) Migrates the docs/sources documentation to the new docsite. --------- Co-authored-by: Anubhav Dhawan --- .../resources/sources/_index.md} | 20 ++-- docs/{ => en/resources}/sources/alloydb-pg.md | 69 ++++++++----- docs/en/resources/sources/cloud-sql-pg.md | 96 +++++++++++++++++++ docs/{ => en/resources}/sources/neo4j.md | 32 ++++--- docs/{ => en/resources}/sources/postgres.md | 13 ++- docs/en/resources/sources/spanner.md | 65 +++++++++++++ docs/sources/cloud-sql-pg.md | 72 -------------- docs/sources/spanner.md | 49 ---------- 8 files changed, 245 insertions(+), 171 deletions(-) rename docs/{sources/README.md => en/resources/sources/_index.md} (58%) rename docs/{ => en/resources}/sources/alloydb-pg.md (50%) create mode 100644 docs/en/resources/sources/cloud-sql-pg.md rename docs/{ => en/resources}/sources/neo4j.md (57%) rename docs/{ => en/resources}/sources/postgres.md (90%) create mode 100644 docs/en/resources/sources/spanner.md delete mode 100644 docs/sources/cloud-sql-pg.md delete mode 100644 docs/sources/spanner.md diff --git a/docs/sources/README.md b/docs/en/resources/sources/_index.md similarity index 58% rename from docs/sources/README.md rename to docs/en/resources/sources/_index.md index 206f025f..221d5b44 100644 --- a/docs/sources/README.md +++ b/docs/en/resources/sources/_index.md @@ -1,4 +1,10 @@ -# Sources +--- +title: "Sources" +type: docs +weight: 1 +description: > + Sources represent your different data sources that a tool can interact with. +--- A Source represents a data sources that a tool can interact with. You can define Sources as a map in the `sources` section of your `tools.yaml` file. Typically, @@ -20,14 +26,4 @@ sources: In implementation, each source is a different connection pool or client that used to connect to the database and execute the tool. -## Kinds of Sources - -We currently support the following types of kinds of sources: - -* [alloydb-postgres](./alloydb-pg.md) - Connect to an AlloyDB for PostgreSQL - cluster. -* [cloud-sql-postgres](./cloud-sql-pg.md) - Connect to a Cloud SQL for - PostgreSQL instance. -* [postgres](./postgres.md) - Connect to any PostgreSQL compatible database. -* [spanner](./spanner.md) - Connect to a Spanner database. -* [neo4j](./neo4j.md) - Connect to a Neo4j instance. \ No newline at end of file +## Available Sources \ No newline at end of file diff --git a/docs/sources/alloydb-pg.md b/docs/en/resources/sources/alloydb-pg.md similarity index 50% rename from docs/sources/alloydb-pg.md rename to docs/en/resources/sources/alloydb-pg.md index eeee1557..21a0e580 100644 --- a/docs/sources/alloydb-pg.md +++ b/docs/en/resources/sources/alloydb-pg.md @@ -1,27 +1,40 @@ -# AlloyDB for PostgreSQL Source +--- +title: "AlloyDB for PostgreSQL" +linkTitle: "AlloyDB" +type: docs +weight: 1 +description: > + AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for + demanding transactional workloads. + +--- + +## About [AlloyDB for PostgreSQL][alloydb-docs] is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. It provides enterprise-grade performance and availability while maintaining 100% compatibility with open-source PostgreSQL. -If you are new to AlloyDB for PostgreSQL, you can try [creating and connecting -to a database by following these instructions][alloydb-quickstart]. +If you are new to AlloyDB for PostgreSQL, you can [create a free trial +cluster][alloydb-free-trial]. [alloydb-docs]: https://cloud.google.com/alloydb/docs -[alloydb-quickstart]: https://cloud.google.com/alloydb/docs/quickstart/create-and-connect +[alloydb-free-trial]: https://cloud.google.com/alloydb/docs/create-free-trial-cluster ## Requirements -### IAM Identity + +### IAM Permissions By default, AlloyDB for PostgreSQL source uses the [AlloyDB Go Connector][alloydb-go-conn] to authorize and establish mTLS connections to your AlloyDB instance. The Go connector uses your [Application Default Credentials (ADC)][adc] to authorize your connection to AlloyDB. -In addition to [setting the ADC for your server][set-adc], you need to ensure the -IAM identity has been given the following IAM permissions: +In addition to [setting the ADC for your server][set-adc], you need to ensure +the IAM identity has been given the following IAM roles (or corresponding +permissions): - `roles/alloydb.client` - `roles/serviceusage.serviceUsageConsumer` @@ -30,19 +43,26 @@ IAM identity has been given the following IAM permissions: [adc]: https://cloud.google.com/docs/authentication#adc [set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc -### Network Path +### Networking + +AlloyDB supports connecting over both from external networks via the internet +([public IP][public-ip]), and internal networks ([private IP][private-ip]). +For more information on choosing between the two options, see the AlloyDB page +[Connection overview][conn-overview]. -Currently, AlloyDB supports connection over both [private IP][private-ip] and -[public IP][public-ip]. Set the `ipType` parameter in your source -configuration to `public` or `private`. +You can configure the `ipType` parameter in your source configuration to +`public` or `private` to match your cluster's configuration. Regardless of which +you choose, all connections use IAM-based authorization and are encrypted with +mTLS. [private-ip]: https://cloud.google.com/alloydb/docs/private-ip [public-ip]: https://cloud.google.com/alloydb/docs/connect-public-ip +[conn-overview]: https://cloud.google.com/alloydb/docs/connection-overview ### Database User -Current, this source only uses standard authentication. You will need to [create a -PostreSQL user][alloydb-users] to login to the database with. +Currently, this source only uses standard authentication. You will need to [create +a PostgreSQL user][alloydb-users] to login to the database with. [alloydb-users]: https://cloud.google.com/alloydb/docs/database-users/about @@ -59,18 +79,19 @@ sources: database: "my_db" user: "my-user" password: "my-password" + # ipType: "public" ``` ## Reference -| **field** | **type** | **required** | **description** | -|-----------|:--------:|:------------:|------------------------------------------------------------------------------| -| kind | string | true | Must be "alloydb-postgres". | -| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | -| region | string | true | Name of the GCP region that the cluster was created in (e.g. "us-central1"). | -| cluster | string | true | Name of the AlloyDB cluster (e.g. "my-cluster"). | -| instance | string | true | Name of the AlloyDB instance within the cluser (e.g. "my-instance"). | -| ipType | string | true | IP Type of the AlloyDB instance, must be either `public` or `private`. Default: `public`. | -| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | -| user | string | true | Name of the Postgres user to connect as (e.g. "my-pg-user"). | -| password | string | true | Password of the Postgres user (e.g. "my-password"). | +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|-------------------------------------------------------------------------------------------| +| kind | string | true | Must be "alloydb-postgres". | +| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | +| region | string | true | Name of the GCP region that the cluster was created in (e.g. "us-central1"). | +| cluster | string | true | Name of the AlloyDB cluster (e.g. "my-cluster"). | +| instance | string | true | Name of the AlloyDB instance within the cluser (e.g. "my-instance"). | +| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | +| user | string | true | Name of the Postgres user to connect as (e.g. "my-pg-user"). | +| password | string | true | Password of the Postgres user (e.g. "my-password"). | +| ipType | string | false | IP Type of the AlloyDB instance; must be one of `public` or `private`. Default: `public`. | diff --git a/docs/en/resources/sources/cloud-sql-pg.md b/docs/en/resources/sources/cloud-sql-pg.md new file mode 100644 index 00000000..a62fbe39 --- /dev/null +++ b/docs/en/resources/sources/cloud-sql-pg.md @@ -0,0 +1,96 @@ +--- +title: "Cloud SQL for PostgreSQL" +linkTitle: "Cloud SQL (Postgres)" +type: docs +weight: 1 +description: > + Cloud SQL for PostgreSQL is a fully-managed database service for Postgres. + +--- + +## About + +[Cloud SQL for PostgreSQL][csql-pg-docs] is a fully-managed database service +that helps you set up, maintain, manage, and administer your PostgreSQL +relational databases on Google Cloud Platform. + +If you are new to Cloud SQL for PostgreSQL, you can try [creating and connecting +to a database by following these instructions][csql-pg-quickstart]. + +[csql-pg-docs]: https://cloud.google.com/sql/docs/postgres +[csql-pg-quickstart]: https://cloud.google.com/sql/docs/postgres/connect-instance-local-compaduter + +## Requirements + +### IAM Permissions + +By default, this source uses the [Cloud SQL Go Connector][csql-go-conn] to +authorize and establish mTLS connections to your Cloud SQL instance. The Go +connector uses your [Application Default Credentials (ADC)][adc] to authorize +your connection to Cloud SQL. + +In addition to [setting the ADC for your server][set-adc], you need to ensure +the IAM identity has been given the following IAM roles (or corresponding +permissions): + +- `roles/cloudsql.client` + +> **_NOTE:_** +> If you are connecting from Compute Engine, make sure your VM also has the +> [proper scope][gce-access-scopes] to connect using the Cloud SQL Admin API. + +[csql-go-conn]: /~https://github.com/GoogleCloudPlatform/cloud-sql-go-connector +[adc]: https://cloud.google.com/docs/authentication#adc +[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc +[gce-access-scopes]: https://cloud.google.com/compute/docs/access/service-accounts#accesscopesiam + +### Networking + +AlloyDB supports connecting over both from external networks via the internet +([public IP][public-ip]), and internal networks ([private IP][private-ip]). +For more information on choosing between the two options, see the AlloyDB page +[Connection overview][conn-overview]. + +You can configure the `ipType` parameter in your source configuration to +`public` or `private` to match your cluster's configuration. Regardless of which +you choose, all connections use IAM-based authorization and are encrypted with +mTLS. + +[private-ip]: https://cloud.google.com/alloydb/docs/private-ip +[public-ip]: https://cloud.google.com/alloydb/docs/connect-public-ip +[conn-overview]: https://cloud.google.com/alloydb/docs/connection-overview + +### Database User + +Current, this source only uses standard authentication. You will need to [create +a PostreSQL user][cloud-sql-users] to login to the database with. + +[cloud-sql-users]: https://cloud.google.com/sql/docs/postgres/create-manage-users + +## Example + +```yaml +sources: + my-cloud-sql-pg-source: + kind: "cloud-sql-postgres" + project: "my-project-id" + region: "us-central1" + instance: "my-instance" + database: "my_db" + user: "my-user" + password: "my-password" + # ipType: "public" +``` + +## Reference + +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|---------------------------------------------------------------------------------------------| +| kind | string | true | Must be "cloud-sql-postgres". | +| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | +| region | string | true | Name of the GCP region that the cluster was created in (e.g. "us-central1"). | +| instance | string | true | Name of the Cloud SQL instance within the cluster (e.g. "my-instance"). | +| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | +| user | string | true | Name of the Postgres user to connect as (e.g. "my-pg-user"). | +| password | string | true | Password of the Postgres user (e.g. "my-password"). | +| ipType | string | false | IP Type of the Cloud SQL instance; must be one of `public` or `private`. Default: `public`. | diff --git a/docs/sources/neo4j.md b/docs/en/resources/sources/neo4j.md similarity index 57% rename from docs/sources/neo4j.md rename to docs/en/resources/sources/neo4j.md index f90e3800..b460be62 100644 --- a/docs/sources/neo4j.md +++ b/docs/en/resources/sources/neo4j.md @@ -1,8 +1,15 @@ -# Neo4j Source +--- +title: "Neo4j" +type: docs +weight: 1 +description: > + Neo4j is a powerful, open source graph database system -[Neo4j][neo4j-docs] is a powerful, open source graph database -system with over 15 years of active development that has earned it a strong -reputation for reliability, feature robustness, and performance. +--- + +[Neo4j][neo4j-docs] is a powerful, open source graph database system with over +15 years of active development that has earned it a strong reputation for +reliability, feature robustness, and performance. [neo4j-docs]: https://neo4j.com/docs @@ -10,8 +17,9 @@ reputation for reliability, feature robustness, and performance. ### Database User -This source only uses standard authentication. You will need to [create a -Neo4j user][neo4j-users] to log in to the database with, or use the default `neo4j` user if available. +This source only uses standard authentication. You will need to [create a Neo4j +user][neo4j-users] to log in to the database with, or use the default `neo4j` +user if available. [neo4j-users]: https://neo4j.com/docs/operations-manual/current/authentication-authorization/manage-users/ @@ -29,12 +37,12 @@ sources: ## Reference -| **field** | **type** | **required** | **description** | -|-----------|:--------:|:------------:|---------------------------------------------------------------------| -| kind | string | true | Must be "neo4j". | +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|----------------------------------------------------------------------| +| kind | string | true | Must be "neo4j". | | uri | string | true | Connect URI ("bolt://localhost", "neo4j+s://xxx.databases.neo4j.io") | -| user | string | true | Name of the Neo4j user to connect as (e.g. "neo4j"). | -| password | string | true | Password of the Neo4j user (e.g. "my-password"). | -| database | string | true | Name of the Neo4j database to connect to (e.g. "neo4j"). | +| user | string | true | Name of the Neo4j user to connect as (e.g. "neo4j"). | +| password | string | true | Password of the Neo4j user (e.g. "my-password"). | +| database | string | true | Name of the Neo4j database to connect to (e.g. "neo4j"). | diff --git a/docs/sources/postgres.md b/docs/en/resources/sources/postgres.md similarity index 90% rename from docs/sources/postgres.md rename to docs/en/resources/sources/postgres.md index c741d1a7..23de1466 100644 --- a/docs/sources/postgres.md +++ b/docs/en/resources/sources/postgres.md @@ -1,4 +1,13 @@ -# PostgreSQL Source +--- +title: "PostgreSQL" +type: docs +weight: 1 +description: > + PostgreSQL is a powerful, open source object-relational database. + +--- + +## About [PostgreSQL][pg-docs] is a powerful, open source object-relational database system with over 35 years of active development that has earned it a strong @@ -6,7 +15,7 @@ reputation for reliability, feature robustness, and performance. [pg-docs]: https://www.postgresql.org/ -## Requirements +## Requirements ### Database User diff --git a/docs/en/resources/sources/spanner.md b/docs/en/resources/sources/spanner.md new file mode 100644 index 00000000..6233e732 --- /dev/null +++ b/docs/en/resources/sources/spanner.md @@ -0,0 +1,65 @@ +--- +title: "Spanner" +type: docs +weight: 1 +description: > + Spanner is a fully managed database service from Google Cloud that combines + relational, key-value, graph, and search capabilities. + +--- + +# Spanner Source + +[Spanner][spanner-docs] is a fully managed, mission-critical database service +that brings together relational, graph, key-value, and search. It offers +transactional consistency at global scale, automatic, synchronous replication +for high availability, and support for two SQL dialects: GoogleSQL (ANSI 2011 +with extensions) and PostgreSQL. + +If you are new to Spanner, you can try to [create and query a database using +the Google Cloud console][spanner-quickstart]. + +[spanner-docs]: https://cloud.google.com/spanner/docs +[spanner-quickstart]: + https://cloud.google.com/spanner/docs/create-query-database-console + +## Requirements + +### IAM Permissions + +Spanner uses [Identity and Access Management (IAM)][iam-overview] to control +user and group access to Spanner resources at the project, Spanner instance, and +Spanner database levels. Toolbox will use your [Application Default Credentials +(ADC)][adc] to authorize and authenticate when interacting with Spanner. + +In addition to [setting the ADC for your server][set-adc], you need to ensure +the IAM identity has been given the correct IAM permissions for the query +provided. See [Apply IAM roles][grant-permissions] for more information on +applying IAM permissions and roles to an identity. + +[iam-overview]: https://cloud.google.com/spanner/docs/iam +[adc]: https://cloud.google.com/docs/authentication#adc +[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc +[grant-permissions]: https://cloud.google.com/spanner/docs/grant-permissions + +## Example + +```yaml +sources: + my-spanner-source: + kind: "spanner" + project: "my-project-id" + instance: "my-instance" + database: "my_db" + # dialect: "googlesql" +``` + +## Reference + +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|---------------------------------------------------------------------------------------------------------------------| +| kind | string | true | Must be "spanner". | +| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | +| instance | string | true | Name of the Spanner instance. | +| database | string | true | Name of the database on the Spanner instance | +| dialect | string | false | Name of the dialect type of the Spanner database, must be either `googlesql` or `postgresql`. Default: `googlesql`. | diff --git a/docs/sources/cloud-sql-pg.md b/docs/sources/cloud-sql-pg.md deleted file mode 100644 index 66ae19cb..00000000 --- a/docs/sources/cloud-sql-pg.md +++ /dev/null @@ -1,72 +0,0 @@ -# Cloud SQL for PostgreSQL Source - -[Cloud SQL for PostgreSQL][csql-pg-docs] is a fully-managed database service -that helps you set up, maintain, manage, and administer your PostgreSQL -relational databases on Google Cloud Platform. - -If you are new to Cloud SQL for PostgreSQL, you can try [creating and connecting -to a database by following these instructions][csql-pg-quickstart]. - -[csql-pg-docs]: https://cloud.google.com/sql/docs/postgres -[csql-pg-quickstart]: https://cloud.google.com/sql/docs/postgres/connect-instance-local-computer - -## Requirements - -### IAM Identity - -By default, this source uses the [Cloud SQL Go Connector][csql-go-conn] to -authorize and establish mTLS connections to your Cloud SQL instance. The Go -connector uses your [Application Default Credentials (ADC)][adc] to authorize -your connection to Cloud SQL. - -In addition to [setting the ADC for your server][set-adc], you need to ensure the -IAM identity has been given the following IAM roles: - -- `roles/cloudsql.client` - -[csql-go-conn]: /~https://github.com/GoogleCloudPlatform/cloud-sql-go-connector -[adc]: https://cloud.google.com/docs/authentication#adc -[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc - -### Network Path - -Currently, Cloud SQL supports connection over both [private IP][private-ip] and -[public IP][public-ip]. Set the `ipType` parameter in your source -configuration to `public` or `private`. - -[private-ip]: https://cloud.google.com/sql/docs/postgres/configure-private-ip -[public-ip]: https://cloud.google.com/sql/docs/postgres/configure-ip - -### Database User - -Current, this source only uses standard authentication. You will need to [create a -PostreSQL user][cloud-sql-users] to login to the database with. - -[cloud-sql-users]: https://cloud.google.com/sql/docs/postgres/create-manage-users - -## Example - -```yaml -sources: - my-cloud-sql-pg-source: - kind: "cloud-sql-postgres" - project: "my-project-id" - region: "us-central1" - instance: "my-instance" - database: "my_db" - user: "my-user" - password: "my-password" -``` - -## Reference - -| **field** | **type** | **required** | **description** | -|-----------|:--------:|:------------:|------------------------------------------------------------------------------| -| kind | string | true | Must be "cloud-sql-postgres". | -| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | -| region | string | true | Name of the GCP region that the cluster was created in (e.g. "us-central1"). | -| instance | string | true | Name of the Cloud SQL instance within the cluser (e.g. "my-instance"). | -| ipType | string | true | IP Type of the Cloud SQL instance, must be either `public` or `private`. Default: `public`. | -| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | -| user | string | true | Name of the Postgres user to connect as (e.g. "my-pg-user"). | -| password | string | true | Password of the Postgres user (e.g. "my-password"). | diff --git a/docs/sources/spanner.md b/docs/sources/spanner.md deleted file mode 100644 index 132b9241..00000000 --- a/docs/sources/spanner.md +++ /dev/null @@ -1,49 +0,0 @@ -# Spanner Source - -[Spanner][spanner-docs] fully managed, mission-critical database service -that brings together relational, graph, key-value, and search. It offers -transactional consistency at global scale, automatic, synchronous replication -for high availability, and support for two SQL dialects: GoogleSQL (ANSI 2011 -with extensions) and PostgreSQL. - -If you are new to Spanner, you can try to [create and query a database using -the Google Cloud console][spanner-quickstart]. - -[spanner-docs]: https://cloud.google.com/spanner/docs -[spanner-quickstart]: https://cloud.google.com/spanner/docs/create-query-database-console - -## Requirements - -### IAM Identity -By default, Spanner uses the [OAuth 2.0][oauth2] for API authentication and -authorization. The Cloud Spanner API uses your [Application Default Credentials -(ADC)][adc] to authorize your connection to Spanner. - -In addition to [setting the ADC for your server][set-adc], you need to ensure the IAM identity has been given the following IAM permissions: -- `roles/spanner.databaseUser` - -[oauth2]: https://datatracker.ietf.org/doc/html/rfc6749 -[adc]: https://cloud.google.com/docs/authentication#adc -[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc - -## Example - -```yaml -sources: - my-spanner-source: - kind: "spanner" - project: "my-project-id" - instance: "my-instance" - database: "my_db" - # dialect: "googlesql" -``` - -## Reference - -| **field** | **type** | **required** | **description** | -|-----------|:--------:|:------------:|------------------------------------------------------------------------------| -| kind | string | true | Must be "spanner". | -| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). | -| instance | string | true | Name of the AlloyDB instance within the cluser (e.g. "my-instance"). | -| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | -| dialect | string | true | Name of the dialect type of the Spanner database, must be either `googlesql` or `postgresql`. Default: `googlesql`. |