Skip to content

Commit b1c11f2

Browse files
AnouckColsonchadwcarlson
AnouckColson
and
chadwcarlson
authored
Document -replica and -all endpoints (#4059)
* Document endpoints * Add PostgreSQL and Redis * Add endpoint doc * Fix heading --------- Co-authored-by: Chad Carlson <[email protected]>
1 parent 5711864 commit b1c11f2

File tree

5 files changed

+263
-0
lines changed

5 files changed

+263
-0
lines changed

‎sites/platform/src/add-services/mysql/_index.md

+130
Original file line numberDiff line numberDiff line change
@@ -386,9 +386,139 @@ Possible permissions:
386386
| Admin | `admin` | In addition to read-write permissions, can also create, drop, and alter tables; create views; and create and alter routines. |
387387
| Replication | `replication` | For [replicating databases](./mysql-replication.md). In addition to read-only permissions, can also lock tables. |
388388

389+
### Restrict access to database replicas only
390+
391+
{{< partial "banners/replicas/body.md" >}}
392+
393+
Your main database lives on one of the three nodes provided on Grid HA and {{% names/dedicated-gen-3 %}}.
394+
The two other nodes can each accommodate a replica of your main database.
395+
396+
For security reasons, you can grant your app access to a replica instead of your main database.
397+
To do so, when defining the relationship between your app and database,
398+
make sure you do the following:
399+
400+
1. Use the [explicit endpoint syntax](/create-apps/app-reference/single-runtime-image.html#relationships).
401+
2. Add the `-replica` suffix to the name of the endpoint you want to use.
402+
403+
This results in the following configuration:
404+
405+
```yaml {configFile="app"}
406+
relationships:
407+
{{% variable "RELATIONSHIP_NAME" %}}:
408+
service: {{% variable "SERVICE_NAME" %}}
409+
endpoint: {{% variable "ENDPOINT_NAME" %}}-replica
410+
```
411+
412+
For example, if you define a `mariadb` database as follows:
413+
414+
```yaml {configFile="services"}
415+
mariadb:
416+
type: mariadb:{{% latest "mariadb" %}}
417+
disk: 2048
418+
configuration:
419+
schemas:
420+
- main
421+
endpoints:
422+
admin:
423+
default_schema: main
424+
privileges:
425+
main: admin
426+
reporter:
427+
privileges:
428+
main: ro
429+
```
430+
431+
To create a replica of the `mariadb` database and allow your app to connect to it
432+
through the `admin` endpoint with admin permissions,
433+
use the following configuration:
434+
435+
```yaml {configFile="app"}
436+
relationships:
437+
mariadb:
438+
service: mariadb
439+
endpoint: admin-replica
440+
```
441+
442+
To create a replica of the `mariadb` database and allow your app to connect to it
443+
through the `reporter` endpoint with read-only permissions instead,
444+
use the following configuration:
445+
446+
```yaml {configFile="app"}
447+
relationships:
448+
mariadb:
449+
service: mariadb
450+
endpoint: reporter-replica
451+
```
452+
453+
### Grant access to the main database and its replicas
454+
455+
{{< partial "banners/replicas/body.md" >}}
456+
457+
Your main database lives on one of the three nodes provided on Grid HA and {{% names/dedicated-gen-3 %}}.
458+
The two other nodes can each accommodate a replica of your main database.
459+
460+
You may want to grant access to both your main database and its replicas.
461+
To do so, when defining the relationship between your app and database,
462+
make sure you do the following:
463+
464+
1. Use the [explicit endpoint syntax](/create-apps/app-reference/single-runtime-image.html#relationships).
465+
2. Add the `-all` suffix to the name of the endpoint you want to use.
466+
467+
This results in the following configuration,
468+
which creates a replica on each of the secondary nodes:
469+
470+
```yaml {configFile="app"}
471+
relationships:
472+
{{% variable "RELATIONSHIP_NAME" %}}:
473+
service: {{% variable "SERVICE_NAME" %}}
474+
endpoint: {{% variable "ENDPOINT_NAME" %}}-all
475+
```
476+
477+
For example, if you define a `mariadb` database as follows:
478+
479+
```yaml {configFile="services"}
480+
mariadb:
481+
type: mariadb:{{% latest "mariadb" %}}
482+
disk: 2048
483+
configuration:
484+
schemas:
485+
- main
486+
endpoints:
487+
admin:
488+
default_schema: main
489+
privileges:
490+
main: admin
491+
reporter:
492+
privileges:
493+
main: ro
494+
```
495+
496+
To allow your app to connect to your main database and both its replicas
497+
through the `admin` endpoint with admin permissions,
498+
use the following configuration:
499+
500+
```yaml {configFile="app"}
501+
relationships:
502+
mariadb:
503+
service: mariadb
504+
endpoint: admin-all
505+
```
506+
507+
To allow your app to connect to your main database and both its replicas
508+
through the `reporter` endpoint with read-only permissions,
509+
use the following configuration:
510+
511+
```yaml {configFile="app"}
512+
relationships:
513+
mariadb:
514+
service: mariadb
515+
endpoint: reporter-all
516+
```
517+
389518
## Multiple databases
390519

391520
With version `10.0` or later, you can define multiple databases.
521+
392522
To do so, define multiple `schemas` in your [service configuration](#configuration-options).
393523

394524
You can also specify multiple `endpoints` for [permissions](#define-permissions).

‎sites/platform/src/add-services/postgresql.md

+63
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,69 @@ make sure your service name remains unchanged.
438438
Failure to do so results in the creation of a new service,
439439
which removes any existing data from your database.
440440

441+
## Restrict access to database replicas only
442+
443+
{{< partial "banners/replicas/body.md" >}}
444+
445+
For security reasons, you can grant your app access to replicas instead of your actual database.
446+
To do so, when defining the relationship between your app and database,
447+
make sure you do the following:
448+
449+
1. Use the [explicit endpoint syntax](/create-apps/app-reference/single-runtime-image.html#relationships).
450+
2. Add the `-replica` suffix to the name of the endpoint you want to use.
451+
452+
This results in the following configuration:
453+
454+
```yaml {configFile="app"}
455+
relationships:
456+
{{% variable "RELATIONSHIP_NAME" %}}:
457+
service: {{% variable "SERVICE_NAME" %}}
458+
endpoint: {{% variable "ENDPOINT_NAME" %}}-replica
459+
```
460+
461+
For example, if you define a `postgresql` database as follows:
462+
463+
```yaml {configFile="services"}
464+
postgresql:
465+
type: "postgresql:16"
466+
disk: 2048
467+
configuration:
468+
databases:
469+
- main
470+
- legacy
471+
endpoints:
472+
admin:
473+
privileges:
474+
main: admin
475+
legacy: admin
476+
reporter:
477+
default_database: main
478+
privileges:
479+
main: ro
480+
```
481+
482+
To create a replica of the `postgresql` database and allow your app to connect to it
483+
through the `admin` endpoint with admin permissions,
484+
use the following configuration:
485+
486+
```yaml {configFile="app"}
487+
relationships:
488+
postgresql:
489+
service: postgresql
490+
endpoint: admin-replica
491+
```
492+
493+
To create a replica of the `postgresql` database and allow your app to connect to it
494+
through the `reporter` endpoint with read-only permissions instead,
495+
use the following configuration:
496+
497+
```yaml {configFile="app"}
498+
relationships:
499+
postgresql:
500+
service: postgresql
501+
endpoint: reporter-replica
502+
```
503+
441504
## Service timezone
442505

443506
To change the timezone for the current session, run `SET TIME ZONE {{< variable "TIMEZONE" >}};`.

‎sites/platform/src/add-services/redis.md

+63
Original file line numberDiff line numberDiff line change
@@ -393,6 +393,69 @@ const value = await client.get('x'); // returns 42
393393

394394
{{< /codetabs >}}
395395

396+
## Restrict access to database replicas only
397+
398+
{{< partial "banners/replicas/body.md" >}}
399+
400+
For security reasons, you can grant your app access to replicas instead of your actual database.
401+
To do so, when defining the relationship between your app and database,
402+
make sure you do the following:
403+
404+
1. Use the [explicit endpoint syntax](/create-apps/app-reference/single-runtime-image.html#relationships).
405+
2. Add the `-replica` suffix to the name of the endpoint you want to use.
406+
407+
This results in the following configuration:
408+
409+
```yaml {configFile="app"}
410+
relationships:
411+
{{% variable "RELATIONSHIP_NAME" %}}:
412+
service: {{% variable "SERVICE_NAME" %}}
413+
endpoint: {{% variable "ENDPOINT_NAME" %}}-replica
414+
```
415+
416+
For example, if you define a `redis-persistent` database as follows:
417+
418+
```yaml {configFile="services"}
419+
postgresql:
420+
type: "redis-persistent:16"
421+
disk: 2048
422+
configuration:
423+
databases:
424+
- main
425+
- legacy
426+
endpoints:
427+
admin:
428+
privileges:
429+
main: admin
430+
legacy: admin
431+
reporter:
432+
default_database: main
433+
privileges:
434+
main: ro
435+
```
436+
437+
To create a replica of the `redis-persistent` database and allow your app to connect to it
438+
through the `admin` endpoint with admin permissions,
439+
use the following configuration:
440+
441+
```yaml {configFile="app"}
442+
relationships:
443+
redis-persistent:
444+
service: redis-persistent
445+
endpoint: admin-replica
446+
```
447+
448+
To create a replica of the `redis-persistent` database and allow your app to connect to it
449+
through the `reporter` endpoint with read-only permissions instead,
450+
use the following configuration:
451+
452+
```yaml {configFile="app"}
453+
relationships:
454+
redis-persistent:
455+
service: redis-persistent
456+
endpoint: reporter-replica
457+
```
458+
396459
## Relationship reference
397460

398461
Example information available through the [`{{% vendor/prefix %}}_RELATIONSHIPS` environment variable](/development/variables/use-variables.md#use-provided-variables)

‎themes/psh-docs/layouts/partials/banners/replicas/banner.html

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<!-- Creates single page banner note for warning about a feature being part of the Observability Suite -->
2+
{{ if .Params.replicas }}
3+
{{ partial "replicas/body.md" . }}
4+
{{ end }}

‎themes/psh-docs/layouts/partials/banners/replicas/body.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{{ $content := `This feature is available on Grid HA (High Availability) and {{% names/dedicated-gen-3 %}} projects. For more information, [contact Sales](https://platform.sh/contact/).`}}
2+
3+
{{ partial "premium-features/banner" ( dict "context" . "content" $content "title" "Feature availability" )}}

0 commit comments

Comments
 (0)