Getting Started with Ant Media Server Kubernetes
  • 17 May 2022
  • 6 Minutes to read
  • Dark

Getting Started with Ant Media Server Kubernetes

  • Dark

Kubernetes as known is the open source container orchestration tool that is widely used in all over the world. With the version 2.2.0+, Ant Media Server is fully compatible with Kubernetes. 

Let us show how to use Ant Media Server with Kubernetes.


The scope of this document is giving you the basics about how to run Ant Media Server Kubernetes Cluster. If you're not familiar with Kubernetes then you can get started with Kubernetes and follow interactive tutorials.

Running Ant Media Server in Kubernetes is fully about clustering. If you are not familiar with Ant Media Server Clustering & Scaling, please read the Cluster & Scaling documentation.

Before proceeding, we assume that you've installed Kubernetes in your test environment or in a cloud service like AWS. The scenario below is generally running the Kubernetes with Minikube. It's also tested in AWS EKS as well. If you use Minikube, we start the it with sudo minikube start --driver=none in VPS and need to use sudo command in docker and kubectl. On the other hand, you don't need to use sudo in kubectl commands if you're running in AWS.

Preparing MongoDB

MongoDB is essential to create an Ant Media Server cluster. Before running Ant Media Server nodes, you should prepare it first. You can run it any where that can be accessible from the Ant Media Server nodes with the one of the following ways.

  • You can install and run it directly on a computer using this link.
  • You can also use Mongo Atlas as a cloud based data store.
  • You can deploy it in your kubernetes with the following command: kubectl create -f

Whichever way you deploy Mongo DB, you should note the IP, user name and password if exists. We will use them soon.

1. Create image for container

We first need to create a docker image to run our pods in Kubernetes.

  • Get the Dockerfile: Dockerfile is available in Ant Media Server's Scripts repository that is actively used in CI pipeline. You can get it with the command below.
wget \
-O Dockerfile_Process
  • Download or copy AMS Enterprise Edition ZIP file into the same directory that you download Dockerfile above.
  • Create the docker image. Before running the command below, please pay attention that you should replace {CHANGE_YOUR_ANT_MEDIA_SERVER_ZIP_FILE} in the command below with your exact Ant Media Server ZIP file name.
sudo docker build --network=host --file=Dockerfile_Process -t ant-media-server-enterprise-k8s:test
--build-arg AntMediaServer={CHANGE_YOUR_ANT_MEDIA_SERVER_ZIP_FILE} .

The second thing we should point out is the image name and tag. The command above use the ant-media-server-enterprise-k8s:test as image name and tag. The image name is compatible with deployment file. I mean you can absolutely change the image name and tag, just make it compatible with deployment file we'll mention soon.

If everything is OK, your image is available in your environment. If you're going to use this image in AWS EKS or similar service, you need to upload the image to repository such as AWS ECR or you can run a local registry.

2. Run Ant Media Server K8s Deployment

  • Download the ams-k8s-deployment.yaml file with the following command.
wget -O ams-k8s-deployment.yaml
  • Change the deployment file according to your needs. In order to do that, let us give some more information about the ams-k8s-deployment.yaml The content of the file is as follows.
kind: Service
apiVersion: v1
  name: ant-media-server
    app: ant-media
    - name: http
      protocol: TCP
      port: 5080 
apiVersion: apps/v1
kind: Deployment
  name: ant-media-server
      app: ant-media
  replicas: 1
        app: ant-media
          - labelSelector:
              - key: app
                operator: In
                - ant-media
            topologyKey: ""
      hostNetwork: true
      dnsPolicy: ClusterFirstWithHostNet
      - name: ant-media-server
        imagePullPolicy: IfNotPresent # change this value accordingly. It can be Never, Always or IfNotPresent
        image: ant-media-server-enterprise-k8s:test #change this value according to your image.
# By default, mongodb deployment is used. If you're using mongodb somewhere else, specify it  with server url(-h) below. 
# You may also need to add -u and -p parameters for
# specifying mongodb username and passwords respectively         
        args: ["-g", "true", "-s", "true", "-r", "true", "-m", "cluster", "-h", "mongo"]
             cpu: 1000m
 #     imagePullSecrets:
 #     - name: docker

