🚚 release

.github/workflows/configs/helm-ct.yaml

@@ -0,0 +1,2 @@
+validate-maintainers: false
+skip-helm-dependencies: false

.github/workflows/helm-lint.yaml

@@ -1,4 +1,5 @@
 name: Helm - lint
+
 on:
   push:
     branches:
@@ -20,16 +21,44 @@ permissions:
 jobs:
   helm-lint:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
-    defaults:
-      run:
-        working-directory: charts
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup Helm
-        uses: azure/setup-helm@fe7b79cd5ee1e45176fcad797de68ecaf3ca4814 # v4
-      - name: Update helm dependencies
-        run: helm dependency update diode
-      - name: Run helm lint
-        run: helm lint diode
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # 4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Set up Helm
+        uses: azure/setup-helm@b9e51907a09c216f16ebe8536097933489208112 # v4.3.0
+        with:
+          version: v3.17.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.x'
+          check-latest: true
+
+      - name: Extract Helm repo dependencies from Chart.yaml
+        id: extract_repos
+        uses: mikefarah/yq@b534aa9ee5d38001fba3cd8fe254a037e4847b37 # v4.45.4
+        with:
+          cmd: yq -o=tsv '.dependencies[] | [.name, .repository] | @tsv' charts/diode/Chart.yaml
+      - name: Add Helm repos from dependencies
+        run: |
+          echo "${{ steps.extract_repos.outputs.result }}" | while IFS=$'\t' read -r name repo; do
+            helm repo add "$name" "$repo"
+          done   
+
+      - name: Set up chart-testing
+        uses: helm/chart-testing-action@0d28d3144d3a25ea2cc349d6e59901c4ff469b3b # v2.7.0
+
+      - name: Run chart-testing (list-changed)
+        id: list-changed
+        run: |
+          changed=$(ct list-changed --target-branch release)
+          if [[ -n "$changed" ]]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run chart-testing (lint)
+        if: steps.list-changed.outputs.changed == 'true'
+        run: ct lint --config .github/workflows/configs/helm-ct.yaml --target-branch release

GET_STARTED.md

