This repository contains the source code for all Elastic connectors, developed by the Search team at Elastic. Use connectors to sync data from popular data sources to Elasticsearch.
These connectors are available to be self-managed on your own infrastructure.
Note
Managed connectors on Elastic Cloud Hosted are no longer available as of version 9.0.
ℹ️ For an overview of the steps involved in deploying connectors refer to Self-managed connectors in the official Elastic documentation.
To get started quickly with self-managed connectors using Docker Compose, check out this README file.
The main documentation for using connectors lives in the Elastic docs. You'll find the individual references for each connector there.
For everything to do with developing connectors, you'll find that here in this repo.
Since 8.12.0, you can manage connectors and sync jobs programmatically using APIs. Refer to the Connector API documentation.
Learn about our CLI tool in docs/CLI.md.
There are two directories that contain the relevant code for running a connector:
app/libs/
The app/ directory contains the primary connector service, as well as the individual data source implementations.
The libs/ directory is the home of the Connectors SDK, which is where the connectors framework is defined.
The Connectors SDK is a dependency of the connectors application. You can use the Connectors SDK in and of itself to create your own data source connectors without needing to ingest data into Elasticsearch.
Note
For those who are familiar with the monolithic project structure that preceded the current structure:
Functionality has not been affected in any way. The top-level project Makefile provides the same general commands as were previously present, and they will behave the same as before.
make run will run the Connectors code directly from source by calling the make run command defined under the app/ directory.
Furthermore, make docker-build and make docker-run commands will still build and run local Docker images.
As mentioned in the section above, the connector service code lives under the app/ directory. The code here defines tasks such as running connectors and managing scheduling, syncs, and cleanup.
This is shared code that is not used by individual connectors, but helps to coordinate and run a deployed instance/process.
The libs/ directory is home to the Elastic connector SDK. This SDK provides a framework that enables developers to build self-managed connectors.
The framework implements common functionalities out of the box, so developers can focus on the logic specific to integrating their chosen data source.
The framework ensures compatibility, makes it easier for our team to review PRs, and help out in the development process. When you build using our framework, we provide a pathway for the connector to be officially supported by Elastic.
This repo provides a set of scripts to allow a user to set up a full Elasticsearch, Kibana, and Connectors service stack using Docker. This is useful to get up and running with the Connectors framework with minimal effort, and provides a guided set of prompts for setup and configuration. For more information, instructions, and options, see the README file in the stack folder.
The framework serves two distinct, but related use cases:
- Customizing an existing Elastic connector client
- Building a new self-managed connector
- Code of Conduct
- Getting Support
- Releasing
- Developer guide
- Connectors Reference
- Security Policy
- Elastic-internal guide
- Connector Protocol
- Configuration
- Command line interface
- Contribution guide
- Upgrading
Note
Version compatibility is not checked when Elasticsearch is serverless (the connector service skips the check on startup).
The connector service compares its version to the configured Elasticsearch server on startup. If the versions are incompatible, the service exits and logs the mismatch. If the versions differ but are compatible, the service logs a warning and continues.
We recommend running the connector service on the same stack version as Elasticsearch. Use this table to decide whether a deliberate version skew is supported.
Do not downgrade the connector service to an older release than the one used when connectors were created. If you downgrade anyway, connector configuration stored in Elasticsearch may no longer match what the older service expects — you may need to recreate affected connectors.
| Situation | Example connector version | Example ES version | Outcome |
|---|---|---|---|
| Versions match | 8.15.1.0 | 8.15.1 | OK |
| Connector has a build suffix | 8.15.1.3 | 8.15.1 | OK |
| ES patch is newer | 8.15.0.0 | 8.15.1 | Warning |
| ES minor is newer | 8.14.2.0 | 8.15.0 | Warning |
| ES major is newer | 8.15.1.0 | 9.0.0 | Fatal error |
| ES patch is older | 8.15.1.0 | 8.15.0 | Warning |
| ES minor is older | 8.15.1.0 | 8.14.2 | Fatal error |
| ES major is older | 9.0.0.0 | 8.15.1 | Fatal error |