Skip to content

Operator Network Activation Team

Enabling SmartConnect begins in AWS. There are numerous critical steps required for configuring, protecting and controling the resources that users of the Appearition Platform can consume.

You are in control of your AWS infrustructure

At all times you have full control of which resources the Appearition Platform can see and use when provisioning edge services for end user applications and solutions.

The following sections describe what needs to be done in an AWS account to allow the Appearition Platform to see and work with resources.

AWS Configuration#

Accounts and Privileges#

  1. You will need an AWS account with these minimum policies:
  • AmazonVPCFullAccess
  • AmazonEC2FullAccess
  • AmazonRoute53FullAccess
  1. You will need an IAM Role that is assigned to EC2 instances when they are launched. Create the IAM Role with this min policy:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeTags"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Note you may need to assign other policies to this IAM Role which the EC2 instance (i.e. the Edge Machine) needs. The policies depend on the application services that are going to be deployed onto the Edge Machine

Infrastructure#

Decide which region(s) you want edge compute services#

Access to edge services via the Appearition Platform require specific configuration per region as part of an opt-in policy

Create a new VPC in each region#

Isolate the edge machine resources from any other infrastructure. If you decide to use a dedicated AWS account to manage and isolate the Appearition Platform, then instead of creating a new VPC you can use the default VPC created for the account.

Regardless of the VPC you choose to use, you must create a special tag on the VPC so that it becomes visible to the Appearition Platform:

  • Key: Appearition.Edge.IsEnabled
  • Value: True

Create a subnet for each of the Availability Zones in the region#

You must decide and configure which zones will be used to launch and run edge compute instances. This applies to both Local Availability Zones and Wavelength Zones.

You must create a special tag on all subnets so that they become visible to the Appearition Platform:

  • Key: Appearition.Edge.IsEnabled
  • Value: True

Create security groups for each region#

Security groups need to be configured to allow/deny access to the various services that will be deployed on the Edge Machines. Note, you can only have 1 security group assigned per Edge Machine type, so ensure all relevant ports are configured.

You must create a special tag on all security groups so that they become visible to the Appearition Platform:

  • Key: Appearition.Edge.IsEnabled
  • Value: True

Create a KeyPair in each region#

The Appearition Platform will launch specific configured instances in the region and zones. You will need to configure the KeyPairs in each region and then declare that in the Appearition Platform.

You must create a special tag on all KeyPairs so that they become visible to the Appearition Platform:

  • Key: Appearition.Edge.IsEnabled
  • Value: True

Decide on a Route53 Domain and Hosted Zone#

When launching an instance, the EMS will allocate a dynamic subdomain to the EC2 instance. The subdomain will be a generic UUID created under the domain of your choice. Automatically, the Appearition Platform will create an “A” record in a specified Hosted Zone in Route53 that points to the public IP address of the launched EC2 instance. Everytime the instance is stopped, that “A” record will be automatically removed from Route53. Similarly, when the EC2 instance is restarted, and a new public IP address is allocated, a new “A” record with the same original subdomain will be recreated in the specified Hosted Zone in Route53.

Route53

It is recommended that you allocate a dedicated Hosted Zone for the Appearition Platform. All updates and changes to the “A” records can then be isolated from any other domains your organisation is hosting in Route53.

AMIs#

An AMI is ultimately what the Appearition Platform will use to launch an EC2 instance when it provisions an edge machine for a tenant.

As such in the AWS account, you will need to prepare all of the AMIs which will be used to run edge compute services and then declare them in the Appearition Platform as Edge Machine Types.

AMIs only live in one region. However, via the Appearition Platform, an AMI can be easily copied across to other regions and made available there for launching instances. Hence, choose a region which will hold the master copy and then via the Appearition Platform, you will be able to copy that master AMI over to the other regions you have enabled.

Tagging your AMIs

You will need to tag your AMIs so they become visible to the Appearition Platform:

  • Key: Appearition.Edge.IsEnabled, Value:True
  • Key: Appearition.Edge.IsAmi, Value:True
  • Key: Appearition.Edge.Version, Value:up to you

The above Appearition.Edge.Version tag allows you to control which version of Edge Machine Types are launched in regions.

Edge Machine Type#

