diff --git a/.gitignore b/.gitignore index 25ac166e43..8838fac087 100644 --- a/.gitignore +++ b/.gitignore @@ -50,3 +50,4 @@ default.profraw **errorutil_analyze_summary.json **errorutil_errors_export.json .ruby-version +helm-kanvas-snapshot diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab41e45426..eec1d86c30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,360 +115,6 @@ Or you may configure your IDE, for example, Visual Studio Code to automatically -## Documentation Contribution Flow - -Please contribute! Meshery documentation uses GitHub Pages to host the docs site. Learn more about [Meshery's documentation framework](https://docs.google.com/document/d/17guuaxb0xsfutBCzyj2CT6OZiFnMu9w4PzoILXhRXSo/edit?usp=sharing). The process of contributing follows this flow: - -1. Create a fork, if you have not already, by following the steps described [here](docs/CONTRIBUTING-gitflow.md) -1. In the local copy of your fork, navigate to the docs folder. - `cd docs` -1. Create and checkout a new branch to make changes within - `git checkout -b ` -1. Edit/add documentation. - `vi .md` -1. Add redirect link on the old page (only when a new page is created that replaces the old page) -1. Run site locally to preview changes. - `make docs` - -- **Note:** _From the Makefile, this command is actually running `$ bundle exec jekyll serve --drafts --livereload --config _config_dev.yml`. If this command causes errors try running the server without Livereload with this command: `$ bundle exec jekyll serve --drafts --config _config_dev.yml`. Just keep in mind you will have to manually restart the server to reflect any changes made without Livereload. There are two Jekyll configuration, `jekyll serve` for developing locally and `jekyll build` when you need to generate the site artifacts for production._ - -1. Commit, [sign-off](#commit-signing), and push changes to your remote branch. - `git push origin ` -1. Open a pull request (in your web browser) against our main repo: https://github.com/meshery/meshery. - -_Alternatively, LiveReload is available as an option during development: with jekyll serve --livereload no more manual page refresh. - -`bundle exec jekyll serve --drafts --livereload --incremental --config _config_dev.yml` - - -## Meshery Contribution Flow - -Meshery is written in `Go` (Golang) and leverages Go Modules. UI is built on React and Next.js. To make building and packaging easier a `Makefile` is included in the main repository folder. - -Relevant coding style guidelines are the [Go Code Review Comments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments) and the _Formatting and style_ section of Peter Bourgon's [Go: Best -Practices for Production Environments](https://peter.bourgon.org/go-in-production/#formatting-and-style). - -**Please note**: All `make` commands should be run in a terminal from within the Meshery's main folder. - -### Prerequisites for building Meshery in your development environment: - -1. Go version 1.21.1 must be installed if you want to build and/or make changes to the existing code. The binary `go1.21.1` should be available in your path. If you don't want to disturb your existing version of Go, then follow these [instructions](https://go.dev/doc/manage-install#:~:text=and%20run%20them.-,Installing%20multiple%20Go%20versions,-You%20can%20install) to keep multiple versions of Go in your system. -2. `GOPATH` environment variable should be configured appropriately -3. `npm` and `node` should be installed on your machine, preferably the latest versions. -4. Fork this repository (`git clone https://github.com/meshery/meshery.git`), and clone your forked version of Meshery to your development environment, preferably outside `GOPATH`. -5. `golangci-lint` should be installed if you want to test Go code, for MacOS and linux users. - -#### Build and Run Meshery Server - -Before you can access the Meshery UI, you need to install the UI dependencies, - -```sh -make ui-setup -``` - -and then build and export the UI - -```sh -make ui-build -``` - -To build & run Meshery Server, run the following command: - -```sh -make server -``` - -Any time changes are made to the Go code, you will have to stop the server and run the above command again. -Once the Meshery server is up and running, you should be able to access Meshery on your `localhost` on port `9081` at `http://localhost:9081`. - -**Please note**: If you see "Meshery Development Incompatible" while trying to sign into Meshery Server, then follow these steps: - - - -Potential Solution: - -- Go to your meshery folder in your local-system where you’ve cloned it. -Execute: - -- `git remote add upstream https://github.com/meshery/meshery` -- `git fetch upstream` -- Restart the meshery server -- Additionally, before restarting the server, if you like to pull the latest changes, you can do: `git pull upstream master` -### UI Development Server - -If you want to work on the UI, it will be a good idea to use the included UI development server. You can run the UI development server by running the following command: - -``` -make ui -``` - -Once you have the server configured, and running successfully on the default port `http://localhost:9081`, you may proceed to access the Meshery UI at `http://localhost:3000`. -Any UI changes made now will automatically be recompiled and served in the browser. - -To access the [Meshery UI Development Server](#ui-development-server) on port `3000`, you will need to select your **Cloud Provider** by navigating to `localhost:9081` after running the Meshery server. - -**Please note**: When running `make server` on the macOS platform, some may face errors with the crypto module in Go. This is caused due to invalid C headers in Clang installed with XCode platform tools. Replacing Clang with gcc by adding `export CC=gcc` to .bashrc / .zshrc should fix the issue. More information on the issue can be found [here](https://github.com/golang/go/issues/30072) - -**Please Note** : Little minor things where you can face some issues in the windows platform - - -1. Meshery requires gcc at the `make server` step, **x64 windows** architecture can face issues while finding the best **GCC compiler**, You can install [tdm64-GCC](https://jmeubank.github.io/tdm-gcc/) which worked smoothly but many compilers other than that can cause issues, you also have to set an environment variable for this step. - -2. Installing `make` in windows requires you to install [choco](https://chocolatey.org/install) first, which makes it easier to install `make` then, It requires security access which can only be done in admin mode. - -#### Tests - -Users can now test their code changes on their local machine against the CI checks implemented through golang-ci lint. - -To test code changes on your local machine, run the following command: - -``` -make golangci-run -``` - -#### Building Docker image - -To build a Docker image of Meshery, please ensure you have `Docker` installed to be able to build the image. Now, run the following command to build the Docker image: - -```sh -make docker -``` - -#### Writing a Meshery Adapter - -Meshery uses adapters to provision and interact with different service meshes. Follow these instructions to create a new adapter or modify an existing adapter. - -1. Get the proto buf spec file from Meshery repo: - `wget https://raw.githubusercontent.com/meshery/meshery/master/server/meshes/meshops.proto` -1. Generate code - 1. Using Go as an example, do the following: - - install the protocol buffer compiler: https://grpc.io/docs/protoc-installation/ - - add GOPATH to PATH: `export PATH=$PATH:$(go env GOPATH)/bin` - - install the protocol compiler plugins for go: - `go install google.golang.org/protobuf/cmd/protoc-gen-go@latest` - `go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest` - - create a directory _meshes_ - - Generate Go code: - `protoc --proto_path=. --go_out=meshes --go_opt=paths=source_relative --go-grpc_out=meshes --go-grpc_opt=paths=source_relative meshops.proto` - - 1. For other languages, please refer to gRPC.io for language-specific guides. -1. Implement the service methods and expose the gRPC server on a port of your choice (e.g. 10000). - -_Tip:_ The [Meshery adapter for Istio](https://github.com/meshery/meshery-istio) is a good reference adapter to use as an example of a Meshery adapter written in Go. - -#### Running Meshery Adapter (Meshery-Istio) - -**Meshery-Istio** is a pre-written example of Meshery Adapter written in Go. Follow these instructions to run meshery-istio to avoid errors related to Meshery Adapters - -1. Fork [Meshery-Istio](https://github.com/meshery/meshery-istio) -2. Clone your fork locally -3. Run this command from the root directory of **meshery-istio** - ```sh - make run - ``` -4. Try connecting to port 10000 as Meshery Adapter URL - -## UI Contribution Flow - -Meshery is written in `Go` (Golang) and leverages Go Modules. UI is built on React, Billboard.js and Next.js. To make building and packaging easier a `Makefile` is included in the main repository folder. - -![ui/assets/img/readme/meshery_ui.png](ui/assets/img/readme/meshery_ui.png) - -### Install UI dependencies - -To install/update the UI dependencies: - -``` -make ui-setup -``` - -### Build and export UI - -To build and export the UI code: - -``` -make ui-build -``` - -### Build and run Meshery Server - -To build & run Meshery Server: - -``` -make server -``` - -Now that the UI code is built, Meshery UI will be available at `http://localhost:9081`. -Any time changes are made to the UI code, the above code will have to run to rebuild the UI. - -### UI Development Server - -If you want to work on the UI, it will be a good idea to use the included UI development server. You can run the UI development server by running the following command: - -``` -make ui -``` - -Once you have the server configured, and running successfully on the default port `http://localhost:9081`, you may proceed to access the Meshery UI at `http://localhost:3000`. -Any UI changes made now will automatically be recompiled and served in the browser. - -### Running Meshery from IDE - -If you want to run Meshery from IDE like Goland, VSCode. set below environment variable - -``` -PROVIDER_BASE_URLS="https://cloud.layer5.io" -PORT=9081 -DEBUG=true -ADAPTER_URLS=localhost:10000 localhost:10001 localhost:10002 localhost:10003 localhost:10004 localhost:10005 localhost:10006 localhost:10007 localhost:10008 localhost:10009 -``` - -go tool argument - -```shell --tags draft -``` - -### UI Lint Rules - -We are using ES-Lint to maintain code quality & consistency in our UI Code. To make sure your PR passes all the UI & ES-Lint Tests, please see below : - -- Remember to run `make ui-lint` & `make ui-provider-lint` if you are making changes in Meshery-UI & Provider-UI respectively. -- The above commands will only fix some basic indenting rules. You will have to manually check your code to ensure there are no duplications, un-used variables or un-declared constants. -- We will soon be adding Pre-Commit Hooks to make sure you get to know your errors before you commit the code. -- In case you are unable to fix your lint errors, ping us on our [Slack](https://slack.meshery.io). - - -# Using Sistent in Meshery UI - -## Overview - -Meshery UI utilizes three component libraries: - -1. Material-UI (MUI) v4 -2. Material-UI (MUI) v5 -3. Sistent - -While MUI v4 and v5 are being phased out, Sistent is now the preferred component library. Sistent internally uses MUI v5, and Meshery UI globally still relies on MUI v4. This can lead to conflicts between themes when Sistent components are used directly. - -## The `UseSistent` Wrapper - -To resolve theme conflicts and ensure proper functionality, a custom wrapper called `UseSistent` has been created. This wrapper provides the Sistent theme to its child components. - -## Usage Guidelines - -1. Wrap any custom component that exclusively uses Sistent components with `UseSistent`. -2. Individual Sistent components can also be wrapped with `UseSistent`. -3. Avoid using MUI v4 components within a component wrapped with `UseSistent`. - -## Examples - -### Example 1: Wrapping a custom component - -```jsx -import { UseSistent } from './UseSistent'; -import { Button, TextField } from 'sistent'; - -const MyCustomForm = () => ( - -
- - - -
-); -``` - -### Example 2: Wrapping an individual Sistent component - -```jsx -import { UseSistent } from './UseSistent'; -import { DataGrid } from 'sistent'; - -const MyDataGridComponent = ({ data }) => ( - - - -); -``` - -### Example 3: Incorrect usage (avoid this) - -```jsx -import { UseSistent } from './UseSistent'; -import { Button } from 'sistent'; -import { TextField } from '@material-ui/core'; // MUI v4 - -// Don't do this! -const IncorrectUsage = () => ( - - - {/* This will cause conflicts */} - -); -``` - -## Best Practices - -1. Gradually migrate components to use Sistent instead of MUI v4 or v5. -2. Always wrap Sistent components or custom components using Sistent with `UseSistent`. -3. Keep MUI v4 components separate from Sistent components to avoid theme conflicts. - - - -## Mesheryctl Documentation - -### mesheryctl - -`mesheryctl` is the CLI client for Meshery. - -### Contributing - -Please refer to the [Meshery Contributing Guidelines](https://docs.meshery.io/project/contributing/contributing-cli) for setting up your development environment and the [mesheryctl Command Reference and Tracker](https://docs.google.com/spreadsheets/d/1q63sIGAuCnIeDs8PeM-0BAkNj8BBgPUXhLbe1Y-318o/edit#gid=0) for current status of `mesheryctl`. - -For a quick introduction to `mesheryctl`, checkout [Beginner's guide to contributing to Meshery and mesheryctl](https://youtu.be/hh_kFLZx3G4). - -### Building and running `mesheryctl` - -The [`/mesheryctl`](https://github.com/meshery/meshery/tree/master/mesheryctl) folder contains the complete code for `mesheryctl`. - -`mesheryctl` is written in Golang or the Go Programming Language. For development use Go version 1.15+. - -After making changes, run `make` in the `mesheryctl` folder to build the binary. You can then use the binary by, say, `./mesheryctl system start`. - -### `mesheryctl` command reference - -- See user-facing, documentation of the `mesheryctl` commands is available in the [Meshery Docs](https://docs.meshery.io/reference/mesheryctl). -- See contributor-facing design spec for [Meshery CLI Commands and Documentation](https://docs.google.com/document/d/1xRlFpElRmybJ3WacgPKXgCSiQ2poJl3iCCV1dAalf0k/edit#heading=h.5fucij4hc5wt) for a complete reference of `mesheryctl`. - -### General guidelines and resources - -`mesheryctl` might be the interface that the users first have with Meshery. As such, `mesheryctl` needs to provide a great UX. - -The following principles should be taken in mind while designing `mesheryctl` commands- - -1. Provide user experiences that are familiar. -2. Make the commands and their behavior intuitive. -3. Avoid long commands with chained series of flags. -4. Design with automated testing in mind, e.g. provide possibility to specify output format as json (-o json) for easy inspection of command response. - -Part of delivering a great user experience is providing intuitive interfaces. In the case of `mesheryctl`, we should take inspiration from and deliver similar user experiences as popular CLIs do in this ecosystem, like `kubectl` and `docker`. Here is relevant `kubectl` information to reference - [Kubectl SIG CLI Community Meeting Minutes](https://docs.google.com/document/u/2/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit#), [contributing to kubectl](https://github.com/kubernetes/community/blob/master/sig-cli/CONTRIBUTING.md), [code](https://github.com/kubernetes/kubernetes/tree/master/pkg/kubectl/cmd/config). - -`mesheryctl` uses the [Cobra](https://github.com/spf13/cobra) framework. A good first-step towards contributing to `mesheryctl` would be to familiarise yourself with the [Cobra concepts](https://github.com/spf13/cobra#concepts). - -For manipulating config files, `mesheryctl` uses [Viper](https://github.com/spf13/viper). - -A central `struct` is maintained in the `mesheryctl/internal/cli/root/config/config.go` file. These are updated and should be used for getting the Meshery configuration. - -For logs, `mesheryctl` uses [Logrus](https://github.com/sirupsen/logrus). Going through the docs and understanding the different [log-levels](https://github.com/sirupsen/logrus#level-logging) will help a lot. - -`mesheryctl` uses [golangci-lint](https://github.com/golangci/golangci-lint). Refer to it for lint checks. - -All contributors are invited to review [pull requests](https://github.com/meshery/meshery/pulls) on `mesheryctl` as on other Meshery components. - -# Reviews - -All contributors are invited to review pull requests. See this short video on [how to review a pull request](https://www.youtube.com/watch?v=isLfo7jfE6g&feature=youtu.be). - # New to Git? Resources: https://lab.github.com and https://try.github.com/ diff --git a/README.md b/README.md index ccd12d4e8b..0229ea19eb 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ - **Table of Contents** - [Meshery Extension: Kanvas Snapshot Helm Plugin](#meshery-extension-kanvas-snapshot-helm-plugin) @@ -46,8 +45,6 @@ To install the Meshery Snapshot Helm Plugin, use the following steps: - `helm` must be [installed]( helm plugin install https://github.com/meshery/helm-kanvas-snapshot) on your system. - (Optional) A free [Layer5 Cloud](https://cloud.layer5.io) user account. -- Environemnt Variables: - 1. ...? **Plugin Installation** @@ -63,10 +60,13 @@ To install the Meshery Snapshot Helm Plugin, use the following steps: helm plugin list ``` - You should see the Kanvas Snapshot listed as `snapshot`. + You should see the Kanvas Snapshot listed as `helm-kanvas-snapshot`. -4. Set up the required environment variables (see the [Environment Variables](#environment-variables) section). +Update to the latest version: +```bash +helm plugin update helm-kanvas-snapshot +``` ### Usage Once the plugin is installed, you can generate a snapshot using either a packaged or unpackaged Helm chart. @@ -77,28 +77,29 @@ helm helm-kanvas-snapshot -f [--name ] [-e ] - **`-f`**, **`--file`**: (required) path or URL to the Helm chart (required). - **`--name`**: (optional) name for the snapshot. If not provided, a name will be auto-generated based on the chart name. -- **`-e`, **`--email`**: (optional) email address to notify when snapshot is ready. If not provided, a link to the snapshot will be displayed in the terminal. +- **`-e`**, **`--email`**: (optional) email address to notify when snapshot is ready. If not provided, a link to the snapshot will be displayed in the terminal. **Example** -To generate a snapshot for a Helm chart located at `https://meshery.io/charts/v0.8.0-meshery.tar.gz`, you can use: +To generate a snapshot for a Helm chart located at `https://meshery.io/charts/meshery-v0.8.12.tgz`, you can use: ```bash -helm helm-kanvas-snapshot -f https://meshery.io/charts/v0.8.0-meshery.tar.gz --name meshery-chart +helm helm-kanvas-snapshot -f https://meshery.io/charts/meshery-v0.8.12.tgz --name meshery-chart ``` ## Contributing Please do! Thank you for your help in improving this Meshery extension! :balloon: -Start by forking the repository. +Start by forking the repository. After making your changes, submit a pull request. For more information, see the [Contributing Guide](CONTRIBUTING.md). + **1. Fork the Repository** To get started, you'll first need to clone the Meshery Snapshot Helm Plugin repository from GitHub. Run the following command in your terminal: ```bash -git clone https://github.com/layer5labs/meshery-extensions-packages.git +git clone https://github.com/meshery/helm-kanvas-snapshot.git ``` **2. Navigate to the Plugin Directory** @@ -109,42 +110,20 @@ Once the repository is cloned, navigate to the `helm-kanvas-snapshot` directory. cd helm-kanvas-snapshot ``` -**3. Replace the placeholder values with your actual credentials.** - -**4. Build the binary** +**4. Build the binary locally** ```bash -make +make local.build ``` -**5. Install the Snapshot plugin** +**5. Test the binary** ```bash -helm plugin install kanvas-snapshot -``` - -**6. Test the Plugin Locally** - -Once the plugin is built, you can test it locally. For example, to generate a snapshot for a Helm chart, run the following command: - -```bash -helm helm-kanvas-snapshot -f https://meshery.io/charts/v0.8.0-meshery.tar.gz --name meshery-chart +./helm-kanvas-snapshot -f https://meshery.io/charts/v0.8.0-meshery.tar.gz ``` This command will trigger the snapshot generation process. If everything is set up correctly, you should see a visual snapshot URL or receive the snapshot via email, depending on the options you specified. -**7. Debugging** - -If you encounter any issues during testing, check the log file generated in the `snapshot-plugin` directory. The logs can provide more insight into any errors that may occur. - -To check the logs, open the log file in your preferred text editor: - -```bash -cat snapshot.log -``` - -This file contains a timestamped log of operations performed during the snapshot generation process. -
 
## Join the Meshery community! @@ -205,7 +184,7 @@ Please do! We're a warm and welcoming community of open source contributors. Ple ### Show Your Support

- If you like Meshery, please ★ star this repository to show your support! 🤩 + If you like Helm kanvas Snapshot, please ★ star this repository to show your support! 🤩

### License diff --git a/helm-kanvas-snapshot b/helm-kanvas-snapshot deleted file mode 100755 index b3c332405b..0000000000 Binary files a/helm-kanvas-snapshot and /dev/null differ diff --git a/helpers/Makefile.core.mk b/helpers/Makefile.core.mk index 0047349e21..81f0e4c84b 100644 --- a/helpers/Makefile.core.mk +++ b/helpers/Makefile.core.mk @@ -1,4 +1,5 @@ GOVERSION = 1.21 PROVIDER_TOKEN="dev_token" -MESHERY_CLOUD_API_BASE_URL="http://localhost:9876" -MESHERY_API_BASE_URL="http://localhost:3000" +MESHERY_CLOUD_API_BASE_URL="https://cloud.layer5.io" +MESHERY_API_BASE_URL="https://playground.meshery.io" +GH_ACCESS_TOKEN="your_github_access_token" # replace with your github access token. do not commit this