From 13193f83f3dffe7b3a8faee6ceda6d89eb533ec3 Mon Sep 17 00:00:00 2001 From: skabbina Date: Sun, 26 May 2024 11:05:02 +0530 Subject: [PATCH] Initial commit --- CHANGELOG.md | 35 ------------ CODE_OF_CONDUCT.md | 132 ------------------------------------------ CONTRIBUTING.md | 47 --------------- MAINTAINERS.md | 5 -- README.md | 139 ++++++++++++++------------------------------- SECURITY.md | 39 ------------- 6 files changed, 44 insertions(+), 353 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 MAINTAINERS.md delete mode 100644 SECURITY.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index d93e211..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,35 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### TBA - -## [1.0.1] - 2024-05-17 - -### Added - -- Bump actions/checkout from 4.1.1 to 4.1.2 by @dependabot in #16 -- Bump actions/checkout from 4.1.2 to 4.1.3 in the github group by @dependabot in #17 -- Bump actions/checkout from 4.1.3 to 4.1.4 in the github group by @dependabot in #18 -- Bump actions/checkout from 4.1.4 to 4.1.5 in the github group by @dependabot in #20 -- Bump step-security/harden-runner from 2.7.0 to 2.7.1 by @dependabot in #19 - -## [1.0.0] - 2024-02-16 - -### Added - -- Add initial workflow for calling reusable workflow by @lelia in #3 -- README: Fix maintainer reference by @GaryPWhite in #1 -- .github: Add Scorecard workflow by @lelia in #10 -- .github: Add Dependabot configuration by @openclarity-service in #11 -- Deprecate Renovate and fix GitHub URL refs by @lelia in #14 -- Bump actions/checkout from 3.6.0 to 4.1.1 by @dependabot in #15 - -[unreleased]: https://github.com/cisco-ospo/oss-template/compare/v1.0.1...HEAD -[1.0.1]: https://github.com/cisco-ospo/oss-template/releases/tag/v1.0.1 -[1.0.0]: https://github.com/cisco-ospo/oss-template/releases/tag/v1.0.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 4b161db..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,132 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official email address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -**. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available -at [https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7bd83d5..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,47 +0,0 @@ -# How to Contribute - -Thanks for your interest in contributing to ``! Here are a few general guidelines on contributing and -reporting bugs that we ask you to review. Following these guidelines helps to communicate that you respect the time of -the contributors managing and developing this open source project. In return, they should reciprocate that respect in -addressing your issue, assessing changes, and helping you finalize your pull requests. In that spirit of mutual respect, -we endeavor to review incoming issues and pull requests within 10 days, and will close any lingering issues or pull -requests after 60 days of inactivity. - -Please note that all of your interactions in the project are subject to our [Code of Conduct](/CODE_OF_CONDUCT.md). This -includes creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in -any real-time space e.g., Slack, Discord, etc. - -## Reporting Issues - -Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our -[issues list](https://github.com/org_name/repo_name/issues). - -When creating a new issue, please be sure to include a **title and clear description**, as much relevant information as -possible, and, if possible, a test case. - -**If you discover a security bug, please do not report it through GitHub. Instead, please see security procedures in -[SECURITY.md](/SECURITY.md).** - -## Sending Pull Requests - -Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix -has been discussed in the past, or if the change was already implemented but not yet released. - -We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning, we may -reserve breaking changes until the next major version release. - -## Other Ways to Contribute - -We welcome anyone that wants to contribute to `` to triage and reply to open issues to help troubleshoot -and fix existing bugs. Here is what you can do: - -- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section, - providing feedback to the issue's author on what might be missing. -- Review and update the existing content of our [Wiki](https://github.com/org_name/repo_name/wiki) with up-to-date - instructions and code samples. -- Review existing pull requests, and testing patches against real existing applications that use ``. -- Write a test, or add a missing test case to an existing test. - -Thanks again for your interest on contributing to ``! - -:heart: diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 422fdc0..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,5 +0,0 @@ -# Maintainers - -- [GitHub Username](https://github.com/username) -- [GitHub Username](https://github.com/username) -- [GitHub Username](https://github.com/username) diff --git a/README.md b/README.md index 05ebacd..5813db6 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,44 @@ -# Open Source Project Template - -[![Release](https://img.shields.io/github/v/release/cisco-ospo/oss-template?display_name=tag)](CHANGELOG.md) -[![Lint](https://github.com/cisco-ospo/oss-template/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/cisco-ospo/oss-template/actions/workflows/lint.yml) -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md) -[![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com) - -## Before You Start - -As much as possible, we have tried to provide enough tooling to get you up and running quickly and with a minimum of effort. This includes sane defaults for documentation; templates for bug reports, feature requests, and pull requests; and [GitHub Actions](https://github.com/features/actions) that will automatically manage stale issues and pull requests. This latter defaults to labeling issues and pull requests as stale after 60 days of inactivity, and closing them after 7 additional days of inactivity. These [defaults](.github/workflows/stale.yml) and more can be configured. For configuration options, please consult the documentation for the [stale action](https://github.com/actions/stale). - -In trying to keep this template as generic and reusable as possible, there are some things that were omitted out of necessity and others that need a little tweaking. Before you begin developing in earnest, there are a few changes that need to be made: - -- [ ] ✅ Select an [OSI-approved license](https://opensource.org/licenses) for your project. This can easily be achieved through the 'Add File' button on the GitHub UI, naming the file `LICENSE`, and selecting your desired license from the provided list. -- [ ] Update the `` placeholder in this file to reflect the name of the license you selected above. -- [ ] Replace `[INSERT CONTACT METHOD]` in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) with a suitable communication channel. -- [ ] Change references to `org_name` to the name of the org your repo belongs to (eg. `cisco-open`): - - [ ] In [`README.md`](README.md) - - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) -- [ ] Change references to `repo_name` to the name of your new repo: - - [ ] In [`README.md`](README.md) - - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) -- [ ] Update the link to the contribution guidelines to point to your project: - - [ ] In [`.github/ISSUE_TEMPLATE/BUG_REPORT.md`](.github/ISSUE_TEMPLATE/BUG_REPORT.md) - - [ ] In [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) -- [ ] Replace the `` placeholder with the name of your project: - - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) - - [ ] In [`SECURITY.md`](SECURITY.md) -- [ ] Add names and contact information for actual project maintainers to [`MAINTAINERS.md`](MAINTAINERS.md). -- [ ] Delete the content of [`CHANGELOG.md`](CHANGELOG.md). We encourage you to [keep a changelog](https://keepachangelog.com/en/1.0.0/). -- [ ] Configure [`.github/dependabot.yaml`](dependabot.yaml) for your project's language and tooling dependencies. -- [ ] Replace the generic content in this file with the relevant details about your project. -- [ ] Acknowledge that some features like [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) are only available when the repo is `public`. -- [ ] 🚨 Delete this section of the `README`! - -## About The Project - -Provide some information about what the project is/does. - -## Getting Started - -To get a local copy up and running follow these simple steps. - -### Prerequisites - -This is an example of how to list things you need to use the software and how to install them. - -- npm - - ```sh - npm install npm@latest -g - ``` - -### Installation - -1. Clone the repo - - ```sh - git clone https://github.com/org_name/repo_name.git - ``` - -2. Install NPM packages - - ```sh - npm install - ``` - -## Usage - -Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. - -_For more examples, please refer to the [Documentation](https://example.com) or the [Wiki](https://github.com/org_name/repo_name/wiki)_ - -## Roadmap - -See the [open issues](https://github.com/org_name/repo_name/issues) for a list of proposed features (and known issues). - -## Contributing - -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. For detailed contributing guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md) - -## License - -Distributed under the `` License. See [LICENSE](LICENSE) for more information. - -## Contact - -Your Name - [@twitter_handle](https://twitter.com/twitter_handle) - email - -Project Link: [https://github.com/org_name/repo_name](https://github.com/org_name/repo_name) - -## Acknowledgements - -This template was adapted from -[https://github.com/othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template). +# Sustainability Insights + +This package contains Cisco Sustainability Insights tooling. This collects near-real-time power, energy efficiency other metrics from devices to generate visualisation and insights. This is a reference implementation of [POWEFF specification](https://datatracker.ietf.org/doc/draft-opsawg-poweff/) as the normalised data model for power metrics. + +![Dashboard](./docs/dashboard.png "Dashboard") + +This version supports two Cisco devices families viz. Cisco ASR 1000 and Cisco Catalyst 9300 and one connection type viz SSH/CLI. This can be easily extended to other vendors' device types and other connection types e.g. REST, RESTCONF, SNMP etc. + +# Prerequisites +[Docker v24](https://docs.docker.com/get-docker/) OR [Podman v5.x](https://podman.io/get-started) +If using podman, update the build and running scipts to use `podman`, `podman-compose` in place of `docker` and `docker-compose` respectively. + +# Quickstart +- [Configure device inventory and collection](./docs/device-configuration.md) +- For Linux users: run `$ chmod 666 config.yaml` as read-write permission is required +- [Configure micro services](./docs/service-configuration.md) +- For Windows users: Edit the shell environment substitues in the `docker-compose.yaml` file. Refer to the `.env` file for default values +- For Windows users: Change the EOL Sequence from CRLF to LF for the following files: + 1. `dbscripts/dbcreate.sh` + 2. `superset/superset-init.sh` +- Start applciations `$ start-susi.sh` or simply `$ docker compose up -d`. Building the docker images is already integreated into the Docker Compose process. +- Open [Application Dashboard](https://locahost:8088) in a browser +- Login with default credential `admin/5cS9Fb73CUnd` +- Select top level, site level or device level dashboard for visualisation and insights +- To stop applciations `$ stop-susi.sh` or simply `$ docker compose down` + +# Design +This solution uses below microservices communicating over Apache Kafka messaging infrastructure. +- Scheduler MS + - Reads device inventory configuration and validates against schema + - Initiates collection for each device at configured intervals +- SSH Collector MS + - Initiates connection to the network device using [Cisco pyATS](https://developer.cisco.com/docs/pyats/) + - Runs platform specific CLI commands + - Parses CLI command output and normlises to POWEFF data model +- Processor MS + - Processes POWEFF data + - Fetches CO2 Intensity (realtime if Electricity Maps API is configured or uses configured default) + - Calculates CO2eq emissions and other metrics + - Stores collected and calculated metrics in [Timescale](https://www.timescale.com) database +- Apache Superset + - Renders dashboards for metrics visualisation and insights + +![Design](./docs/arch.png "Design") diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 210a9c1..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,39 +0,0 @@ -# Security Policies and Procedures - -This document outlines security procedures and general policies for the -`` project. - -- [Reporting a Bug](#reporting-a-bug) -- [Disclosure Policy](#disclosure-policy) -- [Comments on this Policy](#comments-on-this-policy) - -## Reporting a Bug - -The `` team and community take all security bugs in -`` seriously. Thank you for improving the security of -``. We appreciate your efforts and responsible disclosure and -will make every effort to acknowledge your contributions. - -Report security bugs by emailing `oss-security@cisco.com`. - -The lead maintainer will acknowledge your email within 48 hours, and will send a -more detailed response within 48 hours indicating the next steps in handling -your report. After the initial reply to your report, the security team will -endeavor to keep you informed of the progress towards a fix and full -announcement, and may ask for additional information or guidance. - -## Disclosure Policy - -When the security team receives a security bug report, they will assign it to a -primary handler. This person will coordinate the fix and release process, -involving the following steps: - -- Confirm the problem and determine the affected versions. -- Audit code to find any potential similar problems. -- Prepare fixes for all releases still under maintenance. These fixes will be - released as quickly as possible. - -## Comments on this Policy - -If you have suggestions on how this process could be improved please submit a -pull request.