Skip to content

Commit 00b7620

Browse files
chadwcarlsonchadwcarlson
committed
add-services/_index.md
1 parent 1ae1d97 commit 00b7620

File tree

2 files changed

+71
-70
lines changed

2 files changed

+71
-70
lines changed

Diff for: ‎sites/friday/src/add-services/_index.md

+59-50
Original file line numberDiff line numberDiff line change
@@ -26,26 +26,28 @@ All service configuration happens in the `{{< vendor/configfile "services" >}}`
2626
Configure your service in the following pattern:
2727

2828
```yaml {configFile="services"}
29-
{{% snippet name="SERVICE_NAME" config="service" %}}
30-
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
31-
# Other options...
32-
{{% /snippet %}}
29+
# The name of the service container. Must be unique within a project.
30+
services:
31+
SERVICE_NAME:
32+
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
33+
# Other options...
3334
```
3435

3536
An example service configuration for two databases might look like this:
3637

3738
```yaml {configFile="services"}
38-
{{% snippet name="database1" config="service" %}}
39-
type: mariadb:{{% latest "mariadb" %}}
40-
{{% /snippet %}}
41-
{{% snippet name="database2" config="service" globKey="false" %}}
42-
type: postgresql:{{% latest "postgresql" %}}
43-
{{% /snippet %}}
39+
services:
40+
# The name of the service container. Must be unique within a project.
41+
mariadb:
42+
type: mariadb:{{% latest "mariadb" %}}
43+
# The name of the service container. Must be unique within a project.
44+
postgresql:
45+
type: postgresql:{{% latest "postgresql" %}}
4446
```
4547
4648
This YAML file contains a dictionary defining all of the services you want to use.
4749
The top-level key `services` defines an object of all of the services to be provisioned for the project.
48-
Below that, come custom service names ({{<variable "SERVICE_NAME" >}}; in the example, `database1` and `database2`), which you use to identify services in step 2.
50+
Below that, come custom service names ({{<variable "SERVICE_NAME" >}}; in the example, `mariadb` and `postgresql`), which you use to identify the service in step 2.
4951

5052
You can give it any name you want with lowercase alphanumeric characters, hyphens, and underscores.
5153

