Linking Jobs

Apcera Platform provides robust facilities for orchestrating services. Many situations can benefit from these features, yet don't require all of the power of the service model. Job links provide many of the same benefits as services, including policy controls and dynamic routing, but with less overhead.

Overview

A job link is a TCP connection between jobs in the system. Typically you use job links to create network connections between client-server apps.

Assuming policy permissions, you can link a job to any other job in the system, including across runtime hosts (Instance Managers).

Unlike a service binding, the system does not manage a job link, but the system does provide the same dynamic remapping for job links that it provides for service bindings, as well as policy-based security controls.

A job link is a TCP network connection between a source job and a target job in the form of ip:port. The syntax for creating a job link is as follows:

apc job link <source-job> --to <target-job> --name <link-name> --port <port on target-job>

When you create a job link, the system sets an environment variable on the source job whose value is the URI it uses to connect to the target job. If you specify a value for the --name parameter then the environment variable name takes the form of <NAME>_URI. For example:

apc job link app1 --to app2 --name mylink
Stopping the job... done
Binding "job::/sandbox/admin::app1" to "job::/sandbox/admin::app2"... done
╭───────────────────────────────╮
│ Binding Environment Variables │
├───────────────────────────────┤
│ "MYLINK_URI"                  │
╰───────────────────────────────╯

If you don't specify a value for the --name parameter, the name of the environment variable takes the form of BIND_<SOURCE-JOB-NAME>_<TARGET-JOB-NAME>_URI. For example:

apc job link app1 --to app2
Stopping the job... done
Binding "job::/sandbox/admin::app1" to "job::/sandbox/admin::app2"... done
╭───────────────────────────────╮
│ Binding Environment Variables │
├───────────────────────────────┤
│ "BIND_APP1_APP2_URI"          │
╰───────────────────────────────╯

The system automatically provides security and dynamic routing.

See the Job link tutorial for an example implementation.

If you are linking two jobs with multiple instances, then for each instance of the connecting job an instance of the target job will be randomly selected when the link is created.

In order to obtain a link to another job, your job must be authorized to do so. You control the authorization using policies to permit link on the job. The other job must be authorized to accept the connection. This does not mean that it can initiate a connection with your job. That requires separate permission.

Apcera Platform also provides security through routing. The system maps the URI (actually an IP address and port) it gives you so the traffic your job sends using that address arrives at the other job. Your job never knows the actual IP address of the other job.

Job link routing is an aspect of the service orchestration of jobs. Apcera Platform ensures that traffic goes to the correct instance of the correct job, even if jobs fail and restart or if the system moves a job to a new Instance Manager to balance loads. Your job continues to use the address that the system initially provided, and Apcera Platform ensures that the traffic goes to the correct place.

Occasionally, two jobs may need to use the same address to refer to a third job. This comes up, for example, when you are running a replicated MySQL database and need to ensure that failover works properly. Apcera Platform provides the --bound-ip and bound-port options for you to specify that address. The bound-port option is different from the --port option in that --port specifies a real port on the other job.

For example, assume that you have jobs called foo and bar and that bar provides functionality on port 1234 that you want foo to access.

Begin by exposing port 1234 on bar:

apc job update bar --port-add 1234

╭──────────────────────╮
│ Job Update Settings  │
├──────────────┬───────┤
│        Name: │ bar   │
│ Port to Add: │ 1234  │
╰──────────────┴───────╯

Is this correct? [Y/n]: y
Exposed port 1234
Applying update... done
Success!

Now you can link foo to bar:

apc job link foo --to bar --name foobar --port 1234
Stopping the job... done
Binding "job::/sandbox/john::foo" to "job::/sandbox/john::bar"... done
Starting the application... done
Waiting for the job to start...
Success!

By supplying the name foobar for the link, you determine the name of the environment variable in the foo runtime environment that contains the URI that foo uses to connect to bar:

FOOBAR_URI=tcp://169.254.0.62:10000

However, if you have more than one job that connects to bar, you can add the --bound-ip and --bound-port options to each linking command:

apc job link foo --to bar --name foobar --port 1234 --bound-ip 1.2.3.4 --bound-port 27
apc job link bas --to bar --name basbar --port 1234 --bound-ip 1.2.3.4 --bound-port 27

In this case, the system sets the environment variable to use those values:

FOOBAR_URI=tcp://1.2.3.4:27  //in the foo environment
BASBAR_URI=tcp://1.2.3.4:27  //in the bas environment