An edge machine type represents one server that is allocated by the Appearition Platform as an edge machine. When an edge machine type is allocated by the Appearition Platform, in actual fact an AMI is launched as one EC2 instance as the default instance type configured for that edge machine type (e.g. t2.micro).

Deployed on that EC2 instance (i.e. preconfigured as part of the AMI) will be all of the services required to fulfill the application requirements of the end user solution. The actual services that are deployed as part of the AMI is entirely up to your organisation’s delivery team who are building out the solutions that consumes the Appearition Platform.

We are here to help you

Appearition can assist with a number of existing Edge Compute solutions. Please reach out to us for assistance.

Appearition Platform Tenant Configuration#

Once your AWS account has been configured, you are then ready to setup a tenancy in the Appearition Platform.

The following section will guide you on setting up a tenant on the Appearition Platform where you will declare and configuring the AWS resources prepared in the previous sections.

Pre-requisites#

The following instructions assume you already have access to the Appearition Platform and to an empty tenant.

Contact us

Please contact us so that we can setup an account that is right for your organisation

Activate and Configure Modules#

The following modules are required as a minimum in your tenant:

Edge Compute Using AWS#

This will be the first module to activate and because of its dependencies on other modules, automatically the other modules will also be activated for you.

It is on this module that you will set the necessry credentials to the AWS account you have allocated for the Appearition platform. The following settings must be configured:

  • AwsCredentialsAccessKey and AwsCredentialsSecretKey: Generate these API Access details for the AWS account configured and the beginning of this page
  • AwsRoute53HostedZoneDomain: This is the domain which all launched EC2 instances will be tagged with (e.g. appearition.com)
  • AwsRoute53HostedZoneId: This is the ID to the Hosted Zone in Route53 for the domain set in the previous setting AwsRoute53HostedZoneDomain

Protecting secret keys and IDs

When setting the values of secret keys and ID fields, ALWAYS protect those values by using the Add Encrypted Setting button. By default, sensitive settings are already created with a default secret value which you must change.

Edge Compute Scaffold#

Scaffolding is a concept adopted by the Appearition Platform for abstracting implementations of technology. Edge Compute is a scaffolded feature to enable the Appearition Platform to support any providers of cloud infrastructure.

SmartConnect current supports AWS but can be adapted to any other cloud provider by implementing the scaffold modules for Edge Compute.

To configure your tenant to use the AWS implementation of Edge Compute, will need to update the EdgeComputeProviderName setting and set AwsEdgeCompute

Want to learn more?

Please contact us to find out more

IP Lookup Scaffold#

IP Lookup is another scaffolded feature of the Appearition Platform. It’s purpose is to provide solutions with a service for discovering information about any IP address.

SmartConnect introduces a service referred to as the SmartConnect Broker whose job is to find and allocate the closest edge server to a connecting client device. The SmartConnect Broker uses the IP Lookup Scaffold to get information about the incoming IP request.

You will need to activate this module and also configure the IpLookupProviderName setting with the value IpInfoIpLookup

IP Lookup by ipinfo#

This module provides an implementation of the above IP Lookup Scaffold. You will need to activate this module.

Publish to AWS Edge Servers#

Publishing is a feature available to Digital Experience Builders whereby once they have created an immersive experience, they are able to publish it for an end user to view. Publishing is another scaffolded ferature of the Appearition Platform where many different mediums and providers of “Publishing” can be activated and used for the same immersive experience.

To take advantage of the SmartConnect, AWS edge services, you will need to activate the Publish to AWS Edge Servers module.

You will also need to configure a number of important settings in the module:

  • EdgeServerApiToken; and
  • EdgeServerSyncInstance

You will find and generate the values for these two settings from the API Access screen.

Every instance of an Edge Machine will need to include at least one important service… the Appearition Agent. The role of the Appearition Agent service is to handle the synchronisation of published experiences from tenants and channels on the central Appearition Platform. The Appearition Agent needs to communicate to the central Appearition Platform via API calls. Since your development team will control the services that are deployed as part of the AMI, you can also configure the unique Application ID of the Appearition Agent via the API Access screen.

The Appearition Agent acts like any other external application which wants to access modules and data. An application must be registered in the tenant, the correct roles and channel priviliges must be assigned to that application and finally an API Token needs to be generated. That API Token is configured against the agent on the edge machine as part of the original AMI. This is important because when a new instance of an Edge Machine is launched from the defined AMI, the Agent needs to be ready to connect to the EMS and retrieve experience data.

