Inter Service Traffic

By Inter Service Traffic (IST), we mean all private communications between services. These communications are authenticated and encrypted. No other services, or any connection from outside, will have access to the services. These private communications work if your services are on the same runner, but they also work if they are on two different runners or even on different providers. These communications support any port but are restricted to the TCP protocol.

Using Inter Service Traffic (IST) is as easy as using a predefined private hostname or predefined environment variables.

Communications between services in the same deployment

Without configuration

Without configuration, services can communicate with other services inside the same deployment by using specific environment variables or specific hostnames without any further setting.

With hostname

For each service in the same deployment, a hostname is set with the private IP of the service. So, in application code or in script, you can use these hostnames to communicate by TCP with another service.

For a service <service-name>, a hostname <encoded-service-name>.warp is accessible. Usually, the <encoded-service-name> is equal to the <service-name>, but in case you use non-127 ASCII characters (e.g. Unicode characters) or space, the <encoded-service-name> is computed as follows:

• Convert the name with Internationalized domain name and Punycode.
• Lowercase all characters.
• Replace all non-alphanumeric characters with a hyphen ( - ).
• Remove all trailing hyphens ( - ).

With environment variables

For each service in the same deployment, two environment variables are declared and set with the private IP of the service. So, in application code or in script, you can use these environment variables to communicate by TCP with another service. No other configuration is needed.

General environment variables

For a service <service-name>, an environment variable WARP_IST_<encoded-service-name> is accessible. Usually, the <encoded-service-name> is equal to the <service-name>, but in case you use non-127 ASCII characters (e.g. Unicode characters) or space in your service name, the <encoded-service-name> is computed as follows:

• Convert the name into 127 ASCII characters with the ASCIIFoldingFilter.
• If there are remaining non-127 ASCII characters, encode them with Punycode.
• Replace all spaces and equals ( = ) with underscores ( _ ).

Environment variable oriented shell script

Because some shell and Unix utilities could have difficulties dealing with special characters in the name of an environment variable, a second environment variable is also set by replacing all non-alphanumeric characters in the previous one with underscores ( _ ).

Encoding examples

Service name	Hostname	Generic environment variable	Shell environment variable
my-db	my-db.warp	WARP_IST_my-db	WARP_IST_my_db
my db	my-db.warp	WARP_IST_my_db
my=db	my-db.warp	WARP_IST_my_db
my-db:dev	my-db-dev.warp	WARP_IST_my-db:dev	WARP_IST_my_db_dev
My-DB-	my-db.warp	WARP_IST_My-DB-	WARP_IST_My_DB_
mes-données	xn--mes-donnes-i7a.warp	WARP_IST_mes-donnees	WARP_IST_mes_donnees
✅ db	xn---db-8g6a.warp	WARP_IST__db-8g6a	WARP_IST__db_8g6a
我的数据	xn--wnu53ab8bw85a.warp	WARP_IST_wnu53ab8bw85a

Specific configuration in warp.config.js

If you want to manage the names of environment variables and/or hostnames, you can add a section ist in the warp.config.js file, as follows:

module.exports = {
  container: "my-container-service",
  ist: [
    {
      service: 'my-sql',
      variables: [ 'MY_SQL_SERVICE', 'ANOTHER_VAR' ],
      hostnames: [ 'mysql.local' ],
    },
  ],
};

In this case, the platform will create two environment variables (MY_SQL_SERVICE and ANOTHER_VAR) and one hostname (mysql.local) in the container my-docker-service, to communicate privately with the service my-sql by TCP on any port.

• ist can contain only one entry by service, but any number of entries for different services.
• arrays are optional.
• variables and hostnames can be omitted if not needed.

Notes

Conflicts

In cases where two service names give the same environment variables and hostnames due to the encoding, the behavior is undefined. In this case, we suggest using a configuration in the warp.config.js to be able to manage variable names and hostnames adequately.

Resolution of IST hostname

Hostnames for IST are automatically injected in the files /etc/hosts of your container. In classic configuration and usage, everything will work well. There are two reasons why your IST hostname could not be resolved:

• Your application does not use the getaddrinfo or equivalent call. In this case, your application probably uses the DNS service by using DNS over TLS, DNS over HTTPS, or even the DNS standard UDP port.
• Your container does not use the file /etc/hosts by having a specific setting in /etc/nsswitch.conf. Usually, this file indicates with a hosts: files dns to use the /etc/hosts file. If there is no files, the resolution of IST hostnames will not be successful.

In these rare cases, you need to use environment variables instead of hostnames.

Service visibility

Currently, on our platform, each service has a public URL that allows access at the HTTPS level. By default, this public URL is mapped to the exposed port of your container image. If you want to avoid exposing this port to the public URL, indicate in the warp.config.js of the service a port not processed by your service. Access via the public URL will be directed to this port, which will do nothing.

To set the port, use deployment.port property.

module.exports = {
  container: "my-docker-service",
  deployment: {
    port: 65500,
  },
};