Step 8: Build and run the Amazon Kinesis Video Streams Edge Agent - Amazon Kinesis Video Streams
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Step 8: Build and run the Amazon Kinesis Video Streams Edge Agent

Build and run the Amazon Kinesis Video Streams Edge Agent

  1. Download the tar file using the link that was provided to you.

    If you completed the Amazon Kinesis Video Streams Edge Agent interest form, check your email for the download link. If you haven't completed the form, complete it here.

  2. Verify the checksum.

  3. Extract the binaries and jar in your device.

    Type: tar -xvf kvs-edge-agent.tar.gz.

    After extraction, your folder structure will look like the following:

    kvs-edge-agent/LICENSE
kvs-edge-agent/THIRD-PARTY-LICENSES
kvs-edge-agent/pom.xml
kvs-edge-agent/KvsEdgeComponent
kvs-edge-agent/KvsEdgeComponent/recipes
kvs-edge-agent/KvsEdgeComponent/recipes/recipe.yaml
kvs-edge-agent/KvsEdgeComponent/artifacts
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/edge_log_config
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/kvs-edge-agent.jar
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/libgstkvssink.so
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/libIngestorPipelineJNI.so
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/libcproducer.so
kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/libKinesisVideoProducer.so
    Note

    The release folder name should be set up in a way that reflects the latest binary release number. For example, a 1.0.0 release will have the folder name set as 1.0.0.

  4. Build the dependencies jar.

    Note

    The jar included with the kvs-edge-agent.tar.gz does not have the dependencies. Use the following steps to build those libraries.

    Navigate to the kvs-edge-agent folder that contains pom.xml.

    Type mvn clean package.

    This generates a jar file containing the dependencies the Amazon Kinesis Video Streams Edge Agent requires at kvs-edge-agent/target/libs.jar.

  5. Place the libs.jar into the folder that contains the component's artifacts.

    Type mv ./target/libs.jar ./KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/.

  6. Set environment variables using the values from previous steps. The following table provides descriptions for the variables.

    Environment Variable Name Required Description

    AWS_REGION

    Yes

    The Region that is used.

    Example: us-west-2

    AWS_IOT_CA_CERT

    Yes

    File path to the CA certificate used to establish trust with the backend service through TLS.

    Example: /file/path/to/AmazonRootCA1.pem

    AWS_IOT_CORE_CERT

    Yes

    File path to the X.509 certificate.

    Example: /file/path/to/certificateID-certificate.pem.crt

    AWS_IOT_CORE_CREDENTIAL_ENDPOINT

    Yes

    The Amazon IoT Core credential endpoint provider endpoint for your Amazon account.

    Example: credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com

    AWS_IOT_CORE_DATA_ATS_ENDPOINT

    Yes

    The Amazon IoT Core data plane endpoint for your Amazon account.

    Example: data-account-specific-prefix.iot.aws-region.amazonaws.com

    AWS_IOT_CORE_PRIVATE_KEY

    Yes

    File path to the private key used in the public/private key pair. For more information, see Key management in Amazon IoT.

    Example: /file/path/to/certificateID-private.pem.key

    AWS_IOT_CORE_ROLE_ALIAS

    Yes

    The name of the role alias pointing to the Amazon IAM role to use when connecting to Amazon IoT Core.

    Example: kvs-edge-role-alias

    AWS_IOT_CORE_THING_NAME

    Yes

    The name of the Amazon IoT thing that the application is being run on.

    Example: my-edge-device-thing

    GST_PLUGIN_PATH

    Yes

    File path pointing to the folder that contains the gstkvssink and IngestorPipelineJNI platform-dependent libraries. Lets GStreamer load these plugins. For more information, see Download, Build, and Configure the GStreamer Element.

    Example: /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/

    LD_LIBRARY_PATH

    Yes

    File path pointing to the directory containing the cproducer and KinesisVideoProducer platform-dependent libraries.

    Example: /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion/lib/

    AWS_KVS_EDGE_CLOUDWATCH_ENABLED

    No

    Determines if the Amazon Kinesis Video Streams Edge Agent will post job health metrics onto Amazon CloudWatch.

    Accepted values: TRUE/FALSE (case insensitive). Defaults to FALSE if not provided.

    Example: FALSE

    AWS_KVS_EDGE_LOG_LEVEL

    No

    The level of logging the Amazon Kinesis Video Streams Edge Agent outputs.

    Accepted values:

    • OFF

    • ALL

    • FATAL

    • ERROR

    • WARN

    • INFO, default, if not provided

    • DEBUG

    • TRACE

    Example: INFO

    AWS_KVS_EDGE_LOG_MAX_FILE_SIZE

    No

    Once the log file reaches this size, a rollover will occur.

    • Min: 0

    • Max: 10000

    • Default: 20, if not provided

    • Units: Megabytes (MB)

    Example: 5

    AWS_KVS_EDGE_LOG_OUTPUT_DIRECTORY

    No

    The file path pointing to the directory where the Amazon Kinesis Video Streams Edge Agent logs are output. Defaults to ./log if not provided.

    Example: /file/path/

    AWS_KVS_EDGE_LOG_ROLLOVER_COUNT

    No

    The number of rolled-over logs to keep before deleting.

    • Min: 1

    • Max: 100

    • Default: 10, if not provided

    Example: 20

    AWS_KVS_EDGE_RECORDING_DIRECTORY

    No

    File path pointing to the directory recorded media will be written to. Defaults to the current directory if not provided.

    Example: /file/path/

    GST_DEBUG

    No

    Specifies the level of GStreamer logs to output. For more information, see the GStreamer documentation.

    Example: 0

    GST_DEBUG_FILE

    No

    Specifies the output file of the GStreamer debug logs. If unset, debug logs get output to standard error. For more information, see the GStreamer documentation.

    Example: /tmp/gstreamer-logging.log

  7. Clear the GStreamer cache. Type:

    rm ~/.cache/gstreamer-1.0/registry.your-os-architecture.bin

    For more information, see the GStreamer registry documentation.

  8. Prepare and run the java command. The Amazon Kinesis Video Streams Edge Agent accepts the following arguments:

    Java Property Name Required Description

    java.library.path

    No

    File path pointing to the folder containing the gstkvssink and IngestorPipelineJNI dependent libraries. If not provided, the Amazon Kinesis Video Streams Edge Agent will search for them in the current directory.

    Important

    The Amazon Kinesis Video Streams Edge Agent won't function correctly if it can't locate these files.

    Example: /file/path/

    To set these, add -Djava-property-name=value to the java command used to run the jar.

    For example:

    java -Djava.library.path=/download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion \
  --add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
  -Dio.netty.tryReflectionSetAccessible=true \
  -cp kvs-edge-agent.jar:libs.jar \
  com.amazonaws.kinesisvideo.edge.controller.ControllerApp
    Important

    Run the java command above from the same directory as /download-location/kvs-edge-agent/KvsEdgeComponent/artifacts/aws.kinesisvideo.KvsEdgeComponent/EdgeAgentVersion.

  9. Send configurations to the application using the Amazon CLI.

    1. Create a new file, example-edge-configuration.json.

      Paste the following code into the file. This is a sample configuration that records daily from 9:00:00 AM to 4:59:59 PM (according to the system time on your Amazon IoT device). It also uploads the recorded media daily from 7:00:00 PM to 9:59:59 PM.

      For more information, see StartEdgeConfigurationUpdate.

      {
    "StreamARN": "arn:aws:kinesisvideo:your-region:your-account-id:stream/your-stream/0123456789012",
    "EdgeConfig": {
        "HubDeviceArn": "arn:aws:iot:your-region:your-account-id:thing/kvs-edge-agent-demo",
        "RecorderConfig": {
            "MediaSourceConfig": {
                "MediaUriSecretArn": "arn:aws:secretsmanager:your-region:your-account-id:secret:your-secret-dRbHJQ",
                "MediaUriType": "RTSP_URI"
            },
            "ScheduleConfig": {
                "ScheduleExpression": "0 0 9,10,11,12,13,14,15,16 ? * * *",
                "DurationInSeconds": 3599
            }
        },
        "UploaderConfig": {
            "ScheduleConfig": {
                "ScheduleExpression": "0 0 19,20,21 ? * * *",
                "DurationInSeconds": 3599
            }
        },
        "DeletionConfig": {
            "EdgeRetentionInHours": 15,
            "LocalSizeConfig": {
              "MaxLocalMediaSizeInMB": 2800,
              "StrategyOnFullSize": "DELETE_OLDEST_MEDIA"
            },
            "DeleteAfterUpload": true
        }
    }
}

    2. To send the file to the Amazon Kinesis Video Streams Edge Agent, type the following in the Amazon CLI:

      aws kinesisvideo start-edge-configuration-update --cli-input-json "file://example-edge-configuration.json"

  10. Repeat the previous step for each stream for the Amazon Kinesis Video Streams Edge Agent.