Educates
Docs (external site)Hub (external site)Educates on GitHubGet startedSite map
Educates
Get started

Lookup service and Portal REST APIDelivering

Start Sessions from your own site, on one portal or many clusters

Every training portal has a REST API, so a site of yours can list its workshops and start Sessions behind whatever sign-in you choose. The lookup service puts one API in front of many portals on one or more clusters. Your site asks it for a Session, it sends the request to a portal with room, and you add capacity by adding a cluster, not by growing the one you have.

Get startedRead the docs for Lookup service (external site)

What you can do with it

  • A training team's own site listing a training portal's workshops for the person signed in, through the portal's REST API: how many Sessions each has free, and Resume on the workshop they already have a Session for.

    Your own front end on one portal

    Each training portal comes with a robot account for its REST API. Your site logs in with it, lists the portal's workshops, asks for a Session for the person signed in, and sends their browser to the URL that comes back. Turn off the portal's own registration, as the docs recommend, so people come in through your site.

  • Two requests for a Session for the same user ID, answered with the same Session.

    People get their own Session back

    Pass your own ID for each person with every request. Someone who closes the tab and clicks again gets the Session they already have, not a second one. A portal's API also lists a person's Sessions, extends one close to expiring where the workshop allows it, and ends one early.

  • The lookup service's admin API listing the clusters it watches, and the training portals on them.

    One API in front of many clusters

    Register clusters with the lookup service, the one it runs on or remote ones, and it watches the training portals on each. A request for a Session goes to the portal with the most room, so the same workshop on several clusters shares the load, and an admin client sees every cluster, portal and Session from one place.

  • Two customers' own sites side by side, each listing the workshops of its own lookup service tenant: Acme Training shows two workshops, and Globex Academy a different one.

    A tenant for each customer

    Tenants pick clusters and portals by name or by label, and each client of the API reaches only the tenants it is granted. One lookup service can keep customers apart, or production apart from staging.

  • A request to the lookup service for a person's Session, with their name and email address, a workshop parameter, the page to return to and a webhook for its events, and the Session it got.

    Set up each Session as it starts

    With each request, pass the parameters the workshop declares, the person's name and email address, the page to send them back to when the Session ends, and a webhook to receive that Session's analytics events.

How you use it

From one training portal

Every training portal has a robot account for its REST API, with its credentials in the portal's status. Your site logs in with them for an access token:

Terminal window
curl -v -X POST -d "grant_type=password&username=robot@educates&password=<robot-password>" -u "<robot-client-id>:<robot-client-secret>" https://lab-markdown-sample-ui.test/oauth2/token/

Then it asks for a Session of a workshop environment, with the page to send the person back to when the Session ends:

Terminal window
curl -H "Authorization: Bearer <access-token>" https://lab-markdown-sample-ui.test/workshops/environment/<name>/request/?index_url=https://hub.test/

The response names the Session, gives an ID for the person, and holds the url on the portal to send their browser to. Pass that ID as user on the next request, and the person gets the Session of that workshop they already have.

From many, through the lookup service

The lookup service is off until the configuration you install Educates with turns it on:

lookupService:
  enabled: true

It then needs a cluster to watch, a tenant, and a client, as resources in the educates-config namespace. Here the cluster is the one the lookup service runs on, the tenant reaches one portal on it, and the client can request Sessions through that tenant:

apiVersion: lookup.educates.dev/v1beta1
kind: ClusterConfig
metadata:
  name: local-cluster
  namespace: educates-config
---
apiVersion: lookup.educates.dev/v1beta1
kind: TenantConfig
metadata:
  name: tenant-1
  namespace: educates-config
spec:
  clusters:
    nameSelector:
      matchNames:
        - local-cluster
  portals:
    nameSelector:
      matchNames:
        - portal-1
---
apiVersion: lookup.educates.dev/v1beta1
kind: ClientConfig
metadata:
  name: custom-portal
  namespace: educates-config
spec:
  client:
    password: my-secret
  roles:
    - tenant
  tenants:
    - tenant-1

Your site logs in as that client and asks for a Session, passing its own ID for the person:

Terminal window
ACCESS_TOKEN=$(curl --silent -X POST \
  http://educates-api.<ingress-domain>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "custom-portal", "password": "my-secret"}' \
  | jq -r -e .access_token)


curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantName": "tenant-1",
    "workshopName": "lab-k8s-fundamentals",
    "clientIndexUrl": "https://portal.example.com/",
    "clientUserId": "user-12345"
  }' \
  http://educates-api.<ingress-domain>/api/v1/workshops

The response's sessionActivationUrl is where the person's browser goes. The lookup service docs cover remote clusters, tenants chosen by label, and the admin API.

Limits

What it does not do, and what it needs from you, so you can judge it before you build on it.

Where it is used

Use cases that rely on it

Deploy it from the Hub

The Hub is a catalog of workshops you deploy on your own Educates, each with one command. These ones show this Feature at work.

Explore the Hub

Read more

Try it yourself, or talk to us

Get started runs Educates on your laptop with a first workshop in a few commands. Get help is where you ask the community, and where you can hire the people who build Educates.

Get startedGet help