Link Search Menu Expand Document

Running an experiment on EdgeNet

If you are familiar with Docker and Kubernetes, you already know almost everything that you need to know to deploy experiments on EdgeNet. If not, you can rely on the wealth of documentation and tutorials already available for these technologies online. This page describes the basic steps required to run an experiment on EdgeNet, with attention to the few EdgeNet-specific features.

Register for a free account

We welcome bona fide researchers and instructors whose work will benefit from a global testbed that is open to the Internet. Its value lies in its distributed vantage points rather than in raw compute power. Kindly review the Acceptable Use Policy for more details.

To run experiments on EdgeNet, you need an account that you can obtain for free by signing up on the web console:

Create an EdgeNet account

Please provide an institutional e-mail address. EdgeNet administrators will verify the information that you provide and, if all checks out, send you your kubeconfig file within 48 hours, at which point you can start using the system.

If you work as part of a team that has not yet signed up, please start by registering an account for your team leader (with their agreement, of course). Once that person is approved by the EdgeNet administrators, they will be able to authorize accounts for all those for whom they are prepared to take responsibiity. The team leader does not need to be familiar with Docker or Kubernetes; they can perform all authorizations via the web console, and they can delegate authorization responsibility to a team member.

Users at not-for-profit institutions

For researchers at not-for-profit institutions, including universities, research institutes, laboratories, and government, EdgeNet administrators will verify a researcher’s status, for instance by checking for their publications.

We welcome instructors who wish to use EdgeNet for laboratory exercises for their classes. An instructor who is a team leader can authorize student accounts, for which they take responsibility. Verification of your status might require e-mail exchange with

If you are a student or intern, please ask your supervisor to register themselves, or to allow you to register them. They can then authorize your account.

All users of a team’s account free account share that team’s limited quota. That quota can be automatically increased if the team contributes nodes to EdgeNet, either from their institutional premises, team members’ homes, or from the cloud; it takes no more than five minutes to do so. Those unable to contribute nodes can ask to nonetheless consider a quota increase.

Even if your limited quota is sufficient, but you find that EdgeNet proves to be valuable to your research, we do ask that you kindly support the platform through node contributions.

Users at for-profit institutions

EdgeNet welcomes pre-commercial research conducted by individuals at for-profit institutions. You may obtain a trial account with a limited quota for free. Verification of your status might require e-mail exchange with Quota increases can be obtained as described above for not-for-profits.
If EdgeNet proves to be valuable in your work, we ask that your institution kindly make a financial contribution to support the platform.


To run an experiment, you need to have Docker and kubectl installed on your machine. You can find the installation instructions on their respective websites. You will also need a free account on Docker Hub to store your container images.

Building a container image

Let’s consider a simple scenario where we want to serve a static web page. We will define two files in simple-experiment directory: the web page index.html, and the Dockerfile.

├── Dockerfile
└── index.html

The index.html file contains a minimal HTML page:

<!-- index.html -->
<html><body>Hello World!</body></html>

The Dockerfile contains the instructions needed to build the container image. We will use Python’s built-in web server to serve the page. Start with an image from Docker Hub that has Python pre-installed:

# Dockerfile
FROM python:latest
ADD index.html /data/index.html
CMD python3 -m http.server -d /data 80

We can then build and test our image locally:

docker build -t simple-experiment .
docker run -p 8080:80 -it simple-experiment
curl http://localhost:8080 # (In another terminal)
# <html><body>Hello World!</body></html>

Once we’ve tested our image, we can tag it and push it to the Docker Hub registry. To do so, first create a repository on Docker Hub:

Docker Hub - Create Repository

Then run the following commands, replacing username with your Docker Hub user name:

docker login
docker tag simple-experiment username/simple-experiment:1.0
docker push username/simple-experiment:1.0

Important: Make sure that you build your image on an x86-64 machine, as EdgeNet does not yet support ARM processors, such as the Apple M1 CPU. If you build your image on an ARM machine, the image will fail to run on EdgeNet nodes and you will receive the message: exec user process caused "exec format error".

Deploying containers

Creating a slice

Your EdgeNet account is associated with what we term an authority, which is the namespace in which you are allowed to work. Within your authority namespace, you will create a slice namespace for each Kubernetes workload that you intend to deploy. To do so, prepare a slice.yaml file by replacing your-authority and your-username with the corresponding values in the following:

# slice.yaml
kind: Slice
  name: your-username-1
  namespace: your-authority
  type: Development
  profile: Medium
    - authority: your-authority
      username: your-username

Then run:

kubectl apply --kubeconfig /path/to/kubeconfig.cfg -f slice.yaml

Creating a deployment

Here is an example deployment.yaml file:

# deployment.yaml
kind: SelectiveDeployment
  name: simple-experiment
  namespace: your-authority-slice-your-username-1
      - apiVersion: apps/v1
        kind: DaemonSet
          name: simple-experiment
          namespace: your-authority-slice-your-username-1
            app: simple-experiment
              app: simple-experiment
                app: simple-experiment
                - name: simple-experiment
                  image: username/simple-experiment:1.0
                    - containerPort: 80
                      cpu: 100m
                      memory: 125Mi
                      cpu: 100m
                      memory: 125Mi
    - value:
        - North_America
        - Europe
      operator: In
      quantity: 5
      name: Continent

And here is the command to launch it (provide the correct path to your kuheconfig file):

kubectl --kubeconfig /path/to/kubeconfig.cfg apply -f deployment.yaml

Monitoring the experiment

These commands allow you to find the pod names and to forward the container port. We omit the --kubeconfig and -n options for brevity here.

View the selective deployment (sd) status:

kubectl describe sd simple-experiment 

View the daemon set (ds) status:

kubectl kubeconfig /path/to/kubeconfig.cfg -n your-authority-slice-your-username-1 \
  describe ds simple-experiment

View the logs of a pod:

kubectl logs POD_NAME

Forward the ports of a pod:

kubectl port-forward POD_NAME 8080:80

Stopping the experiment

kubectl --kubeconfig /path/to/kubeconfig.cfg delete -f deployment.yaml


To avoid passing --kubeconfig on each command, you can copy your kubeconfig file to $HOME/.kube/config, or export the KUBECONFIG variable. For example, export KUBECONFIG=/home/user/Downloads/kubeconfig.cfg.

To avoid passing -n/--namespace on each command, you can use a tool like kubectx.

Going further

For more information, please refer to the Docker and Kubernetes documentation.