Upgrade from 1.21.2 to 1.22.0

Genvid SDK Prefab for Unity

You should call the Streams prefab function SubmitGameDataJSON rather than SubmitGameData when you provide a serializable object. The SubmitGameData method should be called when you already have a serialized or raw payload such as string or byte array. We have deprecated the SubmitGameData overload for type “object”.

See samples/unity/package/Assets/Genvid/Scripts/GenvidStreams.cs for an example of how this now works.

Unity Sample Build and Config

We updated the Unity Sample build.cs file to generate the project in the Build directory at the same level as Assets and ProjectSettings. If you are using a previous version of config/game.hcl, you need to update unity.binary.unity.path to reflect the new project location.

For example: \app\*Build*\ProjectName.exe

Change of Default Value in SDK.upload_images* Methods

We changed the update_config parameter in upload_images() and upload_images_sdk() methods to not update the configuration by default. You can use update_images_config() to do the same.

The command line behavior still updates the configuration by default.

Terraform 0.12 Upgrade

We upgraded Terraform to version 0.12, which is not backwards-compatible with Terraform modules from prior versions. We also upgraded the Genvid SDK stock modules to be compatible with the new version.

Important

Existing clusters will not use new modules by default, causing Terraform commands run on the clusters to fail. If you choose to use existing clusters rather than creating new ones, you will need to update them to use stock and custom modules that are Terraform 0.12 compatible.

See the upgrade procedure for information on updating an existing cluster using one of the stock Genvid modules. Note that the Bastion-UI Terraform cluster settings page will fail to load until you apply the upgrade procedure.

If you are using custom modules, you will need to upgrade them to be compatible with Terraform 0.12.

See the official Terraform documentation for more information.

Instructions for Upgrading Custom Modules

Important

Upgrading custom modules is an iterative trial-and-error process which you should not perform on production clusters. It is safer to create a copy of your production clusters to work on while upgrading the Terraform modules. Only when everything is working as expected should you use the upgraded modules on the production cluster. The following procedure implies working with a development cluster.

You can see the list of repositories containing Terraform module definitions from the Bastion-UI.

  1. Open the Bastion UI page.

  2. Click Settings.

  3. Click Modules.

    Note

    Module names using the format SDK-#.##.# are the stock Genvid modules, which were upgraded with this version of the SDK. You only need to manually upgrade custom modules you’re using.

  4. Select the custom module to upgrade.

  5. Copy the path for the module’s local folder.

    If the folder path isn’t local, you should copy the module to a local directory to perform the upgrade.

  6. Open the local folder in Windows Explorer.

  7. Copy the module repository to another location as a backup.

    The upgrade process changes the module’s definition. We recommend making a copy of the original in case there’s a problem with the upgrade.

  8. Open a command prompt.

  9. Navigate to the repository folder.

  10. Upgrade the Terraform modules.

    For each folder of the repository containing Terraform module files (.tf):

    1. Open the folder in the command prompt.

    2. Run the upgrade commands.

      The commands are in your local Genvid SDK install directory, so adjust the Terraform path accordingly. For example, if your install directory is C:\genvid:

      C:\genvid\bin\terraform init
      C:\genvid\bin\terraform 0.12upgrade
      

      The output of the upgrade command may return errors. Fix them and re-run the command as needed.

    3. Delete the .terraform folder created by the command.

    The modules upgraded for Terraform 0.12 will have a less verbose syntax. Some examples of these changes are:

    • Using variables directly without string interpolation. A string containing only a variable will trigger a warning with Terraform 0.12:

      $"{var.value1}" => var.value1

    • Accessing a value at a specfic index in a collection has changed:

      values.0.resource => values[0].resource

  11. If the modules were not stored locally, push the upgraded files to their original location.

  12. Go back to the Bastion-UI Modules page.

  13. Click Refresh.

    This pulls the updated files into your bastion and makes them ready for use with the clusters.

  14. Go to the Terraform page.

  15. Select the cluster to upgrade.

  16. Click REIMPORT MODULE.

  17. Make sure the correct module is selected.

  18. Click IMPORT MODULE.

  19. Resolve any errors reported in the Terraform output.

    The 0.12upgrade command doesn’t cover all the changes that are necessary to make the module compatible with Terraform 0.12. Refer to the error messages and make the necessary modifications to the module files.

    For example, some manual changes we had to make to the Genvid stock modules include:

    • Removing extra square brackets [] around expressions that return an array.
    • A module was using the configuration ignore_changes = true, which now takes an array of properties instead of a boolean. The keyword all needed to be used as a replacement but wasn’t supported with the version of the provider that was configured. The version of the aws provider was bumped to the latest version as well as the vpc module.
    • Using the method formatlist was required to properly cast a list into a list of string.

    If a custom module was based on one of the Genvid modules, refer to the upgraded version to see what adaptations we made for the new Terraform version.

  20. After addressing any errors, click Refresh and try to re-import again.

  21. Click PLAN APPLY.

  22. Check the output to see if the cluster needs to be modified in any way.

    • In most cases, it will end with No changes. Infrastructure is up to date.
    • If changes are required, carefully examine them. If the listed modifications look correct, click APPLY.
    • If there are errors, the Terraform modules need further modifications. Fix them in the source files and try again.

