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:: services: wordpress: exposed: yes formula: local:wordpress-42 relations: {db: mysql} units: wordpress/0: 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. .. note:: 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.