diff --git a/docs/app/admin/AdminControls.mdx b/docs/app/admin/AdminControls.mdx index 5155fe6b..3cb967a9 100644 --- a/docs/app/admin/AdminControls.mdx +++ b/docs/app/admin/AdminControls.mdx @@ -8,11 +8,9 @@ import { UserDeleteOutlined } from '@ant-design/icons'; -## Summary - The Admin page enables administrators to manage user access, configure environment secrets, and view platform integration details. This page can be accessed by clicking on the bubble containing your email address in the top right corner of the top navbar and selecting Environment Settings. -### Access Levels +## Access Levels The Roles panel shown below enables administrators to specify access levels for different users. The Last Seen column is populated in the permissions panel for users that have accessed Ganymede after [August 2024](../../releases/202408#august-15-2024), when the feature was introduced. @@ -31,7 +29,7 @@ The New User Roles box appears for users with Admin privileges, enabling admins For dashboards, permissions can be viewed by navigating to the dashboards page and clicking Settings > List Users. -### Environment Secrets +## Environment Secrets The Secrets panel enables administrators to configure secrets that are used by Ganymede cloud to connect to external services such as Benchling or AWS. These secrets are specific to the nodes used within a given environment (i.e. - development or production environment). The example shown in the image below shows an environment with a AWS S3 Role ARN specified, enabling connectivity between Ganymede cloud and AWS S3 Storage when using the [S3_Read](../../nodes/App/S3_Read) or [S3_Write](../../nodes/App/S3_Write) nodes. @@ -48,7 +46,7 @@ Secrets cannot be viewed from this panel, so if a secret is lost, it can either Any secrets entered here will not be committed into code, but can be printed by environment users with the *Writer* or *Admin* role in notebooks. -### Environment Version +## Environment Version The Environment Version panel displays version information for the Ganymede environment: @@ -59,7 +57,7 @@ The Environment Version panel displays version information for the Ganymede envi - **Agent Versions**: The latest version of each Agent, along with links to historical Agent binaries - **Flow Versions**: The latest version of each Flow, along with links to the Flow Version History page showing commit history for each Flow -### Platform Integration Details +## Platform Integration Details The Integration panel contains details about the Ganymede environment, which can be used for integration with external systems, as well as for IP whitelisting Ganymede. @@ -72,14 +70,16 @@ The Integration panel contains details about the Ganymede environment, which can - **AWS Trust Policy JSON**: Role configuration for AWS Policy, to establish connectivity between AWS and Ganymede cloud -#### Connecting to an S3 Bucket +### Connecting to an S3 Bucket In order to allow Ganymede Flows to read and write to an S3 bucket, follow the steps below for each Ganymede environment that needs access to the bucket: 1. Identify which S3 buckets you would like to connect to Ganymede 2. Create a Policy that allows the desired access to the bucket(s), replacing `my-bucket` with the name of the bucket(s) you would like to connect to. - Example: - ``` + + Example: + + ```json { "Version": "2012-10-17", "Statement": [ @@ -104,10 +104,12 @@ In order to allow Ganymede Flows to read and write to an S3 bucket, follow the s ] } ``` + 3. Record the identity number of the Ganymede Environment - Navigate to the Environment Settings page - Select the Integration tab - Record the number in the `accounts.google.com:aud` field + 4. Create the Role in AWS - In the IAM console, select Roles > Create Role - Select 'Web Identity' @@ -118,25 +120,37 @@ In order to allow Ganymede Flows to read and write to an S3 bucket, follow the s - Press Next - Name the role something like 'ganymede-storage-access' - Press Create Role + 5. Add the Role ARN as an [environment secret in the Ganymede environment](#environment-secrets) named _aws_s3_role_arn_. -#### Connecting to Ganymede from an External Tool +### Connecting to Ganymede from an External Tool Ganymede can generate Service Account credentials for use with other tools, such as BigQuery or ODBC. Access using these credentials is restricted to read-only data of the environment in which they were generated. To do this, follow the steps below: 1. Navigate to the Environment Settings page, Integration tab Admin - Integration Panel Add Credentials -1. Select 'New Credentials' and enter a description and name for the Credentials -1. Click 'Create' +2. Select 'New Credentials' and enter a description and name for the Credentials +3. Click 'Create' Admin - Integration Panel Copy Key -1. Copy the JSON key that is displayed and save it to a file. - NOTE: This key is only displayed once, so be sure to save it in a secure location. - NOTE: Treat this key as a password, as it provides access to the Ganymede environment. -1. Use the JSON key to authenticate with the external tool. +4. Copy the JSON key that is displayed and save it to a file. + +:::note + +This key is only displayed once, so be sure to save it in a secure location. + +::: + +:::warning + +Treat this key as a password, as it provides access to the Ganymede environment. + +::: + +5. Use the JSON key to authenticate with the external tool. -### Environment Detection in the SDK +## Environment Detection in the SDK The SDK has helper functions to determine the state of the environments, such as production versus development. Please see [Environment Detection](../../sdk/markdowns/EnvironmentDetection) for more information. diff --git a/docs/app/agents/Agent.mdx b/docs/app/agents/Agent.mdx index 84c2036a..0f4b1ca8 100644 --- a/docs/app/agents/Agent.mdx +++ b/docs/app/agents/Agent.mdx @@ -9,26 +9,16 @@ import { DiffOutlined, PlusOutlined, SelectOutlined } from "@ant-design/icons"; ## Overview +Agents are Windows/Linux background services that can filter and process data, upload files into Ganymede Cloud, initiate data processing pipelines, and deliver data from Ganymede Cloud to instrument PCs. Once configured, the executable associated with an Agent is built in the Cloud and downloaded to the instrument PC for installation. + +Individual instances of an Agent are called [Connections](./AgentMonitoring.mdx). Users configure Agent and Connection behavior through a combination of configuration and user-defined code, allowing for flexibility in capturing files and interacting with the Ganymede ecosystem. + Connections front page   -Agents can - -- filter and process data -- upload files into Ganymede Cloud -- initiate data processing pipelines, based on: - - files written to the local machine by the instrument - - files written to a cloud storage bucket - - a scheduled cadence -- deliver data from Ganymede Cloud to instrument PCs - -Users specify these actions by configuring the Agent in the Ganymede app. Doing so creates a Linux binary and Windows executable, which can then be installed on instrument PCs. Optionally, users can [configure a user-defined Python script](#configuring-user-defined-python) associated with the Agent. - -After creating an Agent, users can build and install local executables called Connections, individual instances of a given Agent, on instrument PCs. Each Connection consists of a combination of user-defined code and Ganymede configuration, providing flexibility in capturing files and interacting with the Ganymede ecosystem. - For system requirements, see [Agent Network Config & Prerequisites](../configuration/AgentSystemRequirements). ### Terminology diff --git a/docs/app/agents/AgentMonitoring.mdx b/docs/app/agents/AgentMonitoring.mdx index 939de233..dbda7e12 100644 --- a/docs/app/agents/AgentMonitoring.mdx +++ b/docs/app/agents/AgentMonitoring.mdx @@ -1,6 +1,6 @@ --- id: AgentMonitoring -title: Monitoring and Configuring Connections +title: Connections Configuration & Maintenance displayed_sidebar: webUiSidebar toc_max_heading_level: 4 --- @@ -192,6 +192,9 @@ Below the Connection Details box, you'll find Connection-specific configurations - **Variables**: [Key-value pairs](./Agent#variables-and-labels-in-windows-agent-connections) that can be referenced in user-defined code. These are also used to specify [reserved keywords](Agent#reserved-variables) for the Connection, if applicable. - **Labels**: [Strings](./Agent#variables-and-labels-in-windows-agent-connections) that can be used to group Connections in the Ganymede UI - **Emails**: Email addresses to notify when the Connection encounters an error or has an update in its [Connection status](#connection-status). These email addresses are also used by the [notify function found in the `agent_sdk`](../../sdk/markdowns/AgentSDK#notifications). + - *Send Connection Status Email Notifications*: When enabled, Ganymede will send an email notification to the specified email addresses when the Connection status changes. + - *Connection Offline Alert Timeout (min)*: The number of minutes that the Connection must be offline before an email notification is sent. + - *Send Email Notification on Connection Shutdown*: When enabled, Ganymede will send an email notification to the specified email addresses when the Connection enters a shutdown state. ### Connection Status diff --git a/docs/app/files/Tags.mdx b/docs/app/files/Tags.mdx index a4bd9ad3..52d52b40 100644 --- a/docs/app/files/Tags.mdx +++ b/docs/app/files/Tags.mdx @@ -47,7 +47,7 @@ Files can be tagged in user-defined code within flows and Agents, though the met The full set of methods available for interacting with tags can be found on the [File Tag](../../sdk/FileTags.mdx) module in the SDK documentation. -#### Tagging files in flows +#### Tagging files in Flows To tag a file within a flow, use the `add_file_tag` function in the `ganymede_sdk.file_tag` module. This function takes the following arguments: @@ -160,7 +160,13 @@ def execute(flow_params_fw: FileWatcherResult, **kwargs) -> TriggerFlowParams: multi_file_params[param] = MultiFileParam.from_file_param(files) ``` -:::info +:::note Tagging Agent-Captured Files + +Files captured by Agents can be tagged via either the Connections page or by code, but should not be tagged in both spots. + +::: + +:::info Tagging Files used with Virtualization Files are passed to and from Virtualization environments using Agents. Therefore, files passed to and from Virtualization environments can be tagged as well. diff --git a/docs/releases/202411.mdx b/docs/releases/202411.mdx index 5f0726f3..3d4b187f 100644 --- a/docs/releases/202411.mdx +++ b/docs/releases/202411.mdx @@ -10,11 +10,11 @@ displayed_sidebar: releaseSideBar - **UI**: Service Accounts can be [exported](../app/admin/AdminControls#connecting-to-ganymede-from-an-external-tool) for use in external applications - Each service account has read-only access to your table data and metadata - Access is scoped to a single environment's data - - These can be used in tools that support BigQuery or BigQuery via ODBC -- ** Agents**: Connections can be monitored for disconnect or shutdown events + - These can be used in tools that support BigQuery or BigQuery via ODBC. +- **Agents**: Connections can be monitored for disconnect or shutdown events - Configure this option on the Connection details page - Adjust the monitoring window as needed - - Emails will be sent when the Connection is Disconnected and when it resumes + - Emails are sent when the connectivity is lost or when connectivity is restored **Improvements** - **Agents**: Improved the robustness of Connections that are restarted after updates were made while they were offline diff --git a/sidebars.js b/sidebars.js index 0e3f0c94..f3010819 100644 --- a/sidebars.js +++ b/sidebars.js @@ -124,37 +124,44 @@ module.exports = { id: 'app/agents/Agent', label: 'Agent Overview & Configuration' }, - 'app/configuration/AgentSystemRequirements', - { - type: 'doc', - id: 'app/agents/AgentInstall', - label: 'Installing Agent Connections' - }, { type: 'doc', id: 'app/agents/AgentMonitoring', - label: 'Monitoring and Configuring Connections' - }, - { - type: 'doc', - id: 'app/agents/DebuggingAgents', - label: 'Troubleshooting Agents & FAQ' + label: 'Connections Configuration & Maintenance' }, { - type: 'doc', - id: 'app/agents/AgentTemplates', - label: 'Example Agent Templates' - }, - { - type: 'doc', - id: 'app/agents/AgentLogs', - label: 'Agent Logging and Reference' + type: 'doc', + id: 'app/agents/AgentInstall', + label: 'Installing Agent Connections' }, { - type: 'ref', - id: 'releases/AgentVersionHistory', - label: 'Agent Change Log' - }, + type: 'category', + label: 'Reference & Troubleshooting', + collapsed: false, + items: [ + 'app/configuration/AgentSystemRequirements', + { + type: 'doc', + id: 'app/agents/DebuggingAgents', + label: 'Troubleshooting Agents & FAQ' + }, + { + type: 'doc', + id: 'app/agents/AgentTemplates', + label: 'Example Agent Templates' + }, + { + type: 'doc', + id: 'app/agents/AgentLogs', + label: 'Agent Logging and Reference' + }, + { + type: 'ref', + id: 'releases/AgentVersionHistory', + label: 'Agent Change Log' + }, + ] + } ] }, {