Configuring Services

This section provides the APC syntax and examples for creating and consuming various types of services, including:

Creating services

To create a service you use the following command:

apc service create <service-name> [options]

The command options are as follows:

Type Description
--provider <name> Provider of the service
--name <name> Name of the binding; if job is specified, this is generated automatically
--description <desc> Description of the service
--job <name> Job to bind to the service (optional)
--type <type> Service type (optional, if the provider is specified)

You must specify a provider if the type uses a provider; otherwise specify a service type.

Consuming services

To consume a service, you must bind a job to it. Some services already exist in Apcera, so you can bind to them directly. In many cases, however, you must first create a service. For example, if you wish to connect to a PostgreSQL database server, you create a service, specifying a provider registered to provide services of type postgres.

Creating service bindings

Jobs connect to services through information stored in the bindings on the job. These bindings include a URI with the host and port of the service when the service is running outside Apcera, and the UUID and port of the job when the service is running inside Apcera.

To bind a job to a service, you use the following command:

apc service bind [options]

The command options are as follows:

Type Description
--job <name> Job to bind to the service
--name <name> Name of the binding

If you don't specify a job, Apcera creates the service but doesn't bind a job to it. If you specify a job but not a binding name, Apcera creates a name in the form of bind_<service>_<job>.

When you create a service binding, Apcera adds environment variables to the job's container that include the URIs for the service name and service binding name. These URIs have the following form:

  • <service-type>_URI
  • <binding-name>_URI
  • <service-name>_URI

Ignore (do not use) the first URI (<service-type>_URI) if the job is bound to multiple services of the same type.

To connect different apps to the same service, bind each app separately to the service using the apc service bind command.

JDBC-specific Binding URIs

When you create a service binding with a supported JDBC-compliant database, Apcera adds environment variables that contain JDBC-specific connection URIs in the form of jdbc:mysql://<host>:<port>/<dbname>?user=<username>&password=<password>. These are in addition to the the standard environment variables that contain to the native connection string format. This feature is currently supported for MySQL and Postgres services.

For instance, suppose you create a binding between a job and a MySQL service, as shown below:

$ apc service bind mysql-service -j jdbc-mysql

This would add the following binding environment variables to the job's environment:

  • JDBC_MYSQL_URI
  • MYSQLSERVICE_URI
  • MYSQL_URI

The MYSQL_URI environment variable contains the native MySQL connection string, for example:

MYSQL_URI=mysql://3n18JwITkvIVYJCb:ZJiOj9BrvZZd00Mx@tc9y5bhkk181k5.ckzmdzmswebf.us-west-2.rds.amazonaws.com:3306/6d846be9233b49b5916babcfc817dea4

And the JDBC_MYSQL_URI environment variable contains the JDBC-specific connection string, for example:

JDBC_MYSQL_URI=jdbc:mysql://tc9y5bhkk181k5.ckzmdzmswebf.us-west-2.rds.amazonaws.com:3306/6d846be9233b49b5916babcfc817dea4?user=3n18JwITkvIVYJCb&password=ZJiOj9BrvZZd00Mx&useSSL=true

Your Java application can use the value of JDBC_MYSQL_URI directly as the JDBC connection string, rather than having to parse the MYSQL_URI environment variable into the right format, for example:

import java.sql.*;
public class JdbcMysql
{
  private static final String dbClassName = "com.mysql.jdbc.Driver";
  private static final String CONNECTION = System.getenv("JDBC_MYSQL_URI");
  public static void main(String[] args) throws
                                        ClassNotFoundException,SQLException
  {
    Class.forName(dbClassName);
    Connection c = null;
    try {
        c = DriverManager.getConnection(CONNECTION);
    }
    catch (Exception e) {
        System.out.println(e);
        e.printStackTrace();
        System.exit(1);
    }
    finally {
        c.close();
    }
    System.out.println("MySQL Connection Successful!");
  }
}

Unbinding jobs from services

To unbind a job from a service, use the following command:

apc service unbind <service> --job <name>

This command deletes the binding between the job and the service. If more than one binding exists between the job and the service, use --name <binding name> to specify which binding to delete.

If necessary you can force the unbinding of a service from a job using the following command:

apc service unbind <service> -j <job> --force

Removing services gracefully

If a job is bound to a service, you cannot delete the service. To completely remove a service, follow this procedure to do so gracefully:

  1. Unbind the service from the job:

     apc service unbind --job <name>
    

    Use --force, if necessary:

     apc service unbind <service> -j <job> --force
    
  2. Delete the service:

     apc service delete <service>
    

    Use --force, if necessary:

     apc service delete <service> --force
    

    Using the --force option may be necessary if the service has become orphaned by a non-existing provider. You should try the standard service delete method first before using the --force option.

  3. Optionally, if the job and/or provider are no longer needed, you can fully clean up your state using the following commands:

     apc job delete <job>
     apc provider delete <provider>
    

Managing services

Use the following commands to manage services in the cluster.

apc service list

List the services in the current namespace:

apc service list

List the services in the root namespace:

apc service list -ns /

Use the -l option to produce a list of fully qualified names (FQNs) of services:

apc service list -l Or apc service list -ns / -l

apc service show

Display information (for example FQN, type, provider, and jobs bound to it) about a specific service:

apc service <service name> show

Beginning with version 0.19.5 of the APC client, you can query the Apcera cluster for definitions of existing Network services using the apc show service comand.

The following example demonstrates this, including service creation and network definitions after creation:

apc service create gabe-test --type network –- --ipnet 184.168.61.190/32 --protocol tcp --portrange 443
╭──────────────────────────────────────────────────────────────╮
│ Service Creation Settings                                    │
├───────────────┬──────────────────────────────────────────────┤
│ Service:      │ service::/apcera/service-gateways::gabe-test │
│ Service Type: │ network                                      │
╰───────────────┴──────────────────────────────────────────────╯

Is this correct? [Y/n]: Y
Creating service... done
Success!

Run apc service show to see the network details:

apc service show gabe-test
╭─────────────┬──────────────────────────────────────────────╮
│ Service:    │ gabe-test                                    │
├─────────────┼──────────────────────────────────────────────┤
│ FQN:        │ service::/apcera/service-gateways::gabe-test │
│ Type:       │ network                                      │
│ ipnet:      │ 184.168.61.190/32                            │
│ portrange:  │ 443                                          │
│ protocol:   │ tcp                                          │
│             │                                              │
│ Created by: │ hyang@apcera.com                             │
│ Created at: │ 2015-09-10 21:23:38.084201271 +0000 UTC      │
╰─────────────┴──────────────────────────────────────────────╯

apc service delete

Delete a service from the cluster:

apc service delete <service name>

Force removal of a named service from the cluster when the provider is no longer available.

apc service delete <service> --force

See also Removing services gracefully.

Managing service gateways

You use the apc gateway <command> [options] command to perform operations specific to service gateways, such as promoting an application to service gateway, listing service gateways, and starting or stopping service gateways. View all of the options using apc help gateway. See also the service examples that follow.

To view the list of available service types (that is, service gateways) on your cluster, use the apc gateway list -ns / command. See Supported Service Types for a full list of service gateways supplied by Apcera. You can also create your own service gateways using the Service Gateway API.

Managing service providers

Use the command apc provider <command> [options] to perform operations on providers such as registering a provider, promoting a provider, listing all providers, and deleting a provider.

See Working with Providers for guidance.