search

opensearch-project / reporting-cli

Apache License 2.0
4 stars 13 forks source link

[FEATURE] Reporting CLI #26

Closed davidcui1225 closed 1 year ago

davidcui1225 commented 2 years ago

Overview

Currently, Reporting does not have any quick out-of-box options to be able to download reports. Users have to download from OpenSearch Dashboards itself with the plugin installed. Reporting Anything provides users with a Reporting CLI to be able to download reports without requiring the use of Dashboards and the Dashboards plugin.

Feature Suggestion

When users encounter issues using the Dashboards plugin, there is no work-around aside from a code change that can enable report downloads. Additionally, users with a specific use case for reporting will have a convenient option to download reports directly. Customers will be able to integrate this CLI component into their own workflows/environments to bypass any authentication or security issues.

User Quote - "The current manually generated csv and pdf reports are nice but it’d be great to be able to automate and send these via email or even just fetch via an API request."

Requirements

Out of scope

Solution

Solution overview

Reporting Anything's solution is to provide a mechanism for users to be able to download reports independent of the plugin. It will also provide extensibility in that users can create a report from anything by providing a URL, and are not limited to the report source options provided in the reporting plugin.

Proposed Solution

The proposed solution is to provide a CLI option. Users will be able to work around authentication issues by integrating into their own workflows. For example, a user running Reporting Anything in an AWS Lambda instance will not have to deal with any security issues that they would running the Reporting plugin in OpenSearch Dashboards. From there, the user can also integrate with an email service to create an email report mechanism.

Detailed Design

User interface

The user interface will be on the command line, with the user being given several parameters, including:

Sample commands:

reporting-anything --object-id 7adfa750-4c81-11e8-b3d7-01146121b73d --format pdf 
 reporting anything --url http://localhost:5601/app/dashboards#/view/7adfa750-4c81-11e8-b3d7-01146121b73d?_g=(filters:!(),refreshInterval:(pause:!f,value:900000),time:(from:now-24h,to:now))&_a=(description:'Analyze%20mock%20flight%20data%20for%20OpenSearch-Air,%20Logstash%20Airways,%20OpenSearch%20Dashboards%20Airlines%20and%20BeatsWest',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),query:(language:kuery,query:''),timeRestore:!t,title:'%5BFlights%5D%20Global%20Flight%20Dashboard',viewMode:view) --format png

Component design

The only component of the project is the command line interface, which contains all the functionality for reporting anything. The design of the CLI is in the above section.

joshuali925 commented 2 years ago

it would be good if we could list some difference/advantages over just using chrome binary to save screenshots e.g.

chromium --headless --screenshot=report.png https://www.google.com
chromium --headless --print-to-pdf=report.pdf https://www.google.com

object id and filters are part of URL, the only difference seems to be supporting csv reports

davidcui1225 commented 2 years ago

it would be good if we could list some difference/advantages over just using chrome binary to save screenshots e.g.

chromium --headless --screenshot=report.png https://www.google.com
chromium --headless --print-to-pdf=report.pdf https://www.google.com

object id and filters are part of URL, the only difference seems to be supporting csv reports

Good point, the scope of this should increase to at least include email reports then.

abbashus commented 2 years ago

As a thought, we should be publishing a library that includes the mentioned functionality, and CLI being just a wrapper on top of it. This way we can use it in serverless environments like AWS Lambda, Azure Functions etc or any other app.

davidcui1225 commented 2 years ago

  • Is Anything a placeholder for actual coming soon name?

    • "without requiring the use of Dashboards" : Is it possible to do without Dashboards? 🤔

As a thought, we should be publishing a library that includes the mentioned functionality, and CLI being just a wrapper on top of it. This way we can use it in serverless environments like AWS Lambda, Azure Functions etc or any other app.

Anything is just a placeholder name, yes. Also without requiring the use of Dashboards was meant to convey "without requiring navigation to the OpenSearch Dashboards front-end."

I agree that publishing a library is probably the best path forward. I think we will have a clearer picture of what functionalities customers will want next week. A good baseline is likely the mentioned features above, and email reports.

vamsi-amazon commented 2 years ago

When users encounter issues using the Dashboards plugin, there is no work-around aside from a code change that can enable report downloads.

Wont this be same with cli command? Any issue with report generation logic would need upgradation of command. Also it is mentioned in the design section that we will be packaging the existing plugin code into a command.

