Redis connector reference

edit

Redis connector reference

edit

The Redis connector is built with the Elastic connectors Python framework and is available as a self-managed connector client. View the source code for this connector (branch 8.15, compatible with Elastic 8.15).

Availability and prerequisites

edit

This connector was introduced in Elastic 8.13.0, available as a self-managed connector client.

To use this connector, satisfy all connector client prerequisites. Importantly, you must deploy the connectors service on your own infrastructure. You have two deployment options:

This connector is in technical preview and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Technical preview features are not subject to the support SLA of official GA features.

Usage

edit

To set up this connector in the UI, select the Redis tile when creating a new connector under Search → Connectors.

For additional operations, see Using connectors.

Deploy with Docker

edit

You can deploy the Redis connector as a self-managed connector client using Docker. Follow these instructions.

Step 1: Download sample configuration file

Download the sample configuration file. You can either download it manually or run the following command:

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

Remember to update the --output argument value if your directory name is different, or you want to use a different config file name.

Step 2: Update the configuration file for your self-managed connector

Update the configuration file with the following settings to match your environment:

  • elasticsearch.host
  • elasticsearch.api_key
  • connectors

If you’re running the connector service against a Dockerized version of Elasticsearch and Kibana, your config file will look like this:

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: redis
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

Using the elasticsearch.api_key is the recommended authentication method. However, you can also use elasticsearch.username and elasticsearch.password to authenticate with your Elasticsearch instance.

Note: You can change other default configurations by simply uncommenting specific settings in the configuration file and modifying their values.

Step 3: Run the Docker image

Run the Docker image with the Connector Service using the following command:

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.15.2.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

Refer to DOCKER.md in the elastic/connectors repo for more details.

Find all available Docker images in the official registry.

We also have a quickstart self-managed option using Docker Compose, so you can spin up all required services at once: Elasticsearch, Kibana, and the connectors service. Refer to this README in the elastic/connectors repo for more information.

Configuration

edit
host (required)

The IP of your Redis server/cloud. Example:

  • 127.0.0.1
  • redis-12345.us-east-1.ec2.cloud.redislabs.com
port (required)

Port where the Redis server/cloud instance is hosted. Example:

  • 6379
username (optional)

Username for your Redis server/cloud. Example:

  • default
password (optional)

Password for your Redis server/cloud instance. Example:

  • changeme
database (required)

List of database index for your Redis server/cloud. * will fetch data from all databases. Example:

  • 0,1,2
  • *

    This field is ignored when using advanced sync rules.

ssl_enabled
Toggle to use SSL/TLS. Disabled by default.
mutual_tls_enabled
Toggle to use secure mutual SSL/TLS. Ensure that your Redis deployment supports mutual SSL/TLS connections. Disabled by default. Depends on ssl_enabled.
tls_certfile
Specifies the certificate from the Certificate Authority. The value of the certificate is used to validate the certificate presented by the Redis instance. Depends on mutual_tls_enabled.
tls_keyfile
Specifies the client private key. The value of the key is used to validate the connection in the Redis instance. Depends on mutual_tls_enabled.

Documents and syncs

edit

The connector syncs the following objects and entities:

  • KEYS and VALUES of every database index
  • Permissions are not synced. All documents indexed to an Elastic deployment will be visible to all users with access to the relevant Elasticsearch index.

Sync rules

edit

Basic sync rules are identical for all connectors and are available by default.

Advanced Sync Rules

edit

Advanced sync rules are defined through a source-specific DSL JSON snippet.

Use advanced sync rules to filter data at the Redis source, without needing to index all data into Elasticsearch.

They take the following parameters:

  1. database: Specify the Redis database index as an integer value.
  2. key_pattern: 2. key_pattern: Pattern for finding keys in Redis.
  3. type: Key type for the Redis.

    Supported values:

    • HASH
    • LIST
    • SET
    • STREAM
    • STRING
    • ZSET

Provide at least one of the following: key_pattern or type, or both.

Advanced sync rules examples

edit
Example 1
edit

Fetch database records where keys start with alpha:

[
  {
    "database": 0,
    "key_pattern": "alpha*"
  }
]
Example 2
edit

Fetch database records with exact match by specifying the full key name:

[
  {
    "database": 0,
    "key_pattern": "alpha"
  }
]
Example 3
edit

Fetch database records where keys start with test1, test2 or test3:

[
  {
    "database": 0,
    "key_pattern": "test[123]"
  }
]
Example 4
edit

Exclude database records where keys start with test1, test2 or test3:

[
  {
    "database": 0,
    "key_pattern": "test[^123]"
  }
]
Example 5
edit

Fetch all database records:

[
  {
    "database": 0,
    "key_pattern": "*"
  }
]
Example 6
edit

Fetch all database records where type is SET:

[
  {
    "database": 0,
    "key_pattern": "*",
    "type": "SET"
  }
]
Example 7
edit

Fetch database records where type is SET:

[
  {
    "database": 0,
    "type": "SET"
  }
]

Connector Client operations

edit

End-to-end Testing

edit

The connector framework enables operators to run functional tests against a real data source, using Docker Compose. You don’t need a running Elasticsearch instance or Redis source to run this test.

Refer to Connector testing for more details.

To perform E2E testing for the Redis connector, run the following command:

$ make ftest NAME=redis

For faster tests, add the DATA_SIZE=small flag:

make ftest NAME=redis DATA_SIZE=small

By default, DATA_SIZE=MEDIUM.

Known issues

edit
  • The last modified time is unavailable when retrieving keys/values from the Redis database. As a result, all objects are indexed each time an advanced sync rule query is executed.

Refer to Known issues for a list of known issues for all connectors.

Troubleshooting

edit

See Troubleshooting.

Security

edit

See Security.