Exposing a service

In Ensemble, making a service public – its ports available for public use – requires that it be explicitly exposed. Note that this exposing does not yet involve DNS or other directory information. For now, it simply makes the service public.

Service exposing works by opening appropriate ports in the firewall of the cloud provider. Because service exposing is necessarily tied to the underlying provider, Ensemble manages all aspects of exposing. Such management ensures that a formula can work with other cloud providers besides EC2, once support for them is implemented.

Ensemble provides the ensemble expose command to expose a service. For example, you might have deployed a my-wordpress service, which is defined by a wordpress formula. To expose this service, simply execute the following command:

ensemble expose my-wordpress

To stop exposing this service, and make any corresponding firewall changes immediately, you can run this command:

ensemble unexpose my-wordpress

You can see the status of your exposed ports by running the ensemble status command. If ports have been opened by the service and you have exposed the service, then you will see something like the following output for the deployed services:

    exposed: yes
    formula: local:wordpress-42
    relations: {db: mysql}
        machine: 2
        open-ports: [80/tcp]

Service exposing for formula authors

Service exposing determines which ports to expose by using the open-port and close-port commands in hooks. The commands take the same arguments:

open-port port[/protocol]

close-port port[/protocol]

As an example, consider the WordPress formula, which has been deployed as my-wordpress. After completing the setup and restart of Apache, the wordpress formula can then publish the available port in its start hook for a given service unit:

open-port 80

External access to the service unit is only allowed when both open-port is executed within any hook and the administrator has exposed its service. The order in which these happen is not important, however.


Being able to use any hook may be important for your formula. Ideally, the service does not have ports that are vulnerable if exposed prior to the service being fully ready. But if that’s the case, you can solve this problem by only opening the port in the appropriate hook and when the desired conditions are met.

Alternatively, you may need to expose more than one port, or expose ports that don’t use the TCP protocol. To expose ports for HTTP and HTTPS, your formula could instead make these settings:

open-port 80
open-port 443

Or if you are writing a formula for a DNS server that you would like to expose, then specify the protocol to be UDP:

open-port 53/udp

When the service unit is removed or stopped for any reason, the firewall will again be changed to block traffic which was previously allowed to reach the exposed service. Your formula can also do this to close the port:

close-port 80

To be precise, the firewall is only open for the exposed ports during the time both these conditions hold:

  • A service has been exposed.
  • A corresponding open-port command has been run (without a subsequent close-port).

exposed and unexposed hooks

Upon a service being exposed, the exposed hook will be run, if it is present in the formula.

This may be an appropriate place to run the open-port command, however, it is up to the formula author where it should be run, since it and close-port are available commands for every hook.

Likewise, when a service is unexposed, the unexposed hook will be run, if present. Many formulas likely do not need to implement this hook, however, it could be an opportunity to shutdown unnecessary processes or remove other resources.

Project Versions

Table Of Contents

Previous topic


Next topic

Formula Namespaces

This Page