Tutorials

• 1: Create a Datum Gateway (Reverse Proxy)
• 2: Create a Datum Workload backed by Google Cloud

1 - Create a Datum Gateway (Reverse Proxy)

Before you begin

This tutorial assumes you have already:

• Registered a Datum account
• Installed and configured the necessary tools
• Created a Datum project

Understanding Datum Gateways

A Datum Gateway acts as a reverse proxy that manages incoming traffic to your services. It’s built on top of the Kubernetes Gateway API specification and provides a way to:

• Route traffic to different services based on hostnames and paths
• Load balance requests across multiple backend services
• Apply TLS termination
• Monitor traffic flow

This tutorial will create a Datum Gateway that will use example.com as the origin service.

Creating a Basic Gateway

Let’s start by creating a simple Gateway that will listen for HTTP traffic on port 80. Here’s a basic Gateway configuration:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  gatewayClassName: datum-external-global-proxy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same

Apply this configuration using kubectl:

kubectl apply -f gateway.yaml

Verify the Gateway was created:

kubectl get gateway

Configuring Endpoints

Endpoints in Datum Gateway are defined using EndpointSlice resources, which provide a more efficient way to manage service endpoints. Here’s an example of how to define endpoints for your gateway:

apiVersion: discovery.k8s.io/v1
kind: EndpointSlice
metadata:
  name: my-endpoint
addressType: IPv4
endpoints:
- addresses:
  - 23.192.228.80
  conditions:
    ready: true
    serving: true
- addresses:
  - 23.192.228.84
  conditions:
    ready: true
    serving: true
ports:
- name: https
  appProtocol: https
  port: 443

This EndpointSlice configuration:

• Defines a set of endpoints for a service named “my-endpoint”
• Specifies the endpoint by 2x IPv4 addresses
• Includes port configuration for HTTP traffic
• Includes readiness conditions for the endpoint

Apply the endpoints:

kubectl apply -f endpoints.yaml

Creating Routes

Routes define how traffic should be directed to your services. Let’s create a simple HTTPRoute that directs traffic to a backend service:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
spec:
  parentRefs:
    - name: my-gateway
      kind: Gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - group: discovery.k8s.io
          kind: EndpointSlice
          name: my-endpoint
          port: 443
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: "example.com"

This route configuration:

• Attaches to our previously created gateway
• Routes all requests with path prefix “/” with a hostname rewrite to “example.com”.

Apply the route:

kubectl apply -f route.yaml

Verifying the Setup

Check the status of your gateway components:

# Check Gateway status
kubectl get gateway -o wide

Note: This output will provide the address to be used with cURL, below.

Check EndpointSlices

# Check Endpoint status
kubectl get endpointslices

Check Routes

# Check Route status
kubectl get httproute

Check the Service using cURL

# Use cURL to test the gateway
curl -sv http://$ADDRESS (ending in `datum-dns.net from above step`)

Alternatively, copy/paste $ADDRESS into a browser to view example.com via a Datum gateway.

Next Steps

• Understand how to use Datum’s observability tools via Telemetry Exporters.

Troubleshooting

Common issues and their solutions:

1. Gateway not accepting traffic:

   • Verify the Gateway is in the “Ready” state
   • Check that the gatewayClassName is properly configured to be datum-external-global-proxy.
   • Ensure the listeners are correctly defined

2. Endpoints not receiving traffic:

   • Ensure the EndpointSlice addresses are correct
   • Verify the ports are correctly configured
   • Check that the endpoints are marked as ready

2 - Create a Datum Workload backed by Google Cloud

Before you begin

This tutorial assumes you have already:

• Registered a Datum account
• Installed and configured the necessary tools
• Created a Datum project
• Install and access to the Google Cloud CLI
• Enabling an API in your Google Cloud project
• Enable Identity and Access Management (IAM) API in your Google Cloud project
• Enable Compute Engine API in your Google Cloud project

Discover Available Datum Cloud Projects

Use kubectl get projects to list your Datum Cloud Projects. Select a DATUM_PROJECT_NAME to be used in this tutorial.

Discover Available Google Cloud Projects

Ensure your gcloud CLI has authenticated to Google Cloud.

Use gcloud list projects to obtain a list of GCP_PROJECT_IDs. Select the GCP_PROJECT_ID to be used with this tutorial.

Grant Datum Cloud access to your GCP Project

Datum requires the following roles to be granted to a Datum managed service account which is specific to each Datum project:

