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.
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.
Using job links
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" │ ╰───────────────────────────────╯
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.
Job link security
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
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-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
bar and that
bar provides functionality on port
1234 that you want
foo to access.
Begin by exposing port
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
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
However, if you have more than one job that connects to
bar, you can add the
--bound-port options to each linking command:
apc job link foo --to bar --name foobar --port 1234 --bound-ip 18.104.22.168 --bound-port 27 apc job link bas --to bar --name basbar --port 1234 --bound-ip 22.214.171.124 --bound-port 27
In this case, the system sets the environment variable to use those values:
FOOBAR_URI=tcp://126.96.36.199:27 //in the foo environment BASBAR_URI=tcp://188.8.131.52:27 //in the bas environment