API Changes for ConsulTemplateTool

We added the new class ConsulTemplate, which is a more flexible API implementation of ConsulTemplateTool. However, this change is not backwards-compatible.

The goal is to make using the most common cases simpler:

  • If your template has stored configurations in Consul or Vault, use the use_consul=True or use_value=True parameter, as needed.
  • The env parameter lets you inject environment variables in the environment consul-template will run in.
  • All other keyword-parameters are the options of the consul-template executable.
# This example assumes we are working in a class that is a subclass of
# ``ConsulTemplateTool``.

# Before
process = self.consul_template(template,
                               stdout=PIPE,
                               stderr=PIPE,
                               log_level="debug",
                               timeout=1,
                               env=env)

# After
output = self.consul_template_once(use_consul=True,
                                   use_vault=True,
                                   env=env,
                                   template=template,
                                   dry=True)

In this example, we use the template and dry options of the underlying consul-template command directly. The template value is the path to the templated configuration. The dry value specifies that the resulting configuration is to be placed inside output.configuration instead of writing it to disk.

Issue with Sample Files from Releases Prior to 1.20.0

This change to the API causes an issue with the sample scripts that predate the 1.20.0 release. If you used those scripts as a base for your project, you need to adjust them to work with the updated API.

Specifically, you will need to replace this block of code:

try:
    process = self.consul_template(
        file_path,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        log_level="debug",
        cwd=self.base_dir,
        timeout=1,
        env=env)
except subprocess.SubprocessError as ex:
    error_message = ex.stderr.decode()
    self.logger.error("Consul template has return an error:\n" +
                        error_message)
    raise
output = process.stdout.decode()
return hcl.loads(output[1:])

with the skd.load_config_template function we added for ease of use:

return self.sdk.load_config_template(file_path, env=env)

If You Were Using Advanced Features of the Subprocess

Note

ConsulTemplateLegacyTool is available as of version 1.22.1. If you are using Genvid SDK 1.22.0, you must upgrade to 1.22.1 in order to use this class.

If you were using the subprocess.CompletedProcess instance returns by the previous API, you can use the previous implementation from the class directly in your code.

We include the previous version as ConsulTemplateLegacyTool.

To use it, make the following change in your Python code.

Replace:

from genvid.toolbox import (
   ConsulTemplateTool,
   SDK,
)

class TutorialSample(ConsulTemplateTool):

with:

from genvid.toolbox import (
   ConsulTemplateLegacyTool,
   SDK,
)

class TutorialSample(ConsulTemplateLegacyTool):