Deploy the GX Agent

To use GX Cloud features and functionality, you need to deploy the GX Agent. The GX Agent is an intermediary between GX Cloud and your organization's data stores. GX Cloud does not connect directly to your data, all data access occurs within the GX Agent. GX Cloud sends jobs to the GX Agent, the GX Agent executes these jobs against your data, and then sends the job results to GX Cloud.

To test GX Cloud, you use a self-hosted deployment to run the GX Agent with Docker, connect the GX Agent to your target Data Sources, and use the GX Cloud web UI to define your Data Assets, create Expectations, and run Validations. When you've finished testing GX Cloud, you move to an org-hosted deployment and deploy the GX Agent to your organization's development, staging, or production cloud services environment. The GX Agent serves all GX Cloud users within your organization. It can be run as part of your development or production workflows. To learn more about the GX Agent and deployment patterns, see About GX Cloud.

Prerequisites

• You have a GX Cloud account.

Get your access token and organization ID

You need your access token and organization ID to deploy the GX Agent. Access tokens shouldn't be committed to version control software.

If you've used GX Cloud previously, you have your access token and organization ID, and you need to restart the GX Agent, see Deploy the GX Agent.

New GX Cloud account

1. Sign in to GX Cloud.

2. Complete the survey and then click Continue to GX Cloud.

3. Copy and then paste the Access token and Organization ID values into a temporary file. You'll need them to deploy the GX Agent.

4. Click Deploy the GX Agent and deploy the GX Agent.

Existing GX Cloud account

Use the information provided here to view your organization ID or create a new access token. This can be helpful if you've forgotten your organization ID or access token, and you need to restart the GX Agent.

1. In GX Cloud, click Settings > Tokens.

2. In the User access tokens pane, click Create user access token.

3. In the Token name field, enter a name for the token that will help you quickly identify it.

4. Click Create.

5. Copy and then paste the user access token into a temporary file. The token can't be retrieved after you close the dialog.

6. Click Close.

7. Copy the value in the Organization ID field into the temporary file with your user access token and then save the file.

   GX recommends deleting the temporary file after you set the environment variables.

8. Deploy the GX Agent.

Deploy the GX Agent

The GX Agent allows you to securely access your data without connecting to it or interacting with it directly. To learn more about the GX Agent and deployment patterns, see About GX Cloud.

Prerequisites

• You have a GX Cloud access token and organization ID. See Get your access token and organization ID.

• You have a Docker instance or kubectl.

Org-hosted

You can deploy the GX Agent container in any deployment environment where you can run Docker container images.

To learn how to deploy a Docker container image in a specific environment, see the following documentation:

• Quickstart: Deploy a container instance in Azure using the Azure CLI

• Build and push a Docker image with Google Cloud Build

• Deploy Docker Containers on Amazon ECS

You can deploy the GX Agent in any environment in which you create Kubernetes clusters. For example:

• Amazon Elastic Kubernetes Service (EKS)

• Microsoft Azure Kubernetes Service (AKS)

• Google Kubernetes Engine (GKE)

• Any Kubernetes cluster version 1.21 or greater which uses standard Kubernetes

Docker

1. Download the GX Agent Docker container image from Docker Hub.

2. After configuring your cloud service to run Docker containers, run the following Docker command to start the GX Agent:

   Terminal input

   docker run -it \
   -e GX_CLOUD_ACCESS_TOKEN= YOUR_ACCESS_TOKEN \ 
   -e GX_CLOUD_ORGANIZATION_ID= YOUR_ORGANIZATION_ID \  
   greatexpectations/agent:latest

   Replace YOUR_ACCESS_TOKEN and YOUR_ORGANIZATION_ID with the values you copied previously.

3. Optional. If you created a temporary file to record your user access token and Organization ID, delete it.

4. Optional. Run the following command to use the GX Agent image as the base image and optionally add custom commands:

   Terminal input

   FROM greatexpectations/agent
   RUN echo "custom_commands"

5. Optional. Run the following command to rebuild the Docker image:

   Terminal input

   docker build -t myorg/agent

6. Optional. Run docker ps or open Docker Desktop to confirm the agent is running.

Kubernetes

1. Install kubectl. See Install Tools.

2. Run the following command to provide the access credentials to the Kubernetes container:

   kubectl create secret generic gx-agent-secret \
   --from-literal=GX_CLOUD_ORGANIZATION_ID=YOUR_ORGANIZATION_ID \
   --from-literal=GX_CLOUD_ACCESS_TOKEN=YOUR_ACCESS_TOKEN \

   Replace YOUR_ORGANIZATION_ID and YOUR_ACCESS_TOKEN with the values you copied previously.

3. Optional. If you created a temporary file to record your user access token and Organization ID, delete it.

4. Create and save a file named deployment.yaml, with the following configuration:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    name: gx-agent
    labels:
    app: gx-agent
    spec:
    replicas: 1
    selector:
    matchLabels:
    app: gx-agent
    template:
    metadata:
      labels:
        app: gx-agent
    spec:
      containers:
       name: gx-agent
        image: greatexpectations/agent:latest
        envFrom:
        secretRef:
         name: gx-agent-secret

5. Run the following command to use the deployment.yamlconfiguration file to deploy the GX Agent:

   kubectl apply -f deployment.yaml

6. Optional. Run the following command to confirm the agent is running:

   kubectl logs -l app=gx-agent

7. Optional. Run the following command to terminate running resources gracefully:

   kubectl delete -f deployment.yaml
   kubectl delete secret gx-agent-secret

Self-hosted

1. Start the Docker Engine.

2. Run the following code to set the GX_CLOUD_ACCESS_TOKEN and GX_CLOUD_ORGANIZATION_ID environment variables, install GX Cloud and its dependencies, and start the GX Agent:

   Terminal input

   docker run --rm --pull=always -e GX_CLOUD_ACCESS_TOKEN="<user_access_token>" -e GX_CLOUD_ORGANIZATION_ID="<organization_id>" greatexpectations/agent

   Replace user_access_token and organization_id with the values you copied previously.

3. In GX Cloud, confirm the GX Agent status icon is green. This indicates the GX Agent is running. If it isn't, repeat step 2 and confirm the user_access_token and organization_id values are correct.

   

4. Optional. If you created a temporary file to record your user access token and Organization ID, delete it.

5. Optional. Run docker ps or open Docker Desktop to confirm the agent is running.

   If you stop the GX Agent, close the terminal, and open a new terminal you'll need to set the environment variables again.

   To edit an environment variable, stop the GX Agent, edit the environment variable, save the change, and then restart the GX Agent.

Next steps

Want to continue testing GX Cloud features and functionality?

• Create a Data Asset

Ready to connect GX Cloud to your deployment environment?

• Connect GX Cloud