@@ -0,0 +1,194 @@
+# Getting Started with Diode
+
+This guide will help you set up and start using Diode to ingest data into NetBox.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- NetBox version 4.2.3 or later
+- Docker version 27.0.3 or newer
+- bash 4.x or newer
+- jq
+
+## Installation Steps
+
+### Deploy Diode server
+
+> **Host**: These steps should be performed on the host where you want to run the Diode server.
+
+> **Note**: For the complete installation instructions, please refer to the [official Diode Server documentation](https://github.com/netboxlabs/diode/tree/develop/diode-server).
+
+We provide a `quickstart.sh` script to automate the setup process. The script will download and configure all necessary files:
+
+- `docker-compose.yaml` — Defines Diode server containers
+- `.env` — Environment settings for customization
+- `nginx.conf` — Nginx configuration for routing Diode endpoints
+- `client-credentials.json` — Defines OAuth2 clients for secure communication
+
+1. Create a working directory:
+   ```bash
+   mkdir /opt/diode
+   cd /opt/diode
+   ```
+
+2. Download and prepare the quickstart script:
+   ```bash
+   curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
+   chmod +x quickstart.sh
+   ```
+
+3. Run the script with your NetBox server address:
+   ```bash
+   ./quickstart.sh https://<netbox-server>
+   ```
+   This should have created an `.env` file for your environment.
+
+4. Start the Diode server:
+   ```bash
+   docker compose up -d
+   ```
+5. Extract the `netbox-to-diode` client secret. This will be needed for the Diode NetBox plugin installation:
+   ```bash
+   echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)
+   ```
+   > **Note**: This will return a credential that will be used by the Diode NetBox plugin to connect to the Diode server. Store it safely.
+
+### Install Diode NetBox Plugin
+
+> **Host**: These steps should be performed on the host where NetBox is installed.
+
+> **Note**: For the complete installation instructions, please refer to the [official Diode NetBox Plugin documentation](https://github.com/netboxlabs/diode-netbox-plugin/blob/develop/README.md).
+
+1. **Source the NetBox Python Virtual Environment**
+   ```bash
+   cd /opt/netbox
+   source venv/bin/activate
+   ```
+
+2. **Install the Plugin Package**
+   ```bash
+   pip install netboxlabs-diode-netbox-plugin
+   ```
+
+3. **Configure NetBox Settings**
+   Add the following to your `configuration.py`:
+   ```python
+   PLUGINS = [
+       "netbox_diode_plugin",
+   ]
+
+   PLUGINS_CONFIG = {
+       "netbox_diode_plugin": {
+           # Diode gRPC target for communication with Diode server
+           "diode_target_override": "grpc://<diode-server:port>/diode",
+           # NetBox username associated with changes applied via plugin
+           "diode_username": "diode",
+           # netbox-to-diode client secret from earlier step
+           "netbox_to_diode_client_secret": "<netbox-to-diode-secret>"
+       },
+   }
+   ```
+
+4. **Apply Database Migrations**
+   ```bash
+   cd /opt/netbox/netbox
+   ./manage.py migrate netbox_diode_plugin
+   ```
+
+5. **Restart NetBox Services**
+   ```bash
+   sudo systemctl restart netbox netbox-rq
+   ```
+
+6. **Generate Diode Client Credentials**
+   > **Note**: These credentials will be used by the Orb agent to send discovery results to NetBox via Diode.
+
+   1. Go to your NetBox instance (https://<netbox-server>)
+   2. In the left-hand pane, navigate to **Diode -> Client Credentials**
+   3. Click on **+ Add a Credential**
+   4. For Client Name, enter any name and click **Create**
+   5. **IMPORTANT**: Copy the _Client ID_ and _Client Secret_ and save them securely
+   6. Click **Return to List**
+
+   You have now created your Diode client credentials. These will be used as environment variables when running the Orb agent.
+
+### Ingest Data with Orb Agent
+
+> **Host**: These steps should be performed on the host where you want to run the Orb agent for network discovery.
+
+> **Note**: For the complete installation instructions, please refer to the [official Orb Agent documentation](https://github.com/netboxlabs/orb-agent).
+
+1. **Export Client Credentials**
+   ```bash
+   # Export the client credentials you generated in NetBox
+   export DIODE_CLIENT_ID="<your-client-id>"
+   export DIODE_CLIENT_SECRET="<your-client-secret>"
+   ```
+
+2. **Create Agent Configuration File**
+   Create an `agent.yaml` file with the following content:
+   ```yaml
+   orb:
+     config_manager:
+       active: local
+     backends:
+       network_discovery:  # Enable network discovery backend
+       common:
+         diode:
+           target: grpc://<diode-server:port>/diode
+           client_id: ${DIODE_CLIENT_ID}
+           client_secret: ${DIODE_CLIENT_SECRET}
+           agent_name: my_agent
+     policies:
+       network_discovery:
+         loopback_policy:
+           config:
+           scope:
+             targets: 
+               - 127.0.0.1
+   ```
+
+3. **Run the Agent**
+
+   Using host network mode (recommended):
+   ```bash
+   docker run --net=host \
+     -v $(pwd):/opt/orb/ \
+     -e DIODE_CLIENT_ID \
+     -e DIODE_CLIENT_SECRET \
+     netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
+   ```
+
+   Alternative using root user:
+   ```bash
+   docker run -u root \
+     -v $(pwd):/opt/orb/ \
+     -e DIODE_CLIENT_ID \
+     -e DIODE_CLIENT_SECRET \
+     netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
+   ```
+
+   > **Note**: The container needs sufficient permissions to send ICMP and TCP packets. This can be achieved either by:
+   > - Setting the network mode to `host` (recommended)
+   > - Running the container as root user
+
+4. **Verify Agent Operation**
+   - Check the agent logs for successful startup
+   - Verify data appears in NetBox
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Issues**
+   - Verify network connectivity between Diode and NetBox
+   - Check firewall rules
+   - Validate URLs and ports
+
+### Getting Help
+
+If you encounter issues:
+
+1. Search GitHub: [Issues](https://github.com/netboxlabs/diode/issues)
+2. Find us in Slack: [NetDev Community #orb](https://https://netdev-community.slack.com/)

README.md

@@ -1,56 +1,55 @@
 # Diode
 
-Diode is a NetBox data ingestion service that greatly simplifies and enhances the process to add and update network data
-in NetBox, ensuring your network source of truth is always accurate and can be trusted to power your network automation
-pipelines. Our guiding principle in designing Diode has been to make it as easy as possible to get data into NetBox,
-removing as much burden as possible from the user while shifting that effort to technology.
-
-To achieve this, Diode sits in front of NetBox and provides an API purpose built for ingestion of complex network data.
-Diode eliminates the need to preprocess data to make it conform to the strict object hierarchy imposed by the NetBox
-data model. This allows data to be sent to NetBox in a more freeform manner, in blocks that are intuitive for network
-engineers (such as by device or by interface) with much of the related information treated as attributes or properties
-of these components of interest. Then, Diode takes care of the heavy lifting, automatically transforming the data to
-align it with NetBox’s structured and comprehensive data model. Diode can even create placeholder objects to compensate
-for missing information, which means even fragmented information about the network can be captured in NetBox.
-
-## Project status
-
-The Diode project is currently in the _Public Preview_ stage. Please
-see [NetBox Labs Product and Feature Lifecycle](https://netboxlabs.com/docs/console/product_feature_lifecycle/) for more
-details. We actively welcome feedback to help identify and prioritize bugs, new features and areas of improvement.
-
-## Get started
-
-Diode runs as a sidecar service to NetBox and can run anywhere with network connectivity to NetBox, whether on the same
-host or elsewhere. The overall Diode service is delivered through three main components (and a fourth optional
-component):
-
-1. Diode plugin - see how to [install the Diode plugin](https://github.com/netboxlabs/diode-netbox-plugin)
-2. Diode server - see how
-   to [run the Diode server](https://github.com/netboxlabs/diode/tree/develop/diode-server#readme)
-3. Diode SDK - see how
-   to [install the Diode Python client SDK](https://github.com/netboxlabs/diode-sdk-python), [download Diode Python script examples](https://github.com/netboxlabs/netbox-learning/tree/develop/diode)
-   and [use the Diode SDK Go](https://github.com/netboxlabs/diode-sdk-go)
-4. Diode agent (optional) - see how
-   to [install and run the Diode NAPALM discovery agent](https://github.com/netboxlabs/diode-agent/tree/develop/diode-napalm-agent)
+Diode is a data ingestion service for NetBox that greatly simplifies and enhances the process of adding and updating data in NetBox, ensuring your network source of truth is always accurate and up to date. Our guiding principle in designing Diode has been to make it as easy as possible to get data into NetBox, removing as much burden as possible from the user while shifting that effort to technology.
+
+## Project Status
+
+The Diode project is currently in the _Public Preview_ stage. Please see [NetBox Labs Product and Feature Lifecycle](https://netboxlabs.com/docs/console/product_feature_lifecycle/) for more details. We actively welcome feedback to help identify and prioritize bugs, new features and areas of improvement.
+
+## Prerequisites
+
+- NetBox 4.2.3 or later
+- Python 3.8 or later (for Python SDK)
+- Go 1.18 or later (for Go SDK)
+- Network connectivity between Diode and NetBox
+
+## Quick Start
+
+For a quick step-by-step guide, see our [Getting Started Guide](./GET_STARTED.md).
+
+1. **Deploy the Diode Server**
+   See [deployment instructions](https://github.com/netboxlabs/diode/blob/develop/diode-server/README.md)
+
+2. **Install the Diode NetBox Plugin**
+   See [installation instructions](https://github.com/netboxlabs/diode-netbox-plugin/blob/develop/README.md)
+
+3. **Choose Your Data Ingestion Method**
+   - Use the NetBox Discovery agent for automated network discovery: see [instructions to run Orb agent](https://github.com/netboxlabs/orb-agent)
+   - Build custom integrations using our SDKs:
+     - [Python SDK](https://github.com/netboxlabs/diode-sdk-python)
+     - [Go SDK](https://github.com/netboxlabs/diode-sdk-go)
+
+## Documentation
+
+- [Diode Protocol Documentation](https://github.com/netboxlabs/diode/blob/develop/docs/diode-proto.md)
 
 ## Related Projects
 
-- [diode-netbox-plugin](https://github.com/netboxlabs/diode-netbox-plugin) - The Diode NetBox plugin is a NetBox plugin
-  and a required component of the Diode ingestion service.
-- [diode-sdk-python](https://github.com/netboxlabs/diode-sdk-python) - Diode SDK Python is a Python library for
-  interacting with the Diode ingestion service utilizing gRPC.
-- [diode-sdk-go](https://github.com/netboxlabs/diode-sdk-go) - Diode SDK Go is a Go module for interacting with the
-  Diode ingestion service utilizing gRPC.
-- [diode-agent](https://github.com/netboxlabs/diode-agent) - A collection of agents that leverage the Diode SDK to
-  interact with the Diode server.
+- [diode-netbox-plugin](https://github.com/netboxlabs/diode-netbox-plugin) - The Diode NetBox plugin is a NetBox plugin and a required component of the Diode ingestion service.
+- [diode-sdk-python](https://github.com/netboxlabs/diode-sdk-python) - Diode SDK Python is a Python library for interacting with the Diode ingestion service utilizing gRPC.
+- [diode-sdk-go](https://github.com/netboxlabs/diode-sdk-go) - Diode SDK Go is a Go module for interacting with the Diode ingestion service utilizing gRPC.
+- [orb-agent](https://github.com/netboxlabs/orb-agent) - The NetBox Discovery agent.
+
+## Support
+
+- [GitHub Issues](https://github.com/netboxlabs/diode/issues)
+- [Slack NetDev Community (#orb channel)](https://https://netdev-community.slack.com/)
 
 ## License
 
 Distributed under the NetBox Limited Use License 1.0. See [LICENSE.md](./LICENSE.md) for more information.
 
-Diode protocol buffers are distributed under the Apache 2.0 License. See [LICENSE.txt](./diode-proto/LICENSE.txt) for
-more information.
+Diode protocol buffers are distributed under the Apache 2.0 License. See [LICENSE.txt](./diode-proto/LICENSE.txt) for more information.
 
 ## Required Notice
 

charts/diode/Chart.yaml

@@ -2,7 +2,7 @@ apiVersion: v2
 name: diode
 description: A Helm chart for Diode
 type: application
-version: 1.5.0
+version: 1.6.0
 appVersion: "1.2.0"
 home: https://github.com/netboxlabs/diode
 sources: