# Configure environment variables

This page describes the preparation part of the
[migration process](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-data.md.txt)
where you configure environment variables in your local environment. From this
environment, you will later execute the commands that configure and actuate the
migration process. Each of these commands will use one or more environment
variables that you set at this stage.

At this stage, you do the following:

1. Set environment variables that are common to all supported
   MongoDB-compatible sources.

2. Set environment variables that are specific to the type of the
   MongoDB-compatible source database and to how it is deployed.

### Set common environment variables

The following template helps to set up environment variables that are common to
all supported MongoDB-compatible sources. You will add extra variables that are
specific to your MongoDB source later.

The template configures the following set of environment variables:

- **General parameters** that are applicable to the entire migration procedure.
- **Datastream connection parameters** that are used to create and manage [Datastream connection profiles](https://docs.cloud.google.com/datastream/docs/create-connection-profiles.md.txt).
- **Datastream data placement parameters** for managing data placement in the Cloud Storage bucket during the migration.
- **Dataflow template parameters** for managing the pipeline that will copy data from the Cloud Storage bucket into your Firestore with MongoDB compatibility database.
- **Additional Dataflow template parameters** these parameters are derived from other parameters that you specify and you don't need to set them.
- **Firestore connection parameters** for establishing a connection to your destination Firestore with MongoDB compatibility database.

Set the following variables before proceeding with other commands in this guide:

```bash
# General parameters
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

# Datastream connection parameters
SRC_CONNECTION_PROFILE_NAME="SRC_CONNECTION_PROFILE_NAME"
DST_CONNECTION_PROFILE_NAME="DST_CONNECTION_PROFILE_NAME"
DATASTREAM_NAME="DATASTREAM_NAME"

# Datastream data placement parameters
GCS_BUCKET_NAME="GCS_BUCKET_NAME"
GCS_BUCKET_ROOT_PATH="GCS_BUCKET_ROOT_PATH"
GCS_BUCKET_SUB_PATH="GCS_BUCKET_SUB_PATH"

# Dataflow template parameters
GCS_BUCKET_TEMPLATE_PATH="GCS_BUCKET_TEMPLATE_PATH"
NUM_WORKERS=NUM_WORKERS
MAX_WORKERS=MAX_WORKERS
WORKER_TYPE="WORKER_TYPE"

# Additional Dataflow template parameters: these are initialized
# from parameters above and don't require further customization
INPUT_FILE_LOCATION="gs://${GCS_BUCKET_NAME}/${GCS_BUCKET_ROOT_PATH}/${GCS_BUCKET_SUB_PATH}/"
TEMP_OUTPUT_LOCATION="gs://${GCS_BUCKET_NAME}/${GCS_BUCKET_ROOT_PATH}/tmp"
DLQ_LOCATION="gs://${GCS_BUCKET_NAME}/${GCS_BUCKET_ROOT_PATH}/dql"
STAGING_LOCATION="gs://${GCS_BUCKET_NAME}/${GCS_BUCKET_ROOT_PATH}/staging"

# Firestore connection parameters
FIRESTORE_CONNECTION_URI="FIRESTORE_CONNECTION_URI"
FIRESTORE_DATABASE_NAME="FIRESTORE_DATABASE_NAME"
```

Replace the following:

- General parameters:

  - <var translate="no">PROJECT_ID</var>: a
    [Project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt)
    of the Google Cloud project where the migration pipeline will run.
    Example: `example-project`.

    It's possible to use a destination Firestore with
    MongoDB compatibility database that is located in another project.
    However, this guide assumes that all relevant resources are located in
    the same project.
  - <var translate="no">LOCATION</var>:
    [a region](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/locations.md.txt) where the
    migration pipeline will run. Examples: `nam5`, `us-central1`.

    We recommed to use the same region as the destination
    Firestore with MongoDB compatibility database.
- Datastream connection parameters:

  - <var translate="no">SRC_CONNECTION_PROFILE_NAME</var>: a human-readable name for the
    [Datastream connection profile](https://docs.cloud.google.com/datastream/docs/create-connection-profiles.md.txt)
    of the MongoDB-compatible source database.
    Example: `source-mongo-profile`.

    You create a connection profile with this name later.
  - <var translate="no">DST_CONNECTION_PROFILE_NAME</var>: a human-readable name for the
    [Datastream connection profile](https://docs.cloud.google.com/datastream/docs/create-connection-profiles.md.txt)
    for the destination Cloud Storage bucket. Example:
    `destination-gcs-profile`.

    You create a destination connection profile with this name later.
  - <var translate="no">DATASTREAM_NAME</var>: A human-readable name of a
    [Datastream stream](https://docs.cloud.google.com/datastream/docs/create-a-stream.md.txt)
    that will transfer the data from the MongoDB-compatible source database
    into Cloud Storage. Example: `mongo-to-gcs-stream`.

    You create this stream later.
- Datastream data placement parameters:

  > [!NOTE]
  > **Note:** Wildcards are not supported in the Cloud Storage paths.

  - <var translate="no">GCS_BUCKET_NAME</var>: the name of the
    Cloud Storage bucket that you've
    [created earlier](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-configure-resources.md.txt#create-bucket).
    Example: `mongo-migration-bucket`.

    This value is used to create a destination connection profile later.
  - <var translate="no">GCS_BUCKET_ROOT_PATH</var>: The name of the top-level directory
    in the Cloud Storage bucket for placing the intermediate data
    during the migration. Example: `mongo-migration-root`.

    This value is used to create a destination connection profile later.
  - <var translate="no">GCS_BUCKET_TEMPLATE_PATH</var>: A sub-path in the
    <var translate="no">GCS_BUCKET_ROOT_PATH</var> directory for a given
    Datastream instance.

    The same destination connection profile can be used for multiple
    exports to Cloud Storage. However **you must designate a
    unique sub-path** for each migration. Example: `mongo-migration-data-0`.

    This value is used to create a stream later.
- Dataflow template parameters:

  - <var translate="no">GCS_BUCKET_TEMPLATE_PATH</var>: A sub-path in the
    <var translate="no">GCS_BUCKET_ROOT_PATH</var> directory where a
    [Dataflow template](https://docs.cloud.google.com/dataflow/docs/concepts/dataflow-templates.md.txt)
    will be staged. Example: `mongo-migration-template-path`.

  - <var translate="no">NUM_WORKERS</var>: The starting number of workers to run the
    Dataflow template with. Example: `2`.

  - <var translate="no">MAX_WORKERS</var>: The maximum number of workers to run the
    Dataflow template with. Example: `8`.

  - <var translate="no">WORKER_TYPE</var>: The Compute Engine instance type to use for
    the Dataflow job. The recommended machine type is
    [`e2-highmem-8`](https://docs.cloud.google.com/compute/docs/general-purpose-machines.md.txt#e2-high-mem).

- Firestore connection parameters:

  - <var translate="no">FIRESTORE_DATABASE_NAME</var>: The name of the
    Firestore with MongoDB compatibility database
    where you migrate the data. Example: `firestore-database-name`.

  - <var translate="no">FIRESTORE_CONNECTION_URI</var>: The
    [connection URI string](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/create-and-query-database.md.txt#create-database)
    for the Firestore with MongoDB compatibility database.

    Example: `mongodb://USERNAME:PASSWORD@CONNECTION_STRING:443/FIRESTORE_DATABASE_NAME?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false`.

### Set environment variables specific to the source database type

The following templates help to set up environment variables that are specific
to the type of the MongoDB-compatible source database and to how it is deployed.

### MongoDB on Compute Engine

The following variables are specific for MongoDB source databases located in a
self-managed cluster (Compute Engine). Set them before proceeding
with other commands in this guide:

```bash
# Google Compute Engine VM MongoDB Parameters
MONGODB_USERNAME="MONGODB_USERNAME"
MONGODB_PASSWORD="MONGODB_PASSWORD"
MONGODB_IP_ADDRESS="MONGODB_IP_ADDRESS"
REPLICA_SET="REPLICA_SET"
MONGODB_DATABASE_NAME="MONGODB_DATABASE_NAME"
PRIVATE_CONNECTION_NAME="PRIVATE_CONNECTION_NAME"
```

Replace the following:

- <var translate="no">MONGODB_USERNAME</var>: The username of the MongoDB-compatible source
  database. Example: `mongouser`.

- <var translate="no">MONGODB_PASSWORD</var>: The password of the MongoDB-compatible source
  database. Example: `mongopassword`.

- <var translate="no">MONGODB_IP_ADDRESS</var>: specify the internal IP address, along with
  the port number, of the VM that hosts your MongoDB server.
  Example: `10.0.0.1:27017`.

  - For deployments that are not sharded, but configured with
    [replica sets](https://www.mongodb.com/docs/manual/replication),
    the IP address of any replica in the set is valid. However, we
    recommend to use one of the secondary replicas.

  - For [sharded clusters](https://www.mongodb.com/docs/manual/sharding),
    specify the address of one of your *mongos* servers.

- (Only for clusters with replica sets that aren't sharded)
  <var translate="no">REPLICA_SET</var>: Specify the name of the replica
  set that must be used for the migration process. Example: `rs0`.

- <var translate="no">MONGODB_DATABASE_NAME</var>: The name of the MongoDB-compatible source
  database. Example: `source_db`.

- <var translate="no">PRIVATE_CONNECTION_NAME</var>: The ID of the private connectivity
  configuration that
  [you've created earlier](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-configure-resources.md.txt#source-specific-configuration).
  Example: `pc_name`.

### MongoDB over SSH

If you are managing a private MongoDB deployment outside of
Compute Engine, Datastream supports connecting to your source
database over a forward-SSH tunnel. For more information, see [SSH tunnels](https://docs.cloud.google.com/datastream/docs/network-connectivity-options.md.txt#sshtunnel).

The following variables are specific for connecting to MongoDB source
databases over a forward-SSH tunnel. Set them before proceeding with other
commands in this guide:

```bash
# MongoDB over an SSH Tunnel Parameters
MONGODB_USERNAME="MONGODB_USERNAME"
MONGODB_PASSWORD="MONGODB_PASSWORD"
MONGODB_IP_ADDRESS="MONGODB_IP_ADDRESS"
REPLICA_SET="REPLICA_SET"
MONGODB_DATABASE_NAME="MONGODB_DATABASE_NAME"
BASTION_IP_ADDRESS="BASTION_IP_ADDRESS"
BASTION_SSH_PORT="BASTION_SSH_PORT"
BASTION_SSH_USERNAME="BASTION_SSH_USERNAME"
BASTION_SSH_PRIVATE_KEY="BASTION_SSH_PRIVATE_KEY"
```

Replace the following:

- <var translate="no">MONGODB_USERNAME</var>: The username of the MongoDB-compatible source
  database. Example: `mongouser`.

- <var translate="no">MONGODB_PASSWORD</var>: The password of the MongoDB-compatible source
  database. Example: `mongopassword`.

- <var translate="no">MONGODB_IP_ADDRESS</var>: specify the internal IP address, along with
  the port number, of the VM that hosts your MongoDB server.
  Example: `10.0.0.1:27017`.

  - For deployments that are not sharded, but configured with
    [replica sets](https://www.mongodb.com/docs/manual/replication),
    the IP address of any replica in the set is valid. However, we
    recommend to use one of the secondary replicas.

  - For [sharded clusters](https://www.mongodb.com/docs/manual/sharding),
    specify the address of one of your *mongos* servers.

- (Only for clusters with replica sets that aren't sharded)
  <var translate="no">REPLICA_SET</var>: Specify the name of the replica
  set that must be used for the migration process. Example: `rs0`.

- <var translate="no">MONGODB_DATABASE_NAME</var>: The name of the MongoDB-compatible source
  database. Example: `source_db`.

- <var translate="no">BASTION_IP_ADDRESS</var>: the address of the host on your network that
  can accept an SSH connection. This can be the MongoDB server itself, or
  a designated [Bastion](https://cloud.google.com/solutions/connecting-securely#bastion) host that
  allows SSH access from a public network, and also provides internal
  connectivity to the actual MongoDB server.
  Example: `30.0.0.1`.

- <var translate="no">BASTION_SSH_PORT</var>: The SSH port on the host. Example: `22`.

- <var translate="no">BASTION_SSH_USERNAME</var>: Username for the ssh connection.

- <var translate="no">BASTION_SSH_PRIVATE_KEY</var>: The full payload of the SSH private key.
  For example, for an RSA key, this payload would include the
  `---BEGIN RSA PRIVATE KEY---` header and the
  `---END RSA PRIVATE KEY---` footer.
  Example: `BASTION_SSH_PRIVATE_KEY=$(cat ~/.ssh/private_key)`

  > [!NOTE]
  > **Note:** Datastream also accepts an SSH password. This alternative is described in the [Connection Profile](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-create-connection-profiles.md.txt#connection-profile-source) section.

### Amazon DocumentDB

Ensure that you have the private SSH key for the Amazon EC2 instance that
will provide the connection to the DocumentDB cluster. Also ensure that you
have downloaded the region-specific Certificate Bundle as described in the
[Resource Configuration](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-configure-resources.md.txt#source-specific-configuration)
section, and extracted and validated a specific certificate.

The following variables are specific for connecting to DocumentDB source
databases over a forward-SSH tunnel. Set them before proceeding with other
commands in this guide:

```bash
# DocumentDB over an EC2 SSH Tunnel Parameters
MONGODB_USERNAME="MONGODB_USERNAME"
MONGODB_PASSWORD="MONGODB_PASSWORD"
MONGODB_HOST_ADDRESS="MONGODB_HOST_ADDRESS"
REPLICA_SET="REPLICA_SET"
MONGODB_DATABASE_NAME="MONGODB_DATABASE_NAME"
BASTION_IP_ADDRESS="BASTION_IP_ADDRESS"
BASTION_SSH_PORT="BASTION_SSH_PORT"
BASTION_SSH_USERNAME="BASTION_SSH_USERNAME"
BASTION_SSH_PRIVATE_KEY="BASTION_SSH_PRIVATE_KEY"
DOCUMENT_DB_CA_CERTIFICATE="DOCUMENT_DB_CA_CERTIFICATE"
```

Replace the following:

- <var translate="no">MONGODB_USERNAME</var>: The username of the DocumentDB source
  database. Example: `mongouser`.

- <var translate="no">MONGODB_PASSWORD</var>: The password of the DocumentDB source
  database. Example: `mongopassword`.

- <var translate="no">MONGODB_HOST_ADDRESS</var>: The address of the DocumentDB cluster.
  Example: `mydocumentdb.cluster-abcd.us-east-2.docdb.amazonaws.com:27017`.

- <var translate="no">REPLICA_SET</var>: Specify the name of the replica set that must be
  used for the migration process. Example: `rs0`.

- <var translate="no">MONGODB_DATABASE_NAME</var>: The name of the DocumentDB source
  database. Example: `source_db`.

- <var translate="no">BASTION_IP_ADDRESS</var>: the external IP address of the EC2 instance
  that allows SSH access from a public network, and also provides internal
  connectivity to the DocumentDB cluster within your Amazon VPC.
  Example: `30.0.0.1`.

- <var translate="no">BASTION_SSH_PORT</var>: The SSH port on the host. Example: `22`.

- <var translate="no">BASTION_SSH_USERNAME</var>: Username for the ssh connection.

- <var translate="no">BASTION_SSH_PRIVATE_KEY</var>: The full payload of the SSH private key.
  For example, for an RSA key, this payload would include the
  `---BEGIN RSA PRIVATE KEY---` header and the
  `---END RSA PRIVATE KEY---` footer.
  Example: `BASTION_SSH_PRIVATE_KEY=$(cat ~/ec2_bastion_host.pem)`

- <var translate="no">DOCUMENT_DB_CA_CERTIFICATE</var>: The full payload of the DocumentDB
  CA Certificate.
  This payload should include the
  `---BEGIN CERTIFICATE---` header and the
  `---END CERTIFICATE---` footer and must only include a single
  certificate.
  Example: `BASTION_SSH_PRIVATE_KEY=$(cat ~/us-east-1.pem)`

### Azure Cosmos DB

The following variables are specific for Azure Cosmos DB source databases. Set
them before proceeding with other commands in this guide:

```bash
# Azure Cosmos DB Parameters
MONGODB_USERNAME="MONGODB_USERNAME"
MONGODB_PASSWORD="MONGODB_PASSWORD"
MONGODB_HOST_ADDRESS="MONGODB_HOST_ADDRESS"
MONGODB_DATABASE_NAME="MONGODB_DATABASE_NAME"
```

Replace the following:

- <var translate="no">MONGODB_USERNAME</var>: The username of the MongoDB-compatible source database. Example: `mongouser`.
- <var translate="no">MONGODB_PASSWORD</var>: The password of the MongoDB-compatible source database. Example: `mongopassword`.
- <var translate="no">MONGODB_HOST_ADDRESS</var>: The hostname of the MongoDB-compatible source database. The value must conform to the [MongoDB SRV connection format](https://www.mongodb.com/docs/manual/reference/connection-string). Example:`host.cosmos.azure.example.com`.
- <var translate="no">MONGODB_DATABASE_NAME</var>: The name of the MongoDB-compatible source database. Example: `source_db`.

### MongoDB Atlas

The following variables are specific for MongoDB Atlas source databases. Set
them before proceeding with other commands in this guide:

```bash
# MongoDB Atlas Parameters
MONGODB_USERNAME="MONGODB_USERNAME"
MONGODB_PASSWORD="MONGODB_PASSWORD"
MONGODB_HOST_ADDRESS="MONGODB_HOST"
MONGODB_DATABASE_NAME="MONGODB_DATABASE_NAME"
```

Replace the following:

- <var translate="no">MONGODB_USERNAME</var>: The username of the MongoDB-compatible source database. Example: `mongouser`.
- <var translate="no">MONGODB_PASSWORD</var>: The password of the MongoDB-compatible source database. Example: `mongopassword`.
- <var translate="no">MONGODB_HOST_ADDRESS</var>: The hostname of the MongoDB-compatible source database. The value must conform to the [MongoDB SRV connection format](https://www.mongodb.com/docs/manual/reference/connection-string). Example:`host.mongodb.example.com`.
- <var translate="no">MONGODB_DATABASE_NAME</var>: The name of the MongoDB-compatible source database. Example: `source_db`.

## What's next

Proceed to
[Create connection profiles](https://docs.cloud.google.com/firestore/mongodb-compatibility/docs/migrate-create-connection-profiles.md.txt).