User Quote - "The current manually generated csv and pdf reports are nice but it’d be great to be able to automate and send these via email or even just fetch via an API request."

From the above statement what I understood is User wants to avoid all the possible manual touch points in fetching the reports. Probably, the API request is also for automating the process themselves. What I couldn't understand is How does having CLI command will solve this problem?

Installing CLI command vs installing opensearch plugins. Manually writing commands vs Manually triggering UI buttons. I might be missing something here. Why can't we build and enhance automated report generation features.

davidcui1225 commented 2 years ago

Wont this be same with cli command? Any issue with report generation logic would need upgradation of command. Also it is mentioned in the design section that we will be packaging the existing plugin code into a command.

Not quite- the issue is not with the logic of the report generation itself. It is with other functionalities reporting is meant to provide, such as emailing of reports. Some customers have also run into authentication issues.

From the above statement what I understood is User wants to avoid all the possible manual touch points in fetching the reports. Probably, the API request is also for automating the process themselves. What I couldn't understand is How does having CLI command will solve this problem?

The email use case is one that we should plan to add. The CLI interface's initial thought was for users who were running into authentication issues, and those who wanted email support. But it will be easier to dive into this conversation further once we get more user feedback.

Installing CLI command vs installing opensearch plugins. Manually writing commands vs Manually triggering UI buttons. I might be missing something here. Why can't we build and enhance automated report generation features.

We can, but for a CLI interface automated report generation, particularly for scheduled reports, could be tricky because it would require the server to be continuously running. Automated report generation is supported in the current Dashboards plugin in the form of scheduled report definitions.

ps48 commented 2 years ago

This is nice proposal! I have a some questions about the motivation and the proposed solution.

When users encounter issues using the Dashboards plugin, there is no work-around aside from a code change that can enable report downloads.

  1. What issues do users have with the current reporting plugin? What work around/code changes do they make to get things running? If these issues are common, can't we just provide configurations for them in dashboards.yml config file?

User Quote - "The current manually generated csv and pdf reports are nice but it’d be great to be able to automate and send these via email or even just fetch via an API request."

  1. From the quote it appears like users need more of automation/email and API enpoints. How much of this will get solved with upcoming notifications plugin?

  2. Why do we propose CLI tool as a solution (and not APIs)? Shouldn't a simpler solution be to expose APIs re-using the existing ones from dashboards node backend?

  3. How would the CLI tool work with permissions/user access and security plugin?

  4. Is "Reporting Anything" still restricted to be used within the OpenSearch realm? If not, how do we plan to replace the existing scheduler dependency?

davidcui1225 commented 2 years ago

What issues do users have with the current reporting plugin? What work around/code changes do they make to get things running? If these issues are common, can't we just provide configurations for them in dashboards.yml config file?

Most of the issues we are trying to address here are related to authentication in Opensearch and Dashboards core. These issues have been encountered by several customers but the scope of the fix is too large for a config file change.

From the quote it appears like users need more of automation/email and API enpoints. How much of this will get solved with upcoming notifications plugin?

The original issue needs to be updated to reflect the customer need more accurately. Essentially by providing Reporting Anything, customers can integrate it into their own workflows however they want to bypass auth issues (e.g AWS Lambda), which is not in scope of Notifications.

Why do we propose CLI tool as a solution (and not APIs)? Shouldn't a simpler solution be to expose APIs re-using the existing ones from dashboards node backend?

An API is an option, but for providing customers a method to download reports within their own workflow is more convenient with a simple CLI that takes in a handful of parameters.

How would the CLI tool work with permissions/user access and security plugin?

That should be entirely up to the discretion of the user- ideally, since they would be running this workflow from their own environment, they shouldn't be encountering any auth/security issues.

Is "Reporting Anything" still restricted to be used within the OpenSearch realm? If not, how do we plan to replace the existing scheduler dependency?

Reporting Anything is a generic CLI tool that can be used to download a report of anything. It will have CLI parameters for OpenSearch users (e.g saved object ID, report source), but non-OpenSearch pages can be downloaded as reports as well with the URL parameter. There is no plan to add a scheduler component at this time.

joshuali925 commented 2 years ago

A few questions for this project:

Most of the issues we are trying to address here are related to authentication in Opensearch and Dashboards core.

