Amazon Neptune
User Guide (API Version 2017-11-29)

Connect to Neptune Using the Gremlin Console with Version 4 Signing

This section shows how to connect to Neptune using the Gremlin Console with Signature Version 4 authentication.

Note

The maximum number of concurrent websocket connections per database instance is 60,000. When the limit is reached Neptune will throttle a request to open a new websocket connection.

If a client properly closes a connection then it will be reflected in the open connections count immediately. If the client does not close the connection then the connection will remain open until it is closed after a 60 minute idle timeout. The idle timeout is the time elapsed since the last message was received from the client.

WebSocket connections are disconnected 36 hours after the connection is established.

Prerequisites

To connect to Neptune using the Gremlin Console with Version 4 signing

  1. Download Gremlin Console (version 3.3.2+) from the Apache Tinkerpop3 website on to your EC2 instance.

  2. Unzip the Gremlin Console zip file.

    unzip apache-tinkerpop-gremlin-console-3.3.2-bin.zip
  3. Clone the sample repository from GitHub.

    git clone https://github.com/aws/amazon-neptune-gremlin-java-sigv4.git
  4. Change directory into amazon-neptune-gremlin-java-sigv4.

    cd amazon-neptune-gremlin-java-sigv4
  5. Build, package, and get the dependencies of the project.

    mvn package dependency:copy-dependencies
  6. Copy the package jar and all dependency jars to the Gremlin Console library directory.

    cp target/{*.jar,dependency/*.jar} ../apache-tinkerpop-gremlin-console-3.3.2/lib
  7. Remove conflicitng dependency jars in the Gremlin Console library directory.

    rm ../apache-tinkerpop-gremlin-console-3.3.2/lib/*2.4.11*jar
    rm ../apache-tinkerpop-gremlin-console-3.3.2/lib/netty-all-4.0.56.Final.jar
  8. Change directories into the unzipped Gremlin Console directory.

    cd ../apache-tinkerpop-gremlin-console-3.3.2
  9. In the conf subdirectory of the extracted directory, create a file named neptune-remote.yaml with the following text. Replace your-neptune-endpoint with the hostname or IP address of your Neptune DB instance. The square brackets ([ ]) are required.

    Note

    For information about finding the hostname of your Neptune DB instance, see the Amazon Neptune Endpoints section.

    hosts: [your-neptune-endpoint] port: 8182 connectionPool: { channelizer: org.apache.tinkerpop.gremlin.driver.SigV4WebSocketChannelizer} serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GryoMessageSerializerV3d0, config: { serializeResultToString: true }}
  10. Important

    You must provide IAM credentials to sign the requests. Type the following commands to set your credentials as environment variables, replacing the relevant items with your credentials.

    export AWS_ACCESS_KEY_ID=access_key_id export AWS_SECRET_ACCESS_KEY=secret_access_key export SERVICE_REGION=us-east-1|us-east-2|us-west-2|eu-west-1|eu-west-2|eu-central-1

    The Neptune Version 4 Signer uses the default credential provider chain. For additional methods of providing credentials, see Using the Default Credential Provider Chain.

    The SERVICE_REGION variable is required, even when using a credentials file.

  11. In a terminal, navigate to the Gremlin Console directory (apache-tinkerpop-gremlin-console-3.3.2-bin), and then type the following command to run the Gremlin Console.

    bin/gremlin.sh

    You should see the following output:

    \,,,/ (o o) -----oOOo-(3)-oOOo----- plugin activated: tinkerpop.server plugin activated: tinkerpop.utilities plugin activated: tinkerpop.tinkergraph gremlin>

    You are now at the gremlin> prompt. You will type the remaining steps at this prompt.

  12. At the gremlin> prompt, type the following to connect to the Neptune DB instance.

    :remote connect tinkerpop.server conf/neptune-remote.yaml
  13. At the gremlin> prompt, type the following to switch to remote mode. This sends all Gremlin queries to the remote connection.

    :remote console