DNS Integration Guide

Integrate Wallaroo Enterprise Into an Organization’s DNS.

The following guide demonstrates how to integrate a Wallaroo Enterprise instance with an organization’s DNS. DNS services integration is required for Wallaroo Enterprise edition. It is not required for Wallaroo Community. This guide is indented to assist organizations complete their Wallaroo Enterprise installation, and can be used as a reference if changes to the DNS services are modified and updates to the Wallaroo Enterprise instance are required.

Installation Flow

A typical installation of Wallaroo Enterprise follows this flow:

  • Create Environment: Create the environment to install Wallaroo that meets the system prerequisites.
  • Install Wallaroo: Install Wallaroo into the target environment.
  • Configure DNS: Configure DNS services and the Wallaroo instance for your organization’s use.

DNS Services Integration Introduction

DNS services integration is required for Wallaroo Enterprise to provide access to the various supporting services that are part of the Wallaroo instance. These include:

  • Simplified user authentication and management.
  • Centralized services for accessing the Wallaroo Dashboard, Wallaroo SDK and Authentication.
  • Collaboration features allowing teams to work together.
  • Managed security, auditing and traceability.

This guide is not intended for Wallaroo Community, as those DNS entries are managed by Wallaroo during the installation. For more information on installing Wallaroo Community, see the Wallaroo Community Install Guides.

Once integrated, users can access the following services directly from a URL starting with the suffix domain - this is the domain name where other DNS entries are appended to. For example, if the suffix domain is sales.example.com, then the other services would be referenced by api.sales.sample.com, etc.

Note that even when accessing specific Wallaroo services directly that the user must still be authenticated through Wallaroo.

Service DNS Entry Description
Wallaroo Dashboard suffix domain Provides access to a user interface for updating workspaces, pipelines, and models. Also provides access to the integrated JupyterHub service.
JupyterHub jupyterhub Allows the use of Jupyter Notebooks and access to the Wallaroo SDK.
API api Provides access to the Wallaroo API.
Keycloak keycloak Keycloak provides user management to the Wallaroo instance.

Wallaroo DNS integration falls into one of two formats: with a prefix, or without:

  • With a Prefix: Connections to Wallaroo services are provided as https://{prefix}.service.{suffix domain}. For example, if the domain suffix is wallaroo.example.com and the prefix sales, then the URLs to access the various Wallaroo services would be:
    • sales.wallaroo.example.com
    • sales.jupyter.wallaroo.example.com
    • sales.api.wallaroo.example.com
    • sales.keycloak.wallaroo.example.com
  • Without a Prefix: Connections to Wallaroo services are provided as https://service.{suffix domain}. For example, if the domain suffix is wallaroo.example.com and there is no prefix, then the URLs to access the various Wallaroo services would be:
    • wallaroo.example.com
    • jupyter.wallaroo.example.com
    • api.wallaroo.example.com
    • keycloak.wallaroo.example.com

Prerequisites

  • Install Wallaroo Enterprise into a qualified environment. For more details, see the Wallaroo Install Guides and the Wallaroo Enterprise Install Guides.
  • Determine whether your organization will use a prefix or not as detailed above.
  • Have access to the Wallaroo Administrative Dashboard - this requires access to the Kubernetes environment that the Wallaroo instance is installed into.
  • Have access to internal corporate DNS configurations that can be updated. A subdomain for the Wallaroo instance will be created through this process.

