Custom Resources

The lookup service uses three custom resource definitions (CRDs) for its configuration. All three belong to the lookup.educates.dev API group with version v1beta1, and all are namespaced resources that should be created in the educates-config namespace.

ClusterConfig

A ClusterConfig resource registers a Kubernetes cluster for monitoring by the lookup service. The lookup service will watch the cluster for training portals, workshop environments, and workshop sessions.

apiVersion: lookup.educates.dev/v1beta1
kind: ClusterConfig
metadata:
  name: local-cluster
  namespace: educates-config

When no spec.credentials section is provided, the lookup service will monitor the local cluster where it is deployed, using the service account credentials available to the lookup service pod. A local cluster can still include spec.labels for use with tenant label selectors:

apiVersion: lookup.educates.dev/v1beta1
kind: ClusterConfig
metadata:
  name: local-cluster
  namespace: educates-config
spec:
  labels:
    - name: environment
      value: production

For remote clusters, the spec.credentials section provides the kubeconfig needed to access the remote cluster:

apiVersion: lookup.educates.dev/v1beta1
kind: ClusterConfig
metadata:
  name: remote-cluster-1
  namespace: educates-config
spec:
  credentials:
    kubeconfig:
      secretRef:
        name: kubeconfig-cluster-1
  labels:
    - name: customer
      value: customer-1
    - name: environment
      value: production

The full set of fields in the spec is:

  • spec.labels - An optional list of label objects for categorizing the cluster. Each label has a name field (required) and a value field (optional). These labels are used by tenant configurations to select which clusters are accessible through a given tenant.

  • spec.credentials.kubeconfig.secretRef.name - The name of a Kubernetes secret in the educates-config namespace containing the kubeconfig for accessing the remote cluster. Required for remote clusters.

  • spec.credentials.kubeconfig.secretRef.key - The key within the secret that contains the kubeconfig data. Defaults to config if not specified.

  • spec.credentials.kubeconfig.context - The name of the context to use from the kubeconfig file. If not specified, the current context in the kubeconfig will be used.

TenantConfig

A TenantConfig resource defines a logical tenant and the rules for determining which clusters and training portals are accessible through that tenant.

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

The spec section contains two optional top-level fields, clusters and portals, each of which can use name-based or label-based selectors to determine which resources are included in the tenant.

Cluster selectors:

  • spec.clusters.nameSelector.matchNames - A list of cluster names to include. Names can contain wildcard patterns (e.g., cluster-*).

  • spec.clusters.labelSelector.matchLabels - A map of key-value pairs. A cluster must have all specified labels to match.

  • spec.clusters.labelSelector.matchExpressions - A list of label match expressions for more advanced selection. Each expression has a key, an operator (one of In, NotIn, Exists, DoesNotExist), and for the In and NotIn operators, a values list.

Portal selectors:

  • spec.portals.nameSelector.matchNames - A list of portal names to include. Names can contain wildcard patterns.

  • spec.portals.labelSelector.matchLabels - A map of key-value pairs. A portal must have all specified labels to match.

  • spec.portals.labelSelector.matchExpressions - A list of label match expressions with the same structure as for cluster selectors.

If neither clusters nor portals is specified, the tenant will have no access to any resources. If clusters is specified but portals is not, all portals on the matched clusters will be accessible. If portals is specified but clusters is not, the portal selector will apply across all clusters.

The following example uses label selectors to match clusters and portals for a production environment:

apiVersion: lookup.educates.dev/v1beta1
kind: TenantConfig
metadata:
  name: customer-1-production
  namespace: educates-config
spec:
  clusters:
    labelSelector:
      matchLabels:
        customer: customer-1
  portals:
    labelSelector:
      matchLabels:
        environment: production

Note that the labels used by the lookup service for matching are Educates-specific labels defined in the spec of the custom resources, not standard Kubernetes metadata labels. For training portals, labels are defined in the spec.portal.labels section of the TrainingPortal resource and can be set when creating a portal using the -l flag with the Educates CLI:

educates create-portal -p portal-1 -l environment=production

ClientConfig

A ClientConfig resource defines a client that can authenticate against the lookup service REST API.

apiVersion: lookup.educates.dev/v1beta1
kind: ClientConfig
metadata:
  name: custom-portal
  namespace: educates-config
spec:
  client:
    password: my-secret
  roles:
    - tenant
  tenants:
    - tenant-1

The full set of fields in the spec is:

  • spec.client.password - The password for the client. Must be at least 8 characters. This is used together with the resource name (metadata.name) as the username when authenticating via the REST API.

  • spec.roles - A list of roles assigned to the client. At least one role must be specified. Supported roles are admin and tenant.

  • spec.tenants - A list of tenant names the client is permitted to access. For clients with the tenant role, this restricts which tenants they can query workshops for and request sessions against. Wildcard patterns are supported (e.g., customer-*). For clients with the admin role, this can be set to ["*"] to grant access to all tenants.

  • spec.user - An optional user identifier to associate with the client.

An admin client typically uses a wildcard for tenant access:

apiVersion: lookup.educates.dev/v1beta1
kind: ClientConfig
metadata:
  name: admin
  namespace: educates-config
spec:
  client:
    password: super-secret
  roles:
    - admin
  tenants:
    - "*"

Managing resources

All configuration resources are created in the educates-config namespace. If this namespace does not already exist, create it before applying any configuration:

kubectl create ns educates-config

Resources can then be created, updated, and deleted using standard kubectl commands:

kubectl apply -f cluster-config.yaml
kubectl apply -f tenant-config.yaml
kubectl apply -f client-config.yaml

To list the current configuration resources:

kubectl get clusterconfigs -n educates-config
kubectl get tenantconfigs -n educates-config
kubectl get clientconfigs -n educates-config

Changes to configuration resources are picked up by the lookup service automatically. You can monitor the lookup service logs to verify that configuration changes are being processed:

kubectl logs -n educates --follow deployment/lookup-service