Declaring and managing AWS infrastructure#

The following sections will guide you to setting up the tenant so that it knows about the configuration and infrastructure in the AWS account.

You can access the management screens for this via AWS Edge Compute from the home screen.

Dashboard#

The first screen you will see is the Dashboard. It provides you with a quick glimpse at the status of all of the Data Centres and and the number of instances which have been launched in each Data Centre.

You will see colour coded pins on the map locating each Data Centre around the world and a table under the map listing the instances which have been launched.

Tip

Click on a pin to reveal a panel of stats

Data Centres#

Data Centre is another term for an “AWS Region” and in this screen, you can control which of those AWS Regions are available to the tenant and where Edge Servers can be launched in.

Important

You must explicitly declare which Region(s) are available to the tenant

This screen also allows you add new Data Centres and set the GEO location coordinates for them

Region Edge Config#

Once you have chosen the Regions, you can then move on to declare the AWS resources available to that region.

This is where you declare the VPC, Subnets, Security Groups and Key Pairs that you have setup in the AWS account. All of those AWS resources will only appear in this screen is you have tagged them with the key Appearition.Edge.IsEnabled and the value of True

As per the above screen shot, when adding a new Region Edge Config entry, you must choose the Region and then the Zone. As you will see in a further section below, when launching EC2 instances (Edge Instances), you
will be prompted to choose region and zone. This is by design and gives you complete control in your tenant as to what AWS resources can be used.

Region Wavelength Zone#

Wavelength Zone is a relatively new feature offered by AWS and serves to provide ultra low latency and high bandwidth connectivity over 5G. This service is currently offered through a select number of telco companies around the world with more and more coming on board over time.

Given the fluid nature of this service, there is a special configuration section just for Wavelength. In particular, this section allows you to declare which Wavelength Zones are available in the regions.

The information configured on this screen is used by the Appearition Broker service when deciding the closed Edge Server connection to allocate to a device client. The Appearition Broker will lookup the incoming request from the client device to determine from which network the client is coming from and then find and allocate the relevant edge server. This screen allows to declare the exact network name which represents each Wavelength Zone. You can declare multiple network names for the same Wavelength Zone.

Appearition Broker

This is a key piece of infrastructure deployed as part of the Appearition Platform. It has the intelligence to discover from which network the client is coming from and allocate the closest available Edge Server.

Edge Machine Type#

This is a key feature of Edge Compute services offered by the Appearition Platform. An Edge Machine Type represents one EC2 instance that will be launched in a region. All of the application services required by the connecting client needs to be installed and running on the EC2 instance.

In AWS, an Edge Machine Type is represented as an AMI. It is up to developers building the end user client applications, to decide what application services need to be installed and running on the Edge Instance. As such, developers need to manually launch and setup an EC2 instance during the build phase of the project. They will instal and setup everything needed and then once tested and verified, will kake an AMI via the AWS console. When an AMI is created, it then needs to be tagged with the key Appearition.Edge.IsAmi and value True so that it becomes visible to the Appearition Platform in this section.

When adding a new Edge Machine Type, you need to choose the AMI from a “master” region. When an AWS AMI is created, it is only available within the region that it was created in. However, AWS offers the ability to copy AMIs to other regions. Hence the concept of “Master Region” in the screen, whereby you choose the region where the AMI was created. Subsequently, this screen allows you to choose the other regions where you want the AMI copied into. You must manually choose these other regions and the Appearition Platform will copy them for you.

Properties are a feature of this screen which allows you add any “KEY / VALUE” pair which can then be used by other components of the Appearition Platform.

The following table describes property keys which are used by the system when launching new instances or when returning service connections to a client.