@@ -65,7 +67,7 @@ The following table presents the keys you can define for each service:
6567
| --------------- | ---------- | ----------------- | ----------- |
6668
| `type` | `string` | Yes | One of the [available services](#available-services) in the format `type:version`. |
6769
| `configuration` | dictionary | For some services | Some services have additional specific configuration options that can be defined here, such as specific endpoints. See the given service page for more details. |
68-
| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](../create-apps/app-reference.md#relationships). The `endpoint_name` for apps is always `http`. |
70+
| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](/create-apps/app-reference.md#relationships). The `endpoint_name` for apps is always `http`. |
6971

7072
##### Resources (CPU, RAM, disk)
7173

@@ -78,44 +80,51 @@ For more information, see how to [manage resources](/manage-resources.md).
7880

7981
### 2. Connect the service
8082

81-
Once you have configured a service, you need to create a relationship to connect it to an app.
82-
This is done in your [app configuration for relationships](../create-apps/app-reference.md#relationships).
83-
84-
The relationship follows this pattern:
83+
To connect the service, use the following configuration:
8584

8685
```yaml {configFile="app"}
87-
{{% snippet name="<APP_NAME>" config="app" root="false"%}}
88-
89-
# Other options...
90-
91-
# Relationships enable an app container's access to a service.
92-
relationships:
93-
{{< variable "RELATIONSHIP_NAME" >}}: "{{< variable "SERVICE_NAME" >}}:{{< variable "ENDPOINT" >}}"
94-
{{% /snippet %}}
95-
{{% snippet name="SERVICE_NAME" config="service" placeholder="true"%}}
96-
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
97-
# Other options...
98-
{{% /snippet %}}
86+
applications:
87+
# The name of the app container. Must be unique within a project.
88+
{{<variable "APP_NAME" >}}:
89+
90+
# Other options...
91+
92+
# Relationships enable an app container's access to a service.
93+
# The example below shows simplified configuration leveraging a default service (identified from the relationship name) and a default endpoint.
94+
# See the Application reference for all options for defining relationships and endpoints.
95+
relationships:
96+
{{<variable "SERVICE_NAME" >}}:
97+
services:
98+
# The name of the service container. Must be unique within a project.
99+
{{<variable "SERVICE_NAME" >}}:
100+
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
101+
# Other options...
99102
```
100103

104+
You can define `<SERVICE_NAME>` as you like, so long as it's unique between all defined services
105+
and matches in both the application and services configuration.
106+
107+
The example above leverages [default endpoint](/create-apps/app-reference#relationships) configuration for relationships.
108+
That is, it uses default endpoints behind-the-scenes, providing a [relationship](/create-apps/app-reference#relationships)
109+
(the network address a service is accessible from) that is identical to the _name_ of that service.
110+
111+
Depending on your needs, instead of default endpoint configuration,
112+
you can use [explicit endpoint configuration](/create-apps/app-reference#relationships).
113+
101114
An example relationship to connect to the databases given in the [example in step 1](#1-configure-the-service):
102115

103-
```yaml {configFile="app"}
104-
{{% snippet name="<APP_NAME>" config="app" root="false" %}}
105-
106-
# Other options...
107-
108-
# Relationships enable an app container's to a service.
109-
relationships:
110-
mysql_database: "database1:mysql"
111-
postgresql_database: "database2:postgresql"
112-
{{% /snippet %}}
113-
{{% snippet name="database1" config="service" placeholder="true" %}}
114-
type: mariadb:{{% latest "mariadb" %}}
115-
{{% /snippet %}}
116-
{{% snippet name="database2" config="service" globKey="false" placeholder="true" %}}
117-
type: postgresql:{{% latest "postgresql" %}}
118-
{{% /snippet %}}
116+
```yaml {configFile="apps"}
117+
applications:
118+
# The name of the app container. Must be unique within a project.
119+
{{<variable "APP_NAME" >}}:
120+
relationships:
121+
mariadb:
122+
postgresql:
123+
services:
124+
mariadb:
125+
type: mariadb:{{% latest "mariadb" %}}
126+
postgresql:
127+
type: postgresql:{{% latest "postgresql" %}}
119128
```
120129

121130
As with the service name, you can give the relationship any name you want
@@ -187,17 +196,17 @@ To get the credentials for a given service, run the following command:
187196
You get output like the following:
188197

189198
```yaml
190-
database:
199+
mariadb:
191200
-
192201
username: user
193202
scheme: mysql
194-
service: database
203+
service: mariadb
195204
fragment: null
196205
ip: 198.51.100.37
197-
hostname: abcdefghijklm1234567890123.database.service._.eu.{{< vendor/urlraw "hostname" >}}
206+
hostname: abcdefghijklm1234567890123.mariadb.service._.eu.{{< vendor/urlraw "hostname" >}}
198207
public: false
199208
cluster: abcdefgh1234567-main-abcd123
200-
host: database.internal
209+
host: mariadb.internal
201210
rel: mysql
202211
query:
203212
is_master: true
@@ -206,10 +215,10 @@ database:
206215
type: 'mariadb:10.6'
207216
port: 3306
208217
host_mapped: false
209-
url: 'mysql://user:@database.internal:3306/main'
218+
url: 'mysql://user:@mariadb.internal:3306/main'
210219
```
211220

212-
With this example, you can connect to the `database` relationship
221+
With this example, you can connect to the `mariadb` relationship
213222
with the user `user`, an empty password, and the database name `main` (from the `path`).
214223
The `url` property shows a full database connection that can be used from your app.
215224

Diff for: ‎sites/platform/src/add-services/_index.md

+12-20
Original file line numberDiff line numberDiff line change
@@ -28,27 +28,27 @@ All service configuration happens in the `{{< vendor/configfile "services" >}}`
2828
Configure your service in the following pattern:
2929

3030
```yaml {configFile="services"}
31-
{{% snippet name="SERVICE_NAME" config="service" %}}
31+
# The name of the service container. Must be unique within a project.
32+
SERVICE_NAME:
3233
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
3334
# Other options...
34-
{{% /snippet %}}
3535
```
3636

3737
An example service configuration for two databases might look like this:
3838

3939
```yaml {configFile="services"}
40-
{{% snippet name="database1" config="service" %}}
40+
# The name of the service container. Must be unique within a project.
41+
mariadb:
4142
type: mariadb:{{% latest "mariadb" %}}
4243
disk: 2048
43-
{{% /snippet %}}
44-
{{% snippet name="database2" config="service" globKey="false" %}}
44+
# The name of the service container. Must be unique within a project.
45+
postgresql:
4546
type: postgresql:{{% latest "postgresql" %}}
4647
disk: 1024
47-
{{% /snippet %}}
4848
```
4949
5050
This YAML file is a dictionary defining all of the services you want to use.
51-
The top-level key is a custom service name ({{<variable "SERVICE_NAME" >}}; in the example, `database1` and `database2`), which you use to identify the service in step 2.
51+
The top-level key is a custom service name ({{<variable "SERVICE_NAME" >}}; in the example, `mariadb` and `postgresql`), which you use to identify the service in step 2.
5252

5353
You can give it any name you want with lowercase alphanumeric characters, hyphens, and underscores.
5454

@@ -70,7 +70,7 @@ The following table presents the keys you can define for each service:
7070
| `disk` | `integer` | For some services | The size in [MB](/glossary.md#mb) of the [persistent disk](#disk) allocated to the service. Can't be set for memory-resident-only services such as `memcache` and `redis`. Limited by your plan settings. |
7171
| `size` | `string` | | How many CPU and memory [resources to allocate](#size) to the service. Possible values are `AUTO`, `S`, `M`, `L`, `XL`, `2XL`, and `4XL`. Limited by your plan settings.<BR><BR>When `AUTO` applies, available resources are automatically balanced out based on the number of containers on your plan, so that no container is oversized compared to the others. To view the actual sizes of your containers, check the **Environment Configuration** section in your deployment [activity logs](../increase-observability/logs/access-logs.md#activity-logs). |
7272
| `configuration` | dictionary | For some services | Some services have additional specific configuration options that can be defined here, such as specific endpoints. See the given service page for more details. |
73-
| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](../create-apps/app-reference.md#relationships). The `endpoint_name` for apps is always `http`. |
73+
| `relationships` | dictionary | For some services | Some services require a relationship to your app. The content of the dictionary has the same type as the `relationships` dictionary for [app configuration](/create-apps/app-reference.md#relationships). The `endpoint_name` for apps is always `http`. |
7474

7575
##### Disk
7676

@@ -90,24 +90,16 @@ Note that service containers in preview environments are always set to size `S`.
9090

9191
### 2. Connect the service
9292

93-
Once you have configured a service, you need to create a relationship to connect it to an app.
94-
This is done in your [app configuration for relationships](../create-apps/app-reference.md#relationships).
95-
96-
The relationship follows this pattern:
93+
To connect the service, use the following configuration:
9794

9895
```yaml {configFile="app"}
99-
{{% snippet name="<APP_NAME>" config="app" root="false"%}}
100-
10196
# Other options...
10297
10398
# Relationships enable an app container's access to a service.
99+
# The example below shows simplified configuration leveraging a default service (identified from the relationship name) and a default endpoint.
100+
# See the Application reference for all options for defining relationships and endpoints.
104101
relationships:
105-
{{< variable "RELATIONSHIP_NAME" >}}: "{{< variable "SERVICE_NAME" >}}:{{< variable "ENDPOINT" >}}"
106-
{{% /snippet %}}
107-
{{% snippet name="SERVICE_NAME" config="service" placeholder="true"%}}
108-
type: {{<variable "SERVICE_TYPE" >}}:{{<variable "VERSION" >}}
109-
# Other options...
110-
{{% /snippet %}}
102+
{{<variable "SERVICE_NAME" >}}:
111103
```
112104

113105
An example relationship to connect to the databases given in the [example in step 1](#1-configure-the-service):

0 commit comments

Comments
 (0)