Exposing services

Service ports

To make a service available to other services inside a project or to the outside world, ports need to be defined within the ports section. Each port entry consists of a service_port:container_port pair.

services:
  db:
    image: redis
    deploy:
      replicas: 1
    ports:
      - 6379:6379

Without defining the ports, services are not allowed to communicate with each other.

Note

ports entries can also be specified as a string, using the same format, e.g. "6379:6379"

Exposing services to the Internet

levv supports exposing HTTP, TCP, and UDP services publicly. When a service requires such functionality, a list of ports to be exposed needs to be defined in the io.levv.public label. The usual ports entries should also be specified.

The io.levv.public label takes a list of service ports that you would like to expose to the outside world. Allowed protocols are http, tcp, and udp.

HTTP services

For HTTP services, the ports mapping for a public service requires an entry with 80 at the left side, and the container port that handles HTTP requests on the right side (e.g. 80:8080). Even though the service port is 80, the service will be reachable externally through HTTPS on port 443.

services:
  frontend:
    image: nginxdemos/nginx-hello:plain-text
    deploy:
      replicas: 2
    labels:
      io.levv.size: "medium"
      io.levv.public: "80/http"
    ports:
      - "80:8080" # ServicePort:ContainerPort

When launched through the cli, the public endpoint (URL) is displayed as part of the success message:

Applying specification    successful

SERVICE   PROJECT       REPLICAS  SIZE  PUBLIC ENDPOINTS   STATUS
frontend  <PROJECT-ID>  2/2       nano  <PUBLIC-URL>       DEPLOYED

Deprecation notice

The legacy usage of io.levv.public is still supported but will be deprecated in the future. By defining io.levv.public: true, your service will be published using HTTP.

Custom domain names

To make your application accessible via a custom domain name, add the domainname field to your service's configuration:

services:
  frontend:
    image: nginxdemos/nginx-hello:plain-text
    deploy:
      replicas: 2
    labels:
      io.levv.size: "medium"
      io.levv.public: "80/http"
    ports:
      - "80:8080" # ServicePort:ContainerPort
    domainname: "www.example.com"

When launched through the cli, additional instructions will be displayed in order to finalize the configuration:

To access your app via its custom domain name, please add the following record(s) to your domain name server(s):

NAME         TYPE   VALUE
example.com  CNAME  <PUBLIC-URL>

Please refer to your domain name server documentation for more info on adding a CNAME record.

TCP/UDP services

To access TCP/UDP services, the io.levv.public labels needs to be set with the service port followed by the protocol, eg. 6379/tcp.

services:
  frontend:
    image: redis
    deploy:
      replicas: 1
    labels:
      io.levv.public: "6379/tcp"
    ports:
      - "6379:6379" # ServicePort:ContainerPort

The service port will then be exposed using a dynamic TCP/UDP port. The port number will be displayed after deploying the service, and can be displayed again using the levv ls command.

In this case, the public endpoint for the service will be reachable at public.levv.io.

Note

The levv ps command can be used to display the service and container ports, but does not show the actual public ports being used. Use the levv ls command instead.