Skip to main content

Implementation Guide

Not availableCloud Not availableSelf-Managed Community (OSS)AvailableSelf-Managed Enterprise

Airbyte Self-Managed Enterprise is in an early access stage for select priority users. Once you are qualified for a Self-Managed Enterprise license key, you can deploy Airbyte with the following instructions.

Airbyte Self-Managed Enterprise must be deployed using Kubernetes. This is to enable Airbyte's best performance and scale. The core components (api server, scheduler, etc) run as deployments while the scheduler launches connector-related pods on different nodes.

Prerequisites​

For a production-ready deployment of Self-Managed Enterprise, various infrastructure components are required. We recommend deploying to Amazon EKS or Google Kubernetes Engine. The following diagram illustrates a typical Airbyte deployment running on AWS:

AWS Architecture Diagram

Prior to deploying Self-Managed Enterprise, we recommend having each of the following infrastructure components ready to go. When possible, it's easiest to have all components running in the same VPC. The provided recommendations are for customers deploying to AWS:

ComponentRecommendation
Kubernetes ClusterAmazon EKS cluster running in 2 or more availability zones on a minimum of 6 nodes.
IngressAmazon ALB and a URL for users to access the Airbyte UI or make API requests.
Object StorageAmazon S3 bucket with two directories for log and state storage.
Dedicated DatabaseAmazon RDS Postgres with at least one read replica.
External Secrets ManagerAmazon Secrets Manager for storing connector secrets.

We also require you to install and configure the following Kubernetes tooling:

  1. Install helm by following these instructions
  2. Install kubectl by following these instructions.
  3. Configure kubectl to connect to your cluster by using kubectl use-context my-cluster-name:
Configure kubectl to connect to your cluster
  1. Configure your AWS CLI to connect to your project.
  2. Install eksctl.
  3. Run eksctl utils write-kubeconfig --cluster=$CLUSTER_NAME to make the context available to kubectl.
  4. Use kubectl config get-contexts to show the available contexts.
  5. Run kubectl config use-context $EKS_CONTEXT to access the cluster with kubectl.

Deploy Airbyte Enterprise​

Add Airbyte Helm Repository​

Follow these instructions to add the Airbyte helm repository:

  1. Run helm repo add airbyte https://airbytehq.github.io/helm-charts, where airbyte is the name of the repository that will be indexed locally.
  2. Perform the repo indexing process, and ensure your helm repository is up-to-date by running helm repo update.
  3. You can then browse all charts uploaded to your repository by running helm search repo airbyte.

Clone & Configure Airbyte​

  1. git clone the latest revision of the airbyte-platform repository

  2. Create a new airbyte.yml file in the configs directory of the airbyte-platform folder. You may also copy airbyte.sample.yml to use as a template:

cp configs/airbyte.sample.yml configs/airbyte.yml

  1. Add your Airbyte Self-Managed Enterprise license key to your airbyte.yml.

  2. Add your auth details to your airbyte.yml.

Configuring auth in your airbyte.yml file

To configure SSO with Okta, add the following at the end of your airbyte.yml file:

auth:   
    identity-providers:
        -   type: okta
            domain: $OKTA_DOMAIN
            app-name: $OKTA_APP_INTEGRATION_NAME
            client-id: $OKTA_CLIENT_ID
            client-secret: $OKTA_CLIENT_SECRET

See the following guide on how to collect this information for Okta.

To configure basic auth (deploy without SSO), remove the entire auth: section from your airbyte.yml config file. You will authenticate with the instance admin user and password included in the your airbyte.yml.

To modify auth configurations after Airbyte is installed, you will need to redeploy Airbyte with the additional environment variable RESET_KEYCLOAK_REALM=TRUE. As this also resets the list of Airbyte users and permissions, please use this with caution.

Configuring the Airbyte Database​

For Self-Managed Enterprise deployments, we recommend using a dedicated database instance for better reliability, and backups (such as AWS RDS or GCP Cloud SQL) instead of the default internal Postgres database (airbyte/db) that Airbyte spins up within the Kubernetes cluster.

info

Currently, Airbyte requires connection to a Postgres 13 instance.

We assume in the following that you've already configured a Postgres instance:

External database setup steps
  1. In the charts/airbyte/values.yaml file, disable the default Postgres database (airbyte/db):
postgresql:
    enabled: false
  1. In the charts/airbyte/values.yaml file, enable and configure the external Postgres database:
externalDatabase:   
    host: ## Database host
    user: ## Non-root username for the Airbyte database
    database: db-airbyte ## Database name
    port: 5432 ## Database port number

For the non-root user's password which has database access, you may use password, existingSecret or jdbcUrl. We recommend using existingSecret, or injecting sensitive fields from your own external secret store. Each of these parameters is mutually exclusive:

