Constellation Distributed Serving

This feature (and its associated documentation) is currently in beta and requires a separate license and fee. To learn more and to get set up using Constellation with your Algorithmia installation, please contact your customer success manager.

This feature is only available in Algorithmia Enterprise installations.

Table of Contents

• Table of Contents
• Overview
• Satellite configuration
  • Creating a satellite deployment
    • Adding algorithms to a satellite
  • Configuring a satellite deployment
    • Editing a satellite’s algorithms
    • Creating a new launch instance
  • Editing a launch instance
  • Removing a launch instance
• Satellite deployment
• Kubernetes configuration
• FAQ

Overview

Our Constellation Distributed Serving feature provides a flexible deployment option in which an Algorithmia “mothership” development cluster has “satellite” production runtime environments, thereby decoupling the Algorithmia development experience from runtime execution.

This architecture provides for the ability to develop algorithms in a centralized location and then distribute the runtime, unlocking additional workload possibilities relative to a standard Algorithmia installation. With Constellation, you can do the following:

• Deploy and execute algorithms behind a firewall to support high-security workloads.
• Execute algorithms in close geographic proximity to your data to adhere to data regulatory compliance standards and to support low-latency SLAs.
• Meet robust disaster recovery, high-availability, and business continuity requirements.
• Create Development-to-Production algorithm promotion workflows to ensure that algorithms are tested thoroughly before supporting production workloads.
• Execute algorithms on the edge, where and when you need them.
• Execute algorithms periodically and in batch for workloads that don’t require an entire standard Algorithmia cluster or that are only run infrequently on demand.
• Increase operational efficiency and reduce overhead by leveraging existing infrastructure (e.g., Kubernetes).

Satellite configuration

The Constellation page in the admin panel provides functionality for selecting algorithms from which to create a satellite cluster.

Creating a satellite deployment

On the Constellation page you’ll see a list of existing satellites.

To configure a new satellite of algorithms, click on the New satellite button. In the modal, provide a Satellite name.

Adding algorithms to a satellite

Next, you can add algorithms by clicking the Add an algorithm button, and another modal will pop up for adding your algorithm information.

Note that you’ll need to have an Admin API key configured in your account in order to add algorithms.

In the Algorithm field you’ll provide the name of the account or organization that owns the algorithm, the name of the algorithm, and the algorithm version hash (SHA-1), in the format ALGO_OWNER/ALGO_NAME/ALGO_VERSION_HASH.

In the Algorithm vanity URL field, supply a unique URL to associate with your algorithm; this enables you to specify a concise endpoint at which the algorithm can be called. For example, if you specify a vanity URL of foo/bar, the algorithm will be callable at https://CLUSTER_DOMAIN/v1/algo/foo/bar.

In the Replica count field, configure the number of algorithm replicas for the satellite.

Click Add algorithm and you’ll see the algorithm added to the Algorithms section.

Once you’ve filled out the Satellite name and added the algorithms that’ll be connected to the satellite, click Create satellite. You’ll be sent back to the Constellation admin page, where your newly created satellite should now be visible.

Configuring a satellite deployment

Click on the name of an existing satellite from the Constellation admin page. On the satellite details page, you’ll have the ability to edit the algorithms in the satellite, create a new launch instance, and remove a launch instance.

Editing a satellite’s algorithms

To edit the list of algorithms associated with an existing satellite, click on the gear icon at the upper-right corner of the screen or click on the Algorithms tab and then the Edit algorithms button.

A form titled Edit satellite will open. The satellite’s current algorithms will be listed. You can remove existing algorithms from the satellite using the X button to the right of an algorithm. You can add algorithms by clicking the Add an algorithm button and a new window will pop up for you to specify which algorithm you’d like to add. The fields to fill out are identical to those described in the Adding algorithms to a satellite section above.

Click the Save changes button, and your satellite will be updated. Back in the satellite details page, you’ll be able to view the new algorithms under the Algorithms tab.

Note that editing algorithms for a satellite will increment the latest satellite version.

Creating a new launch instance

To create a new launch instance, click on the New launch instance button. Select the Satellite version for your new launch instance, and provide an Instance name and Description. Click Create launch instance and you should see your new launch instance under the Launch instances tab.

Editing a launch instance

Click on the name of the launch instance you’d like to edit, and a sidesheet will open with details about your launch instance. You can also use the search functionality to find your launch instance.

Click Edit Launch Instance and a window will pop up that’ll allow you to edit the Satellite version, Instance name, and Description. Click Save changes and you’ll return to the satellite details page.

