Upgrade from Previous Versions

Upgrading the Genvid SDK from one version to another may include some manual steps. This page includes any steps required to update to version 1.24.0 from the last version. If you’re upgrading an older version of the SDK, start with any special upgrade instructions for your version found here.

General Upgrade Instructions

Upgrade the Genvid SDK

To set up the new SDK locally:

  1. Install the new SDK.

  2. Run the Python script to install the Genvid Toolbox.

    py install-toolbox.py

  3. Run the Genvid Bastion script to update your bastion.

    genvid-bastion reinstall --reconfigure -b {mybastion} -uml

Update Your Broadcast Website

If you used code from the samples we provide in your own project, note that we recently enforced a best practice concerning service discovery using consul in those samples. You should check again the samples and update your project accordingly. We invite you to use the consul health api instead of the catalog api to fetch the url of your services, since it is more likely that the url will point to a healthy service.

Update Your Game

To update your game without applying new features, just replace the old genvid.dll from the previous SDK with the one from the new SDK. The old plugins and integration should work as-is, with the exception of the specific upgrade instructions below.

Attention

Always follow the full upgrade path for the Genvid SDK version you’re using. For example: If you’re upgrading from version 1.6.0 to 1.10.0, start by upgrading from 1.6.0 to 1.7.0 then continue with each version.

See the full list of upgrade instructions for your specific version.

Upgrade the Javascript API

You should also upgrade the Genvid JavaScript API on your website.

Update Your Cluster

We strongly recommend keeping your old clusters as-is and creating a new one for the update.

To create a new cloud-based cluster, follow the standard instructions:

  1. Set up a new wingame AMI that matches the new version.
  2. Create new clusters.

To create a new local cluster, follow the standard instructions listed in the Initialize a Local Cluster section.

Once you have replaced all your clusters, you can remove the old SDK repositories from the Modules Section page.

Updating an Existing Cluster

Warning

Updating your cluster can replace all your instances and even erase your current configuration. We recommend not updating a live cluster. If you do, carefully check the changes before applying the plan.

You can update the module used to build your cluster by clicking on Reimport Module in the module section of your cluster infrastructure, then select the module new version and import it. Finally, click apply in the Terraform section.

Note

Some changes can take time to propagate to AWS. This is especially true for IAM roles and policies, which could then create some conflicts when recreated. Re-applying the Terraform plan should fix the problem.

Update Genvid SDK Samples

Along with your own project, make sure you update any of the Genvid SDK samples you’ve previously installed.

Upgrade from 1.23.0 to 1.24.0

Changes to the Unity Asset Package

We split the Genvid Unity Asset Package into two different parts. One allows you to integrate the Genvid SDK into your game. The other adds tooling to the Unity Editor interface for interacting with your clusters.

Make sure you completely uninstall the older version of the Genvid asset package before upgrading to 1.24.0.

Changes to the Unity Cube Sample

  • We moved the Genvid_SubmitNotification() family of methods from GenvidStreams to GenvidSession as notifications are not sent on streams.

  • We made the error handling of the Submit* methods more consistent and informative.

YouTube Embedded Player and SSL Support

You can now use the YouTube Embedded Player with an SSL protected website. When doing so, you must use SSL clusters with names that terminate in ways that indicate they use SSL (such as _alb_ssl).

When using an SSL module, its leaf endpoint and a web endpoint must be loaded in the cluster configuration by using the loadEndpoint() method in /samples/cube/web/web.py.

    def loadEndpoint(self):
        leaf_endpoint = self.get_leaf_endpoint()
        web_endpoint = self.get_web_endpoint()
        config = {
            'version': '1.7.0',
            'config': {
                'cloud': {
                    'endpoint': {
                        'leaf': '',
                        'web': ''
                    }
                }
            }
        }
        config['config']['cloud']['endpoint']['leaf'] = leaf_endpoint
        config['config']['cloud']['endpoint']['web'] = web_endpoint
        return config

To stream YouTube embedded on a website with SSL, you must load the file youtube.sample.hcl located in samples/streaming_services to the cluster configuration. This file contains the new configuration that enables embedding with SSL by setting embed_ssl to true.

config {
  embed_ssl {
    enabled = false
  }
} // end of config

SSL Support on Local Cluster

It is now possible to generate self-signed SSL certificates for your local cluster when loading the web sample. A new python script /samples/cube/web/generate_ssl.py uses HashiCorp Vault to generate the certificates that the backend of the Web Sample will use.

#!/usr/bin/env python3
import hvac
import os
import json
import consul


def create_new_ssl():
    client = hvac.Client(url='http://127.0.0.1:8200')

    secrets_engines_list = client.sys.list_mounted_secrets_engines()['data']

    if "pki/" in secrets_engines_list:
        print('The PKI engine is already enabled.')
    else:
        client.sys.enable_secrets_engine(backend_type='pki', )
        print('The PKI engine has been enabled')

    client.sys.tune_mount_configuration(
        path='pki',
        max_lease_ttl='87600h',
    )

    generate_root_response = client.secrets.pki.generate_root(
        type='exported', common_name='New root CA')
    print('New root CA: {}'.format(generate_root_response))

    set_urls_response = client.secrets.pki.set_urls({
        'issuing_certificates': ['http://127.0.0.1:8200/v1/pki/ca'],
        'crl_distribution_points': ['http://127.0.0.1:8200/v1/pki/crl']
    })

    create_or_update_role_response = client.secrets.pki.create_or_update_role(
        'localhostrole', {
            'ttl': '72h',
            'allow_localhost': 'true'
        })
    print('New role: {}'.format(create_or_update_role_response))

    generate_certificate_response = client.secrets.pki.generate_certificate(
        name='localhostrole', common_name='localhost')
    response = generate_certificate_response.json()
    print('Certificate response data: ', response)

    # the following lines will create the files needed for Nodejs to read the certificate and private key.
    cur_path = os.path.dirname(__file__)

    f = open(os.path.join(cur_path, "certificate.pem"), "w")
    f.write(response["data"]["certificate"])
    f.close()

    f = open(os.path.join(cur_path, "key.pem"), "w")
    f.write(response["data"]["private_key"])
    f.close()

When loading the web sample, use the -s option to trigger the generate_ssl.py script.

py web.py load -s

Whether you’re using the standalone mode or a streaming platform, make sure to set embed_ssl to true in your hcl file to enable embedding with SSL.

config {
  embed_ssl {
    enabled = true
  }
}

Warning

If you need to load multiple hcl configuration files containing the embed_ssl key (such as twitch.sample.hcl or youtube.sample.hcl), make sure to load them after loading the web sample. Otherwise you might overwrite the values associated with the embed_ssl key.

Terraform Modules Changes

  • We removed the variable force_az from all the AWS Terraform modules. We replaced it with the new variable azs which lets you select specific availability zones.
  • We added the variable subnet_ids to AWS Terraform modules, which is an ordered list of AWS subnet IDs. The module will use the list you provide for this variable. If you don’t provide a list, the module uses the first subnet from each availability zone in the variable azs.
  • The module azurerm_basic_cluster now uses Azure Shared Images Versions to speed cluster instantiation.

To make sure that the availability zone is preserved on an existing cluster following the upgrade:

  • Write down a value of force_az,
  • Reimport the module,
  • Open the Cluster Settings page,
  • Add the noted value of force_az to the azs setting.

genvidClient.IDataFrame.timeCode adjustment

We converted genvidClient.IDataFrame.timeCode to milliseconds to match the format of genvidClient.IDataStreamFrame.timeCode. (Version 1.23.0 introduced a mismatch in the formats.)