Connector Metadata

Overview

Twingate supports adding custom metadata as key-value pairs to Connectors when deploying them. Any metadata you add will be displayed in the Connector detail view in the Admin console.

For many of the deployment methods we’ve provided in the Admin console, we preset the hostname metadata value with the local hostname of the device the Connector is deployed on. This helps with identifying where the Connector in question has been deployed later on.

In many cases there is also a deployed_by label that indicates which deployment method has been used.

Setting custom metadata

Depending on the Connector deployment method, you will need to add your metadata to the script that is provided. In each case the goal is to have additional configuration options that are prefixed TWINGATE_LABEL_ followed by your choice of metadata suffix and the value. For example, if you wanted to add metadata to a Connector to indicate which development environment it was providing access to, you would add:

TWINGATE_LABEL_DEV_ENVIRONMENT=dev1

This would display in the Twingate Admin Console as Dev Environment: dev1, and any additional metadata would display below it on the left-hand side of the Connector page.

Examples

Twingate provides simple-to-use deployment scripts, and the metadata can be added to the script in the same way as you would add any other environment variable.

For example, if you were using the Docker script, it would initially look like this:

The highlighted section of the script shows existing environment variables for other metadata, automatically added by Twingate. Adding your own custom ones would look like this:

docker run -d
    --sysctl net.ipv4.ping_group_range="0 2147483647"
    --env TWINGATE_NETWORK="twindemo"
    --env TWINGATE_ACCESS_TOKEN=""
    --env TWINGATE_REFRESH_TOKEN=""
    --env TWINGATE_LABEL_HOSTNAME="`hostname`"
    --env TWINGATE_LABEL_DEPLOYED_BY="docker"
    --env TWINGATE_LABEL_CUSTOM_METADATA_1="custom_value_1"
    --env TWINGATE_LABEL_CUSTOM_METADATA_2="custom_value_2"
    --name "twingate-us-central"
    --restart=unless-stopped
    --pull=always
    twingate/connector:1

When the command is run, the two additional custom metadata environment variables will be included and then displayed in the Twingate Admin Console.

If you were deploying an ECS Fargate-based connector, it would by default look like this:

The highlighted section of the script shows the existing single environment variable being defined as part of the task. Adding additional custom ones would look like this:

aws ecs register-task-definition
    --region 
    --cli-input-json '{
        "requiresCompatibilities":["FARGATE"],
        "containerDefinitions":[{
            "name":"twingate-rigorous-inchworm",
            "image":"twingate/connector:1",
            "memory":2048,
            "cpu":1024,
            "environment":[{
                "name":"TWINGATE_NETWORK",
                "value":"twindemo"
            },{
                "name":"TWINGATE_ACCESS_TOKEN",
                "value":""
            },{
                "name":"TWINGATE_REFRESH_TOKEN",
                "value":""
            },{
                "name":"TWINGATE_LABEL_DEPLOYED_BY",
                "value":"ecs"
            },{
                "name":"TWINGATE_LABEL_CUSTOM_METADATA_1",
                "value":"custom_value_1"
            },{
                "name":"TWINGATE_LABEL_CUSTOM_METADATA_2",
                "value":"custom_value_2"
            }]
        }],
        "volumes":[],
        "networkMode":"awsvpc",
        "placementConstraints":[],
        "family":"twingate-rigorous-inchworm",
        "memory":"2048",
        "cpu":"1024"
     }'

When the command is run, the two additional custom metadata environment variables will be included and then displayed in the Twingate Admin Console.