Note that updating launch instance configuration details won’t automatically update any deployed instances. To do this, you’ll need to re-launch those instances with the new configuration. The command to do this is provided in the upper-right corner of the sidesheet, and its usage is demonstrated in the Satellite deployment section below.

Removing a launch instance

To remove a launch instance, click on the instance name you’d like to remove. You can also use the search functionality to find the specific launch instance.

A sidesheet will open with details about your launch instance. Click the Remove launch instance button and a window will pop up that’ll confirm your action to remove the launch instance. Click the Remove launch instance button and you’ll return to the satellite details page.

Note that removing a launch instance will not delete the launched instance; it’ll only remove the configuration from the satellite’s launch instance list.

Satellite deployment

Once a satellite has been configured in the mothership UI as indicated above, it must be deployed to a Kubernetes cluster. See Configuring Azure Kubernetes Service (AKS) or Configuring Amazon Elastic Kubernetes Service (EKS) for provider-specific Kubernetes configuration details. To summarize, the following are required:

• A target Kubernetes cluster, where you must:
  • Be running Kubernetes 1.18.x
  • Have an IngressController created
  • Use Calico network policies, or ensure all inter-pod traffic is enabled
  • Provision adequate pod space to run all pods for the satellite (5 pods for the system + N pods for your algorithms based on the number of replicas)
  • Enable application ingress for the environment as described below
• A target kubernetes namespace within that cluster, in which objects will be created; this references below as NAMESPACE
• A kubeconfig file that can be used to access and create resources within that cluster; see Connecting to an AKS cluster for instructions on how to obtain this using the Azure CLI
• A private docker container registry (and login credentials) to which images needed for the satellite can be pushed during installation, and from which images will be pulled during cluster operation

Once the above configuration is in place, you must launch a codex-install container (version >= 1.10.4).

• Note that whenstarting this container you must also bind-mount the Docker socket from the host with -v /var/run/docker.sock:/var/run/docker.sock

• Perform a docker login to ensure that images can be pulled from Docker Hub

• Images will be pulled from the registry where system images are stored

• Perform a docker login CONTAINER_REGISTRY_NAME to ensure images can be pushed to the needed container registry

Then perform the following:

• Identify the Satellite ID and Launch ID you want to deploy using the Constellation admin page. Click on the name of an existing satellite; the values are displayed as in the screenshot below.

• Using the ID values from above, run the command below. This will download artifacts like Docker images and a plan file that’ll be needed later, and store them in the directory /home/algo/deployment/current/satellite/SATELLITE_ID/LAUNCH_ID. These files can be quite large, so the download process may take some time. Note that you’ll need to run this and subsequent commands from a machine that has network access to the target Kubernetes cluster, so you may need to copy these files onto a machine that has such network access.

$ algo-install satellite SATELLITE_ID LAUNCH_ID get ADMIN_API_KEY

• Next, you’ll need to configure the following variables, which are specific to your deployment target:
  • The destination container registry where images should be pushed; note that you should also perform a docker login to this registry

$ algo-install satellite SATELLITE_ID LAUNCH_ID \
    configure stage.container_registry=<some.customer.foo:1234/registry>

• • Path to the kubeconfig file that has permission to create and read resources from the destination cluster:

$ algo-install satellite SATELLITE_ID LAUNCH_ID \
    configure .stage.kubernetes.kubeconfig_path=/home/algo/cust8s.conf

• • The namespace into which to deploy:

$ algo-install satellite SATELLITE_ID LAUNCH_ID \
    configure .stage.kubernetes.namespace=NAMESPACE_NAME

• • The fully qualified domain name of the mothership cluster

$ algo-install satellite SATELLITE_ID LAUNCH_ID \
    configure .stage.fqdn=<foo.customer.com>

• Finally, launch the satellite!

$ algo-install satellite SATELLITE_ID LAUNCH_ID deploy

At this point, Kubernetes resources should be created, but you may need to configure the Kubernetes ingress based on the requirements of your Kubernetes cluster, cloud provider, or IngressController.

Kubernetes configuration

For detailed guides on how to configure Kubernetes with appropriate network access for use with Constellation Distributed Serving, please see the respective pages for Azure Kubernetes Service (AKS) and Amazon Elastic Kubernetes Service (EKS).

FAQ

Q: Can I use different cloud platforms for the mothership cluster and the satellite clusters? For example, can I create a satellite in my mothership Algorithmia cluster that’s deployed on AWS infrastructure and then deploy that satellite into an AKS environment?

A: Yes. There’s no tie between mothership and satellite, and there’s nothing cloud provider-specific about satellites at this point in time.

****

Q: Where are the logs written from my satellite cluster?

A: It’s up to you to configure your Kubernetes cluster with a log-forwarding agent if desired. Our applications log to stdout.