This page contains the setup guide and reference information for the GCS connector.
Configure and schedule GCS metadata workflows from the CLI:
How to Run the Connector Externally
To run the Ingestion via the UI you'll need to use the OpenMetadata Ingestion Container, which comes shipped with custom Airflow plugins to handle the workflow deployment.
If, instead, you want to manage your workflows externally on your preferred orchestrator, you can check the following docs to run the Ingestion Framework anywhere.
Requirements
To run the GCS ingestion, you will need to install:
OpenMetadata 1.0 or laterTo deploy OpenMetadata, check the Deployment guides.
We need the following permissions in GCP:
GCS Permissions
For all the buckets that we want to ingest, we need to provide the following:
storage.buckets.getstorage.buckets.liststorage.objects.getstorage.objects.list
OpenMetadata Manifest
In any other connector, extracting metadata happens automatically. In this case, we will be able to extract high-level metadata from buckets, but in order to understand their internal structure we need users to provide an openmetadata.json file at the bucket root.
Supported File Formats: [ "csv", "tsv", "avro", "parquet", "json", "json.gz", "json.zip" ]
You can learn more about this here. Keep reading for an example on the shape of the manifest file.
OpenMetadata Manifest
Our manifest file is defined as a JSON Schema, and can look like this:
Entries: We need to add a list of entries. Each inner JSON structure will be ingested as a child container of the top-level one. In this case, we will be ingesting 4 children.
Simple Container: The simplest container we can have would be structured, but without partitions. Note that we still need to bring information about:
- dataPath: Where we can find the data. This should be a path relative to the top-level container.
- structureFormat: What is the format of the data we are going to find. This information will be used to read the data.
- separator: Optionally, for delimiter-separated formats such as CSV, you can specify the separator to use when reading the file. If you don't, we will use
,for CSV and/tfor TSV files.
After ingesting this container, we will bring in the schema of the data in the dataPath.
Partitioned Container: We can ingest partitioned data without bringing in any further details.
By informing the isPartitioned field as true, we'll flag the container as Partitioned. We will be reading the source files schemas', but won't add any other information.
Single-Partition Container: We can bring partition information by specifying the partitionColumns. Their definition is based on the JSON Schema definition for table columns. The minimum required information is the name and dataType.
When passing partitionColumns, these values will be added to the schema, on top of the inferred information from the files.
Multiple-Partition Container: We can add multiple columns as partitions.
Note how in the example we even bring our custom displayName for the column dataTypeDisplay for its type.
Again, this information will be added on top of the inferred schema from the data files.
Unstructured Container: OpenMetadata supports ingesting unstructured files like images, pdf's etc. We support fetching the file names, size and tags associates to such files.
In case you want to ingest a single unstructured file, then just specifying the full path of the unstructured file in datapath would be enough for ingestion.
In case you want to ingest all unstructured files with a specific extension for example pdf & png then you can provide the folder name containing such files in dataPath and list of extensions in the unstructuredFormats field.
In case you want to ingest all unstructured files with irrespective of their file type or extension then you can provide the folder name containing such files in dataPath and ["*"] in the unstructuredFormats field.
Global Manifest
You can also manage a single manifest file to centralize the ingestion process for any container, named openmetadata_storage_manifest.json. For example:
In that case, you will need to add a containerName entry to the structure above. For example:
The fields shown above (dataPath, structureFormat, isPartitioned, etc.) are still valid.
Container Name: Since we are using a single manifest for all your containers, the field containerName will help us identify which container (or Bucket in S3, etc.), contains the presented information.
You can also keep local manifests openmetadata.json in each container, but if possible, we will always try to pick up the global manifest during the ingestion.
Metadata Ingestion
All connectors are defined as JSON Schemas. Here you can find the structure to create a connection to Athena.
In order to create and run a Metadata Ingestion workflow, we will follow the steps to create a YAML configuration able to connect to the source, process the Entities if needed, and reach the OpenMetadata server.
The workflow is modeled around the following JSON Schema
1. Define the YAML Config
This is a sample config for Athena:
Source Configuration - Service Connection
gcpConfig:
1. Passing the raw credential values provided by GCP. This requires us to provide the following information, all provided by GCP:
- type: Credentials Type is the type of the account, for a service account the value of this field is
service_account. To fetch this key, look for the value associated with thetypekey in the service account key file. - projectId: A project ID is a unique string used to differentiate your project from all others in Google Cloud. To fetch this key, look for the value associated with the
project_idkey in the service account key file. You can also pass multiple project id to ingest metadata from different GCP projects into one service. - privateKeyId: This is a unique identifier for the private key associated with the service account. To fetch this key, look for the value associated with the
private_key_idkey in the service account file. - privateKey: This is the private key associated with the service account that is used to authenticate and authorize access to GCP. To fetch this key, look for the value associated with the
private_keykey in the service account file. - clientEmail: This is the email address associated with the service account. To fetch this key, look for the value associated with the
client_emailkey in the service account key file. - clientId: This is a unique identifier for the service account. To fetch this key, look for the value associated with the
client_idkey in the service account key file. - authUri: This is the URI for the authorization server. To fetch this key, look for the value associated with the
auth_urikey in the service account key file. The default value to Auth URI is https://accounts.google.com/o/oauth2/auth. - tokenUri: The Google Cloud Token URI is a specific endpoint used to obtain an OAuth 2.0 access token from the Google Cloud IAM service. This token allows you to authenticate and access various Google Cloud resources and APIs that require authorization. To fetch this key, look for the value associated with the
token_urikey in the service account credentials file. Default Value to Token URI is https://oauth2.googleapis.com/token. - authProviderX509CertUrl: This is the URL of the certificate that verifies the authenticity of the authorization server. To fetch this key, look for the value associated with the
auth_provider_x509_cert_urlkey in the service account key file. The Default value for Auth Provider X509Cert URL is https://www.googleapis.com/oauth2/v1/certs - clientX509CertUrl: This is the URL of the certificate that verifies the authenticity of the service account. To fetch this key, look for the value associated with the
client_x509_cert_urlkey in the service account key file.
2. Passing a local file path that contains the credentials:
gcpCredentialsPath
If you prefer to pass the credentials file, you can do so as follows:
- If you want to use ADC authentication for GCP you can just leave the GCP credentials empty. This is why they are not marked as required.
Source Configuration - Source Config
The sourceConfig is defined here:
containerFilterPattern: Note that the filter supports regex as include or exclude. You can find examples here.
storageMetadataConfigSource: Path to the openmetadata_storage_manifest.json global manifest file. It can be located in S3, a local path or as a URL to the file.
Sink Configuration
To send the metadata to OpenMetadata, it needs to be specified as type: metadata-rest.
Workflow Configuration
The main property here is the openMetadataServerConfig, where you can define the host and security provider of your OpenMetadata installation.
Logger Level
You can specify the loggerLevel depending on your needs. If you are trying to troubleshoot an ingestion, running with DEBUG will give you far more traces for identifying issues.
JWT Token
JWT tokens will allow your clients to authenticate against the OpenMetadata server. To enable JWT Tokens, you will get more details here.
You can refer to the JWT Troubleshooting section link for any issues in your JWT configuration.
Store Service Connection
If set to true (default), we will store the sensitive information either encrypted via the Fernet Key in the database or externally, if you have configured any Secrets Manager.
If set to false, the service will be created, but the service connection information will only be used by the Ingestion Framework at runtime, and won't be sent to the OpenMetadata server.
Store Service Connection
If set to true (default), we will store the sensitive information either encrypted via the Fernet Key in the database or externally, if you have configured any Secrets Manager.
If set to false, the service will be created, but the service connection information will only be used by the Ingestion Framework at runtime, and won't be sent to the OpenMetadata server.
SSL Configuration
If you have added SSL to the OpenMetadata server, then you will need to handle the certificates when running the ingestion too. You can either set verifySSL to ignore, or have it as validate, which will require you to set the sslConfig.caCertificate with a local path where your ingestion runs that points to the server certificate file.
Find more information on how to troubleshoot SSL issues here.
Advanced Configuration
Connection Options (Optional): Enter the details for any additional connection options that can be sent to storage service during the connection. These details must be added as Key-Value pairs.
Connection Arguments (Optional): Enter the details for any additional connection arguments such as security or protocol configs that can be sent to storage service during the connection. These details must be added as Key-Value pairs.