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. You can optionally provide a PEM file that contains root certificate authorities that service gateways and semantic pipelines use when verifying server certificates.

Below is the syntax for registering a provider:

apc provider register <provider name> --type TYPE --url URL \
[--cacert <path-to-cert-file>]  \
[--description 'Provider description...']

Where:

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

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

  • --cacert <path/to/certfile.pem> is the path to a PEM file that contains root certificate authorities used to validate a certificate from an external provider ( an external MySQL database, for example). See Adding root certificates to a provider.

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

The following example uses the Postgres service gateway to register an external Postgres provider with the system. A PEM file is provided that contains root certificate authorities the service gateway uses to authenticate with the Postgres server.

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

Adding root certificates to a provider

When registering an external provider (for example, an external MySQL server) you can optionally upload a PEM file containing root certificate authorities for that provider. Service gateways and semantic pipelines use the root certificate to validate the provider's certificate when making a secure connection with the provider. This is required if you want to bind a job to the external provider and have that connection brokered by a semantic pipeline. The generic service gateway also provides a way to register external providers, but it does not provide root certificate validation or a semantic pipeline.

Note: Currently, only the MySQL and Postgres service gateways and semantic pipeline support root certificate validation.

The apc register provider command takes a --cacerts parameter whose value is path to a PEM file containing the root certificate authorities. For example, the following command creates a new provider (external-postgres) for an external Postgres database and uploads a root certificate (certs/cacert.pem):

apc provider register external-postgres --type postgres \
--url postgres://user:password@pg.example.com:5432 \
--rootcerts ~/certs/cacert.pem
╭───────────────────────────────────────────────────────────────╮
│                Provider Registration Settings                 │
├────────────────┬──────────────────────────────────────────────┤
│ Provider Name: │ external-postgres                            │
│  Service Type: │ postgres                                     │
│           URL: │ postgres://user:password@pg.example.com:5432 │
╰────────────────┴──────────────────────────────────────────────╯

Is this correct? [Y/n]:
Registering provider "external-postgres"... done
Success!

When registering a provider in the Web Console the Add a Provider form includes a Choose PEM File button that opens a file browser for you to select a root certificate:

PEM Upload

The output of the apc provider show command displays the root certificate's common name (CN), serial number, and expiration date.

apc provider show external-postgres
╭────────────────────┬──────────────────────────────────────────────────────────────╮
│ Service:           │ external-postgres                                            │
├────────────────────┼──────────────────────────────────────────────────────────────┤
│ FQN:               │ provider::/sandbox/admin::external-postgres                  │
│ UUID:              │ d268e829-c747-4115-8d7c-02d5357dfd7d                         │
│ Type:              │ postgres                                                     │
│ Completion Status: │ created                                                      │
│ Created by:        │ admin@apcera.me                                              │
│ Created at:        │ 2017-01-12 21:07:53.165736074 +0000 UTC                      │
│                    │                                                              │
│ Root Certificates: │ sgtest-cert; afe0fc76d9ec6d7a; 2027-01-02 17:31:59 +0000 UTC │
╰────────────────────┴──────────────────────────────────────────────────────────────╯

The root certificate details are also displayed in the Web Console on the provider's details page.

You create services on the provider and bind jobs to those services, as usual. The root certificate you provided when creating the provider is used by the service gateway to authenticate when creating the service and bindings.

apc service create todos_db --provider external-postgres
apc service bind todos_db --job=demo-node-todo

By default, service bindings inherit the root certificates associated with the provider that you used to create the corresponding service. You can also override the provider's root certificate when creating the service binding (see Creating service bindings):

apc service bind todos_db --job=demo-node-todo --cacert my-cert.pem

You can also update the root certificate directly on the semantic pipeline job created by the service binding (if the service type provides a semantic pipeline).

apc job update demo-node-todo/postgres/cbc5d271 --cacert new-cert.pem

See Connecting to an existing MySQL database using the MySQL service gateway for an example of registering an external MySQL provider with a root certificate.

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.