> [!CAUTION]
> You are currently viewing version 1.14 of the Apigee hybrid documentation. For more information, see [Supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions).

<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.14 </button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/data-collection-with-data-residency.html)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/data-collection-with-data-residency.html)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/data-collection-with-data-residency.html)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/data-collection-with-data-residency.md.txt)
- [List of supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions)
- Unsupported versions:
- [v1.13](https://docs.cloud.google.com/apigee/docs/hybrid/v1.13/data-collection-with-data-residency.md.txt)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/data-collection-with-data-residency.html)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/data-collection-with-data-residency.html)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/data-collection-with-data-residency.html)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/data-collection-with-data-residency.html)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/data-collection-with-data-residency.html)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/data-collection-with-data-residency.html)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/data-collection-with-data-residency.html)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/data-collection-with-data-residency.html)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/data-collection-with-data-residency.html)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/data-collection-with-data-residency.html)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/data-collection-with-data-residency.html)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/data-collection-with-data-residency.html)

## Overview


Starting with version 1.13.1, newly created Apigee hybrid orgs use a new data pipeline that allows the
runtime components to write data directly to the control plane. Previously, this was done via
the UDCA component which generated signed urls to write to Google Cloud Services. The new
pipeline eliminates the need for UDCA and other related components responsible for processing
data uploaded to Google Cloud Services.

> [!NOTE]
> **Note:** Starting with hybrid v1.14.0, this configuration is included in the regular installation and upgrades procedures.

## Configuration

You can configure hybrid to use the new data pipeline for individual components using the following instructions.

### Setting Authorization Flow

Set permissions for the runtime service account to interact with new pipeline to push data to the control plane. This step is
required to allow Debug sessions and Analytics to operate with the new pipeline:

```
curl -X  PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type:application/json" \
  "https://CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/ORG_NAME/controlPlaneAccess?update_mask=analytics_publisher_identities" \
  -d '{ "analytics_publisher_identities": ["serviceAccount:apigee-runtime@ORG_NAME.iam.gserviceaccount.com"]}'
```

The response should look like the following:

```
{
  "name": "organizations/newpipeline-hybrid-org/operations/8316aa78-c137-4733-92ec-cc0d2d92fd29",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "UPDATE",
    "targetResourceName": "organizations/newpipeline-hybrid-org/controlPlaneAccess",
    "state": "IN_PROGRESS"
  }
}
```


Verify state of the operation using the name parameter from the update response:

### No data residency

```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
  -H "Content-Type:application/json"  \
  "https://apigee.googleapis.com/v1/organizations/ORG_NAME/operations/8316aa78-c137-4733-92ec-cc0d2d92fd29"
```

### Data residency

```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
  -H "Content-Type:application/json"  \
  "https://CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/ORG_NAME/operations/8316aa78-c137-4733-92ec-cc0d2d92fd29"
```

The response should look like the following:

```
{
  "name": "organizations/newpipeline-hybrid-org/operations/8316aa78-c137-4733-92ec-cc0d2d92fd29",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "UPDATE",
    "targetResourceName": "organizations/newpipeline-hybrid-org/controlPlaneAccess",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.ControlPlaneAccess",
    "name": "organizations/newpipeline-hybrid-org/controlPlaneAccess"
  }
}
```

Verify the organization's ControlPlaneAccess configuration:

### No data residency

```
curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/controlPlaneAccess" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
```

### Data residency

```
curl "https://CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/ORG_NAME/controlPlaneAccess" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
```

The response should look like the following:

```
{
  "synchronizerIdentities": [
    "serviceAccount:apigee-synchronizer@newpipeline-hybrid-org.iam.gserviceaccount.com"
  ],
  "analyticsPublisherIdentities": [
    "serviceAccount:apigee-runtime@newpipeline-hybrid-org.iam.gserviceaccount.com"
  ]
}
```

## Switching between new and old pipelines for debug and Analytics data residency

Once the right authorization has been provided to the service accounts, users can switch their Apigee instance to use the new pipeline.

To switch to the new pipeline, set `newDataPipeline.debugSession: true` and `newDataPipeline.analytics: true` in your `overrides.yaml` file.

To stop using the new pipeline, set `newDataPipeline.debugSession: false` and `newDataPipeline.analytics: false` in your `overrides.yaml` file.

For example:

```
... rest of the overrides.yaml ...
gcp:
  projectID: PROJECT_ID
  region: ANALYTICS_REGION  # Specifies the analytics region for the hybrid org. This attribute is
                               # the regional endpoint used to push analytics and debug data to the
                               # control plane. For example: us-central1

newDataPipeline:
  debugSession: true  # this flag enables debug session to use the new data pipeline
  analytics: true     # this flag enables analytics to use the new data pipeline

k8sCluster:
  name: CLUSTER_NAME
  region: CLUSTER_LOCATION # Must be the closest Google Cloud region to your cluster. For example, us-west1
org: ORG_NAME

... rest of the overrides.yaml ...
```

> [!NOTE]
> **Note:** These values are set to `true` by default starting with hybrid v1.14.0. If you are using to hybrid v1.14.0 or newer, you do not need to add the `newDataPipeline` stanza to your `overrides.yaml` file unless you have previously explicitly set these values to `false`. See
> - [`newDataPipeline.debugSession`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/config-prop-ref.md.txt#newdatapipeline-debugsession)
> - [`newDataPipeline.analytics`](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/config-prop-ref.md.txt#newdatapipeline-analytics)
> in the Configuration property reference.
>
Apply these changes with the `helm upgrade` command. Upgrade one environment at a time. Specify the environment with `--set env=`<var translate="no">ENV_NAME</var>.

```
helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE
```

- <var translate="no">ENV_RELEASE_NAME</var> is the name with which you previously installed the `apigee-env` chart.
- <var translate="no">ENV_NAME</var> is the name of the environment you are upgrading.