Cluster Api integration

This covers integrating and using the cluster API in the Unity editor.

1. Files needed for Cluster API
2. How to use the Cluster API
3. Genvid window usage

Files needed for Cluster API

There are three files you need to integrate into your project to fully use our Cluster API. If you want to run the current sample, you don’t need to copy the files in the sample. You can use unity.py to build the project and run it without manually copying any files.

GenvidRESTCSharp.dll

Genvid creates and uses the file GenvidRESTCSharp.dll to make all calls related to RestSharp.

This file needs to be placed inside your project’s Plugins folder. The project command-script handles this for you when you run py unity.py build.

You can make calls from this GenvidRESTCSharp.dll directly, though we recommend using the C# script created to interact with it.

Newtonsoft.Json.dll

GenvidRESTCSharp.dll needs the Newtonsoft.Json.dll to function.

This file needs to be placed inside your project’s Plugins folder. The project command-script handles this for you when you run py unity.py build.

RestSharp.dll

GenvidRESTCSharp.dll needs the RestSharp.dll to function.

This file needs to be placed inside the Plugins folder of your project. The command script of the project handles this for you when you run py unity.py build.

How to use the Cluster API

As long as you include the dll files in your project, you will be able call the GenvidRESTCSharp API without any issues. In this section, we cover step-by-step how to make proper calls to the API:

BastionClustersAPI

1. Create a new Genvid.Consul.Client.

    private static Genvid.Consul.Client _client = null;

    private static Genvid.Consul.Client Consul
    {
        get
        {
            if (_client == null)
            {
                _client = new Genvid.Consul.Client();
            }
            return _client;
        }
    }

2. Get the service bastion-api from the Consul client created in the last

   step.

3. Perform a GetEnumerator on the service and then get the Current on

   the service.

4. Create the string: http:// + the current service ServiceAddress + :

   • the current service ServicePort + /v1.

    private static string BastionUrl
    {
        get
        {
            var iservices = Consul.catalog.service("bastion-api");
            var services = iservices.GetEnumerator();
            if (!services.MoveNext())
            {
                projectAvailable = false;
                return "no project loaded";
            }
            else
            {
                projectAvailable = true;
            }
            var service = services.Current;
            return string.Format("http://{0}:{1}/v1", service.ServiceAddress, service.ServicePort);
        }
    }

5. Create a new Genvid.Api.BastionClustersApi object using the string you

   created as a parameter.

6. You can access the available clusters with the

   Genvid.Api.BastionClustersApi object. You need to do a getClusters() on the Genvid.Api.BastionClustersApi object which returns a list of Genvid.Model.Bastion.ClusterOperator.

                var tempBastion = new Genvid.Api.BastionClustersApi(BastionUrl);
                listClusterOperator = tempBastion.getClusters();

7. Each Genvid.Model.Bastion.ClusterOperator in the list contains

   the same type of structure:

ClusterOperator

A Cluster from the Bastion-API.

Object Properties:  

• id (string) – The cluster ID
• instanceID (string) – The terraform instance ID
• source (string) – The terraform source location
• category (string) – The cluster category

JSON Example

{
    "id": "DlyJAptFSjOvfYjstyeE",
    "source": "AlDosICwEhWyeldfukrW",
    "instanceID": "xETEfBuXnbwVMUCROrRh",
    "category": "cRPnoBXGCiYZxiiLVgoN"
}

HealthAPI

1. Create a new Genvid.Consul.Client.

    private static Genvid.Consul.Client _client = null;

    private static Genvid.Consul.Client Consul
    {
        get
        {
            if (_client == null)
            {
                _client = new Genvid.Consul.Client();
            }
            return _client;
        }
    }

2. Get the service bastion-api from the Consul client created in the

   previous step.

3. Perform a GetEnumerator on the service and then get the Current on

   the service.

4. Create the string: http:// + the current service ServiceAddress + :

   • the current service ServicePort + /v1/proxy/ + theClusterName +

     /cluster-api/v1/.

    private string ClusterUrl
    {
        get
        {
            var iservices = Consul.catalog.service("bastion-api");
            var services = iservices.GetEnumerator();
            if (!services.MoveNext())
            {
                projectAvailable = false;
                return "no project loaded";
            }
            else
            {
                projectAvailable = true;
            }
            var service = services.Current;
            return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
        }
    }

5. Create a new Genvid.Api.HealthApi object using the string you

   created as a parameter.

6. With the Genvid.Api.HealthApi object, you can access the health service

   of your choice. In our case, we want to access the SDK Health check by

   passing the service name as a parameter to getServiceHealth.

                    var healthApi = new Genvid.Api.HealthApi(stringCluster);
                    HealthCheckList = healthApi.getServiceHealth("SDK Health check");

