Registering Providers

Apcera lets you easily integrate external systems by registering them as providers and creating services that apps and jobs can bind to and consume. Apcera maintains a registry of service providers for your cluster. Out-of-the-box Apcera offers a number of service gateways to connect jobs to common third-party providers, including Postgres, MySQL, Redis, NFS, memcache, and more.

Provider registration overview

Often a service is made available by a provider. A provider consists of a resource and an endpoint (for example, the Postgres DB server on the Ubuntu machine called gandalf).

Providers typically supply services like accounts on multi-tenant database servers or software-as-a-service (SaaS) applications. Providers let users provision services on demand. A provider is associated with a service type. The corresponding service gateway knows that it can call on that provider when a job needs a service of that type to bind to.

You can register a provider for any type of service that is supported by a service gateway. Apcera clusters include providers for development purposes for MySQL, Postgres, and NFS. (Apcera Platform trial images include Postgres.)

For production clusters, your organization's IT administrators should identify production providers and register them with the system. If a custom service gateway is required, you can use the Service Gateway API to create one.

Provider requirements

In general Apcera does not require custom configurations to create connections to service providers. And, Apcera may support specific parameters for each provider. Refer to list of supported service types for more information.

Registering external providers

You use the apc provider register command to register an external endpoint or system as a provider. Once registered, the provider shows up in the list of providers and can be used to create a service to bind to a job.

Here is the syntax for registering a provider:

apc provider register <provider name> --type TYPE --url URL [--description]

Where:

  • Parameter --type <service type> is an index to the service gateways (for example, postgres).

  • Parameter --url <URL> is the provider connection string, including credentials (for example, postgres://admin:password@example.com:5432).

  • Parameter --description <phrase> is an optional short phrase that describes the provider purpose or service (for example, catalog database).

The following example registers an external Postgres provider with the system:

apc provider register postgres --type postgres --url postgres://apcera:password@example.com:5432/template1 --description 'PostgreSQL (RDS-backed)'

Registering internal providers

In addition to registering external providers with the system for service consumption, you can also register internal providers. An internal provider is a user-defined app or job deployed in the cluster that you promote to provider status.

The options for promoting a job to an internal provider are similar to those for registering an external provider. To promote a job to a provider, you use the same apc provider register command, but in this case, because you are promoting a job to a provider, the --job argument is required. Apcera automatically modifies the hostname portion of the URL (so you can put anything you like there), but leaves the rest of the URL intact.

Here is the job promotion syntax:

apc provider register <provider name> --job <job name> --type TYPE --url URL [--description]

Where:

  • Parameter --job NAME is the name of the job to promote to a provider. (You can find out the name of the job using apc job list.)

  • Parameter --type <service type> is an index to the service gateways(for example, mysql).

  • Parameter --url <URL> is a connection string, including credentials (for example, mysql://root:password@mysql-server).

  • Parameter --description <phrase> is a short phrase that describes the provider (for example, MySQL DB)

The following example promotes a job to a MySQL provider:

apc provider register mysql-provider --job mysql-app --type mysql --url mysql://root:password@mysql-app --description 'MySQL DB'

For production clusters where provider persistence and high-availability is required, in general you should use external providers for your services. By default jobs have ephemeral file system storage and state is not explicitly preserved if the job is restarted. For many service types you can back the provider with an NFS service for persistence.

Creating services for providers

The following example demonstrates how to create and bind a job to a service that uses a PostgreSQL DB provider:

apc service create cust-db --provider /dev::postgres --job cust-job 

Apcera establishes the binding and sets up a PostgreSQL semantic pipeline between the job and the external service. The job finds the URI of the semantic pipeline in its environment variable named POSTGRES_URI and uses it exactly as if it went directly to the PostgreSQL database.

See Configuring Services for additional guidance.

Managing providers

Use the following commands to manage providers in the system:

  • Command apc provider list lists providers in the current namespace; use the --namespace / flag to view system providers.

  • Command apc provider show <provider name> displays the named provider's FQN, type, and backing job.

  • Command apc provider delete <provider name> deletes the named provider.

The above commands assume you have the necessary policy permissions.