Skip to main content

Home

Install Unravel for GCP BigQuery - Single key authentication method

You can install Unravel on a GCP BigQuery VM instance. Unravel is then set up to monitor the jobs, datasets, tables, and data using a service account outside the Google Cloud environment.

This section provides instructions to install Unravel for GCP BigQuery using the Single key authentication method. In this method, a key is generated for a service account, which is used to configure Unravel to receive BigQuery data. This is used in scenarios where the Unravel is installed on a VM outside the GCP environment. In such cases, you cannot use the VM authentication method.

Before setting up Unravel for BigQuery, you must complete the Prerequisites.

Follow the instructions to install and set up Unravel to receive BigQuery data.

Installing Unravel on the GCP Bigquery VM instance

Do the following to set up Unravel on the GCP VM.

  1. From your GCP console, go to the Compute Engine dashboard and click Create Instance.

  2. Select the following options based on Unravel's instance requirements:

    • Base OS

    • Instance type and size

    • Ports

    • Networking

      The instance must be HTTPS and publicly accessible.

    • Firewall rules or policies

      Sample inbound rule

      Type

      Protocol

      Port range

      Source

      All traffic

      All

      All

      For example, 10.10.0.0/16

      SSH

      TCP

      22

      0.0.0.0/0 or trusted public IP for SSH access

      Custom TCP Rule

      TCP

      3000

      Custom TCP Rule

      TCP

      4043

      Sample outbound rule

      Type

      Protocol

      Port range

      Source

      All traffic

      All

      All

      0.0.0.0/0

    Note

    The GCP VM should have all TCP access to the nodes of the BigQuery cluster (server/parent or worker). You can grant access by adding firewall rules of the BigQuery server/parent and worker with all TCP and all port ranges.

    While creating the GCP VM, add the Firewall properties, Enable the HTTP and HTTPS traffic Go to Network tab, and add Network tags. (This is the firewall rule that is already created.)

    dataproce-https-allow.png
Configuring the GCE instance
  1. Disable selinux.

    sudo setenforce Permissive
  2. Edit /etc/selinux/config to ensure the setting persists after reboot and ensure SELINUX=permissive.

    sudo vi /etc/selinux/config
  3. Install libaio.x86_64, lzop.x86_64, and ntp.x86_64.

    sudo yum install -y libaio.x86_64
    sudo yum install -y lzop.x86_64
    sudo yum install -y ntp.x86_64
  4. Start ntpd and check the system time.

    sudo service ntpd start
    sudo ntpq -p
  5. Create a new Unravel user named unravel.

    sudo useradd unravel

Download Unravel onto the VM instance that you have created.

Deploy Unravel on the GCP instance that you have created.

You can also manually install Unravel; refer to Run setup

Note

The HTTPS load balancer for Unravel endpoint must be configured only when using the Push model.

Unravel LR endpoint should be available over a publically accessible HTTPS endpoint to receive messages from BigQuery PubSub. The Load Balancer is an easier and more secure method to push the log messages between the Google Cloud Platform (GCP) and Unravel. Use the following instructions to configure an HTTPS load balancer for Unravel with public endpoint and SSL termination.

You must have the following information handy before you configure the Load Balancer:

  • Region and Zone where the Unravel VM is running.

  • Network and Subnet-network where the Unravel VM is running.

  • A valid SSL certificate in GCP.

Do the following to create a Load Balancer

  1. Create an instance group. Refer to Create a managed instance group for detailed instructions.

    • In the New unmanaged instance group page, ensure to keep the following items the same as that of Unravel VM.

      • Location > Region

      • Location > Zone

      • Network and Instances > Network

      • Network and Instances > SubNetwork

    • Under Port Mapping, enter the following:

      • Port Name: http4043

      • Port Number: 4043

  2. Set up an HTTPS Load Balancer. Refer to Set up an HTTPS Load Balancer for detailed instructions. Ensure to do the following:

    • Under Name, update the name as unravel-loadbalancer.

    • In Backends > New Backend > Instance groups, select the Unravel instance group that you had created in Step 1.

    • Under Health check, do the following:

      • Select Create a health check, and then add the name as unravel-4043-hc

      • Update the Protocol as HTTP and Port as 4043.

      • Update the Request Path as /lr/status.

    • Ensure that Port is set to 443 to allow HTTPS traffic.

  3. After the Load Balancer is created, find the public IP address of the Load Balancer that is mentioned under Frontend section of the Load Balancer. Add the IP address of the Load Balancer to a valid DNS name.

Setting Unravel to receive BigQuery data

Unravel can be set up to automatically create and configure resources in more than 100 projects at a time. Based on the authentication method you selected while installing Unravel, you can add projects either with customer-supplied credentials or with Unravel-generated credentials for Unravel monitoring. These can be single projects or multiple projects.