7. Afterwards, you can use the Genvid.Api.HealthApi object list to access

   data from it. In this case, we need the first element of the

   list.

   If you want a better format for the Output string,

   you can deserialize it as a Genvid.Model.Cluster.HealthCheckOutput. Before attempting to deserialize the Output string, make sure you set the object Status to passing.

                    if (HealthCheckList.Count > 0)
                    {
                        if (HealthCheckList[healthCheckSelection].Status == "passing")
                        {
                            currentHealthCheckOutput = Newtonsoft.Json.JsonConvert.DeserializeObject<Genvid.Model.Cluster.HealthCheckOutput>(HealthCheckList[healthCheckSelection].Output);
                        }
                        else
                        {
                            currentHealthCheckOutput = null;
                        }
                    }
                    else
                    {
                        currentHealthCheckOutput = null;
                    }

See the SDK Health check section Health Checks for more information about the structure contents for the health check.

JobsAPI

1. Create a new Genvid.Consul.Client.

    private static Genvid.Consul.Client _client = null;

    private static Genvid.Consul.Client Consul
    {
        get
        {
            if (_client == null)
            {
                _client = new Genvid.Consul.Client();
            }
            return _client;
        }
    }

2. Get the service bastion-api From the Consul client created in the

   previous step.

3. Perform a GetEnumerator on the service and then get the Current on

   the service.

4. Create the string: http:// + the current service ServiceAddress + :

   • the current service ServicePort + /v1/proxy/ + theClusterName +

     /cluster-api/v1/.

    private string ClusterUrl
    {
        get
        {
            var iservices = Consul.catalog.service("bastion-api");
            var services = iservices.GetEnumerator();
            if (!services.MoveNext())
            {
                projectAvailable = false;
                return "no project loaded";
            }
            else
            {
                projectAvailable = true;
            }
            var service = services.Current;
            return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
        }
    }

5. Create a new Genvid.Api.JobsApi object using the string you

   created as a parameter.

6. Use the Genvid.Api.JobsApi object to perform the available tasks:

   ‘startJob(properJobName)’ or stopJob(properJobName).

    public void connectToWebJobs(int typeExecution, string jobName)
    {
        var api = new Genvid.Api.JobsApi(ClusterUrl);

        if (typeExecution == startJob)
        {
            api.startJob(jobName);
            UnityEngine.Debug.Log(jobName + " is started !");
        }
        else if (typeExecution == stopJob)
        {
            api.stopJob(jobName);
            UnityEngine.Debug.Log(jobName + " is stopped !");
        }
    }

LinksAPI

1. Create a new Genvid.Consul.Client.

    private static Genvid.Consul.Client _client = null;

    private static Genvid.Consul.Client Consul
    {
        get
        {
            if (_client == null)
            {
                _client = new Genvid.Consul.Client();
            }
            return _client;
        }
    }

2. Get the service bastion-api From the Consul client created in the

   previous step.

3. Perform a GetEnumerator on the service and then get the Current on

   the service.

4. Create the string: http:// + the current service ServiceAddress + :

   • the current service ServicePort + /v1/proxy/ + theClusterName +

     /cluster-api/v1/.

    private string ClusterUrl
    {
        get
        {
            var iservices = Consul.catalog.service("bastion-api");
            var services = iservices.GetEnumerator();
            if (!services.MoveNext())
            {
                projectAvailable = false;
                return "no project loaded";
            }
            else
            {
                projectAvailable = true;
            }
            var service = services.Current;
            return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
        }
    }

5. Create a new Genvid.Api.JobsApi object using the string you

   created as a parameter.

6. Use the Genvid.Api.LinksApi object to perform a getLinks with the

   proper category and JobName as parameters.

7. Perform an Application.OpenUrl on the .href for each object of the

   list returned.

    public void openLink(string name, string category = "")
    {
        if (name == "cluster-ui")
        {
            string url = ClusterUIUrl;
            UnityEngine.Debug.Log(string.Format("Opening Cluster-UI at {0}", url));
            Application.OpenURL(url);
            return;
        }
        var api = new Genvid.Api.LinksApi(ClusterUrl);
        var links = api.getLinks(category, name);
        foreach (var link in links)
        {
            UnityEngine.Debug.Log(string.Format("Opening {0} at {1}", link.name, link.href));
            Application.OpenURL(link.href);
        }
    }

SettingsAPI

1. Create a new Genvid.Consul.Client.

    private static Genvid.Consul.Client _client = null;

    private static Genvid.Consul.Client Consul
    {
        get
        {
            if (_client == null)
            {
                _client = new Genvid.Consul.Client();
            }
            return _client;
        }
    }