DNS Integration Steps

  1. Retrieve the external IP address for your Wallaroo instance LoadBalancer. For example, this can be performed through the following kubectl command:

    kubectl get svc  -A
    

    Example Result:

    NAMESPACE     NAME                           TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)                                     AGE
    default       kubernetes                     ClusterIP      10.64.16.1     <none>         443/TCP                                     3d19h
    wallaroo      alertmanager                   ClusterIP      10.64.16.48    <none>         9093/TCP                                    2d22h
    wallaroo      api-lb                         LoadBalancer   10.64.30.169   34.173.211.9   80:32176/TCP,443:32332/TCP,8080:30971/TCP   2d22h
    

    In this example, the External-IP of the wallaroo LoadBalancer is 34.173.211.9. A more specific command to retrieve just the LoadBalancer address would be:

    kubectl get svc api-lb -n wallaroo -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
    
    34.173.211.9
    

    This procedure is appropriate for both clusters that are in external or internal mode.

  2. Create a CA-signed TLS certificate for your Wallaroo domain with the following settings:

    1. Certificate Authority Options:
      1. Use a public Certificate Authority such as Let’s Encrypt or Verisign. In general, you would send a Certificate Signing Request to your CA and they would respond with your certificates.
      2. Use a private Certificate Authority (CA) to provide the certificates. Your organization will have procedures for clients to verify the certificates from the private CA.
      3. Use a Wallaroo certificate and public name server. Contact our CSS team for details.
    2. Subject Domain:
      1. Set the certificate’s Subject CN to your Wallaroo domain. To use a wildcard this will either be:
        1. With a prefix:
          1. Each Subject CN will be specified as {prefix}.service.{suffix domain}. For example, if the domain suffix is wallaroo.example.com and the prefix sales, then the Subject CNs would be:
            1. sales.wallaroo.example.com
            2. sales.api.wallaroo.example.com
            3. sales.jupyter.wallaroo.example.com
            4. sales.keycloak.wallaroo.example.com
        2. Without a prefix:
          1. With Wildcards: To use wildcards, use the wildcard *.{suffix domain}. For example, if the domain suffix is wallaroo.example.com, then the Subject CNs would be:
            1. wallaroo.example.com
            2. *.wallaroo.example.com
          2. If wildcard domains are not desired, use a combination of Subject and Subject Alternative Names to set names as follows:
            1. wallaroo.example.com
            2. api.wallaroo.example.com
            3. jupyter.wallaroo.example.com
            4. keycloak.wallaroo.example.com
    3. Save your certificates.
      1. You should have two files: the TLS Certificate (.crt) and TLS private key (.key). Store these in a secure location - these will be installed into Wallaroo at a later step.
  3. Create DNS the following entries based on the list above for the Wallaroo instance’s IP address, updating the domain name depending on whether there is a prefix or not:

    1. api: A (address) record
    2. jupyter: A (address) record
    3. keycloak: A (address) record
    4. Suffix domain: A record, NS (nameserver) record, SOA (start of authority) record.

    For example, the following are DNS records without a prefix:

    Wallaroo DNS Records
  4. Access the Wallaroo Administrative Dashboard in your browser. This can be done either after installation, or through the following command (assuming your Wallaroo instance was installed into the namespace wallaroo). By default this provides the Wallaroo Administrative Dashboard through the URL https://localhost:8080.

    kubectl-kots admin-console --namespace wallaroo
    
  5. From the Wallaroo Dashboard, select Config and set the following:

    1. Networking Configuration
      1. Ingress Mode for Wallaroo Endpoints: Internal
    2. DNS
      1. DNS Prefix: Either Empty or with the prefix.
      2. DNS Suffix (Mandatory): The domain name for your Wallaroo instance.
    3. TLS Certificates
      1. Use custom TLS Certs: Checked
      2. TLS Certificate: Enter your TLS Certificate (.crt file).
      3. TLS Private Key: Enter your TLS private key (.key file).
    4. Other settings as desired.
    Wallaroo DNS Records
  6. Once complete, scroll to the bottom of the Config page and select Save config.

  7. A pop-up window will display The config for Wallaroo Enterprise has been updated.. Select Go to updated version to continue.

  8. From the Version History page, select Deploy. Once the new deployment is finished, you will be able to access your Wallaroo services via their DNS addresses.

To verify the configuration is complete, access the Wallaroo Dashboard through the suffix domain either with or without the prefix depending on your settings. For example if the suffix domain is wallaroo.example.com and the enabled prefix is sales, then access sales.wallaroo.example.com in a browser and verify the connection and certificates.

Install Wallaroo Complete

If you were setting Wallaroo Enterprise, integrating your Wallaroo instance with your DNS services was the last step.

Step Status
Setup Environment COMPLETED!
Install Wallaroo Enterprise COMPLETED!
Integrate Wallaroo with DNS Services COMPLETED!
  •