Connecting to Services

Beta

This feature is currently in beta and only available through nctl. Cockpit support is not yet implemented.

Deploio applications can connect to On-Demand Services such as databases and key-value stores by declaring service references on the application. Nine automatically injects the connection credentials as environment variables into the app at runtime.

Under the hood, Nine automatically creates and manages an encrypted ServiceConnection in the target service's project. No manual networking setup is required.

Supported Services

The following service types can be referenced from a Deploio application:

• Key-Value Store
• MySQL
• PostgreSQL
• OpenSearch

Add a Service Reference

Each service reference requires a destination (the service to connect to).

Cockpit

Coming soon

Managing service references in Cockpit is not yet available. We're currently working on the implementation. For now, please use nctl.

nctl

When creating a new application, use --service with the format name=kind/target-name:

nctl create application my-app \
  --git-url=https://github.com/example/app.git \
  --service cache=keyvaluestore/my-kvs

To add a service to an existing application:

nctl update application my-app \
  --service cache=keyvaluestore/my-kvs

To remove a service reference:

nctl update application my-app \
  --delete-service cache

Injected Environment Variables

When service references are configured, Nine injects the connection details as environment variables into every instance of the application. Variable names use the format NINE_<IDENTIFIER>_<NAME>_<KEY>:

• <IDENTIFIER> is a short code for the service type, such as KVS, PG, or MYSQL. Each table below shows the identifier for its service type.
• <NAME> is the reference name you assign in --service <name>=... (the name part), uppercased with non-alphanumeric characters replaced by _. For example, the reference name cache becomes CACHE.
• <KEY> identifies the connection detail, such as FQDN, PORT, or PASSWORD.

The variable names use the reference name you chose, not the target service's resource name. For example, --service cache=keyvaluestore/my-kvs produces variables like NINE_KVS_CACHE_FQDN — using cache, not my-kvs.

A new release is required

Adding or changing a service reference does not update a running instance on its own. Nine injects the variables only when a new release is created. If your change doesn't already produce a new release, trigger one by using the --retry-release function of nctl:

nctl update app my-app --retry-release

A new release redeploys the application: Deploio rolls out new instances with the updated environment and replaces the running ones. Expect a deployment cycle, and plan the change accordingly.

The available variables depend on the service type:

Key-Value Store

Variable	Description
NINE_KVS_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_KVS_<NAME>_PORT	Port (always 6379).
NINE_KVS_<NAME>_USER	Username.
NINE_KVS_<NAME>_PASSWORD	Password.
NINE_KVS_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.

PostgreSQL — Business

Variable	Description
NINE_PG_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_PG_<NAME>_PORT	Port (always 5432).
NINE_PG_<NAME>_USER	Username.
NINE_PG_<NAME>_PASSWORD	Password.
NINE_PG_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.
NINE_PG_<NAME>_DSN	Full PostgreSQL connection URI (postgres://user:pass@host:port/dbname).

PostgreSQL — Economy

Variable	Description
NINE_PGDB_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_PGDB_<NAME>_PORT	Port (always 5432).
NINE_PGDB_<NAME>_USER	Database name (same as the name assigned at creation).
NINE_PGDB_<NAME>_PASSWORD	Password.
NINE_PGDB_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.
NINE_PGDB_<NAME>_DSN	Full PostgreSQL connection URI (postgres://user:pass@host:port/dbname).

MySQL — Business

Variable	Description
NINE_MYSQL_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_MYSQL_<NAME>_PORT	Port (always 3306).
NINE_MYSQL_<NAME>_USER	Username.
NINE_MYSQL_<NAME>_PASSWORD	Password.
NINE_MYSQL_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.

MySQL — Economy

Variable	Description
NINE_MYSQLDB_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_MYSQLDB_<NAME>_PORT	Port (always 3306).
NINE_MYSQLDB_<NAME>_USER	Username (same as the database name assigned at creation).
NINE_MYSQLDB_<NAME>_PASSWORD	Password.
NINE_MYSQLDB_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.

OpenSearch

Variable	Description
NINE_OS_<NAME>_FQDN	Hostname. Uses private networking DNS when private networking is configured; otherwise the public hostname.
NINE_OS_<NAME>_USER	Username.
NINE_OS_<NAME>_PASSWORD	Password.
NINE_OS_<NAME>_CA_CERT	CA certificate. Only injected when a CA certificate is present.

Verifying the Injected Variables

Cockpit

Coming soon

Viewing the injected variables in Cockpit is not yet available. We're currently working on the implementation. For now, please use nctl.

nctl

Verify the injected variables in two ways:

• In the release resource (not the application resource). Releases have generated names, so list them first, then inspect the latest one. Its serviceEnvVars field lists the injected variable names (the values are kept in a referenced secret, so they aren't shown here):

  nctl get releases -p my-project
  nctl get releases <release-name> -p my-project -o yaml

• From inside a running instance, by listing its environment. This shows both the names and the values:

  nctl exec app my-app -p my-project -- env

If the variables are missing, check if a new release was created after the service reference was added.