2. Get the service bastion-api From the Consul client created in the

   previous step.

3. Perform a GetEnumerator on the service and then get the Current on

   the service.

4. Create the string: http:// + the current service ServiceAddress + :

   • the current service ServicePort + /v1/proxy/ + theClusterName +

     /cluster-api/v1/.

    private string ClusterUrl
    {
        get
        {
            var iservices = Consul.catalog.service("bastion-api");
            var services = iservices.GetEnumerator();
            if (!services.MoveNext())
            {
                projectAvailable = false;
                return "no project loaded";
            }
            else
            {
                projectAvailable = true;
            }
            var service = services.Current;
            return string.Format("http://{0}:{1}/v1/proxy/{2}/cluster-api/v1", service.ServiceAddress, service.ServicePort, optionsCluster[currentSelectionCluster]);
        }
    }

5. Create a new Genvid.Api.JobsApi object using the string you

   created as a parameter.

6. Use the Genvid.Api.SettingsApi object to perform a getSettings which

   returns a Genvid.Model.Cluster.Settings object.

    private void loadSettings()
    {
        var tempSettings = new Genvid.Api.SettingsApi(ClusterUrl).getSettings();
        var tempSettingsProperties = tempSettings.GetType().GetProperties();

        if (oldSettingsLoaded == null || compareSettings(tempSettingsProperties, tempSettings, oldSettingsToSendLoaded, oldSettingsLoaded) == false)
        {
            oldSettingsLoaded = tempSettings;
            oldSettingsToSendLoaded = oldSettingsLoaded.GetType().GetProperties();
            var tempSettingsNew = new Genvid.Api.SettingsApi(ClusterUrl).getSettings();
            var tempSettingsPropertiesNew = tempSettingsNew.GetType().GetProperties();
            newSettings = tempSettingsNew;
            settingsToSend = tempSettingsPropertiesNew;
        }
    }

7. You can also use the Genvid.Api.SettingsApi object to perform a

   setSettings with a Genvid.Model.Cluster.Settings object as a parameter to save your settings.

    public void saveSettings(Genvid.Model.Cluster.Settings newSettings)
    {
        var api = new Genvid.Api.SettingsApi(ClusterUrl);

        api.setSettings(newSettings);
    }

Genvid window usage

Warning

This feature is currently in beta. The window is functional, but we expect to make some changes in the future to add new features and improve the user experience. We welcome your feedback on the process.

A Genvid window is now available in the Window dropdown menu. This menu is only available if you integrated files from Cluster-API into your project along with GenvidWindow.cs as indicated at the top of this page.

To be able to see the content in this window, your Genvid Bastion must be set up and the Unity project loaded as explained previously. This gives you some direct access to the different websites available, as well as the ability to control some of the jobs running in your local cluster.

Fig. 14 The Genvid Window for Cluster API inside the Unity Editor.

The following sections give more details on each section of the window and their functions.

Clusters

We display all the clusters currently available for the project in a combo list. < Select a Cluster > is the default selection. The number of clusters available is displayed beside the foldout. Make sure to select the proper cluster when using the SDK with this window.

Health check

In this section, we describe the content of the Genvid.Model.Cluster.HealthCheckOutput.State from the service SDK Health check. The contents include:

1. ComposeConnected is the Compose connection status.
2. NatsConnected is the NATS connection status.
3. NumStreams is the number of streams connected.

This section only appears when the game is running, otherwise it displays the error message No project currently running. At the top of this section, we have a small summary of the number of streams active and if both Compose and NATS are connected.

Jobs

A foldout lists all the jobs available for your project along a Start All button. Opening the foldout displays a button labeled On/Off. The button is green when the job is activated and red when deactivated.

Click on the button to start or stop a job. All the tasks associated with the jobs are listed in the foldout when a job is active.

Links

All the links available for your project are listed with a button. When the button displays Open Link, click the button to open the link. When the button displays Error, clicking the button to display the error in the Console.

If a link is associated with a job, you need to start the job to use the link properly. For example, in our Unity sample the Tutorial Admin and Tutorial Demo links won’t work unless the Web job is running.

Logs

This section only include a button Open Link and upon clicking on it, the logs page is displayed.

Settings

All the settings associated with the project are listed within different foldouts. Beside the foldout, we have the info.name, the encode.output.width, the encode.output.height and the audio status encode.input.silent. You can modify the settings by changing their value either via a textbox or checkbox. Note that you can’t write characters in a field that only contains numbers.

There are two buttons available at the bottom of the page:

• Reload settings reloads the settings (useful for reverting

  incorrect settings).

• Save Settings saves changes to the settings made in this

  window.

See The Genvid Settings for more information about each setting.