externalDatabase:
    ...
    password: ## Password for non-root database user
    existingSecret: ## The name of an existing Kubernetes secret containing the password.
    existingSecretPasswordKey: ## The Kubernetes secret key containing the password.
    jdbcUrl: "jdbc:postgresql://<user>:<password>@localhost:5432/db-airbyte" ## Full database JDBC URL. You can also add additional arguments.

The optional jdbcUrl field should be entered in the following format: jdbc:postgresql://localhost:5432/db-airbyte. We recommend against using this unless you need to add additional extra arguments can be passed to the JDBC driver at this time (e.g. to handle SSL).

Configuring External Logging​

For Self-Managed Enterprise deployments, we recommend spinning up standalone log storage for additional reliability using tools such as S3 and GCS instead of against using the defaul internal Minio storage (airbyte/minio). It's then a common practice to configure additional log forwarding from external log storage into your observability tool.

External log storage setup steps
  1. In the charts/airbyte/values.yaml file, disable the default Minio instance (airbyte/minio):
minio:
  enabled: false
  1. In the charts/airbyte/values.yaml file, enable and configure external log storage:
global:
    ...
    log4jConfig: "log4j2-no-minio.xml"

    logs:
        storage:
            type: "S3"
        
        minio:
            enabled: false

        s3:
            enabled: true
            bucket: "" ## S3 bucket name that you've created.
            bucketRegion: "" ## e.g. us-east-1

        accessKey: ## AWS Access Key.
            password: ""
            existingSecret: "" ## The name of an existing Kubernetes secret containing the AWS Access Key.
            existingSecretKey: "" ## The Kubernetes secret key containing the AWS Access Key.

        secretKey: ## AWS Secret Access Key
            password:
            existingSecret: "" ## The name of an existing Kubernetes secret containing the AWS Secret Access Key.
            existingSecretKey: "" ## The name of an existing Kubernetes secret containing the AWS Secret Access Key.

For each of accessKey and secretKey, the password and existingSecret fields are mutually exclusive.

  1. Ensure your access key is tied to an IAM user with the following policies, allowing the user access to S3 storage:
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action": "s3:ListAllMyBuckets",
         "Resource":"*"
      },
      {
         "Effect":"Allow",
         "Action":["s3:ListBucket","s3:GetBucketLocation"],
         "Resource":"arn:aws:s3:::YOUR-S3-BUCKET-NAME"
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:PutObjectAcl",
            "s3:GetObject",
            "s3:GetObjectAcl",
            "s3:DeleteObject"
         ],
         "Resource":"arn:aws:s3:::YOUR-S3-BUCKET-NAME/*"
      }
   ]
}

Configuring Ingress​

To access the Airbyte UI, you will need to manually attach an ingress configuration to your deployment. The following is a skimmed down definition of an ingress resource you could use for Self-Managed Enterprise:

Ingress configuration setup steps
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: # ingress name, example: enterprise-demo
  annotations:
    ingress.kubernetes.io/ssl-redirect: "false"
spec:
  rules:
  - host: # host, example: enterprise-demo.airbyte.com
    http:
      paths:
      - backend:
          service:
            # format is ${RELEASE_NAME}-airbyte-webapp-svc
            name: airbyte-pro-airbyte-webapp-svc 
            port:
              number: # service port, example: 8080
        path: /
        pathType: Prefix
      - backend:
          service:
            # format is ${RELEASE_NAME}-airbyte-keycloak-svc
            name: airbyte-pro-airbyte-keycloak-svc
            port:
              number: # service port, example: 8180
        path: /auth
        pathType: Prefix
      - backend:
          service:
            # format is ${RELEASE_NAME}-airbyte-api-server-svc
            name: airbyte-pro-airbyte-api-server-svc
            port:
              number: # service port, example: 8180
        path: /v1
        pathType: Prefix

Once this is complete, ensure that the value of the webapp-url field in your airbyte.yml is configured to match the ingress URL.

You may configure ingress using a load balancer or an API Gateway. We do not currently support most service meshes (such as Istio). If you are having networking issues after fully deploying Airbyte, please verify that firewalls or lacking permissions are not interfering with pod-pod communication. Please also verify that deployed pods have the right permissions to make requests to your external database.

Install Airbyte Enterprise​

Install Airbyte Enterprise on helm using the following command:

./tools/bin/install_airbyte_pro_on_helm.sh

The default release name is airbyte-pro. You can change this via the RELEASE_NAME environment variable.

Customizing your Airbyte Enterprise Deployment​

In order to customize your deployment, you need to create values.yaml file in a local folder and populate it with default configuration override values. A values.yaml example can be located in charts/airbyte folder of the Airbyte repository.

After specifying your own configuration, run the following command:

./tools/bin/install_airbyte_pro_on_helm.sh --values path/to/values.yaml
Was this page helpful?