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: user registration, user namespaces and selective deployments.
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:
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.
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 firstname.lastname@example.org.
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 email@example.com 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.
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 firstname.lastname@example.org. 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.
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.
simple-experiment/ ├── Dockerfile └── index.html
index.html file contains a minimal HTML page:
<!-- index.html --> <html><body>Hello World!</body></html>
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>
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
EdgeNet supports both nodes with ARM64 and x86-64 CPUs. If the binaries in your image do not match the target node architecture, it will fail to run with the message:
exec user process caused "exec format error". For example, if you build a C++ program in your Dockerfile, this program will by default be compiled for the architecture of your machine: If you’re running Docker on an Intel MacBook, it will produce an x86-64 binary, while if you run it on an M1 MacBook, it will produce an ARM64 binary.
Docker also supports building multi-architecture image on a single machine, by emulating the target CPUs architecture. The following tutorials provides more information:
- Building Multi-Arch Images for Arm and x86 with Docker Desktop
- Continuous Cross-Architecture Integration with GitLab
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-username with the corresponding values in the following:
# slice.yaml apiVersion: apps.edgenet.io/v1alpha kind: Slice metadata: name: your-username-1 namespace: your-authority spec: type: Development profile: Medium users: - authority: your-authority username: your-username
kubectl apply --kubeconfig /path/to/kubeconfig.cfg -f slice.yaml
Here is an example
# deployment.yaml apiVersion: apps.edgenet.io/v1alpha kind: SelectiveDeployment metadata: name: simple-experiment namespace: your-authority-slice-your-username-1 spec: workloads: daemonset: - apiVersion: apps/v1 kind: DaemonSet metadata: name: simple-experiment namespace: your-authority-slice-your-username-1 labels: app: simple-experiment spec: selector: matchLabels: app: simple-experiment template: metadata: labels: app: simple-experiment spec: containers: - name: simple-experiment image: username/simple-experiment:1.0 ports: - containerPort: 80 resources: limits: cpu: 100m memory: 125Mi requests: cpu: 100m memory: 125Mi selector: - value: - North_America - Europe operator: In quantity: 5 name: Continent
And here is the command to launch it (provide the correct path to your
kubectl --kubeconfig /path/to/kubeconfig.cfg apply -f deployment.yaml
These commands allow you to find the pod names and to forward the container port. We omit the
-n options for brevity here.
View the selective deployment (sd) status:
kubectl --kubeconfig /path/to/kubeconfig.cfg -n your-authority-slice-your-username-1 \ 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 --kubeconfig /path/to/kubeconfig.cfg -n your-authority-slice-your-username-1 \ logs POD_NAME
Forward the ports of a pod:
kubectl --kubeconfig /path/to/kubeconfig.cfg -n your-authority-slice-your-username-1 \ port-forward POD_NAME 8080:80
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,
To avoid passing
-n/--namespace on each command, you can use a tool like kubectx.