services, which is placed in a unified configuration file like .upsun/config.yaml.
If you don’t need any services (such as for a static website), you don’t need to include this configuration. Read on to see how to add services.
Add a service
Adding a service is a two-step process.1. Configure the service
All service configuration happens in the.upsun/config.yaml file in your Git repository.
Configure your service in the following pattern:
An example service configuration for two databases might look like this:
This YAML file contains a dictionary defining all of the services you want to use.
The top-level key services defines an object of all of the services to be provisioned for the project.
Below that, come custom service names (; in the example, mariadb and postgresql), which you use to identify the service in step 2.
You can give it any name you want with lowercase alphanumeric characters, hyphens, and underscores.
Changing the service name is interpreted as creating an entirely new service.
This removes all data in that service.
Always back up your data before changing existing services in your
.upsun/config.yaml file.Service options
The following table presents the keys you can define for each service:| Name | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of the available services in the format type:version. |
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. |
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. The endpoint_name for apps is always http. |
Resources (CPU, RAM, disk)
Upsun allows you to configure resources (CPU, RAM, and disk) per environment for each of your services. For more information, see how to manage resources. You configure the disk size in MB. Your actual available disk space is slightly smaller with some space used for formatting and the filesystem journal. When checking available space, note whether it’s reported in MB or MiB. You can decrease the size of an existing disk for a service. If you do so, be aware that:- You need to create new backups that the downsized disk can accommodate. Backups from before the downsize cannot be restored unless you increase the disk size again.
- The downsize fails if there’s more data on the disk than the desired size.
2. Define the relationship
To define the relationship, use the following configuration:- Using default endpoints
- Using explicit endpoints
You can define
SERVICE_NAME as you like, so long as it’s unique between all defined services
and matches in both the application and services configuration.The example above leverages default endpoint configuration for relationships.
That is, it uses default endpoints behind the scenes, providing a relationship
(the network address a service is accessible from) that is identical to the name of that service.Depending on your needs, instead of default endpoint configuration,
you can use explicit endpoint configuration.- Using explicit endpoints
As with the service name, you can give the relationship any name you want
with lowercase alphanumeric characters, hyphens, and underscores.
It helps if the service name and relationship name are different, but it isn’t required.
mysql or solr).
Available services
The following table presents the available service types and their versions. Add them to thetype key of the service configuration in the format type:version.
Service versions
These services generally follow semantic versioning conventions. You can select the major version, but the latest compatible minor is applied automatically and can’t be overridden. Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.Service timezones
All services have their system timezone set to UTC by default. For some services, you can change the timezone for the running service (this doesn’t affect the container itself and so logs are still in UTC).Connect to a service
For security reasons, you can’t access services directly through HTTP. You can connect through your app or by opening an SSH tunnel to access the service directly.- In an app
- Through an SSH tunnel
Once a service is running and exposed via a relationship,
its credentials (such as the host, username, and password) are automatically available as service environment variables,
in the
$<RELATIONSHIP-NAME>_<SERVICE-PROPERTY> format.
The available information is documented on each service’s page, along with sample code for how to connect to it from your app.The service environment variable names are fixed, but the values may change if you change the relationship name to the service.
So use the environment variable rather than hard coding the values.Upgrading services
Upsun provides a large number of managed service versions. As new versions are made available, you will inevitably upgrade infrastructure to a more recent (or latest version). When you do so, we would recommend:- Use preview environments. Leverage preview (non-production environments) to perform the upgrade, then merge the upgrade into production (promotion). This will give you an opportunity to test inherited production data in a safe, isolated environment first.
- Upgrade progressively. For one reason or another, you may be more than a single version behind the upgrade you are trying to perform. To avoid data loss issues caused by large differences in versions, upgrade one version at a time.