diff --git a/docs/ai-agents/assets/embedded-workspaces.png b/docs/ai-agents/assets/embedded-workspaces.png
index 6e216612b4dd..d73e118e6851 100644
Binary files a/docs/ai-agents/assets/embedded-workspaces.png and b/docs/ai-agents/assets/embedded-workspaces.png differ
diff --git a/docs/ai-agents/embedded/widget/assets/embedded-workspaces.png b/docs/ai-agents/embedded/widget/assets/embedded-workspaces.png
index 6e216612b4dd..d73e118e6851 100644
Binary files a/docs/ai-agents/embedded/widget/assets/embedded-workspaces.png and b/docs/ai-agents/embedded/widget/assets/embedded-workspaces.png differ
diff --git a/docs/ai-agents/embedded/widget/managing-embedded.md b/docs/ai-agents/embedded/widget/managing-embedded.md
index f8dd34842ebe..05eedd224be8 100644
--- a/docs/ai-agents/embedded/widget/managing-embedded.md
+++ b/docs/ai-agents/embedded/widget/managing-embedded.md
@@ -10,7 +10,6 @@ Airbyte Embedded is built upon the Airbyte Platform. As the owner of your embedd
-
## Enabling Connectors within the Widget
Source connectors can be configured to appear in the Embedded widget by creating a configuration template [via the source_template endpoint](https://api.airbyte.ai/api/v1/docs#tag/Template-Sources/operation/create_integrations_templates_sources).
diff --git a/docs/integrations/custom-connectors.md b/docs/integrations/custom-connectors.md
index 69fa77f3a091..09c575e603b3 100644
--- a/docs/integrations/custom-connectors.md
+++ b/docs/integrations/custom-connectors.md
@@ -38,6 +38,14 @@ See the following guides for more information on building custom Airbyte Docker
## Upgrading a connector
+Follow these steps to upgrade a connector version.
+
+1. In the navigaton bar, click **Workspace settings** > **Sources**/**Destinations**.
+
+2. Find your connector in the list and click the edit button .
+
+3. In the dialog, update the Docker image tag to the new version.
+
To upgrade your connector version, go to the Settings in the left hand side of the UI and navigate to either Sources or Destinations. Find your connector in the list, and input the latest connector version.
diff --git a/docs/integrations/sources/asana-migrations.md b/docs/integrations/sources/asana-migrations.md
index c22091ee1b06..d608543b305e 100644
--- a/docs/integrations/sources/asana-migrations.md
+++ b/docs/integrations/sources/asana-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Asana Migration Guide
## Upgrading to 1.0.0
@@ -7,52 +9,8 @@ As part of our commitment to delivering exceptional service, we are transitionin
This is part of a strategic move to streamline many processes across connectors, bolstering maintainability and freeing us to focus more of our efforts on improving the performance and features of our evolving platform and growing catalog.
However, due to differences between the Python and low-code CDKs, this migration constitutes a breaking change.
-This release introduces an updated data type of the `name` field in the `events` stream. Users will need to reset this stream after upgrading.
-
-## Connector Upgrade Guide
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Gitlab in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+This release introduces an updated data type of the `name` field in the `events` stream. You must clear this stream after upgrading.
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+## Connector upgrade guide
+
diff --git a/docs/integrations/sources/gitlab-migrations.md b/docs/integrations/sources/gitlab-migrations.md
index de44352f727e..57f10979cba2 100644
--- a/docs/integrations/sources/gitlab-migrations.md
+++ b/docs/integrations/sources/gitlab-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Gitlab Migration Guide
## Upgrading to 4.0.0
@@ -10,104 +12,18 @@ However, due to differences between the Python and low-code CDKs, this migration
The primary key was changed for streams `group_members`, `group_labels`, `project_members`, `project_labels`, `branches`, and `tags`.
Users will need to reset the affected streams after upgrading.
-## Connector Upgrade Guide
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Gitlab in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
-
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
## Upgrading to 3.0.0
In this release, `merge_request_commits` stream schema has been fixed so that it returns commits for each merge_request.
Users will need to refresh the source schema and reset `merge_request_commits` stream after upgrading.
-## Connector Upgrade Guide
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Gitlab in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
+
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
## Upgrading to 2.0.0
diff --git a/docs/integrations/sources/jira-migrations.md b/docs/integrations/sources/jira-migrations.md
index 816cd4408772..cfda33a4a1a7 100644
--- a/docs/integrations/sources/jira-migrations.md
+++ b/docs/integrations/sources/jira-migrations.md
@@ -11,14 +11,7 @@ Users who do not have this stream enabled will not be affected and can safely up
3. Disable the `pull_requests` stream
4. In the main navbar, navigate to the **Sources** tab and select the affected Jira source. Set the `enable_experimental_streams` field to false and save your changes.
-:::note
-For **OSS users**, the **Pull Request** stream can still be synced by pinning this source to an earlier version:
-
-1. Select **Settings** in the main navbar.
-2. Select **Sources**, edit the entry for `source-jira` and set the **Default Version** to `3.5.4`
-
-This feature is not available in **Airbyte Cloud**
-:::
+If you're a self-managed user and can't upgrade to the new version yet, you can pin the connector to a specific version. [Help managing upgrades](/platform/next/managing-airbyte/connector-updates).
## Upgrading to 3.0.0
diff --git a/docs/integrations/sources/metabase-migrations.md b/docs/integrations/sources/metabase-migrations.md
index c2988c1d0bc2..7465daf8170d 100644
--- a/docs/integrations/sources/metabase-migrations.md
+++ b/docs/integrations/sources/metabase-migrations.md
@@ -1,52 +1,11 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Metabase Migration Guide
## Upgrading to 2.0.0
Source Metabase has updated the `dashboards` stream's endpoint due to the previous endpoint being deprecated by the service. The new version no longer returns the `creator` field for the `dashboards` stream.
-## Connector Upgrade Guide
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Metabase in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main navbar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
diff --git a/docs/integrations/sources/mixpanel-migrations.md b/docs/integrations/sources/mixpanel-migrations.md
index 974c8609cc65..b4f077e97f2d 100644
--- a/docs/integrations/sources/mixpanel-migrations.md
+++ b/docs/integrations/sources/mixpanel-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Mixpanel Migration Guide
## Upgrading to 3.0.0
@@ -13,52 +15,9 @@ To gracefully handle these changes for your existing connections, we highly reco
To add start date filtering for the `Cohorts`, `CohortMembers`, and `Engage` streams, the default retrieval range has been updated from all existing records to only include records created within the past year if start date not provided.
:::
-## Migration Steps
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find `Mixpanel` in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
## Upgrading to 2.0.0
diff --git a/docs/integrations/sources/monday-migrations.md b/docs/integrations/sources/monday-migrations.md
index 492879a984f7..0fcc9af788a8 100644
--- a/docs/integrations/sources/monday-migrations.md
+++ b/docs/integrations/sources/monday-migrations.md
@@ -1,69 +1,11 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Monday Migration Guide
## Upgrading to 2.0.0
Source Monday has deprecated API version 2023-07. We have upgraded the connector to the latest API version 2024-01. In this new version, the Id field has changed from an integer to a string in the streams Boards, Items, Tags, Teams, Updates, Users and Workspaces. Please reset affected streams.
-## Connector Upgrade Guide
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Monday in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh schemas and reset data
-
-1. Select **Connections** in the main navbar.
-2. Select the connection(s) affected by the update.
-3. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-4. Select **Save changes** at the bottom of the page.
- 1. Ensure the **Reset all streams** option is checked.
-5. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
-
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main navb nar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab. 1. Select **Refresh source schema**. 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page. 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
diff --git a/docs/integrations/sources/pinterest-migrations.md b/docs/integrations/sources/pinterest-migrations.md
index 155215d32fb5..e63363efff08 100644
--- a/docs/integrations/sources/pinterest-migrations.md
+++ b/docs/integrations/sources/pinterest-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Pinterest Migration Guide
## Upgrading to 2.0.0
@@ -21,48 +23,9 @@ This change will affect the following streams:
To gracefully handle these changes for your existing connections, we highly recommend resetting your data before resuming your data syncs with the new version.
-## Migration Steps
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Pinterest in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Schema** tab.
-3. Uncheck all streams except the affected ones.
-4. Select **Save changes** at the bottom of the page.
-5. Select the **Settings** tab.
-6. Press the **Clear your data** button.
-7. Return to the **Schema** tab.
-8. Check all your streams.
-9. Select **Sync now** to sync your data
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
## Upgrading to 1.0.0
diff --git a/docs/integrations/sources/postgres/assets/airbyte_postgres_source.png b/docs/integrations/sources/postgres/assets/airbyte_postgres_source.png
deleted file mode 100644
index 4e9db9c4067c..000000000000
Binary files a/docs/integrations/sources/postgres/assets/airbyte_postgres_source.png and /dev/null differ
diff --git a/docs/integrations/sources/postgres/assets/airbyte_source_selection.png b/docs/integrations/sources/postgres/assets/airbyte_source_selection.png
deleted file mode 100644
index 901bed4ab9f2..000000000000
Binary files a/docs/integrations/sources/postgres/assets/airbyte_source_selection.png and /dev/null differ
diff --git a/docs/integrations/sources/postgres/cloud-sql-postgres.md b/docs/integrations/sources/postgres/cloud-sql-postgres.md
index cdf39850ed67..439e8046322a 100644
--- a/docs/integrations/sources/postgres/cloud-sql-postgres.md
+++ b/docs/integrations/sources/postgres/cloud-sql-postgres.md
@@ -1,14 +1,14 @@
# Cloud SQL for PostgreSQL
-Airbyte's certified Postgres connector offers the following features:
+Airbyte's certified Postgres connector offers the following features.
- Multiple methods of keeping your data fresh, including [Change Data Capture (CDC)](/platform/understanding-airbyte/cdc) and replication using the [xmin system column](/integrations/sources/postgres#xmin).
-- All available [sync modes](/platform/using-airbyte/core-concepts/sync-modes), providing flexibility in how data is delivered to your destination.
-- Reliable replication at any table size with [checkpointing](/platform/understanding-airbyte/airbyte-protocol/#state--checkpointing) and chunking of database reads.
-
+- All available [sync modes](/platform/using-airbyte/core-concepts/sync-modes), providing flexibility in how Airbyte delivers data to your destination.
+
+- Reliable replication at any table size with [checkpointing](/platform/understanding-airbyte/airbyte-protocol/#state--checkpointing) and chunking of database reads.
-## Quick Start
+## Quick start
@@ -20,29 +20,27 @@ Here is an outline of the minimum required steps to configure a connection to Po
Once this is complete, you will be able to select Postgres as a source for replicating data.
-#### Step 1: Create a dedicated read-only Postgres user
+### Step 1: Create a dedicated read-only Postgres user
These steps create a dedicated read-only user for replicating data. Alternatively, you can use an existing Postgres user in your database. To create a user, first [connect to your database](https://cloud.google.com/sql/docs/postgres/connect-overview#external-connection-methods). If you are getting started, you can use [Cloud Shell to connect directly from the UI](https://cloud.google.com/sql/docs/postgres/connect-instance-cloud-shell).
The following commands will create a new user:
-```roomsql
+```sql
CREATE USER PASSWORD 'your_password_here';
```
Now, provide this user with read-only access to relevant schemas and tables. Re-run this command for each schema you expect to replicate data from (e.g. `public`):
-```roomsql
+```sql
GRANT USAGE ON SCHEMA TO ;
GRANT SELECT ON ALL TABLES IN SCHEMA TO ;
ALTER DEFAULT PRIVILEGES IN SCHEMA GRANT SELECT ON TABLES TO ;
```
-#### Step 2: Create a new Postgres source in Airbyte UI
-
-From your [Airbyte Cloud](https://cloud.airbyte.com/workspaces) or Airbyte Open Source account, select `Sources` from the left navigation bar, search for `Postgres`, then create a new Postgres source.
+### Step 2: Create a new Postgres source in Airbyte UI
-
+In Airbyte, click **Sources** from the left navigation bar, search for `Postgres`, then create a new Postgres source.
To fill out the required information:
@@ -55,13 +53,13 @@ To fill out the required information:
-#### Step 3: (Airbyte Cloud Only) Allow inbound traffic from Airbyte IPs.
+### Step 3: (Airbyte Cloud Only) Allow inbound traffic from Airbyte IPs
If you are on Airbyte Cloud, you will always need to modify your database configuration to allow inbound traffic from Airbyte IPs. To allowlist IPs in Cloud SQL:
1. In your Google Cloud SQL database dashboard, select `Connections` from the left menu. Then, select `Add Network` under the `Connectivity` section.
-
+ 
2. Add a new network, and enter the Airbyte's IPs, which you can find in our [Airbyte Security documentation](../../../platform/operating-airbyte/security#network-security-1).
@@ -69,9 +67,7 @@ Now, click `Set up source` in the Airbyte UI. Airbyte will now test connecting t
-## Advanced Configuration
-
-### Setup using CDC
+## Advanced: Setup using CDC
Airbyte uses [logical replication](https://www.postgresql.org/docs/10/logical-replication.html) of the Postgres write-ahead log (WAL) to incrementally capture deletes using a replication plugin:
@@ -84,7 +80,7 @@ We recommend configuring your Postgres source with CDC when:
- You have a very large database (500 GB or more).
- Your table has a primary key but doesn't have a reasonable cursor field for incremental syncing (`updated_at`).
-These are the additional steps required (after following the [quick start](#quick-start)) to configure your Postgres source using CDC:
+These are the additional steps required after [following the quick start](#quick-start) to configure your Postgres source using CDC:
1. Provide additional `REPLICATION` permissions to read-only user
2. Enable logical replication on your Postgres database
@@ -92,56 +88,58 @@ These are the additional steps required (after following the [quick start](#quic
4. Create publication and replication identities for each Postgres table
5. Enable CDC replication in the Airbyte UI
-#### Step 1: Prepopulate your Postgres source configuration
+### Step 1: Prepopulate your Postgres source configuration
We recommend following the steps in the [quick start](#quick-start) section to confirm that Airbyte can connect to your Postgres database prior to configuring CDC settings.
For CDC, you may connect to primary/master databases. To use a replica as source, which is available starting from Postgres 16.1, and provided additional configurations have been enabled on the database instance (please visit [Postgres official documentation](https://www.postgresql.org/docs/current/warm-standby.html#CASCADING-REPLICATION)), the most recent required connector's version is 3.6.21.
-
-#### Step 2: Provide additional permissions to read-only user
+### Step 2: Provide additional permissions to read-only user
To configure CDC for the Postgres source connector, grant `REPLICATION` permissions to the user created in [step 1 of the quick start](#step-1-create-a-dedicated-read-only-postgres-user):
-```
+```sql
ALTER USER REPLICATION;
```
-#### Step 3: Enable logical replication on your Postgres database
+### Step 3: Enable logical replication on your Postgres database
To enable logical replication on Cloud SQL for Postgres, set the `cloudsql.logical_decoding` flag to on. You can find the `Flags` section in the `Edit Configuration` view of your database:
-#### Step 4: Create a replication slot on your Postgres database
+### Step 4: Create a replication slot on your Postgres database
Airbyte requires a replication slot configured only for its use. Only one source should be configured that uses this replication slot.
For this step, Airbyte requires use of the pgoutput plugin. To create a replication slot called `airbyte_slot` using pgoutput, provide the instance superuser (default `postgres`) with `REPLICATION` permissions, and run the following:
-```
+```sql
ALTER user postgres with REPLICATION;
SELECT pg_create_logical_replication_slot('airbyte_slot', 'pgoutput');
```
The output of this command will include the name of the replication slot to fill into the Airbyte source setup page.
-#### Step 5: Create publication and replication identities for each Postgres table
+### Step 5: Create publication and replication identities for each Postgres table
For each table you want to replicate with CDC, follow the steps below:
1. Add the replication identity (the method of distinguishing between rows) for each table you want to replicate:
-```
-ALTER TABLE tbl1 REPLICA IDENTITY DEFAULT;
-```
+ ```sql
+ ALTER TABLE tbl1 REPLICA IDENTITY DEFAULT;
+ ```
+
+ In rare cases, if your tables use data types that support [TOAST](https://www.postgresql.org/docs/current/storage-toast.html) or have very large field values, consider instead using replica identity type full:
-In rare cases, if your tables use data types that support [TOAST](https://www.postgresql.org/docs/current/storage-toast.html) or have very large field values, consider instead using replica identity type full: `
-ALTER TABLE tbl1 REPLICA IDENTITY FULL;`.
+ ```sql
+ ALTER TABLE tbl1 REPLICA IDENTITY FULL;
+ ```
2. Create the Postgres publication. You should include all tables you want to replicate as part of the publication:
-```
+```sql
CREATE PUBLICATION airbyte_publication FOR TABLE tbl1, tbl2, tbl3;`
```
@@ -151,7 +149,7 @@ The publication name is customizable. Refer to the [Postgres docs](https://www.p
The Airbyte UI currently allows selecting any tables for CDC. If a table is selected that is not part of the publication, it will not be replicated even though it is selected. If a table is part of the publication but does not have a replication identity, that replication identity will be created automatically on the first run if the Airbyte user has the necessary permissions.
:::
-#### Step 6: Enable CDC replication in Airbyte UI
+### Step 6: Enable CDC replication in Airbyte UI
In your Postgres source, change the replication mode to `Logical Replication (CDC)`, and enter the replication slot and publication you just created.
@@ -166,3 +164,7 @@ See [these instructions](https://docs.airbyte.com/integrations/sources/postgres#
## Limitations & Troubleshooting
To see connector limitations, or troubleshoot your Postgres connector, see more [in our Postgres troubleshooting guide](https://docs.airbyte.com/integrations/sources/postgres/postgres-troubleshooting).
+
+## Changelog
+
+See [Postgres](../postgres.md).
diff --git a/docs/integrations/sources/recurly-migrations.md b/docs/integrations/sources/recurly-migrations.md
index 24b0b88c642e..74b3fc0b6704 100644
--- a/docs/integrations/sources/recurly-migrations.md
+++ b/docs/integrations/sources/recurly-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Recurly Migration Guide
## Upgrading to 1.0.0
@@ -8,50 +10,6 @@ While our intention was to make these updates as seamless as possible, we've obs
Once you have migrated to the new version, we highly recommend all users refresh their schemas and reset their data before resuming syncs
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users with existing connections must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Recurly in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh schemas and reset data
-
-1. Select **Connections** in the main navbar.
-2. Select the connection(s) affected by the update.
-3. Select the **Replication** tab.
- 1. Select **Refresh source schema**.
- 2. Select **OK**.
-
-:::note
-Any detected schema changes will be listed for your review.
-:::
-
-4. Select **Save changes** at the bottom of the page.
- 1. Ensure the **Reset all streams** option is checked.
-5. Select **Save connection**.
-
-:::note
-This will reset the data in your destination and initiate a fresh sync.
-:::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
diff --git a/docs/integrations/sources/sendgrid-migrations.md b/docs/integrations/sources/sendgrid-migrations.md
index e8de83634780..250c500ea4f9 100644
--- a/docs/integrations/sources/sendgrid-migrations.md
+++ b/docs/integrations/sources/sendgrid-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Sendgrid Migration Guide
## Upgrading to 1.0.0
@@ -14,44 +16,6 @@ to our new low-code framework improving maintainability and reliability of the c
To ensure a smooth upgrade, please clear your streams and trigger a sync to bring in historical data.
-## Migration Steps
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Sendgrid in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### For Airbyte Cloud and Open Source: Steps to Update Schema and Clear Streams
-
-To clear your data for the affected streams, follow the steps below:
-
-1. Select **Connections** in the main navbar and select the connection(s) affected by the update.
-2. Select the **Schema** tab.
- 1. Select **Refresh source schema** to bring in any schema changes. Any detected schema changes will be listed for your review.
- 2. Select **OK** to approve changes.
-3. Select **Save changes** at the bottom of the page.
- 1. Ensure the **Clear affected streams** option is checked to ensure your streams continue syncing successfully with the new schema.
-4. Select **Save connection**.
+## Connector upgrade guide
-This will clear the data in your destination for the subset of streams with schema changes. After the clear succeeds, trigger a sync by clicking **Sync Now**. For more information on clearing your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
diff --git a/docs/integrations/sources/zendesk-chat-migrations.md b/docs/integrations/sources/zendesk-chat-migrations.md
index 3d6af4a4b801..702774c44514 100644
--- a/docs/integrations/sources/zendesk-chat-migrations.md
+++ b/docs/integrations/sources/zendesk-chat-migrations.md
@@ -1,33 +1,13 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Zendesk Chat Migration Guide
## Upgrading to 1.0.0
The Live Chat API [changed its URL structure](https://developer.zendesk.com/api-reference/live-chat/introduction/) to use the Zendesk subdomain.
-The `subdomain` field of the connector configuration is now required.
+The `subdomain` field of the connector configuration is now required.
You can find your Zendesk subdomain by following instructions [here](https://support.zendesk.com/hc/en-us/articles/4409381383578-Where-can-I-find-my-Zendesk-subdomain).
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- - Select **Sources**.
-2. Find Zendesk Chat in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### For Airbyte Cloud: Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
+## Connector upgrade guide
-3. Select **Upgrade**
- - Follow the prompt to confirm you are ready to upgrade to the new version.
+
diff --git a/docs/integrations/sources/zendesk-support-migrations.md b/docs/integrations/sources/zendesk-support-migrations.md
index 7ca147a00c2d..dd6bdb2797fa 100644
--- a/docs/integrations/sources/zendesk-support-migrations.md
+++ b/docs/integrations/sources/zendesk-support-migrations.md
@@ -1,61 +1,14 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Zendesk Support Migration Guide
## Upgrading to 4.0.0
The pagination strategy has been changed from `Offset` to `Cursor-Based`. It is necessary to reset the stream.
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- - Select **Sources**.
-2. Find Zendesk Support in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### For Airbyte Cloud: Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- - Follow the prompt to confirm you are ready to upgrade to the new version.
+### Connector upgrade guide
-### Refresh affected schemas and data
-
-1. Select **Connections** in the main nav bar.
- - Select the connection(s) affected by the update.
-2. Select the **Replication** tab.
- - Select **Refresh source schema**.
- - Select **OK**.
-
-:::note
-Any detected schema changes will be listed for your review.
-:::
-
-3. Select **Save changes** at the bottom of the page.
- - Ensure the **Refresh affected streams** option is checked.
-
-:::note
-Depending on destination type you may not be prompted to refresh your data. See below.
-:::
-
-4. Select **Save connection**.
-
-:::note
-This will refresh the data in your destination and initiate a fresh sync.
-:::
-
-For more information on refreshes your data in Airbyte, see [this page](https://docs.airbyte.com/operator-guides/refreshes).
+
## Upgrading to 3.0.0
@@ -67,60 +20,6 @@ For more information on refreshes your data in Airbyte, see [this page](https://
| -------------------|------------------------ |
| `TicketMetrics` | `generated_timestamp` |
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- - Select **Sources**.
-2. Find Zendesk Support in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### For Airbyte Cloud: Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- - Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and data
-
-1. Select **Connections** in the main nav bar.
- - Select the connection(s) affected by the update.
-2. Select the **Replication** tab.
- - Select **Refresh source schema**.
- - Select **OK**.
-
-:::note
-Any detected schema changes will be listed for your review.
-:::
-
-3. Select **Save changes** at the bottom of the page.
- - Ensure the **Refresh affected streams** option is checked.
-
-:::note
-Depending on destination type you may not be prompted to refresh your data. See below.
-:::
-
-4. Select **Save connection**.
-
-:::note
-This will refresh the data in your destination and initiate a fresh sync.
-:::
-
-For more information on refreshes your data in Airbyte, see [this page](https://docs.airbyte.com/operator-guides/refreshes).
-
-
## Upgrading to 2.0.0
Stream `Deleted Tickets` is removed. You may need to refresh the connection schema (skipping the data clearing), and running a sync. Alternatively, you can clear your data.
diff --git a/docs/integrations/sources/zendesk-talk-migrations.md b/docs/integrations/sources/zendesk-talk-migrations.md
index c587e10acb19..1f5e9fc7c730 100644
--- a/docs/integrations/sources/zendesk-talk-migrations.md
+++ b/docs/integrations/sources/zendesk-talk-migrations.md
@@ -1,3 +1,5 @@
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Zendesk Talk Migration Guide
## Upgrading to 1.0.0
@@ -8,52 +10,6 @@ We’ve evolved and standardized how state is managed for incremental streams th
To gracefully handle these changes for your existing connections, we highly recommend resetting your data before resuming your data syncs with the new version.
-## Migration Steps
-
-### For Airbyte Open Source: Update the local connector image
-
-Airbyte Open Source users must manually update the connector image in their local registry before proceeding with the migration. To do so:
-
-1. Select **Settings** in the main navbar.
- 1. Select **Sources**.
-2. Find Zendesk Talk in the list of connectors.
-
-:::note
-You will see two versions listed, the current in-use version and the latest version available.
-:::
-
-3. Select **Change** to update your OSS version to the latest available version.
-
-### Update the connector version
-
-1. Select **Sources** in the main navbar.
-2. Select the instance of the connector you wish to upgrade.
-
-:::note
-Each instance of the connector must be updated separately. If you have created multiple instances of a connector, updating one will not affect the others.
-:::
-
-3. Select **Upgrade**
- 1. Follow the prompt to confirm you are ready to upgrade to the new version.
-
-### Refresh affected schemas and reset data
-
-1. Select **Connections** in the main nav bar.
- 1. Select the connection(s) affected by the update.
-2. Select the **Replication** tab.
- 1. Select **Refresh source schema**.
- 2. Select **OK**.
- :::note
- Any detected schema changes will be listed for your review.
- :::
-3. Select **Save changes** at the bottom of the page.
- 1. Ensure the **Reset affected streams** option is checked.
- :::note
- Depending on destination type you may not be prompted to reset your data.
- :::
-4. Select **Save connection**.
- :::note
- This will reset the data in your destination and initiate a fresh sync.
- :::
+## Connector upgrade guide
-For more information on resetting your data in Airbyte, see [this page](/platform/operator-guides/clear).
+
diff --git a/docs/platform/access-management/rbac.md b/docs/platform/access-management/rbac.md
index 81deee8252b8..b449d32901bb 100644
--- a/docs/platform/access-management/rbac.md
+++ b/docs/platform/access-management/rbac.md
@@ -2,43 +2,46 @@
products: oss-enterprise, cloud-teams
---
-# Role Based Access Control (RBAC)
+# Role-based access control (RBAC)
-Role Based Access Control allows a user with Administrative access to apply roles to users, granting different levels of permission within an Organization or Workspace.
+Role Based Access Control allows a user with Administrative access to apply roles to users, granting different levels of permission within an organization or workspace.
:::info
**Self-Managed Enterprise** instances have an `Instance Admin` role in addition to the other roles outlined in this document. The first user who logs on to Airbyte in a Self-Managed Enterprise instance will be assigned this role. This user will have all permissions listed below for all workspaces and all organizations associated with their Enterprise account. To update this assignment, enterprise customers should contact [Airbyte support](https://support.airbyte.com/hc/en-us).
:::
-## Organization Resource Roles
+## Organization roles
-Permissions are scoped to the given Organization for which the user has this role, and any Workspaces within.
+When you assign an organization role, Airbyte scopes permissions to the entire organization, which includes all workspaces in that organization.
-| Permissions | Member | Reader | Runner | Editor | Admin |
-| :---------------------- | :--------: | :--------: | :--------: | :--------: |:--------: |
-| **Read Organization**
Read individual organizations
| X | X | X | X | X |
-| **Create Workspace**
Create new workspace within a specified organization
Delete a workspace
| | | | X | X |
-| **Update Organization**
Modify organization settings, including billing, PbA, SSO
Create new workspace within a specified organization
Delete a workspace
| | | | X | X |
+| **Update Organization**
Modify organization settings, including billing, PbA, SSO
Modify user roles within the organization
| | | | | X |
-## Workspace Resource Roles
-Permissions are scoped to the specific Workspace in which the user has this role.
+## Workspace roles
-| Permissions | Reader | Runner | Editor | Admin |
-| ---------------------- | :--------: | :--------:| :--------:| :--------: |
-| **Read Workspace**
| | | | X |
+In a workspace role, Airbyte scopes permissions to that specific workspace. You can override an organization role by assigning someone a higher role in a workspace. However, you can't assign a role that's more restricted than the role that person holds in the organization. For example, an organization admin must also be a workspace admin. However, an organization reader can be a workspace reader, editor, or admin.
-## Setting Roles
+| Permissions | Reader | Runner | Editor | Admin |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----: | :----: | :----: | :---: |
+| **Read Workspace**
| | | | X |
-
+## Best practices for assigning roles
-In the UI, navigate to `Settings` > `General` to see a list of your Organization or Workspace members. Here, by selecting the role listed under `Organization Role` or `Workspace Role`, you can change the assignment.
+- At the organization level, assign the lowest level of permission necessary.
+- At the workspace level, assign higher roles for individual workspaces as needed to override organization role within that workspace.
+- Don't assign admin roles frivolously. Once someone is an admin, you can't demote them.
-Note that it is not possible to assign a Workspace member to a role that is more restricted than the role they've been assigned at the Organizational level.
+## Setting roles
-For example, a person who is assigned to be an Organization `Admin` would automatically have Admin-level permissions in all Workspaces within the Organization and can not be demoted within a Workspace. On the other hand, a person assigned to the `Reader` role in an Organization could be assigned the `Reader`, `Editor`, or `Admin` role in an individual Workspace.
+
+1. In the navigation bar, click **Workspace settings** or **Organization settings** > **Members**.
+2. In the table, under **Workspace role**, click the current role and then select a new role.
diff --git a/docs/platform/access-management/sso-providers/azure-entra-id.md b/docs/platform/access-management/sso-providers/azure-entra-id.md
index 37042de62b5a..762adb21b59b 100644
--- a/docs/platform/access-management/sso-providers/azure-entra-id.md
+++ b/docs/platform/access-management/sso-providers/azure-entra-id.md
@@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem";
# Set up single sign on using Entra ID
-This guide shows you how to set up Microsoft Entra ID (formerly Azure ActiveDirectory) and Airbyte so your users can log into Airbyte using your organization's identity provider (IdP) using OpenID Connect (OIDC).
+This guide shows you how to set up Microsoft Entra ID (formerly Azure ActiveDirectory) and Airbyte so your users can log into Airbyte using your organization's identity provider (IdP) using OpenID Connect (OIDC).
## Overview
@@ -16,7 +16,7 @@ This guide is for administrators. It assumes you have:
- Basic knowledge of Entra ID, OIDC, and Airbyte
- The permissions to manage Entra ID in your organization
-- The permissions to manage Airbyte in your organization
+- Organization admin permissions for Airbyte
The exact process differs between the Cloud or Self-Managed versions of Airbyte. Steps for both are below.
@@ -62,15 +62,13 @@ Create client credentials so Airbyte can talk to your application.
#### Configure SSO in Airbyte
-:::info
-Currently, this portion of the setup can only be done by an Airbyte employee. Contact Support to proceed.
-:::
-
-1. In Airbyte, click **Settings**.
+1. In Airbyte, click **Organization settings** > **General**.
-2. Under **Organization**, click **General**.
+ :::info
+ Currently, this portion of the setup requires an Airbyte employee. Contact Support to proceed.
+ :::
-3. Click **Set up SSO**, then input the following information.
+2. Click **Set up SSO**, then input the following information.
- **Email domain**: The full email domain of users who sign in to Entra ID. For example, `airbyte.io`.
@@ -92,9 +90,9 @@ Currently, this portion of the setup can only be done by an Airbyte employee. Co
- It's often your organization name or domain. For example, `airbyte`.
-4. Click **Save changes**.
+3. Click **Save changes**.
-5. Test SSO to make sure people can access Airbyte. **Stay logged in so you don't lock yourself out** and ask a colleague to complete the following steps.
+4. Test SSO to make sure people can access Airbyte. **Stay logged in so you don't lock yourself out** and ask a colleague to complete the following steps.
1. Sign out of Airbyte.
@@ -120,7 +118,7 @@ You will need to create a new Entra ID application for Airbyte. Log into the [Az
From the overview page of Entra ID, press **Add** > **App registration** on the top of the screen. The name you select is your app integration name. Once chosen, **choose who can use the application, typically set to "Accounts in this organization directory only" for specific access,** and configure a **Redirect URI** of type **Web** with the following value:
-```
+```text
/auth/realms/airbyte/broker//endpoint
```
diff --git a/docs/platform/access-management/sso-providers/okta.md b/docs/platform/access-management/sso-providers/okta.md
index 72dafa049a8e..0fa648f08751 100644
--- a/docs/platform/access-management/sso-providers/okta.md
+++ b/docs/platform/access-management/sso-providers/okta.md
@@ -16,7 +16,7 @@ This guide is for administrators. It assumes you have:
- Basic knowledge of Okta, OpenID Connect (OIDC), and Airbyte
- The permissions to manage Okta in your organization
-- The permissions to manage Airbyte in your organization
+- Organization admin permissions for Airbyte
The exact process differs between the Cloud or Self-Managed versions of Airbyte. Steps for both are below.
@@ -60,19 +60,17 @@ Follow these steps to set up SSO in Airbyte Cloud.
- Leave other values as defaults unless you have a reason to change them.
-3. Click **Save**.
+4. Click **Save**.
#### Configure SSO in Airbyte
-:::info
-Currently, this portion of the setup can only be done by an Airbyte employee. Contact Support to proceed.
-:::
-
-1. In Airbyte, click **Settings**.
+1. In Airbyte, click **Organization settings** > **General**.
-2. Under **Organization**, click **General**.
+ :::info
+ Currently, this portion of the setup can only be done by an Airbyte employee. Contact Support to proceed.
+ :::
-3. Click **Set up SSO**, then input the following information.
+2. Click **Set up SSO**, then input the following information.
- **Email domain**: The full email domain of users who sign in to Okta. For example, `airbyte.io`.
@@ -94,9 +92,9 @@ Currently, this portion of the setup can only be done by an Airbyte employee. Co
- It's often your organization name or domain. For example, `airbyte`.
-4. Click **Save changes**.
+3. Click **Save changes**.
-5. Test SSO to make sure people can access Airbyte. **Stay logged in so you don't lock yourself out** and ask a colleague to complete the following steps.
+4. Test SSO to make sure people can access Airbyte. **Stay logged in so you don't lock yourself out** and ask a colleague to complete the following steps.
1. Sign out of Airbyte.
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-status-page.png b/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-status-page.png
index 6cfff830c6f3..b996924b7a14 100644
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-status-page.png and b/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-status-page.png differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-timeline-page.png b/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-timeline-page.png
index 8d5ff1deb757..ff1d08d30e30 100644
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-timeline-page.png and b/docs/platform/cloud/managing-airbyte-cloud/assets/cloud-timeline-page.png differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-add-webhook.png b/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-add-webhook.png
deleted file mode 100644
index f96be7457ded..000000000000
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-add-webhook.png and /dev/null differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-create-app.png b/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-create-app.png
deleted file mode 100644
index 613cf1d959cc..000000000000
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-create-app.png and /dev/null differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-success.png b/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-success.png
deleted file mode 100644
index fba8d0a51e3e..000000000000
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-success.png and /dev/null differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-webhook-url-success.png b/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-webhook-url-success.png
deleted file mode 100644
index c7ac383a95bd..000000000000
Binary files a/docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-webhook-url-success.png and /dev/null differ
diff --git a/docs/platform/cloud/managing-airbyte-cloud/dbt-cloud-integration.md b/docs/platform/cloud/managing-airbyte-cloud/dbt-cloud-integration.md
index c17ddfe272c1..37d451422c22 100644
--- a/docs/platform/cloud/managing-airbyte-cloud/dbt-cloud-integration.md
+++ b/docs/platform/cloud/managing-airbyte-cloud/dbt-cloud-integration.md
@@ -22,7 +22,7 @@ Generate a [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-t
## Step 2: Set up the dbt Cloud integration for the workspace
-1. Click **Settings** and then **Integrations**. Enter your access URL (for example, `https://cloud.getdbt.com/`). [Custom access URLs](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses#accessing-your-account) are also supported.
+1. Click **Workspace settings** > **Integrations**. Enter your access URL (for example, `https://cloud.getdbt.com/`). [Custom access URLs](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses#accessing-your-account) are also supported.
2. Enter the service token and click **Save changes**.
diff --git a/docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md b/docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md
index c0029c119b88..97304d4af54e 100644
--- a/docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md
+++ b/docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md
@@ -4,61 +4,66 @@ products: all
# Manage notifications
-This page provides guidance on how to manage notifications for Airbyte, allowing you to stay up-to-date on the activities in your workspace.
+If you want Airbyte to notify you about important events, use its built-in notification system.
-## Notification Event Types
+## How it works
-| Type of Notification | Description |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Failed Syncs** | A sync from any of your connections fails. Note that if sync runs frequently or if there are many syncs in the workspace these types of events can be noisy |
-| **Successful Syncs** | A sync from any of your connections succeeds. Note that if sync runs frequently or if there are many syncs in the workspace these types of events can be noisy |
-| **Automated Connection Updates** | A connection is updated automatically (ex. a source schema is automatically updated) |
-| **Connection Updates Requiring Action** | A connection update requires you to take action (ex. a breaking schema change is detected) |
-| **Warning - Repeated Failures** | A connection will be disabled soon due to repeated failures. It has failed 20 times consecutively and there were only failed jobs in the past 4 days |
-| **Sync Disabled - Repeated Failures** | A connection was automatically disabled due to repeated failures. It will be disabled when it has failed 30 times consecutively and has been failing for 7 days in a row |
-| **Warning - Upgrade Required** (Cloud only) | A new connector version is available and requires manual upgrade |
-| **Sync Disabled - Upgrade Required** (Cloud only) | One or more connections were automatically disabled due to a connector upgrade deadline passing |
+You configure notifications for each workspace separately. Once you do, Airbyte can send notifications to an email address, webhook, or both.
-### Enabling schema update notifications
+- Airbyte Cloud can send notifications to an email or webhook.
-To be notified of any source schema changes, make sure you have enabled `Automatic Connection Updates` and `Connection Updates Requiring Action` notifications. If these are off, even if you turned on schema update notifications in a connection's settings, Airbyte will _NOT_ send out any notifications related to these types of events.
+- Self-Managed versions of Airbyte can send notifications to a webhook, but not an email.
-To edit this setting, click **Connections** and select the connection you want to receive notifications for. Click the **Settings** tab on the Connection page. In the **Advanced Settings**, toggle **Schema update notifications**.
+### Events Airbyte can notify you about
-## Configure Email Notification Settings
+| Event | Cloud | Self-Managed | Description |
+| --------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Failed syncs** | ✓ | ✓ | A sync from any of your connections fails. If syncs runs frequently or if there are many syncs in the workspace, this event can be noisy. |
+| **Successful syncs** | ✓ | ✓ | A sync from any of your connections succeeds. If syncs runs frequently or if there are many syncs in the workspace, this event can be noisy. |
+| **Connection Updates** | ✓ | ✓ | A connection is updated automatically. For example, a source schema is automatically updated. |
+| **Connection Updates Requiring Action** | ✓ | ✓ | A connection update requires you to take action. For example, a breaking change. |
+| **Warning - Repeated Failures** | ✓ | ✓ | Airbyte is at risk of turning off a connection due to repeated failures. It has failed 20 times consecutively and his not been successful in the last 4 days. |
+| **Sync Disabled - Repeated Failures** | ✓ | ✓ | Airbyte has turned off a connection due to repeated failures. It has failed 30 times consecutively and has not been successful in the last 7 days. |
+| **Warning - Upgrade Required** | ✓ | | A new connector version is available, but you need to manually upgrade. |
+| **Sync Disabled - Upgrade Required** | ✓ | | Airbyte turned off one or more connections automatically because you missed the deadline to upgrade the connector. |
-
+### Enabling schema update notifications
-To set up email notifications, click **Settings** and navigate to **Workspace** > **Notifications**.
+If you want Airbyte to notify you of source schema changes, enable the following notifications.
-Toggle which messages you'd like to receive from Airbyte. All email notifications will be sent by default to the creator of the workspace.
+- `Connection Updates`
+- `Connection Updates Requiring Action`.
-
+If these are off, even if you turned on schema update notifications in a connection's settings, Airbyte won't send notifications about schema changes.
-:::note
-All email notifications except for Successful Syncs are enabled by default.
-:::
+To edit this setting, click **Connections** and select the connection you want to receive notifications for. Click the **Settings** tab on the Connection page. In the **Advanced Settings**, toggle **Be notified when schema changes occur**.
+
+## Set up email notifications (Cloud only)
+
+Follow these steps to set up email notifications from Airbyte Cloud. Email notifications are not available from self-managed editions of Airbyte.
-### Modify the email recipient
+1. Click **Workspace settings** > **Notifications**.
-To change the recipient, edit and save the **notification email recipient**. If you would like to send email notifications to more than one recipient, you can enter an email distribution list (ie Google Group) as the recipient.
+2. Under **Email Notification Recipient**, enter the email you want to receive notifications. If you would like to send email notifications to more than one recipient, enter a distribution list as the recipient.
-## Configure Webhook Notification Settings
+3. Use the toggles in the **Email** column to set which notifications you want to receive.
-Airbyte can send notifications to any generic webhook service. This is helpful when using a downstream service to trigger transformations or other tasks in your data stack.
+## Set up webhook notifications
-### Example Webhook Notification Payload
+Airbyte can send notifications to any generic webhook service. You can use the webhook to send a notification to Slack or trigger other downstream transformations.
+
+### Example webhook payload
Open each section to see an example of the payload returned for the notification type.
:::info
-Airbyte passes both the `data` payload along with text blocks that are intended for Slack usage.
+Airbyte passes both the `data` payload along with text blocks that intended for Slack usage.
:::
- Failed Sync
+ Failed sync
-```
+```json
{
"data": {
"workspace": {
@@ -100,13 +105,13 @@ Airbyte passes both the `data` payload along with text blocks that are intended
}
```
-Note that `errorType` refers to the type of error that occurred, and may indicate the need for a followup action. For example `config_error` indicates a problem with the source or destination configuration (look to `errorOrigin`), while `transient_error` indicates a temporary issue that may resolve itself.
+`errorType` refers to the type of error that occurred, and may indicate the need for a followup action. For example `config_error` indicates a problem with the source or destination configuration. In this case, look to `errorOrigin`. `transient_error` indicates a temporary issue that may resolve itself.
- Successful Sync
+ Successful sync
-```
+```json
{
"data": {
"workspace": {
@@ -148,81 +153,79 @@ Note that `errorType` refers to the type of error that occurred, and may indicat
- Automated Connection Updates
+ Connection updates
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
- Connection Updates Requiring Action
+ Connection updates requiring action
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
Warning - Repeated Failures
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
Sync Disabled - Repeated Failures
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
Warning - Upgrade Required
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
Sync Disabled - Upgrade Required
-Webhook does not contain payload and only works for Slack notifications
+Webhook doesn't contain payload and only works for Slack notifications.
-### Configuring Slack Notifications
+### Configure Slack notifications
-The webhook notification also integrates easily with Slack.
+The webhook notification integrates with Slack. To set up a Slack integration, you create a Slack app, then enable the webhook notification from Airbyte.
-If you're more of a visual learner, head over to [this video](https://www.youtube.com/watch?v=NjYm8F-KiFc&ab_channel=Airbyte) to learn how to set up a Slack app to receive notifications. You can also refer to the Slack documentation on how to [create an incoming webhook for Slack](https://api.slack.com/messaging/webhooks).
+#### Part 1: Create a Slack app
-### Create a Slack app
+1. Navigate to https://api.slack.com/apps/.
-1. To set up Slack notifications, navigate to https://api.slack.com/apps/. Select `Create an App`.
+2. Click **Create an App**.
-
+3. Click **From Scratch**. Enter an app name (for example, "Airbyte Notifications") and pick the Slack workspace you want it to operate in.
-2. Select `From Scratch`. Enter your App Name (e.g. Airbyte Sync Notifications) and pick your desired Slack workspace.
+4. Click **Incoming Webhooks**.
-3. **Enable Incoming Webhooks**: in the left sidebar, click on `Incoming Webhooks`. Click the slider button in the top right to turn the feature on. Then click `Add New Webhook to Workspace`.
+5. Click the toggle in the top right to turn the feature on.
-
+6. Click **Add New Webhook**.
-4. Select the channel that you want to receive Airbyte notifications in (ideally a dedicated one), and click `Allow` to give it permissions to access the channel. You should see the bot show up in the selected channel now. You will see an active webhook right above the `Add New Webhook to Workspace` button.
+7. Select the channel that you want to receive Airbyte notifications in.
-
+8. Click **Allow** to give the app permissions to access the channel. Your webhook appears under "Webhook URLs for Your Workspace", and the bot for this app joins your selected channel.
-5. Click `Copy.` to copy the link to your clipboard, which you will need to enter into Airbyte.
+9. Copy the webhook URL. It looks similar to `https://hooks.slack.com/services/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PM1`
-Your Webhook URL should look similar to this:
+#### Part 2: Enable the Slack notification from Airbyte
-```
-https://hooks.slack.com/services/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PM1
-```
+Once you have set up your Slack app, follow these steps to set up webhook notifications from Airbyte.
-### Enable the Slack notification in Airbyte
+1. Click **Workspace settings** > **Notifications**.
-1. Click **Settings** and navigate to **Notifications**. On this page, you can toggle each slider decide whether you want notifications on each notification type. Paste the copied webhook URL to `Webhook URL`.
+2. Use the toggles in the **Webhook** column to set which notifications you want to receive.
-2. **Test it out**: you can click `Test` to send a test message to the channel. Or, just run a sync now and try it out! For a successful sync, you should receive a notification that looks like this:
+3. Enter the webhook URL, which you copied earlier, for each webhook you enabled.
-
+4. Click **Test** to send a message to the channel.
-4. Click **Save changes** to ensure you continue to receive alerts about your Airbyte syncs.
+5. Click **Save changes**.
diff --git a/docs/platform/cloud/managing-airbyte-cloud/manage-credits.md b/docs/platform/cloud/managing-airbyte-cloud/manage-credits.md
index 1a984ad20f27..50e8c0378815 100644
--- a/docs/platform/cloud/managing-airbyte-cloud/manage-credits.md
+++ b/docs/platform/cloud/managing-airbyte-cloud/manage-credits.md
@@ -2,105 +2,115 @@
products: cloud
---
-# Manage credits
+# Manage billing and credits
-In order to manage your payment and billing information, you must be granted the **Organization Admin** role.
+In order to manage your payment and billing information, you need the **Organization Admin** role.
## What are credits?
Airbyte [credits](https://airbyte.com/pricing) are used to pay for Airbyte resources when you run a sync. Airbyte Cloud plans start at $10 per month, which includes 4 credits. Additional credits are available at $2.50 each.
-:::note
-If you signed up for Airbyte Cloud on or after October 31st, 2024, you are automatically enrolled in our $10/month subscription plan.
-
-For those who signed up prior, we will reach out to you over the coming weeks to migrate you to the new plans, and you can continue to use Airbyte as usual in the interim.
-:::
-
Airbyte uses credits to unify pricing across multiple types of sources. You can refer to the below table to understand how pricing differs across each source.
-|Source Type| Billing Type| Price| Credit Equivalent|
-|-|-|-|-|
-|APIs | Rows| $15 per million rows| 6 credits|
-|Databases| GB | $10 per GB| 4 credits|
-|Files| GB | $10 per GB| 4 credits|
-|Custom sources| Rows | $15 per million rows| 6 credits|
+| Source Type | Billing Type | Price | Credit Equivalent |
+| -------------- | ------------ | -------------------- | ----------------- |
+| APIs | Rows | $15 per million rows | 6 credits |
+| Databases | GB | $10 per GB | 4 credits |
+| Files | GB | $10 per GB | 4 credits |
+| Custom sources | Rows | $15 per million rows | 6 credits |
-For APIs and custom sources, most syncs will sync incrementally, so the row amount will typically be those rows added, edited, or deleted. For Full Refresh syncs, every row synced will be charged.
+For APIs and custom sources, most syncs happen incrementally, so the row amount is typically those rows added, edited, or deleted. For Full Refresh syncs, every row synced is charged.
For Databases and File sources, Airbyte measures the data volume observed by the Airbyte Platform during the sync to determine data volumes. When the data is in transit, it is serialized to Airbyte Protocol format records. This is likely to be a larger representation of your data than you would see if you were to query your database directly, and varies depending on how your database stores and compresses data.
-## Start a Trial
-To begin a trial of Airbyte Cloud, head to https://cloud.airbyte.com/signup. Your trial will only begin after your first successful sync. Trials last 14 days or when 400 trial credits are used, whichever occurs first.
+## Start a trial
+
+To begin a trial of Airbyte Cloud, head to [cloud.airbyte.com/signup](https://cloud.airbyte.com/signup). Your trial begins after your first successful sync. Trials last 14 days or when you use 400 trial credits, whichever occurs first.
+
+If you need additional trial credits or time to evaluate Airbyte, please reach out to Airbyte's [Sales team](https://airbyte.com/company/talk-to-sales).
+
+## Access the Billing page
+
+Follow these steps to access the Billing page.
+
+1. Click **Organization settings** in the navigation bar.
+
+2. Click **Billing**.
+
+From this page, you can view and update your billing information.
+
+## Add payment details
+
+To continue using Airbyte beyond your trial, you must place a valid payment method on file. Airbyte currently only accepts credit cards. If you prefer ACH, [talk to Sales](https://airbyte.com/company/talk-to-sales).
+
+To add payment details, click **Add payment method**.
+
+Airbyte automatically charges the credit card on file at the end of each month's billing period for the subscription amount and any additional usage incurred. Once you enter payment details, Airbyte shows you additional billing information.
+
+- Subscription
+- Account balance
+- Billing information
+- Payment method
+- Invoices
+
+### Review your subscription
+
+The Subscription section shows the subscription plan you have enrolled in. Reach out to [Sales](https://airbyte.com/company/talk-to-sales) to inquire about larger plans, new features, or custom discounts.
+
+### Review your account balance
+
+In the Account balance section, you can view more details about your balance.
+
+- **Upcoming invoice amount**: The amount of the upcoming invoice
+
+- **Invoice date**: The date of the upcoming invoice
+
+- **Remaining credits**: The amount of credits that remain. Airbyte uses these credits first before it accrues an invoice amount. This is typically only relevant if you pre-purchased credits before November 2024.
+
+### Review billing information
+
+In the Billing information section, you can review:
-If you need additional trial credits or time to evaluate Airbyte, please reach out to our [Sales team](https://airbyte.com/company/talk-to-sales).
+- Your **billing email**, which Airbyte uses for invoicing and billing notifications.
-## Add Payment Details
-To continue using Airbyte beyond your trial, we require a valid payment method on file. We currently only accept credit card. If you prefer ACH, please [Talk to Sales](https://airbyte.com/company/talk-to-sales).
+- Your **billing address**, which Airbyte uses to apply any applicable taxes to your invoice.
-To add payment details, navigate to the Cloud UI.
-1. Click on **Settings** in the navigation bar
-2. Under **Organization**, click **Billing**
-3. Enter **Payment Details**
+To edit your billing email or address, click **Update**. Airbyte redirects to the Stripe portal, where you can save any updates.
-Once your payment details have been saved, Airbyte will automatically charge the credit card on file at the end of each month's billing period for the subscription amount and any additional usage incurred.
+### Review payment method
-Once you have entered payment details, additional billing information will be shown:
-- Plan
-- Account Balance
-- Billing Information
-- Payment Method
-- Invoice History
+In the Payment method section, you can review the saved credit card on file. Airbyte uses this for any automatic monthly subscription or overage charges.
-### Review Plan
-The Plan section shows the Plan you are currently enrolled in. You may reach out to [Sales](https://airbyte.com/company/talk-to-sales) to inquire about Airbyte Teams features or custom discounts.
+To edit the **Payment Method**, click **Update**. Airbyte redirects to the Stripe portal, where you can save any updates.
-### Review Account Balance
-In the Account Balance section, you can view:
-1. **Upcoming Invoice Amount**: The amount of the upcoming invoice
-2. **Invoice Date**: The date of the upcoming invoice
-3. **Remaining credits**: The amount of credits that remain on the balance. The credits will be used first before we accrue an invoice amount. This is typically only relevant if you pre-purchased credits before November 2024.
+### Review invoice history
-### Review Billing Information
-In the Billing Information section, you can review:
-1. The **Billing Email**, which we will use for any invoicing or billing notifications.
-2. The **Billing Address**, which we will use to apply any applicable taxes to your invoice.
+In the Invoices section, you can review any past invoices. All invoices have an **Invoice status**. The invoice status indicates whether the invoice is still awaiting payment or are already paid.
-To edit the **Billing Email** or **Billing Address**, click **Update**. You will be redirected to the Stripe portal, where you can save any updates.
+You can view more details about an individual invoice by clicking **View Invoice**.
-### Review Payment Method
-In the Payment Method section, you can review the saved **Payment Method** on file. This will be used for any automatic monthly subscription or overage charges.
+## Billing notifications
-To edit the **Payment Method**, click **Update**. You will be redirected to the Stripe portal, where you can save any updates.
+By default, all customers automatically review upcoming invoice notifications 3 and 7 days before the invoice is finalized. All billing notifications are sent to the billing email on file.
-### Review Invoice History
-In the Invoices section, you can review any past invoices. All invoices will note an **Invoice Status**. The **Invoice Status** indicates whether the invoice is still awaiting payment or are already paid.
+You can also enroll in billing notifications for your organization. Airbyte highly recommends enrolling in billing notifications to ensure you stay up-to-date on your upcoming invoices.
-You can view more details about an individal invoice by clicking **View Invoice**.
+Airbyte can notify you when:
-## Billing Notifications
-By default, all customers will automatically review upcoming invoice notifications 3 and 7 days before the invoice will be finalized. All billing notifications will be sent to the **Billing Email** in the **Billing Information** section.
+- A sync consumes over $__
-Customers can also optionally enroll in billing notifications for their organization. We highly recommend enrolling in billing notifications to ensure you stay up-to-date on your upcoming invoices.
+- Your upcoming invoice has increased __%
-The billing notifications available are:
-- Notify me when a sync consumes over $__
-- Notify me when my upcoming invoice has increased __%
- Notify me when my upcoming invoice is over $___
-To enroll in billing notifications:
-1. Click on **Settings** in the navigation bar
-2. Under **Organization**, click **Billing**
-3. Click on **Set up billing alerts**
-4. Submit the form with custom thresholds for the alerts you are interested in receiving.
+To enroll in or modify your existing billing notifications:
-To change your existing notification thresholds, submit the form again.
+1. From the Billing page, click **Set up billing alerts**.
-To unenroll, [email us](mailto:billing@airbyte.io) with your request.
+2. Submit the form with the thresholds you want to use for alerts.
-## Purchasing Credits
+To unenroll, [email the Billing team](mailto:billing@airbyte.io) with your request.
-:::note
-Credits can no longer be pre-purchased. As of November 2024, Airbyte Cloud has moved to in-arrears billing invoiced monthly.
-:::
+## Purchasing credits
-Purchased credits expire after 12 months after purchase. Purchased credits are used before accruing an invoice for additional usage. Purchased credits can not be used for the monthly subscription fee.
\ No newline at end of file
+You can no longer pre-purchase credits. As of November 2024, Airbyte Cloud has moved to in-arrears billing. You're invoiced monthly.
diff --git a/docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md b/docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md
index 671bef8ca40d..29eba130482b 100644
--- a/docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md
+++ b/docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md
@@ -1,49 +1,57 @@
---
-products: cloud
+products: cloud, oss-enterprise
---
-# Setting data residency
+# Set data residency
-In Airbyte Cloud, you can set the default data residency for your workspace and also set the data residency for individual connections, which can help you comply with data localization requirements.
+Your connections can run in the managed or self-managed region of your choice.
-## Choose your workspace default data residency
+## How it works
-Setting a default data residency allows you to choose where your data is processed. Set the default data residency **before** creating a new source or connection so that subsequent workflows that rely on the default data residency, such as fetching the schema or testing the source or destination, can process data in the correct region.
+You set data residency by assigning a region to a workspace. All connections that run in that workspace run in that region. Changes to data residency do not affect syncs that are already in progress, but affect future syncs.
-:::note
+```mermaid
+flowchart LR
+ subgraph Reg[Region]
+ DP[Data Plane]
+ end
-While the data is processed in a data plane of the chosen residency, the cursor and primary key data is stored in the US control plane. If you have data that cannot be stored in the US, do not use it as a cursor or primary key.
+ subgraph Org[Organization]
+ subgraph WS[Workspace]
+ C[Connection]
+ end
+ end
-:::
+ C -- "Runs in" --> Reg
+ Reg -- "Assigned to" --> WS
+```
-When you set the default data residency, it applies your preference to new connections only. If you do not adjust the default data residency, the [Airbyte Default](configuring-connections.md) region is used (United States). If you want to change the data residency for an individual connection, you can do so in its [connection settings](configuring-connections.md).
+### Capabilities by plan
-To choose your default data residency, click **Settings** in the Airbyte UI. Navigate to **Workspace** > **Data Residency**. Use the dropdown to choose the location for your default data residency and save your changes.
+- **Cloud**: If you're a cloud customer, you can choose from Airbyte's managed regions. If you're an [Enterprise Flex](../../enterprise-flex/) customer, you can also choose one of your own self-managed regions.
-:::info
+- **Self-Managed**: If you're a [Self-Managed Enterprise](../../enterprise-setup/) customer, you can choose one of your own self-managed regions.
-Depending on your network configuration, you may need to add [IP addresses](/platform/operating-airbyte/security/#network-security-1) to your allowlist.
+### Connector Builder data residency
-:::
+The Connector Builder processes all data through Airbyte's control plane, regardless of your workspace's default data residency settings. This limitation applies to the development and testing of connectors within the Connector Builder interface. It doesn't apply to actual connections using that connector, which use the region you set for that workspace.
-## Choose the data residency for a connection
+### Cursor and primary key data residency
-:::info
-As of November 2024, the option to enable a custom data residency for a connection has been deprecated from Airbyte Cloud.
-:::
+While Airbyte processes data in a data plane from your chosen region, it runs cursor and primary key data through the control plane. Airbyte Cloud's control plane is in the United States. If you have data you can't process in the United States, don't use it as a cursor or primary key.
-You can additionally choose the data residency for your connection in the connection settings. You can choose the data residency when creating a new connection, or you can set the default data residency for your workspace so that it applies for any new connections moving forward.
+### IP addresses for managed data planes
-To choose a custom data residency for your connection, click **Connections** in the Airbyte UI and then select the connection that you want to configure. Navigate to the **Settings** tab, open the **Advanced Settings**, and select the **Data residency** for the connection.
+If you're a Cloud customer using one of Airbyte's managed data planes, you might need to add [these IP addresses](/platform/operating-airbyte/ip-allowlist) to your allow list.
-:::note
+## Assign a region to a workspace
-Changes to data residency will not affect any sync in progress.
+When you assign a region to a workspace, all connections in that workspace run in that region, except for the preceding limitations. Follow the steps below to assign a region to a workspace.
-:::
+1. Switch to the workspace you want to change data residency on.
-## Connector Builder data residency
+2. Click **Workspace settings**.
-The Connector Builder currently processes all data through US data planes, regardless of your workspace's default data residency settings. This limitation applies to the development and testing of connectors within the builder interface.
+3. Under **Region**, select the region you want that workspace to use.
-If your use case requires strict data residency compliance outside the US, you can still publish a custom connector from the builder which will respect your workspace's data residency settings during syncs. However, you will be unable to verify the connector's behavior within the builder itself.
+4. Click **Save changes**.
diff --git a/docs/platform/connector-development/connector-builder-ui/record-processing.mdx b/docs/platform/connector-development/connector-builder-ui/record-processing.mdx
index 4e5ed1131d95..01dc9109bc0d 100644
--- a/docs/platform/connector-development/connector-builder-ui/record-processing.mdx
+++ b/docs/platform/connector-development/connector-builder-ui/record-processing.mdx
@@ -1,5 +1,3 @@
-import Diff from "./assets/record-processing-schema-diff.png";
-
# Record processing
Connectors built with the connector builder always make HTTP requests, receive the responses and emit records. Besides making the right requests, it's important to properly hand over the records to the system:
@@ -808,11 +806,7 @@ More strict is always better, but the detected schema is a good default to rely
If `Automatically import detected schema` is disabled, and the declared schema deviates from the detected schema, the "Detected schema" tab in the testing panel highlights the differences. It's important to note that differences are not necessarily a problem that needs to be fixed - in some cases the currently loaded set of records in the testing panel doesn't feature all possible cases so the detected schema is too strict. However, if the declared schema is incompatible with the detected schema based on the test records, it's very likely there will be errors when running syncs.
-
+
In the case of the example above, there are two differences between detected and declared schema. The first difference for the `name` field is not problematic:
diff --git a/docs/platform/contributing-to-airbyte/developing-locally.md b/docs/platform/contributing-to-airbyte/developing-locally.md
index 68fbc19a11ef..0830159686ba 100644
--- a/docs/platform/contributing-to-airbyte/developing-locally.md
+++ b/docs/platform/contributing-to-airbyte/developing-locally.md
@@ -115,30 +115,29 @@ The above connector image is tagged with `dev`. You can change this to use anoth
:::
-- In your browser, visit [http://localhost:8000/](http://localhost:8000/)
-- Log in
-- Go to `Settings` (gear icon in lower left corner)
-- Go to `Sources` or `Destinations` (depending on which connector you are testing)
-- Update the version number to use your docker image tag (default is `dev`)
+- In your browser, visit [http://localhost:8000/](http://localhost:8000/).
+- Log in.
+- Click **Workspace settings** > **Sources**/**Destinations**.
+- Click the edit button .
+- Update the version number to use your docker image tag. The default is `dev`.
- Click `Change` to save the changes
-Now when you run a sync with that connector, it will use your local docker image
-
+Now when you run a sync with that connector, it will use your local docker image.
### Connector Specification Caching
-The Airbyte Server caches connector specifications for performance reasons. If you update the specification of a
-connector, you will need to clear this cache so the new changes are registered. To do this:
+The Airbyte Server caches connector specifications for performance reasons. If you update the specification of a connector, you need to clear this cache so the new changes are registered. To do this:
-- In your browser, visit [http://localhost:8000/](http://localhost:8000/)
-- Log in
-- Go to `Settings` (gear icon in lower left corner)
-- Go to `Sources` or `Destinations` (depending on which connector you are testing)
-- Leave the version set to `dev`
-- Click `Change` to save the changes, which will refresh the dev connectors spec
+- In your browser, visit [http://localhost:8000/](http://localhost:8000/).
+- Log in.
+- Click **Workspace settings** > **Sources**/**Destinations**.
+- Click the edit button .
+- Leave the version set to `dev`.
+- Click `Change` to save the changes, which refreshes the dev connector's spec.
## Platform Contributions
-1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the [ `airbyte-platform`](https://github.com/airbytehq/airbyte-platform) repository.
+
+1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the [`airbyte-platform`](https://github.com/airbytehq/airbyte-platform) repository.
2. Clone the fork on your workstation:
```bash
diff --git a/docs/platform/enterprise-flex/data-plane-util.md b/docs/platform/enterprise-flex/data-plane-util.md
index dcbb263dddd5..d9c50b80c8ed 100644
--- a/docs/platform/enterprise-flex/data-plane-util.md
+++ b/docs/platform/enterprise-flex/data-plane-util.md
@@ -69,7 +69,7 @@ Airbyte runs on Kubernetes. When you deploy your data plane, Airbyte uses Docker
You need an Airbyte application so Airbox can access your control plane. If you don't have one, create one and note the Client ID and Client Secret. If you already have one, you can skip creating one and reuse your existing credentials.
-1. In Airbyte's UI, click your user name > **User Settings** > **Applications** > **Create an application**.
+1. In Airbyte's UI, click your user name > **User settings** > **Applications** > **Create an application**.
2. Enter a descriptive application name. For example, "Data plane deployment." Airbyte creates your application. Note the Client ID and Client Secret.
diff --git a/docs/platform/enterprise-flex/data-plane.md b/docs/platform/enterprise-flex/data-plane.md
index 147e7efa9527..c6ee20a143ad 100644
--- a/docs/platform/enterprise-flex/data-plane.md
+++ b/docs/platform/enterprise-flex/data-plane.md
@@ -123,12 +123,13 @@ curl --request POST \
"organizationId": "00000000-0000-0000-0000-000000000000"
}'
```
+
Include the following parameters in your request.
| Body parameter | Required? | Description |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `name` | Required | The name of your region in Airbyte. We reccomend as best practice that you include the cloud provider (if applicable), and actual region in the name. |
-| `organizationId` | Required | Your Airbyte organization ID. To find this in the UI, navigate to `Settings` > `General`. |
+| `name` | Required | The name of your region in Airbyte. We recommend as best practice that you include the cloud provider (if applicable), and actual region in the name. |
+| `organizationId` | Required | Your Airbyte organization ID. To find this in the UI, navigate to **Organizaton settings** > **General**. |
| `enabled` | Optional | Defaults to true. Set this to `false` if you don't want this region enabled. |
For additional request examples, see [the API reference](https://reference.airbyte.com/reference/regions#/).
@@ -326,13 +327,11 @@ You can only associate each workspace with one region.
Follow these steps to associate your region to your current workspace using Airbyte's user interface.
-1. In the navigation panel, click **Settings**.
-
-2. Under **Workspace**, click **General**.
+1. In the navigation panel, click **Workspace settings** > **General**.
-3. Under **Region**, select your region.
+2. Under **Region**, select your region.
-4. Click **Save changes**. Now, run any sync. You will see the workloads spin up in the new data plane you've configured.
+3. Click **Save changes**. Now, run any sync. You will see the workloads spin up in the new data plane you've configured.
@@ -429,7 +428,6 @@ For additional request examples, see [the API reference](https://reference.airby
-
## Check which region your workspaces use
@@ -437,11 +435,7 @@ For additional request examples, see [the API reference](https://reference.airby
You can see a list of your workspaces and the region associated to each from Airbyte's organization settings.
-1. In Airbyte's user interface, click **Settings**.
-
-2. Under **Organization**, click **General**.
-
-Airbyte displays your workspaces and each workspace region under **Regions**.
+1. In Airbyte's user interface, click **Workspace settings** > **General**. Airbyte displays your workspaces and each workspace region under **Regions**.
diff --git a/docs/platform/enterprise-setup/api-access-config.md b/docs/platform/enterprise-setup/api-access-config.md
index e213de087066..6f8f6d6ea5d7 100644
--- a/docs/platform/enterprise-setup/api-access-config.md
+++ b/docs/platform/enterprise-setup/api-access-config.md
@@ -10,7 +10,13 @@ Access to the API in Self-Managed Enterprise deployments is controlled via appli
## Step 1: Create an Application
-While logged into the Airbyte UI, go to the `settings/applications` page, then create an application to get a pair of `client_id` and `client_secret` credentials. This can be exchanged anytime to get an access token to make requests to the API. These credentials do not expire, but may be deleted at any time.
+1. In the navigation bar, click your user name > **User settings** > **Applications**.
+
+2. Click **Create an application**.
+
+3. Give you application a descriptive name.
+
+4. Copy your `client_id` and `client_secret` credentials. You can exchange them anytime to get an access token to make requests to the API. These credentials don't expire, but you can delete them at any time.
diff --git a/docs/platform/enterprise-setup/assets/enterprise-applications-creation.png b/docs/platform/enterprise-setup/assets/enterprise-applications-creation.png
index 0e4183b34b13..bdceb45ce0b3 100644
Binary files a/docs/platform/enterprise-setup/assets/enterprise-applications-creation.png and b/docs/platform/enterprise-setup/assets/enterprise-applications-creation.png differ
diff --git a/docs/platform/enterprise-setup/assets/multiple-regions-in-airbyte.png b/docs/platform/enterprise-setup/assets/multiple-regions-in-airbyte.png
index b226d50bb3c6..49c23b374653 100644
Binary files a/docs/platform/enterprise-setup/assets/multiple-regions-in-airbyte.png and b/docs/platform/enterprise-setup/assets/multiple-regions-in-airbyte.png differ
diff --git a/docs/platform/enterprise-setup/multi-region.md b/docs/platform/enterprise-setup/multi-region.md
index 6d0772422b1a..2c177bfb7b0f 100644
--- a/docs/platform/enterprise-setup/multi-region.md
+++ b/docs/platform/enterprise-setup/multi-region.md
@@ -163,13 +163,11 @@ You can only associate each workspace with one region.
Follow these steps to associate your region to your current workspace using Airbyte's user interface.
-1. In the navigation panel, click **Settings**.
+1. In the navigation panel, click **Workspace settings** > **General**.
-2. Under **Workspace**, click **General**.
+2. Under **Region**, select your region.
-3. Under **Region**, select your region.
-
-4. Click **Save changes**.
+3. Click **Save changes**.
@@ -445,11 +443,7 @@ helm upgrade --install airbyte-enterprise airbyte/airbyte-data-plane --version 1
You can see a list of your workspaces and the region associated to each from Airbyte's organization settings.
-1. In Airbyte's user interface, click **Settings**.
-
-2. Under **Organization**, click **General**.
-
-Airbyte displays your workspaces and each workspace region under **Regions**.
+1. In Airbyte's user interface, click **Workspace settings** > **General**. Airbyte displays your workspaces and each workspace region under **Regions**.
@@ -478,6 +472,3 @@ Response:
-
-
-
diff --git a/docs/platform/images/organization-homepage.png b/docs/platform/images/organization-homepage.png
new file mode 100644
index 000000000000..53b09aa14aff
Binary files /dev/null and b/docs/platform/images/organization-homepage.png differ
diff --git a/docs/platform/images/organization-switch.png b/docs/platform/images/organization-switch.png
new file mode 100644
index 000000000000..b06d9090d74e
Binary files /dev/null and b/docs/platform/images/organization-switch.png differ
diff --git a/docs/platform/images/workspace-homepage.png b/docs/platform/images/workspace-homepage.png
new file mode 100644
index 000000000000..91f9902307d4
Binary files /dev/null and b/docs/platform/images/workspace-homepage.png differ
diff --git a/docs/platform/managing-airbyte/connector-updates.md b/docs/platform/managing-airbyte/connector-updates.md
index 1618577b5bd4..f93112a33b14 100644
--- a/docs/platform/managing-airbyte/connector-updates.md
+++ b/docs/platform/managing-airbyte/connector-updates.md
@@ -2,6 +2,8 @@
products: oss-community, oss-enterprise
---
+import MigrationGuide from '@site/static/_migration_guides_upgrade_guide.md';
+
# Managing Connector Updates in Airbyte
While maintaining an Airbyte instance, you'll need to manage connector updates. These are essential for improved functionality, reliability, and compatibility over time. Our team and community contributors are dedicated to maintaining up-to-date connectors. Reasons for updates can be broadly categorized into bug fixes, new features, and changes that impact the user experience or the functionality of the connector.
@@ -10,8 +12,9 @@ As various APIs and databases you're syncing with Airbyte evolve over time, we m
This guide helps you understand the types of updates you may see, their impact on your Airbyte environment, and the actions you may need to take in response to certain types of updates.
-## Understanding Connector Versions
-To manage connection updates effectively, it's important to understand versioning and how to interpret the changelog entries.
+## Understanding Connector Versions
+
+To manage connection updates effectively, it's important to understand versioning and how to interpret the changelog entries.
Connectors in Airbyte's catalog generally follow semantic versioning ([semver](https://semver.org/)) Major.Minor.Patch (e.g., 1.2.5)
@@ -25,17 +28,17 @@ Each connector's changelog details its update history. You can find it in the [c
-
## How Airbyte Handles Connector Updates
### Airbyte Cloud
+
**Minor and Patch Versions:** These are applied automatically and immediately to your instance. You don't need to take any action.
**Major Versions:** A major version will include notable changes that affect your schema or sync success. We will notify you ahead of time to give you a window to prepare for the change. At the end of the window, we will automatically upgrade your connector to ensure you receive the latest updates. Examples of major version changes are shared in our [breaking change documentation](/platform/using-airbyte/schema-change-management#major-connector-version-upgrades).
-## Airbyte Open Source (OSS) and Self-Managed Enterprise (SME)
+### Airbyte Open Source (OSS) and Self-Managed Enterprise (SME)
-Airbyte recommends using an updated version of Airbyte when updating connections.
+Airbyte recommends using the latest version of Airbyte when updating connections.
**All Versions (Major, Minor, Patch):** These are opt-in via the settings page. You'll see a badge in the sidebar indicating available updates.
@@ -52,12 +55,4 @@ When new major versions are released, we recommended you update promptly to avoi
## Actions to Take in Response to Connector Updates
-### Review the Changelog:
-Before applying any update, carefully review the changelog to understand the changes and their potential impact on your existing connections. You can find the changelog for any connector by navigating to the bottom of the documentation for the connector and expanding the view. Major version releases will also include a migration guide.
-
-### Plan for Major Updates:
-Major updates may require you to adjust connection settings or even make changes to your data pipelines. Be sure to allocate time and resources for this. Use the migration guide to ensure your transition process goes smoothly.
-
-:::info
-Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You will always need to manually update for major version bumps.
-:::
+
diff --git a/docs/platform/operator-guides/clear.md b/docs/platform/operator-guides/clear.md
index 273941816eb0..93d7d6fd40dc 100644
--- a/docs/platform/operator-guides/clear.md
+++ b/docs/platform/operator-guides/clear.md
@@ -26,7 +26,7 @@ A Clear can be triggered either from the UI or Airbyte API. Airbyte allows you t
## Steps to Clear Data
-To perform a full removal of the data for all your streams, navigate to a connection's `Settings` tab and click "Clear data". Confirm the selection to remove all previously synced data from the destination for that connection.
+To perform a full removal of the data for all your streams, navigate to a connection's **Settings** tab and click **Clear data**. Confirm the selection to remove all previously synced data from the destination for that connection.
To clear data for a single stream, navigate to a Connection's status page, click the three grey dots next to any stream, and select "Clear data". This will clear the data for just that stream. You will then need to sync the connection again in order to reload data for that stream.
diff --git a/docs/platform/operator-guides/telemetry.md b/docs/platform/operator-guides/telemetry.md
index 4ceecfc3db40..f98ae2ba34d9 100644
--- a/docs/platform/operator-guides/telemetry.md
+++ b/docs/platform/operator-guides/telemetry.md
@@ -37,6 +37,7 @@ If you'd like to turn off telemetry data collection, follow the directions below
tracking:
strategy: logging
```
+
@@ -45,8 +46,9 @@ If you'd like to turn off telemetry data collection, follow the directions below
To change this later, do one of the following.
- - In Airbyte, go to **Settings** > **User Settings** > **Cookie Preferences**.
- - On Airbyte's website, click **Cookie Preferences** in the footer of our [homepage](https://airbyte.com).
+ - In the navigation bar, click your user name > **User settings** > **Cookie Preferences**.
+
+ - On Airbyte's [website](https://airbyte.com), click **Cookie Preferences** in the footer.
You can't change server-side telemetry collection in Airbyte Cloud.
diff --git a/docs/platform/operator-guides/using-custom-connectors.md b/docs/platform/operator-guides/using-custom-connectors.md
index 02bcc4d851f9..ee75b129f8f2 100644
--- a/docs/platform/operator-guides/using-custom-connectors.md
+++ b/docs/platform/operator-guides/using-custom-connectors.md
@@ -99,7 +99,7 @@ At this step, you should have:
You can pull your connector image from your private registry to validate the previous steps. On your Airbyte instance: run `docker pull :` if you are using our `docker-compose` deployment, or start a pod that is using the connector image.
-1. Click on `Settings` in the left-hand sidebar. Navigate to `Sources` or `Destinations` depending on your connector. Click on `Add a new Docker connector`.
+1. Click **Workspace settings** > **Sources**/**Destinations** depending on your connector. Click **New connector** > **Add a new Docker connector**.
2. Name your custom connector in `Connector display name`. This is just the display name used for your workspace.
diff --git a/docs/platform/operator-guides/using-the-airflow-airbyte-operator.md b/docs/platform/operator-guides/using-the-airflow-airbyte-operator.md
index 4e76091d7d25..5893b5688e7b 100644
--- a/docs/platform/operator-guides/using-the-airflow-airbyte-operator.md
+++ b/docs/platform/operator-guides/using-the-airflow-airbyte-operator.md
@@ -46,11 +46,13 @@ Don't forget to click save!
### Retrieving the Airbyte Connection ID
-We'll need the Airbyte Connection ID so our Airflow DAG knows which Airbyte Connection to trigger.
+Get the Airbyte Connection ID so your Airflow DAG knows which Airbyte Connection to trigger.
-
+1. Open Airbyte.
-This ID can be seen in the URL on the connection page in the Airbyte UI. The Airbyte UI can be accessed at `localhost:8000`.
+2. Click **Connections** > your connection.
+
+3. Get the connection ID from the URL. The URL looks like the following example, and your connection ID appears near the end: `https:///workspaces//connections//status`.
### Creating a simple Airflow DAG to run an Airbyte Sync Job
@@ -85,15 +87,11 @@ The Airbyte Airflow Operator accepts the following parameters:
- `timeout`: Maximum time Airflow will wait for the Airbyte job to complete. Only valid when `asynchronous=False`. Default value is `3600` seconds.
- `wait_seconds`: The amount of time to wait between checks. Only valid when `asynchronous=False`. Default value is `3` seconds.
-This code will produce the following simple DAG in the Airbyte UI:
-
-
+This code will produce the following simple DAG in the Airbyte UI: `airbyte_money_json_example`.
Our DAG will show up in the Airflow UI shortly after we place our DAG file, and be automatically triggered shortly after.
-Check Airbyte UI's Sync History tab to see if the job started syncing!
-
-
+Check the Timeline tab to see if the job started syncing.
### Using the `asynchronous` parameter
@@ -131,8 +129,6 @@ with DAG(dag_id='airbyte_trigger_job_example_async',
Don't be fooled by our simple example of only one Airflow task. Airbyte is a powerful data integration platform supporting many sources and destinations. The Airbyte Airflow Operator means Airbyte can now be easily used with the Airflow ecosystem - give it a shot!
-We love to hear any questions or feedback on our [Slack](https://slack.airbyte.io/). If you see any rough edges or want to request a connector, feel free to create an issue on our [Github](https://github.com/airbytehq/airbyte) or thumbs up an existing issue.
-
## Related articles and guides
For additional information about using the Airflow and Airbyte together, see the following:
diff --git a/docs/platform/organizations-workspaces/organizations/readme.md b/docs/platform/organizations-workspaces/organizations/readme.md
new file mode 100644
index 000000000000..d150e62aba4b
--- /dev/null
+++ b/docs/platform/organizations-workspaces/organizations/readme.md
@@ -0,0 +1,21 @@
+---
+products: cloud
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Organizations
+
+The highest level of structure in Airbyte is an **organization**. Organizations are how you manage membership and permissions, billing (if applicable), and overall account usage.
+
+Self-Managed deployments only have one organization, but you can deploy Airbyte multiple times to establish different organizations.
+
+Organizations contain one or more [workspaces](../workspaces). From your organization's home page, you can view all of your workspaces and the current status of all syncs. Use this ability to identify workspaces with failed syncs that might need your attention.
+
+
+
+Each organization is unrelated to all others. Most Airbyte users belong to a single organization, but some people belong to multiple organizations. For example, a consultant working with multiple companies might have access to multiple Airbyte organizations.
+
+## Manage your organizations
+
+
diff --git a/docs/platform/organizations-workspaces/organizations/switch-organizations.md b/docs/platform/organizations-workspaces/organizations/switch-organizations.md
new file mode 100644
index 000000000000..ce93d20f2263
--- /dev/null
+++ b/docs/platform/organizations-workspaces/organizations/switch-organizations.md
@@ -0,0 +1,13 @@
+---
+products: cloud
+---
+
+# Switch organizations
+
+If you belong the multiple organizations, you can switch between them.
+
+1. Click the organization name in the navigation bar.
+
+2. Find and click the name of the organization you want to switch to.
+
+ 
diff --git a/docs/platform/organizations-workspaces/readme.md b/docs/platform/organizations-workspaces/readme.md
new file mode 100644
index 000000000000..35d46b658923
--- /dev/null
+++ b/docs/platform/organizations-workspaces/readme.md
@@ -0,0 +1,13 @@
+---
+products: cloud, oss-enterprise
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Organizations and workspaces
+
+Organizations and workspaces are the highest levels of structure in Airbyte. They're the primary ways you segregate data and connections, manage access, and control billing.
+
+If you use Self-Managed Community, you only have one organization and one workspace, so these concepts aren't relevant to you.
+
+
diff --git a/docs/platform/organizations-workspaces/workspaces/readme.md b/docs/platform/organizations-workspaces/workspaces/readme.md
new file mode 100644
index 000000000000..57f6ef621b95
--- /dev/null
+++ b/docs/platform/organizations-workspaces/workspaces/readme.md
@@ -0,0 +1,29 @@
+---
+products: cloud, oss-enterprise
+---
+
+import DocCardList from '@theme/DocCardList';
+
+# Workspaces
+
+Each organization consists of one or more **workspaces**. A workspace groups sources, destinations, connections. You can also use workspaces to assign access and permissions. You can use a single workspace for everything, or you can divide your organization into multiple workspaces.
+
+
+
+You can use workspaces for the following purposes.
+
+- Manage access and monitor usage at a more granular level. For example, you may want to separate Airbyte users into smaller groups who can only access certain data based on their role of permission level in your organization.
+
+- Organize sources, destinations, and connections into different conceptual buckets.
+
+- Control data residency and sovereignty. Each workspace can run syncs in a separate region.
+
+ - If you use Cloud, you can choose between Airbyte's managed regions.
+
+ - If you use [Enterprise Flex](../../enterprise-flex) or [Self-Managed Enterprise](../../enterprise-setup), you can also self-manage your own regions and data planes on your own infrastructure.
+
+- Set up notifications.
+
+If you use Self-Managed Community, you only have one workspace.
+
+
diff --git a/docs/platform/using-airbyte/images/mappings.png b/docs/platform/using-airbyte/images/mappings.png
index 6c0556167a1e..e930673f17fa 100644
Binary files a/docs/platform/using-airbyte/images/mappings.png and b/docs/platform/using-airbyte/images/mappings.png differ
diff --git a/docs/platform/using-airbyte/tagging.md b/docs/platform/using-airbyte/tagging.md
index 8dc777326580..1414947ee23f 100644
--- a/docs/platform/using-airbyte/tagging.md
+++ b/docs/platform/using-airbyte/tagging.md
@@ -70,9 +70,9 @@ Airbyte applies and removes tags and you select and deselect them.
Rename and recolor a tag.
-1. Open Airbyte and click **Settings** > **General**.
+1. Open Airbyte and click **Workspace settings** > **General**.
-2. Under **Workspace Tags**, click the pencil icon .
+2. Under **Connection tags**, click the pencil icon .
3. Rename the tag and update the color as you prefer. The color must be a valid hexadecimal code. Click the color sample and use the color picker to generate this for you.
@@ -84,9 +84,9 @@ Airbyte updates your tag. Next time you view the Connections page, your tags wil
Delete a tag from Airbyte and remove it from any connections that use it.
-1. Open Airbyte and click **Settings** > **General**.
+1. Open Airbyte and click **Workspace settings** > **General**.
-2. Under **Workspace Tags**, click the trash icon .
+2. Under **Connection tags**, click the trash icon .
3. Click **Delete**.
diff --git a/docs/platform/using-airbyte/workspaces.md b/docs/platform/using-airbyte/workspaces.md
index 66d50f360ac4..178439db16d2 100644
--- a/docs/platform/using-airbyte/workspaces.md
+++ b/docs/platform/using-airbyte/workspaces.md
@@ -2,63 +2,86 @@
products: cloud, oss-enterprise
---
-# Manage your workspace
+# Manage workspaces
-A workspace in Airbyte allows you to collaborate with other users and manage connections together.
+You can create, manage, and delete workspaces, and control access to them.
-## Add users to your workspace
+## Create a new workspace
-1. To add a user to your workspace, go to the **Settings** via the side navigation in Airbyte. Navigate to **Workspace** > **General** and click **+ New member**.
+Organization admins and readers can create workspaces. Follow these steps to create a new workspace.
-2. On the **Add new member** dialog, enter the email address of the user you want to invite to your workspace. Click **Add new member**.
+1. Go to your Organization home page.
-:::info
-The user will have access to only the workspace you invited them to. They will be added with a role of `Workspace Admin`, which has the ability to add or delete other users and make changes to connections and connectors in the workspace.
-:::
+2. Click **New workspace**.
-## Remove users from your workspace
+3. Enter a workspace name and select a [region](/platform/cloud/managing-airbyte-cloud/manage-data-residency).
-1. To remove a user from your workspace, to the **Settings** via the side navigation in Airbyte. Navigate to **Workspace** > **General**. In the workspace role column, click the down carat and select **Remove user**.
+4. Click **Create workspace**. Airbyte creates a new, empty workspace.
-2. Complete removal by clicking **Remove** in the confirmation modal.
+## Rename a workspace
-:::tip
-Organization admins cannot be removed from a workspace. Reach out to Airbyte Support if you need assistance removing an organization admin.
-:::
+Workspace admins can rename workspaces. Follow these steps to rename a workspace.
-## Rename a workspace
+1. [Switch](#switch-workspaces) to the workspace you want to rename.
-To rename a workspace, go to the **Settings** via the side navigation in Airbyte. Navigate to **Workspace** > **General**. In the **Workspace name** field, enter the new name for your workspace. Click **Save changes**.
+2. Click **Workspace settings** > **General**.
-## Delete a workspace
+3. Under **Workspace name**, type the new name.
-To delete a workspace, go to the **Settings** via the side navigation in Airbyte. Navigate to **Workspace** > **General**. In the **Danger!** section, click **Delete your workspace**.
+4. Click **Save changes**. Airbyte renames your workspace.
-## Managing multiple workspaces
+## Delete a workspace
-You can have access to one or multiple workspaces with Airbyte Cloud, which gives you flexibility in managing user access and billing. Workspaces can also be linked through an organization, which allows you to collaborate with team members and share workspaces across your team.
+Organizations admins and editors, and workspace admins, can delete a workspace. Follow these steps to delete a workspace.
-:::info
-Organizations are only available in Airbyte Cloud through Cloud Teams. [Get in touch](https://airbyte.com/company/talk-to-sales) with us if you would like to take advantage of organization features.
+:::danger
+Deleting a workspace deletes all its sources, destinations, and connections. This is irreversible. Think carefully before doing this.
:::
-### Billing across multiple workspaces
+1. [Switch](#switch-workspaces) to the workspace you want to delete.
+
+2. Click **Workspace settings** > **General**.
+
+3. Click **Delete your workspace**.
+
+4. Type your workspace name to confirm you want to delete it.
+
+5. Click **Delete workspace**. Airbyte permanently deletes your workspace.
+
+## Add users to your workspace
+
+Workspace admins can add any organization member to a workspace.
+
+1. [Switch](#switch-workspaces) to the workspace you want to add them to.
+
+2. Click **Workspace settings** > **Members**.
+
+3. Click **New member**.
+
+4. Start entering the person's name or email to find them in the list.
+
+5. Click their name to select them, then assign them an [RBAC](../access-management/rbac) role.
+
+6. Click **Add new member**.
+
+## Remove someone from your workspace
+
+Workspace admins can remove someone from a workspace, but can't remove other workspace admins. Follow these steps to remove someone from your workspace.
+
+1. [Switch](#switch-workspaces) to the workspace you want to remove them from.
-Airbyte [credits](https://airbyte.com/pricing) are by default assigned per workspace and cannot be transferred between workspaces. [Get in touch](https://airbyte.com/company/talk-to-sales) with us if you would like to centralize billing across workspaces.
+2. Click **Workspace settings** > **Members**.
-## Managing User Roles
+3. Find the person you want to remove, click the role next to their name, and select **Remove user from workspace**.
-Airbyte offers multiple user roles to enable teams to securely access workspaces or organizations. All roles are available to Cloud Teams and Self-Managed Enterprise users. Cloud users only have admin roles.
+## Switch between workspaces {#switch-workspaces}
-| Role | Cloud | Cloud Teams | Enterprise |
-| ----------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
-| **Organization Admin:** Administer the whole organization, create workspaces in it, and manage organization permissions | ✅ | ✅ | ✅ |
-| **Workspace Admin:** Administer the workspace, create workspace permissions | ✅ | ✅ | ✅ |
-| **Workspace Reader:** View information within a workspace, cannot modify anything within a workspace | | ✅ | ✅ |
+If you have multiple workspaces in the same organization, you can switch between them. Any workspace reader, runner, editor, or admin can open a workspace.
+1. In the navigation bar, under **Workspace**, click the dropdown with your current workspace name.
-More information about specific roles can be found in our [Role-Based Access Control documentation](../access-management/rbac.md).
+2. Find and click the name of the workspace you want to switch to. Airbyte switches to that workspace.
-## Switch between multiple workspaces
+## Managing roles
-To switch between workspaces, click the current workspace name under the Airbyte logo in the navigation bar. Search for the workspace or click the name of the workspace you want to switch to.
+See [Role based access control](../access-management/rbac) to learn more about the different roles available. If you're on the Cloud Standard plan, all users are admins.
diff --git a/docs/vale-styles/config/vocabularies/Airbyte/accept.txt b/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
index a4fe4a3d88c9..f08502c874a2 100644
--- a/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
+++ b/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
@@ -58,11 +58,16 @@ DPath
UUID
URL
SSO
+SQL
+IP[s]
+CDC
# Airbyte connectors
Nessie
S3 Data Lake
+PostgreSQL
+Postgres
# Companies, products, and jargon
@@ -74,6 +79,7 @@ HubSpot
Zendesk
Okta
Entra
+Slack
# Acceptable non-words that shouldn't trigger spellcheck
diff --git a/docusaurus/docusaurus.config.js b/docusaurus/docusaurus.config.js
index 0305892d583d..353032e1467e 100644
--- a/docusaurus/docusaurus.config.js
+++ b/docusaurus/docusaurus.config.js
@@ -246,6 +246,33 @@ const config = {
colorMode: {
disableSwitch: false,
},
+ mermaid: {
+ theme: {
+ light: 'base', // "base" theme is fully customizable
+ dark: 'base'
+ },
+ options: {
+ themeVariables: {
+ primaryColor: '#5F5CFF', // Airbyte blue
+ primaryTextColor: '#FFFFFF', // white labels on colored shapes
+ primaryBorderColor: '#1A194D', // slightly darker for contrast
+ secondaryColor: '#FF6A4D', // accent orange
+ // secondaryTextColor: '#FF6A4D', // accent orange
+ // secondaryBorderColor: '#FF6A4D', // accent orange
+ tertiaryColor: '#E8EAF6', // light neutral fill
+ tertiaryTextColor: '#000000', // black labels on light shapes
+ tertiaryBorderColor: '#E8EAF6', // light neutral border
+ background: '#FFFFFF',
+ clusterBkg: '#F5F5F5',
+ fontFamily: 'var(--ifm-font-family-base)',
+ },
+ flowchart: {
+ rankSpacing: 100, // vertical space
+ subGraphTitleMargin: 10, // space within subgraph border for title
+ nodeSpacing: 100, // horizontal space
+ },
+ },
+ },
docs: {
sidebar: {
autoCollapseCategories: true,
diff --git a/docusaurus/sidebar-platform.js b/docusaurus/sidebar-platform.js
index 2c145cbd2006..13bb7543390f 100644
--- a/docusaurus/sidebar-platform.js
+++ b/docusaurus/sidebar-platform.js
@@ -6,7 +6,7 @@ const sectionHeader = (title) => ({
const buildAConnector = {
type: "category",
- label: "Building Connectors",
+ label: "Build connectors",
link: {
type: "doc",
id: "connector-development/README",
@@ -138,6 +138,7 @@ const buildAConnector = {
"connector-development/local-connector-development",
"connector-development/connector-specification-reference",
"connector-development/partner-certified-destinations",
+ "operator-guides/using-custom-connectors",
"connector-development/debugging-docker",
"connector-development/writing-connector-docs",
"connector-development/schema-reference",
@@ -269,7 +270,7 @@ module.exports = {
id: "readme",
},
items: [
- sectionHeader("Getting Started"),
+ sectionHeader("Get started"),
{
type: "doc",
@@ -284,10 +285,10 @@ module.exports = {
type: "doc",
id: "using-airbyte/getting-started/academy",
},
- sectionHeader("Moving and Managing Data"),
+ sectionHeader("Move and manage data"),
{
type: "category",
- label: "Moving data",
+ label: "Move data",
link: {
type: "doc",
id: "move-data/readme",
@@ -370,11 +371,80 @@ module.exports = {
"move-data/rejected-records"
],
},
- "using-airbyte/sync-files-and-records"
+ "using-airbyte/sync-files-and-records",
],
- },
- buildAConnector,
- sectionHeader("Managing Airbyte"),
+ },
+ {
+ type: "category",
+ label: "Organizations and workspaces",
+ link: {
+ type: "doc",
+ id: "organizations-workspaces/readme",
+ },
+ items: [
+ {
+ type: "category",
+ label: "Organizations",
+ link: {
+ type: "doc",
+ id: "organizations-workspaces/organizations/readme",
+ },
+ items: [
+ "organizations-workspaces/organizations/switch-organizations",
+ "cloud/managing-airbyte-cloud/manage-credits",
+ ],
+ },
+ {
+ type: "category",
+ label: "Workspaces",
+ link: {
+ type: "doc",
+ id: "organizations-workspaces/workspaces/readme",
+ },
+ items: [
+ "using-airbyte/workspaces",
+ "cloud/managing-airbyte-cloud/manage-data-residency",
+ "cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications",
+ ],
+ },
+ {
+ type: "category",
+ label: "Access management",
+ items: [
+ {
+ type: "category",
+ label: "Single Sign-On (SSO)",
+ link: {
+ type: "doc",
+ id: "access-management/sso",
+ },
+ items: [
+ {
+ type: "autogenerated",
+ dirName: "access-management/sso-providers",
+ },
+ ],
+ },
+ {
+ type: "category",
+ label: "Role-Based Access Control (RBAC)",
+ link: {
+ type: "doc",
+ id: "access-management/rbac",
+ },
+ items: [
+ {
+ type: "doc",
+ id: "access-management/role-mapping",
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ },
+ buildAConnector,
+ sectionHeader("Deploy and upgrade Airbyte"),
deployAirbyte,
{
type: "category",
@@ -428,41 +498,6 @@ module.exports = {
"operator-guides/telemetry",
],
},
-
- {
- type: "category",
- label: "Access Management",
- items: [
- {
- type: "category",
- label: "Single Sign-On (SSO)",
- link: {
- type: "doc",
- id: "access-management/sso",
- },
- items: [
- {
- type: "autogenerated",
- dirName: "access-management/sso-providers",
- },
- ],
- },
- {
- type: "category",
- label: "Role-Based Access Control (RBAC)",
- link: {
- type: "doc",
- id: "access-management/rbac",
- },
- items: [
- {
- type: "doc",
- id: "access-management/role-mapping",
- },
- ],
- },
- ],
- },
{
type: "category",
label: "Airbyte at Scale",
@@ -511,18 +546,7 @@ module.exports = {
"operator-guides/using-orchestra-task",
],
},
- {
- type: "category",
- label: "Account Management",
- items: [
- "cloud/managing-airbyte-cloud/manage-data-residency",
- "using-airbyte/workspaces",
- "cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications",
- "cloud/managing-airbyte-cloud/manage-credits",
- "operator-guides/using-custom-connectors",
- ],
- },
- sectionHeader("Developer Guides"),
+ sectionHeader("Developer guides"),
{
type: "doc",
id: "api-documentation",
@@ -555,7 +579,7 @@ module.exports = {
contributeToAirbyte,
"community/getting-support",
"community/code-of-conduct",
- sectionHeader("Product Updates"),
+ sectionHeader("Product updates"),
{
type: "link",
label: "Roadmap",
diff --git a/docusaurus/static/.gitbook/assets/upgrade-connector-version.png b/docusaurus/static/.gitbook/assets/upgrade-connector-version.png
index 1a5f3cf6a286..8765fb4f0aab 100644
Binary files a/docusaurus/static/.gitbook/assets/upgrade-connector-version.png and b/docusaurus/static/.gitbook/assets/upgrade-connector-version.png differ
diff --git a/docusaurus/static/_migration_guides_upgrade_guide.md b/docusaurus/static/_migration_guides_upgrade_guide.md
new file mode 100644
index 000000000000..00c86e799e75
--- /dev/null
+++ b/docusaurus/static/_migration_guides_upgrade_guide.md
@@ -0,0 +1,79 @@
+Review the following information to prepare for and execute your upgrade.
+
+### Review the changelog
+
+Before updating a connector, review the changelog to understand the changes and their potential impact on your existing connections. Find the changelog for any connector by navigating to the bottom of the documentation for that connector. Major version releases also include a migration guide.
+
+### Plan for major updates
+
+Major updates may require you to adjust connection settings or even make changes to your data pipelines. Allocate enough time and resources for this. Use the migration guide to ensure your transition process goes smoothly.
+
+Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You always need to manually update for major version bumps.
+
+### Self-managed plans: pin a specific version if you can't update
+
+If you're unable to upgrade to the new version of a connector, you can pin that connector to a specific version.
+
+1. In the navigation bar:
+
+ - If you're on the Self-Managed Enterprise plan, click **Organization settings** > **Sources**/**Destinations**.
+
+ - If you're on any other plan, click **Workspace settings** > **Sources**/**Destinations**.
+
+2. Edit the entry for the connector you want to pin.
+
+3. Set the **Default Version** to the version you want to use.
+
+### Self-managed plans: update the local connector image
+
+If you self-manage Airbyte, you must manually update the connector image in your local registry before proceeding with the migration. Follow the steps below.
+
+1. In the navigation bar:
+
+ - If you're on the Self-Managed Enterprise plan, click **Organization settings** > **Sources**/**Destinations**.
+
+ - If you're on any other plan, click **Workspace settings** > **Sources**/**Destinations**.
+
+2. Find the connector you want to update in the list of connectors.
+
+ :::note
+ Airbyte lists two versions, the current in-use version and the latest version available.
+ :::
+
+3. Click **Change** to update your OSS version to the latest available version.
+
+### Update the connector version
+
+Update each instance of the connector separately. If you have multiple instances of a connector, updating one doesn't affect the others.
+
+1. In the navigation bar:
+
+ - If you're on the Self-Managed Enterprise plan, click **Organization settings** > **Sources**/**Destinations**.
+
+ - If you're on any other plan, click **Workspace settings** > **Sources**/**Destinations**.
+
+2. Select the instance of the connector you wish to upgrade.
+
+3. Select **Upgrade**.
+
+4. Follow the prompt to confirm you are ready to upgrade to the new version.
+
+### Clear data from affected streams
+
+After upgrading a connector with a breaking change, you must refresh affected schemas and clear your data.
+
+1. In the nav bar, click **Connections**.
+
+2. Find the connection affected by the upgrade.
+
+3. Click the **Schema** tab.
+
+4. Click **Refresh source schema** (looks like ). When Airbyte finishes, it shows you any detected schema changes.
+
+5. Click **OK**.
+
+6. Click **Save changes**
+
+7. [Clear the data](/platform/operator-guides/clear) for the streams affected by this upgrade.
+
+Once the clear is complete, you can begin syncing your data again as usual.