Could you link some issues that needs reporting anything for cross reference?

since they would be running this workflow from their own environment, they shouldn't be encountering any auth/security issues.

Auth depends on credentials provided, why they won't have issues if this runs in their environment (and what does "their own environment" mean)? e.g. how do you pass credentials from user to cli, and from cli to Dashboards?

An API is an option, but for providing customers a method to download reports within their own workflow is more convenient with a simple CLI that takes in a handful of parameters.

CLI requires installation and is not cross platform. API is just a http call, which also accepts parameters. Why is CLI more convenient?

davidcui1225 commented 2 years ago

https://user-images.githubusercontent.com/53581635/166745834-1a93199e-ecae-4f36-9830-4664ab63152e.mp4

davidcui1225 commented 2 years ago

Updated demo video to use CLI wrapper and include generic URL use case

davidcui1225 commented 2 years ago

Remaining Work Breakdown Structure

Authentication Issues

Chromium & Automation

Testing & Documentation

davidcui1225 commented 2 years ago

SOP for installing & running reporting-anything:

git clone git@github.com:davidcui1225/dashboards-reports.git
cd dashboards-reports
git checkout reporting-anything
cd reporting-anything/src

For additional command line parameter options, run with -h flag

sumukhswamy commented 2 years ago

Auth types for CLI

HTTP authentication in Open Search

These are the allowed values for type: basic: HTTP basic authentication. No additional configuration is needed. kerberos: Kerberos authentication. Additional, Kerberos-specific configuration is needed. jwt: JSON web token authentication. Additional, JWT-specific configuration is needed. clientcert: Authentication through a client TLS certificate. This certificate must be trusted by one of the root CAs in the truststore of your nodes. After setting an HTTP authenticator, you must specify against which backend system you want to authenticate the user: noop: No further authentication against any backend system is performed. Use noop if the HTTP authenticator has already authenticated the user completely, as in the case of JWT, Kerberos, or client certificate authentication. internal: Use the users and roles defined in internal_users.yml for authentication. ldap: Authenticate users against an LDAP server. This setting requires additional, LDAP-specific configuration settings.

HTTP basic

The security plugin sends a response with status UNAUTHORIZED (401) back to the client. If the client is accessing the cluster with a browser, this triggers the authentication dialog box, and the user is prompted to enter a user name and password. Kerberos Kerberos authentication does not work with OpenSearch Dashboards. To track OpenSearch’s progress in adding support for Kerberos in OpenSearch Dashboards, see issue #907 Kerberos Auth does not exist (https://github.com/opensearch-project/security-dashboards-plugin/issues/907) in the Dashboard’s Security Plugin repository. {: .warning }

JSON web token

JSON web tokens (JWTs) are JSON-based access tokens that assert one or more claims. They are commonly used to implement single sign-on (SSO) solutions and fall in the category of token-based authentication systems: A user logs in to an authentication server by providing credentials (for example, a user name and password). The authentication server validates the credentials. The authentication server creates an access token and signs it. The authentication server returns the token to the user. The user stores the access token. The user sends the access token alongside every request to the service that it wants to use. The service verifies the token and grants or denies access. A JSON web token is self-contained in the sense that it carries all necessary information to verify a user within itself. The tokens are base64-encoded, signed JSON objects. JSON web tokens consist of three parts: Header Payload Signature

Header

The header contains information about the used signing mechanism, as shown in the following example: { "alg": "HS256", "typ": "JWT" }

In this case, the header states that the message was signed using HMAC-SHA256.

Payload

The payload of a JSON web token contains the so-called JWT Claims. A claim can be any piece of information about the user that the application that created the token has verified. The specification defines a set of standard claims with reserved names (“registered claims”). These include, for example, the token issuer, the expiration date, or the creation date. Public claims, on the other hand, can be created freely by the token issuer. They can contain arbitrary information, such as the user name and the roles of the user. Example: { "iss": "example.com", "exp": 1300819380, "name": "John Doe", "roles": "admin, devops" }

Signature

The issuer of the token calculates the signature of the token by applying a cryptographic hash function on the base64-encoded header and payload. These three parts are then concatenated using periods to form a complete JSON web token: encoded = base64UrlEncode(header) + "." + base64UrlEncode(payload) signature = HMACSHA256(encoded, 'secretkey'); jwt = encoded + "." + base64UrlEncode(signature)

