Network services

By default, network traffic from a job instance (egress) is not allowed because job instances are containers that run in isolation. Network egress on a job or capsule is closed by default. To open egress for a job, the job must be bound to a service that allows it.

The network service type provides direct access, irrespective of protocol, to the network outside the cluster.

Configuring network services

Apcera provides the network service type for direct access, irrespective of protocol, to the network outside the cluster. Unlike the http service type, the network service type does not restrict the protocol to HTTP.

Apcera provides several built-in network service implementations to which you can easily connect jobs. You can also create your own network service type.

The network service type does not provide a semantic pipeline.

Binding to an outside network

Apcera provides the following pre-built services for the network type that let you bind to an outside network for job egress:

Type Description
/apcera::outside Allows connections to IP address outside Apcera.
/apcera::outside-dns Allows UDP port 53 connections to your DNS server.
/apcera::outside-http Allows HTTP connectivity to any address outside Apcera.
/apcera::outside-https Allows HTTPS connectivity to any address outside Apcera.
/apcera::outside-icmp Allows Internet Control Message Protocol (ICMP) to all outside networks.
/apcera::outside-tcp-dns Allows TCP port 53 connections to your DNS server.

For example, the following command binds a job to the service::/apcera::outside network:

apc service bind /apcera::outside -job my-capsule

Note that the /apcera::outside-http network service is not the same as the /apcera::http service type. Refer to the HTTP service type for more information.

Using the allow egress shortcut

As described above, the service /apcera::outside is a system-provided network service that uses the network service gateway to connect to the external network.

Instead of formally binding a job to the outside network, you can instead use the --allow-egress flag (or -ae shortcut), for example:

apc capsule create my-capsule --allow-egress

The --allow-egress option is a shortcut for the service bind /apcera::outside command that binds resulting jobs to the network service.

The --allow-egress (-ae) flag is available for the following commands:

  • apc app create
  • apc capsule create
  • apc gateway from package
  • apc stager from file
  • apc stager from package

You can use --allow-egress flag for any supported job type that needs network access. For example:

apc stager from package my-package my-stager -ae

The -ae flag is a developer convenince. It should not be used for production apps. When you snapshot a capsule, -ae is disabled.​

Creating network services

The APC command to create service of type network accepts additional options on the command line (following the double-dash (--)) and passes them to the network service gateway, which sets up restrictions on the created services.

You can create a service of type network using the following syntax:

apc service create <service-name> --type network -- <options>

Note that the syntax requires a double-dash -- to separate the apc service create command from the network service type options.

The network service type supports the following command options. You must specify a value for only one of the --ipnet, --ipnets, or --domainname options, which are mutually exclusive.

Option Type Description
--ipnet String IP network in CIDR mask format (IP address v4 and v6), for example: 5.5.5.5/32, 4.4.4.4/20, or any.
--ipnets String[] IP networks in CIDR mask format (IP address v4 and v6), for example: 4.4.4.4/32,8.8.4.4/32 (comma-separated).
--domainname String Fully Qualified Domain Name (FQDN) that is resolved to an IP address using a Domain Name Service (DNS) lookup.
--protocol String Allowed protocol; supported values include: tcp, udp, icmp, and all.
--portrange String Allowed ports; supported values include a single port (such as 8080), a port range (such as 8000-9000) or all ports (all).

For example, you could create a network service named marketing-net-service that jobs can bind to using the --ipnet option:

apc service create marketing-net-service --type network -- --ipnet 127.0.0.0/24 --protocol tcp --portrange all

This example allows egress connectivity using the TCP protocol to all ports of the subnet 127.0.0.0 using a network mask of 255.255.255.0 (because of the /24) for all ports.

Or, to support muliple IP addresses, you can use the --ipnets flag with comma-separated values.

apc service create marketing-net-service --type network -- --ipnets 4.4.4.4/32,8.8.4.4/32 --protocol tcp --portrange all

Or, if an internet domain name (--domainname) is used and bound to a job, network egress is allowed to the resolved IP address:

apc service create marketing-net-service --type network –- --domainname www.google.com --protocol tcp --portrange all

If you need to create a network service that supports multiple distinct ports, you can create multiple network services and bind the job to each. For example, if you have a job that needs TCP access on any network for both port 80 and port 443, you would create two network services then bind the job to each network service.