• roles/compute.admin
• roles/secretmanager.admin
• roles/iam.serviceAccountAdmin
• roles/iam.serviceAccountUser

The service account email will be in the following format:

DATUM_PROJECT_NAME@datum-cloud-project.iam.gserviceaccount.com

Use the gcloud tool to grant IAM Roles to your Datum service account, replacing GCP_PROJECT_ID and DATUM_PROJECT_NAME with their respective values:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
  --member="serviceAccount:DATUM_PROJECT_NAME@datum-cloud-project.iam.gserviceaccount.com" \
  --role="roles/compute.admin"

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
  --member="serviceAccount:DATUM_PROJECT_NAME@datum-cloud-project.iam.gserviceaccount.com" \
  --role="roles/secretmanager.admin"

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
  --member="serviceAccount:DATUM_PROJECT_NAME@datum-cloud-project.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountAdmin"

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
  --member="serviceAccount:DATUM_PROJECT_NAME@datum-cloud-project.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

For guidance on granting roles via Google’s Console, see Manage access to projects, folders, and organizations.

Register a Datum Managed Location

Before creating a workload, a Location must be registered.

Use the following example manifest to create a location which Datum’s control plane will be responsible for managing, replacing GCP_PROJECT_ID with your GCP project id:

apiVersion: networking.datumapis.com/v1alpha
kind: Location
metadata:
  name: my-gcp-us-south1-a
spec:
  locationClassName: datum-managed
  topology:
    topology.datum.net/city-code: DFW
  provider:
    gcp:
      projectId: GCP_PROJECT_ID
      region: us-south1
      zone: us-south1-a

1. Replace topology.datum.net/city-code’s value (DFW) with the desired city code for your workloads.
2. Update the gcp provider settings to reflect your GCP project ID, desired region, and zone.

Apply the manifest:

kubectl apply -f <path-to-location-manifest>

List Locations:

kubectl get locations

NAME                 AGE
my-gcp-us-south1-a   5s

Create a Network

Before creating a workload, a Network must be created. You can use the following manifest to do this:

apiVersion: networking.datumapis.com/v1alpha
kind: Network
metadata:
  name: default
spec:
  ipam:
    mode: Auto

Apply the manifest:

kubectl apply -f <path-to-network-manifest>

List Networks:

kubectl get networks

NAME      AGE
default   5s

Create a Workload

Create a manifest for a sandbox based workload, for example:

apiVersion: compute.datumapis.com/v1alpha
kind: Workload
metadata:
  name: my-container-workload
spec:
  template:
    spec:
      runtime:
        resources:
          instanceType: datumcloud/d1-standard-2
        sandbox:
          containers:
            - name: httpbin
              image: mccutchen/go-httpbin
              ports:
                - name: http
                  port: 8080
      networkInterfaces:
        - network:
            name: default
          networkPolicy:
            ingress:
              - ports:
                - port: 8080
                from:
                  - ipBlock:
                      cidr: 0.0.0.0/0
  placements:
    - name: us
      cityCodes: ['DFW']
      scaleSettings:
        minReplicas: 1

Apply the manifest:

kubectl apply -f <path-to-workload-manifest>

Check the state of the workload

kubectl get workloads

The output is similar to:

NAME                    AGE   AVAILABLE   REASON
my-container-workload   9s    False       NoAvailablePlacements

The REASON field will be updated as the system progresses with attempting to satisfy the workload’s intent.

Check Workload Deployments

A Workload will result in one or more WorkloadDeployments being created, one for each unique CityCode per placement.

kubectl get workloaddeployments

The output is similar to:

NAME                           AGE   LOCATION NAMESPCE   LOCATION NAME        AVAILABLE   REASON
my-container-workload-us-dfw   58s   default             my-gcp-us-south1-a   False       LocationAssigned

Similar to workloads, the REASON field will be updated as the system progresses with attempting to satisfy the workload’s intent. In this case, the infra-provider-gcp operator is responsible for these actions.

Check Instances

kubectl -n default get instances -o wide

The output is similar to:

NAME                             AGE   AVAILABLE   REASON              NETWORK IP   EXTERNAL IP
my-container-workload-us-dfw-0   24s   True        InstanceIsRunning   10.128.0.2   34.174.154.114

Confirm that the go-httpbin application is running:

curl -s http://34.174.154.114:8080/uuid

{
  "uuid": "8244205b-403e-4472-8b91-728245e99029"
}

Delete the workload

Delete the workload when testing is complete:

kubectl delete workload my-container-workload