We should point out the somethings important in the file above.

  • hostNetwork: true line above means that Ant Media Server uses the host network. It is required as there is a wide range of UDP and TCP ports are being used for WebRTC streaming. This also means that you can only use one pod of Ant Media Server in a host instance. Don't worry about where and how to deploy as K8s handles that. We're just letting you know this to determine total number of nodes in your cluster.
  • imagePullPolicy: IfNotPresent means that if the image is available in local environment. It'll not be pulled from the private or public registry.
  • image: ant-media-server-enterprise-k8s:test specifies the name of the image. You should pay attention here as it should be the same name with the image you built in previous step.
  • args: ["-g", "true", "-s", "true", "-r", "true", "-m", "cluster", "-h", ""] specifies the parameters for running the Ant Media Server pods. Let us tell their meanings and why we need them.

"-g", "true": It means that Ant Media Server uses the public IP address of the host for internal cluster communication. Default value is false.
"-s", "true": It makes Ant Media Server uses its public IP address as server name.
"-r", "true": It makes Ant Media Server replaces the local IP address in the ICE candidates with the server name. It's false by default.
"-m", "cluster": It specifies the server mode. It can be cluster or standalone. Its default value is standalone. If you're running Ant Media Server in Kubernetes, it's most likely you're running the Ant Media Server in cluster mode. This means, you need to specify the your MongoDB host, username and password as parameter.
"-h", "": It specifies the MongoDB host address. It's necessary to use if you're running in cluster mode. In this example, it's because in the CI pipeline, local MongoDB is installed. You should change it with your own MongoDB address or replica set.
"-u", "username": It specifies the username to connect to the MongoDB. If you don't have credentials, you don't need to specify.
"-p", "password": It specifies the password to connect to the MongoDB. If you don't have credentials, you don't need to specify.

You can now change the ams-k8s-deployment.yaml file according to your environment.

Please pay attention to the following.
  1. Ant Media Server needs to use host network as described above because of the nature of the WebRTC. In other words, it means that single Ant Media Server pod can run in a node. Don't try to run multiple Ant Media Server pods in a single node.
  2. The default configuration above assumes that each node has public IP address in order to directly stream from nodes instead of through load balancer. If your pods don't have public IP addresses, please make the -g parameter to false above.
  • Run the ams-k8s-deployment.yaml with following command.

sudo kubectl create -f ams-k8s-deployment.yaml

If everything is OK, you'll have a running deployment. You can query your deployment with the following command.

sudo kubectl get deployments

Then you should see something like below:

ant-media-server 1/1 1 1 12s

3. Run AMS K8s service

Running Ant Media Server K8s service is the easiest part in pipeline.

  • Check the service if it's working.
sudo kubectl get services

If it's running, you should see something similar like this.

NAME               TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
ant-media-server   LoadBalancer   <pending>     5080:30240/TCP   6s
kubernetes         ClusterIP       <none>        443/TCP          6m50s

If you're running with Minikube, you can directly connect to your platform with your host ip address in the browser and the port name above. Let's assume your host IP address is xxx.yy.yy.zz, then you can connect to AMS web panel via http://xxx.yy.yy.zz:30240. If you're running this service in AWS or any other place, please read their documentation about Load Balancer in Kubernetes.

Origin & edge configurations

We strongly recommend separate origin and edge instances in Ant Media Cluster. In Kubernetes, you can separate them by creating 2 copies of deployment and service YAML files and renaming them.

As an example you will have such files:

  • ams-k8s-deployment-for-edges.yaml
  • ams-k8s-deployment-for-origins.yaml
  • ams-k8s-service-for-edges.yaml
  • ams-k8s-service-for-origins.yaml

Make the following changes in these files:

  • In ams-k8s-deployment-for-edges.yaml and ams-k8s-service-for-edges.yaml files, add -edge suffix to all ant-media-server values.
  • In ams-k8s-deployment-for-origins.yaml and ams-k8s-service-for-origins.yaml file, similarly add -origin suffix to all ant-media-server values.

Deploy the YAML files.

After deploying two services you will have two load balancers as well.

While publishing a stream, you should use the URL of the load balancer of origins. ORIGIN_LOAD_BALANCER_URL/WebRTCAppEE

Similarly, you should use the URL of the load balancer of edges in playing. EDGE_LOAD_BALANCER_URL/WebRTCAppEE/player.html

Was this article helpful?