To integrate the BigQuery projects in Unravel using the single key authentication method, you must create a service account in any project. The key of the service account is downloaded to Unravel VM. This method is used in conditions when the Unravel VM is based outside the GCP environment.

single-key.png

Unravel ships the following resources, which are required to automatically set up Unravel to receive BigQuery data.

  • Terraform

    This is an open-source software for infrastructure provisioning. The Terraform creates resources on the GCP account and facilitates the smooth integration of Unravel with your cloud platform.

    You can choose to either use the Terraform, which is bundled with Unravel installer or edit and use the external Terraform, which is provided separately, independent of the installer.

  • gcloud CLI

    Set of tools to create and manage Google Cloud resources.

BigQuery projects can be set by any one of the following. Ensure to complete the prerequisites before you set up BigQuery projects.

Unravel ships the following resources, which are required to automatically set up Unravel to receive BigQuery data.

You can configure the BigQuery projects using one of the following methods:

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop
  2. Configure the BigQuery projects.

    You can use one of the following methods to configure the BigQuery projects manually:

  3. Add projects.

  4. Run <Unravel installation directory>/unravel/manager config bigquery show to verify. The following output is shown:

    /opt/unravel/manager config bigquery show
    -- Running: config bigquery show
    BigQuery support: Enabled
    LR endpoint: Default
    Mode: pull
    Polling: Default
    
    Billing data location: Not configured
    
    Authentication mode: single
       Project: prj-01
       Shared key file: Integration needed
    
    Project: prj-01
       integration: true
       is_admin: false
       is_monitoring: true
       subscription_id: unravel-bigquery-sub
    Project: prj-02
       integration: true
       is_admin: false
       is_monitoring: true
       subscription_id: unravel-bigquery-sub
  5. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply
  6. Start Unravel.

    <Unravel installation directory>/unravel/manager start
  7. Verify BigQuery integration

    1. On the GCP console, run test queries from the project integrated with Unravel.

    2. Using a supported web browser, navigate to Unravel URL (For example, https://<unravel-host>:3000) and log onto Unravel UI using the credentials.

    3. Navigate to Jobs tab and click All in the left panel. The details of the queries run from the GCP console will be listed.

      bq-jobs.png

      To verify the integration of administrator projects, check the Reservation column from the Projects tab.

      bq-verify-admin-project.png
  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop
  2. Configure the BigQuery projects.

  3. Integrate BigQuery projects for Unravel monitoring. This is a mandatory step for Unravel-generated credentials. The following command configures all the projects added for Unravel.

    Notice

    Do not run the following command if you have used external Terraform to automatically create resources.

    <Unravel installation directory>/unravel/manager config bigquery integrate

    A URL will be provided in the output.

    bigquery-integrate-url.png

    Note

    If you want to skip the interactive gcloud authentication by Unravel and handle the gcloud authentication on your own, then run the command as follows:

    <Unravel installation directory>/unravel/manager config bigquery integrate --skip-authorization
  4. Authenticate gcloud CLI.

    1. On a Google Chrome browser, copy the URL provided in the output, and in the sign-in dialog box, click Allow. Ensure to sign in to the gcloud CLI from the account that is authenticated with the required permissions.

      sign-in-google-auth.png
    2. From the Sign in to the glcoud CLI box, click Copy button to copy the authorization code.

      sign-in-google-auth-copy.png
    3. Go back to the terminal and paste the authorization code in the Enter authorization code field, and press ENTER. This will run the following actions in the background:

      • Authenticate the user with Google Cloud.

      • Configure the required resources on the GCP.

      • Encrypt the credentials (service account keys) and then integrate them with Unravel.

      • Integrate all the added BigQuery projects with Unravel.

      • Securely sign out the end user from the gcloud session.

  5. Run <Unravel installation directory>/unravel/manager config bigquery show to verify. The following output is shown:

    /opt/unravel/manager config bigquery show
    -- Running: config bigquery show
    BigQuery support: Enabled
    LR endpoint: Default
    Mode: pull
    Polling: Default
    
    Billing data location: Not configured
    
    Authentication mode: single
       Project: prj-01
       Shared key file: Integration needed
    
    Project: prj-01
       integration: true
       is_admin: false
       is_monitoring: true
       subscription_id: unravel-bigquery-sub
    Project: prj-02
       integration: true
       is_admin: false
       is_monitoring: true
       subscription_id: unravel-bigquery-sub
  6. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply
  7. Start Unravel.

    <Unravel installation directory>/unravel/manager start
  8. Verify BigQuery integration

    1. On the GCP console, run test queries from the project integrated with Unravel.

    2. Using a supported web browser, navigate to Unravel URL (For example, https://<unravel-host>:3000) and log onto Unravel UI using the credentials.

    3. Navigate to Jobs tab and click All in the left panel. The details of the queries run from the GCP console will be listed.

      bq-jobs.png

      To verify the integration of administrator projects, check the Reservation column from the Projects tab.

      bq-verify-admin-project.png

Note

Only single billing account is supported.

You must separately configure the billing data. For this, you must export the billing data to a BigQuery table and integrate Unravel with that table for Unravel to query the table.

The following information is required for integrating the billing data:

  • Project ID in which billing data is exported. This project ID should be integrated with Unravel for monitoring.

  • Dataset in which the billing data is exported.

  • Table in which billing data is exported.

To export billing data for BigQuery monitoring, do the following:

  1. Export Billing Data to a BigQuery DataSet. Refer to Set up Cloud Billing data export to BigQuery for detailed instructions.

  2. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop
  3. Run the following command and set the billing info.

    <Unravel installation directory>/unravel/manager config bigquery set-billing-data

    You are prompted to enter the following:

    • Project ID where billing export is enabled

    • Dataset ID where data is getting exported

    • Name of the table where data is getting exported

    Note

    To unset the properties that you have set for exporting billing data, run the following command:

    <Unravel installation directory>/unravel/manager config bigquery unset-billing-data

You must separately configure the BigQuery projects that you want to track from the Data page. The Data page on Unravel UI can show data for only up to 100 BigQuery projects.Data

Also, refer to Remove BigQuery projects from the Data page on Unravel UI.

  1. Add projects to the Data page.

    • To add single projects to the Data page, run the following:

      <Unravel installation directory>/unravel/manager config bigquery enable-datapage <project-id>

      For example: /opt/unravel/manager config bigquery enable-datapage myproject

    • To add multiple projects to the Data page, run the following:

      <Unravel installation directory>/unravel/manager config bigquery enable-datapage --batch </path/to/project-id-file> 

      For example: /opt/unravel/manager config bigquery enable-datapage --batch /opt/unravel/project-id-file

  2. Run <Unravel installation directory>/unravel/manager config bigquery show to verify if the project IDs are enabled for the Data page. The following sample output is shown:

Note

When you remove a BigQuery project from the Data page, then the associated data also gets deleted from OpenSearch.

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop
  2. Run the following command from the Unravel installation directory.

    • For single project

      <Unravel installation directory>/unravel/manager config bigquery delete-datapage <project-ID>

      For example: /opt/unravel/manager config bigquery delete-datapage --batch my-project

    • For multiple projects

      <Unravel installation directory>/unravel/manager config bigquery delete-datapage --batch </path/to/project-id-file>

      For example: /opt/unravel/manager config bigquery delete-datapage --batch /opt/unravel/my-projects.txt

  3. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply
  4. Start Unravel.

    <Unravel installation directory>/unravel/manager start

Note

When you remove a BigQuery project from Unravel, then the associated data also gets deleted from OpenSearch.

You can perform the following steps to remove BigQuery projects from Unravel. In case you have integrated BigQuery projects using Terraform, then refer Disintegrating GCP projects with Unravel

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop
  2. Run the following command from the Unravel installation directory.

    • For single project

      <Unravel installation directory>/unravel/manager config bigquery remove <project-ID>

      For example: /opt/unravel/manager config bigquery remove my-project

    • For multiple projects

      <Unravel installation directory>/unravel/manager config bigquery remove --batch </path/to/project-id-file>

      For example: /opt/unravel/manager config bigquery remove --batch /opt/unravel/my-projects.txt

  3. Integrate BigQuery projects for Unravel monitoring. This is a mandatory step for Unravel-generated credentials. The following command configures all the projects added for Unravel monitoring at once i.e. projects with customer-supplied credentials as well as with Unravel-managed credentials.

    Notice

    Do not run the following command if you have used external Terraform to automatically create resources.

    <Unravel installation directory>/unravel/manager config bigquery integrate

    A URL will be provided in the output.

    bigquery-integrate-url.png

    Note

    If you want to skip the interactive gcloud authentication by Unravel and handle the gcloud authentication on your own, then run the command as follows:

    <Unravel installation directory>/unravel/manager config bigquery integrate --skip-authorization
  4. Authenticate gcloud CLI.

    1. On a Google Chrome browser, copy the URL provided in the output, and in the sign-in dialog box, click Allow. Ensure to sign in to the gcloud CLI from the account that is authenticated with the required permissions.

      sign-in-google-auth.png
    2. From the Sign in to the glcoud CLI box, click the Copy button to copy the authorization code.

      sign-in-google-auth-copy.png
    3. Go back to the terminal, paste the authorization code in the Enter authorization code field, and press ENTER. This will run the following actions in the background:

      • Authenticate the user with Google Cloud.

      • Configure the required resources on the GCP.

      • Encrypt the credentials (service account keys) and then integrate them with Unravel.

      • Integrate all the added BigQuery projects with Unravel.

      • Securely sign out the end user from the gcloud session.

  5. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply
  6. Start Unravel.

    <Unravel installation directory>/unravel/manager start