JSON web token

jwt_auth_domain: enabled: true order: 0 http_authenticator: type: jwt challenge: false config: signing_key: "base64 encoded key" jwt_header: "Authorization" jwt_url_parameter: null subject_key: null roles_key: null authentication_backend: I type: noop

Algorithms for the signing_key: Symmetric - HMAC Asymmetric - RSA and ECDSA

davidcui1225 commented 2 years ago

SOP for installing & running reporting-anything:

git clone git@github.com:davidcui1225/dashboards-reports.git
cd dashboards-reports
git checkout reporting-anything
cd reporting-anything/src
* Download chromium zip from [here](https://github.com/davidcui1225/dashboards-reports/releases/tag/reporting-anything), unzip in the `reporting-anything` directory
node download_report.js -u <url>

For additional command line parameter options, run with -h flag

The link to the chromium bundle should be public. FYI that link provided is for Macos-x64 chromium. The other chromium links can be found here

sumukhswamy commented 2 years ago

SAML auth demo with OKTA The third party authentication is provided with OKTA where the below video shows how the authentication is done. -a authentication flag indicates the type of authentication type and performs the necessary login with the credentials provided -u is the url to the dashboard -c takes username:password

https://user-images.githubusercontent.com/107440906/178067767-a94d9c0a-33aa-447f-a269-211cd739c69d.mp4

sumukhswamy commented 2 years ago

Cognito auth demo The third party authentication is provided with Cognito where the below video shows how the authentication is done. -a authentication flag indicates the type of authentication type and performs the necessary login with the credentials provided -u is the url to the dashboard -c takes username:password

https://user-images.githubusercontent.com/107440906/178854168-c11f9cf6-59a7-4c60-8fb6-33086837d129.mp4

mateuszk-gain commented 2 years ago

@davidcui1225 @sumukhswamy

reporting-anything works goods, theres any plan to merge this "tool" to main branch?

anirudha commented 2 years ago

@davidcui1225 @sumukhswamy

reporting-anything works goods, theres any plan to merge this "tool" to main branch?

soon, this will go to main, ~2-4weeks

sumukhswamy commented 2 years ago

SOP for installing & running reporting-anything:

git@github.com:sumukhswamy/dashboards-reports.git cd dashboards-reports git checkout reporting-anything cd reporting-anything/src

reporting-anything -u other flags which can be used -n(name of the file), -a(authentication type), -h (height of the file), w(width of the file) -a cognito → for cognito -a SAML → for SAML no need to mention any flag for FGAC Before running the code a .env file with the username and password needs to be specified as follows

image

the pr: https://github.com/opensearch-project/dashboards-reports/pull/392

The email/username which needs to receive emails needs to be first verified by SES or will throw an error.

the template for the email is to be stored src/views

Sandy381 commented 1 year ago

Opensearch Reporting scheduler not working with E-mails. Cannot schedule reports.

rupal-bq commented 1 year ago

https://user-images.githubusercontent.com/56703525/201599325-07ed7a51-b66c-48cd-86a5-238008a8b871.mov

anirudha commented 1 year ago

@elfisher cli delivery is version independent. i'll remove the version tag on this.

fymaterials98 commented 1 year ago

How to install this report-anything? git clone git@github.com:davidcui1225/dashboards-reports.git cd dashboards-reports git checkout reporting-anything cd reporting-anything/src I did this step. Do I need to download chromium zip to reporting-anything directory? I saw this instruction 1 git@github.com:sumukhswamy/dashboards-reports.git cd dashboards-reports git checkout reporting-anything cd reporting-anything/src 2 Download chromium zip from here, unzip in the reporting-anything directory 3 reporting-anything -u

Do I need to do 1, 2 and 3? What does step 3 do?

Thanks, Arthur

joshuali925 commented 1 year ago

@fymaterials98 thanks for your interest. Reporting-cli release is currently in progress (https://github.com/opensearch-project/opensearch-build/issues/3112)

If you want to try it now you can follow developer instructions steps 1-3 to install and user guide to use

After it gets released it can be installed from npm directly.

rupal-bq commented 1 year ago

Hi, opensearch-reporting-cli is released. Please check https://opensearch.org/docs/latest/dashboards/reporting-cli/rep-cli-index/ for more information.