Key Purpose Example
DefaultInstanceType When launching new EC2 instances of this machine type, the field for specifying the instance type will be default to this value. You will be able to override it before launching if you want. t2.micro
Ec2IamRoleArn When launching new EC2 instances of this type, you can associate an IAM Role to the instance. This property allows you to declare the AWS IAM Role ARN. Note: you can set the Ec2IamRoleName property instead, either will work. Note: Ec2IamRoleArn property takes priority over the Ec2IamRoleName property. arn:aws:iam::646168867975: role/MySpecialEc2Role
Ec2IamRoleName When launching new EC2 instances of this type, you can associate an IAM Role to the instance. This property allows you to declare the AWS IAM Role Name. Note: you can set the Ec2IamRoleArn property instead, either will work. Note: Ec2IamRoleArn property takes priority over the Ec2IamRoleName property. MySpecialEc2Role
AgentProtocol This acts as an override when the Appearition Broker service is fetching the connection details to the Appearition Agent WebAPI service. If you leave it null the broker will default to https http
DevAgentPrivateAddressHost This acts as an override when the Appearition Broker service is fetching the connection details to the Appearition Agent WebAPI service. If you leave it null the broker will default to the private address of the EC2 instance it finds closest to the client. Useful for developing or testing. localhost
DevAgentPrivateAddressPort This acts as an override when the Appearition Broker service is fetching the connection details to the Appearition Agent WebAPI service. If you leave it null the broker will default to 443 5555
DevAgentPublicAddressHost This acts as an override when the Appearition Broker service is fetching the connection details to the Appearition Agent WebAPI service. If you leave it null the broker will default to the public address of the EC2 instance it finds closest to the client. Useful for developing or testing. localhost
DevAgentPublicAddressPort This acts as an override when the Appearition Broker service is fetching the connection details to the Appearition Agent WebAPI service. If you leave it null the broker will default to 443 5556
Service0Name The Appearition Broker will by default return one connection to the client which is the WebAPI endpoint to the Appearition Agent running on the edge machine. However, an edge machine may host other services that a client can use, such as IOT, AR rending, AI.
The services available on the edge are dictated by this Edge Machine Type and whatever services are deployed as part of the image (AWS AMI) which the EC2 instance is launched from.
Hence, to instruct the broker to return connection details for each of the other services running on the box you can declare those services via these net set of properties.
To add multiple services, when you add the property, you can change the index part of the key to reflect the different service connection. It is a zero based index so if you want to add 2 services your property keys would look like this: Service.0.Name for the first service and Service.1.Name for the second service. 		RenderingWebSocket or IotWebSocket
Service0HostAddress Only set this if you want to override the host address that the Appearition Broker finds when seeking the closest server to the client. If you leave the value blank or not have this property, the Appearition Broker will use either the Public IP address of the EC2 instance or the DNS name it finds on it.
To add multiple services, when you add this property, change the index part of the key to reflect the different service connection. It is a zero based index so if you want to add 2 services your property keys would look like this: Service.0.HosAddress for the first service and Service.1.HostAddress for the second service.
Useful for developing or testing. 		localhost
Service0HostAddressIp Only set this if you want to override the public IP address that the Appearition Broker finds when seeking the closest server to the client. If you leave the value blank or not have this property, the Appearition Broker will use the Public IP address of the EC2 instance.
To add multiple services, when you add this property, change the index part of the key to reflect the different service connection. It is a zero based index so if you want to add 2 services your property keys would look like this: Service.0.HosAddressIp for the first service and Service.1.HostAddressIp for the second service.
Useful for developing or testing. 		127.0.0.1
Service0Port Only set this if you want to override the port that the Appearition Broker sets when returning the connection for this service. If your leave the value blank or not have this property, the Appearition Broker will default it to null.
To add multiple services, when you add this property, change the index part of the key to reflect the different service connection. It is a zero based index so if you want to add 2 services your property keys would look like this: Service.0.Port for the first service and Service.1.Port for the second service.
Useful for developing or testing. 		5555
Service0Protocol Only set this if you want to override the protocol that the Appearition Broker sets when returning the connection for this service. If your leave the value blank or not have this property, the Appearition Broker will default it to null.
To add multiple services, when you add this property, change the index part of the key to reflect the different service connection. It is a zero based index so if you want to add 2 services your property keys would look like this: Service.0.Protocol for the first service and Service.1.Protocol for the second service.
Useful for developing or testing. 		http

Channel Edge Machine Type#

Once all of the Edge Machine Types have been configured, you can then decide which of those are available to the channels within the tenant.

A channel can be use to represent different use case applications where each application can be uniquely different in terms of the features and functions it provides. As such, you must declare in this screen, which Edge Machine Type a channel is allowed to have.

You can set a default Edge Machine Type for all channels and then configure unique Edge Machine Types for individual channels.

Edge Instances#

Contact us for information

If you are interested in learning more about this section please reach out to us.