From 9ee46a157a0f44c5d3d0ab188cb5b3ca40489a9b Mon Sep 17 00:00:00 2001 From: Chris Hain Date: Tue, 22 Oct 2024 10:15:44 -0700 Subject: [PATCH 1/2] Add link checking action --- .github/workflows/build-pages.yml | 45 +++++++++++++++++++ README.md | 24 +++++++--- pages/Gemfile | 4 +- pages/Gemfile.lock | 43 ++++++++++++++++++ .../otel_collector/receiver_readme.md | 2 +- pages/config/config.md | 8 ++-- .../config/config_helper/config_datafabric.md | 2 +- pages/config/config_helper/config_defaults.md | 4 +- pages/config/config_helper/config_helper.md | 6 +-- .../config/config_helper/config_receivers.md | 2 +- pages/datafabric/configuration.md | 2 +- pages/getting_started.md | 21 +++++++-- pages/index.md | 2 +- pages/troubleshooting/troubleshooting.md | 2 +- 14 files changed, 143 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/build-pages.yml diff --git a/.github/workflows/build-pages.yml b/.github/workflows/build-pages.yml new file mode 100644 index 0000000..68e3640 --- /dev/null +++ b/.github/workflows/build-pages.yml @@ -0,0 +1,45 @@ +on: + push: + branches: + - main + - development + pull_request: + branches: + - main + - development + +workflow_dispatch: +name: Pages-CI + +jobs: + validate: + name: Validate HTML + strategy: + fail-fast: false + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@v1 + with: + working-directory: ./pages + ruby-version: '3.3' # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + - name: Cache HTMLProofer + id: cache-htmlproofer + uses: actions/cache@v3 + with: + path: tmp/.htmlproofer + key: ${{ runner.os }}-htmlproofer + - name: Build Site + run: bundle exec jekyll build + - name: Test with Nu Validator + uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8 + with: + config: fixtures/html5validator-config.yml + - name: Test with html-proofer + run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/" --swap-urls '^/application-study-tool/:/' + env: + NOKOGIRI_USE_SYSTEM_LIBRARIES: true \ No newline at end of file diff --git a/README.md b/README.md index 26226a2..393fc7d 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,14 @@ configuration, troubleshooting info, etc. The Application Study Tool is intended to provide enhanced insights into (classic) BIG-IP products, leveraging best in class open source telemetry tools. The full installation includes: -* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Full List of Metrics Collected](pages/receiver_metrics.md). +* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Full List of Metrics Collected](pages/components/otel_collector/receiver_metrics.md). * Prometheus timeseries database for storing and querying collected data. * Grafana Instance with pre-configured dashboards for quick insights at the device and "fleet" levels. The Application Study Tool has everything needed to quickly get up and running with application insights at less than production levels of reliability. For production/operational use cases, you can build on the included components, accounting for things like high availability, enhanced security via e.g. Grafana OIDC integration, and similar. Alternatively, -the Openetlemetry Collector can be configured to send data to existing production ops monitoring tools as desired. +the Opentelemetry Collector can be configured to send data to existing production ops monitoring tools as desired. ![](./pages/assets/ui.gif) @@ -163,8 +163,8 @@ BIGIP_PASSWORD_2=bar-foo123! ``` The variable name (the part on the left of the equal sign) must match the configured -value for the devices that use this password in config/ast_defaults.yaml or device specifc -cofig in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1 +value for the devices that use this password in config/ast_defaults.yaml or device specific +config in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1 from the defaults and bigip/2 uses BIGIP_PASSWORD_2 from the device settings: ``` @@ -236,7 +236,7 @@ $ python /app/src/config_helper.py --generate-config This will write 2 new files in the services/otel_collector directory: * `receivers.yaml` - The final list of scraper configs and their settings. -* `pipelines.yaml` - The final pipeline configs that map receievers to output destinations +* `pipelines.yaml` - The final pipeline configs that map receivers to output destinations (prometheus, and optionally F5). ## Adding New Devices or Updating Configs @@ -330,6 +330,20 @@ The default Grafana user/pass is `admin/admin`, and can be accessed at `http://:3000`. +## Updating AST Versions +Updating to a new release of the AST repo can be done with the following general process: + +1. Review the release notes for all intermediate versions and check for warnings about +special instructions / breaking changes. +2. Backup your ast_defaults.yaml and bigip_receivers.yaml files. +3. Stash changes, update the repo state, and unstash changes as follows: +```shell +git stash +git pull origin main +git checkout tags/RELEASE_VERSION #(e.g. tags/v0.7.0) +git stash pop +``` + ## Support For support, please open a GitHub issue. Note, the code in this repository is community supported and is not supported by F5 Networks. For a complete list of supported projects please reference [SUPPORT.md](SUPPORT.md). diff --git a/pages/Gemfile b/pages/Gemfile index ecb5d6f..a736a29 100644 --- a/pages/Gemfile +++ b/pages/Gemfile @@ -34,4 +34,6 @@ gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] gem 'nokogiri' gem 'rack', '~> 2.2.4' -gem 'rspec' \ No newline at end of file +gem 'rspec' + +gem "html-proofer", "~> 5.0", :group => :development \ No newline at end of file diff --git a/pages/Gemfile.lock b/pages/Gemfile.lock index ce522d6..9dcee98 100644 --- a/pages/Gemfile.lock +++ b/pages/Gemfile.lock @@ -1,18 +1,34 @@ GEM remote: https://rubygems.org/ specs: + Ascii85 (1.1.1) addressable (2.8.7) public_suffix (>= 2.0.2, < 7.0) + afm (0.2.2) + async (2.17.0) + console (~> 1.26) + fiber-annotation + io-event (~> 1.6, >= 1.6.5) bigdecimal (3.1.8) colorator (1.1.0) concurrent-ruby (1.3.4) + console (1.27.0) + fiber-annotation + fiber-local (~> 1.1) + json diff-lcs (1.5.1) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) eventmachine (1.2.7) ffi (1.17.0-arm64-darwin) ffi (1.17.0-x86_64-linux-gnu) + fiber-annotation (0.2.0) + fiber-local (1.1.0) + fiber-storage + fiber-storage (1.0.0) forwardable-extended (2.6.0) google-protobuf (4.28.1-arm64-darwin) bigdecimal @@ -20,9 +36,20 @@ GEM google-protobuf (4.28.1-x86_64-linux) bigdecimal rake (>= 13) + hashery (2.1.2) + html-proofer (5.0.9) + addressable (~> 2.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) + zeitwerk (~> 2.5) http_parser.rb (0.8.0) i18n (1.14.6) concurrent-ruby (~> 1.0) + io-event (1.7.3) jekyll (4.3.4) addressable (~> 2.4) colorator (~> 1.0) @@ -47,6 +74,7 @@ GEM jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) + json (2.7.2) just-the-docs (0.10.0) jekyll (>= 3.8.5) jekyll-include-cache @@ -67,9 +95,16 @@ GEM racc (~> 1.4) pathutil (0.16.2) forwardable-extended (~> 2.6) + pdf-reader (2.12.0) + Ascii85 (~> 1.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk public_suffix (6.0.1) racc (1.8.1) rack (2.2.10) + rainbow (3.1.1) rake (13.2.1) rb-fsevent (0.11.2) rb-inotify (0.11.1) @@ -89,6 +124,7 @@ GEM diff-lcs (>= 1.2.0, < 2.0) rspec-support (~> 3.13.0) rspec-support (3.13.1) + ruby-rc4 (0.1.5) safe_yaml (1.0.5) sass-embedded (1.78.0-arm64-darwin) google-protobuf (~> 4.27) @@ -96,14 +132,21 @@ GEM google-protobuf (~> 4.27) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) + ttfunk (1.8.0) + bigdecimal (~> 3.1) + typhoeus (1.4.1) + ethon (>= 0.9.0) unicode-display_width (2.6.0) webrick (1.8.1) + yell (2.2.2) + zeitwerk (2.7.1) PLATFORMS arm64-darwin x86_64-linux-gnu DEPENDENCIES + html-proofer (~> 5.0) http_parser.rb (~> 0.6.0) jekyll (~> 4.3.4) just-the-docs (= 0.10.0) diff --git a/pages/components/otel_collector/receiver_readme.md b/pages/components/otel_collector/receiver_readme.md index 8f18106..a6fca7c 100644 --- a/pages/components/otel_collector/receiver_readme.md +++ b/pages/components/otel_collector/receiver_readme.md @@ -95,4 +95,4 @@ TLS config is documented further under the [opentelemetry collector's configtls ## Metrics -Details about the metrics produced by this receiver can be found in [/docs/receiver_metrics.md](/docs/receiver_metrics.md) +Details about the metrics produced by this receiver can be found in [Receiver Metrics Info]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_metrics.html) diff --git a/pages/config/config.md b/pages/config/config.md index 81075fd..1c3b32a 100644 --- a/pages/config/config.md +++ b/pages/config/config.md @@ -9,7 +9,7 @@ permalink: /config # AST Configuration Management Overview This configuration section applies to the AST Opentelemetry Collector. For Grafana, Prometheus or other -components, see the corresponding documentation in [> Components]({{site.baseurl}}/components/) +components, see the corresponding documentation in [> Components]({{ site.url }}{{ site.baseurl }}components) ## Config Management Options @@ -17,12 +17,12 @@ In the post v0.6.0 management scheme, users can choose from one of the below opt the AST Otel Collector configs: 1. Using a python script to generate full Otel Collector Config files from a small set of default -settings and per-device overrides (recommended for most users, and includes migration path from old big-ips.json configs). See [Configuration > Configuration Helper (Recommended)]({{site.baseurl}}/config/config_helper/) for details. +settings and per-device overrides (recommended for most users, and includes migration path from old big-ips.json configs). See [Configuration > Configuration Helper (Recommended)]({{ site.url }}{{ site.baseurl }}config/config_helper) for details. 2. Manual maintenance of the Otel Collector Config Receivers and Pipelines files (recommended for -advanced use cases or people with their own automation pipelines). See [Configuration > Manual Configuration > Receiver/Pipeline Config]({{site.baseurl}}/config/manual_config/receivers_pipelines.html) for details. +advanced use cases or people with their own automation pipelines). See [Configuration > Manual Configuration > Receiver/Pipeline Config]({{ site.url }}{{ site.baseurl }}config/manual_config/receivers_pipelines.html) for details. 3. Manual maintenance of the Otel Collector Config files in -[/services/otel_collector/defaults](https://github.com/f5devcentral/application-study-tool/blob/main/services/otel_collector/defaults). See [Configuration > Manual Configuration > Std Otel Collector Config]({{site.baseurl}}/config/manual_config/default_otel.html/) for details. +[/services/otel_collector/defaults](https://github.com/f5devcentral/application-study-tool/blob/main/services/otel_collector/defaults). See [Configuration > Manual Configuration > Std Otel Collector Config]({{ site.url }}{{ site.baseurl }}config/manual_config/default_otel.html) for details. diff --git a/pages/config/config_helper/config_datafabric.md b/pages/config/config_helper/config_datafabric.md index 9b70631..e5b705e 100644 --- a/pages/config/config_helper/config_datafabric.md +++ b/pages/config/config_helper/config_datafabric.md @@ -45,4 +45,4 @@ SENSOR_ID="YOUR_ID" $ vi .env ``` -Finally, [Run The Configuration Helper]({{site.baseurl}}/config/config_helper/#run-the-configuration-helper) and restart the project containers. \ No newline at end of file +Finally, [Run The Configuration Helper]({{ site.url }}{{ site.baseurl }}config/config_helper#run-the-configuration-helper) and restart the project containers. \ No newline at end of file diff --git a/pages/config/config_helper/config_defaults.md b/pages/config/config_helper/config_defaults.md index eca436c..2027adf 100644 --- a/pages/config/config_helper/config_defaults.md +++ b/pages/config/config_helper/config_defaults.md @@ -15,14 +15,14 @@ The file [/config/ast_defaults.yaml](https://github.com/f5devcentral/application contains global configuration settings that can be used to reduce the amount of boilerplate configuration required for each BigIP device to be monitored. -Settings for each device are configured as described in [Configuration > Configuration Helper (Recommended) > Device Configuration]({{site.baseurl}}/config/config_helper/config_receivers.html) +Settings for each device are configured as described in [Configuration > Configuration Helper (Recommended) > Device Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_receivers.html) {: .important } The config helper script must run after any changes to the default or device specific configs, and the Otel container restarted before changes will take effect. The config file appears as follows. Syntax for the bigip_receiver_defaults settings follow the spec laid -out in the [BigIP Receiver Readme]({{site.baseurl}}/components/otel_collector/receiver_readme.html) file. +out in the [BigIP Receiver Readme]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_readme.html) file. Details for each section are provided below. diff --git a/pages/config/config_helper/config_helper.md b/pages/config/config_helper/config_helper.md index b428528..670855b 100644 --- a/pages/config/config_helper/config_helper.md +++ b/pages/config/config_helper/config_helper.md @@ -10,7 +10,7 @@ permalink: /config/config_helper # Managing AST Collector Configs With Config Helper This configuration section applies to the AST Opentelemetry Collector. For Grafana, Prometheus or other -components, see the corresponding documentation in [> Components]({{site.baseurl}}/components/) +components, see the corresponding documentation in [> Components]({{ site.url }}{{ site.baseurl }}components) ## Background AST includes a helper python script that can be used to streamline the management of the Opentelemetry @@ -28,12 +28,12 @@ and the otel container restarted before changes will take effect. The default settings file reduces the amount of boilerplate that must be configured for each BigIP device to be monitored. -* [Configuration > Configuration Helper (Recommended) > Default Configuration]({{site.baseurl}}/config/config_helper/config_defaults.html) +* [Configuration > Configuration Helper (Recommended) > Default Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_defaults.html) Settings without a logical default (e.g. url of the bigIP device) or wishing to override the default can be set as described in: -* [Configuration > Configuration Helper (Recommended) > Device Configuration]({{site.baseurl}}/config/config_helper/config_receivers.html) +* [Configuration > Configuration Helper (Recommended) > Device Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_receivers.html) ## Run The Configuration Helper The config helper script can be run via docker (or natively if the system has python installed) diff --git a/pages/config/config_helper/config_receivers.md b/pages/config/config_helper/config_receivers.md index a00fbe7..b969604 100644 --- a/pages/config/config_helper/config_receivers.md +++ b/pages/config/config_helper/config_receivers.md @@ -17,7 +17,7 @@ The config helper script must run after any changes to the default or device spe and the otel container restarted before changes will take effect. The settings in this file are merged with the defaults outlined -in [Configuration > Configuration Helper (Recommended) > Default Configuration]({{site.baseurl}}/config/config_helper/config_defaults.html), with the more specific settings in this file taking precedence. +in [Configuration > Configuration Helper (Recommended) > Default Configuration]({{ site.url }}{{ site.baseurl }}config/config_helper/config_defaults.html), with the more specific settings in this file taking precedence. The following constraints apply: * There must be a top level entry for each BigIP Device you wish to monitor. diff --git a/pages/datafabric/configuration.md b/pages/datafabric/configuration.md index 10e0b82..009862d 100644 --- a/pages/datafabric/configuration.md +++ b/pages/datafabric/configuration.md @@ -5,4 +5,4 @@ parent: F5 Datafabric nav_order: 1 --- -See [>Configuration > Configuration Helper (Recommended) > Configure Export To F5 Datafabric]({{site.baseurl}}/config/config_helper/config_datafabric.html) \ No newline at end of file +See [>Configuration > Configuration Helper (Recommended) > Configure Export To F5 Datafabric]({{ site.url }}{{ site.baseurl }}config/config_helper/config_datafabric.html) \ No newline at end of file diff --git a/pages/getting_started.md b/pages/getting_started.md index 17e40a1..896c6ed 100644 --- a/pages/getting_started.md +++ b/pages/getting_started.md @@ -11,7 +11,7 @@ nav_order: 2 ## Background This instructions in this file will get a new installation up and running in as little as a few minutes. For more detailed information on AST config management options, see the -[Configuration Management Overview]({{site.baseurl}}/config/) and related sections. +[Configuration Management Overview]({{ site.url }}{{ site.baseurl }}config) and related sections. ### Prerequisites @@ -131,7 +131,7 @@ BIGIP_PASSWORD_2=bar-foo123! ``` The variable name (the part on the left of the equal sign) must match the configured -value for the devices that use this password in config/ast_defaults.yaml or device specifc +value for the devices that use this password in config/ast_defaults.yaml or device specific cofig in config/bigip_receivers.yaml. In the following example, bigip/1 uses BIGIP_PASSWORD_1 from the defaults and bigip/2 uses BIGIP_PASSWORD_2 from the device settings: @@ -173,7 +173,7 @@ docker run --rm -it -w /app -v ${PWD}:/app --entrypoint /app/src/bin/init_entryp This will write 2 new files in the services/otel_collector directory: * `receivers.yaml` - The final list of scraper configs and their settings. -* `pipelines.yaml` - The final pipeline configs that map receievers to output destinations +* `pipelines.yaml` - The final pipeline configs that map receivers to output destinations (prometheus). ### Configure CA File @@ -229,3 +229,18 @@ docker compose up #### View The Dashboards The default Grafana user/pass is `admin/admin`, and can be accessed at `http://:3000`. + + +## Updating AST Versions +Updating to a new release of the AST repo can be done with the following general process: + +1. Review the release notes for all intermediate versions and check for warnings about +special instructions / breaking changes. +2. Backup your ast_defaults.yaml and bigip_receivers.yaml files. +3. Stash changes, update the repo state, and unstash changes as follows: +```shell +git stash +git pull origin main +git checkout tags/RELEASE_VERSION #(e.g. tags/v0.7.0) +git stash pop +``` diff --git a/pages/index.md b/pages/index.md index 3b3056e..7c97f67 100644 --- a/pages/index.md +++ b/pages/index.md @@ -9,7 +9,7 @@ nav_order: 1 The Application Study Tool is intended to provide enhanced insights into (classic) BIG-IP products, leveraging best in class open source telemetry tools. The full installation includes: -* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Receiver Metrics Info]({{site.baseurl}}/components/otel_collector/receiver_metrics.html). +* Custom Instance of OpenTelemetry Collector with enhanced BIG-IP data receivers (data fetched via iControlRest) [Receiver Metrics Info]({{ site.url }}{{ site.baseurl }}components/otel_collector/receiver_metrics.html). * Prometheus timeseries database for storing and querying collected data. * Grafana Instance with pre-configured dashboards for quick insights at the device and "fleet" levels. diff --git a/pages/troubleshooting/troubleshooting.md b/pages/troubleshooting/troubleshooting.md index 5ba77b6..b0f3161 100644 --- a/pages/troubleshooting/troubleshooting.md +++ b/pages/troubleshooting/troubleshooting.md @@ -138,4 +138,4 @@ the 'BigIP Collector Stats' dashboard at the top level of the Dashboards section ## GTM and DNS Metrics Not Loading Metrics for DNS and GTM are disabled by default. See -[Configuration > Configuration Helper (Recommended) > Configure DNS & GTM]({{site.baseurl}}/config/config_helper/config_dns_gtm.html) for instructions to enable. \ No newline at end of file +[Configuration > Configuration Helper (Recommended) > Configure DNS & GTM]({{ site.url }}{{ site.baseurl }}config/config_helper/config_dns_gtm.html) for instructions to enable. \ No newline at end of file From 0996e8968f7f5e164135f084300afbbb4c4e379d Mon Sep 17 00:00:00 2001 From: Chris Hain Date: Tue, 22 Oct 2024 10:21:20 -0700 Subject: [PATCH 2/2] fix broken link --- pages/config/config_migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/config/config_migration.md b/pages/config/config_migration.md index f979d4a..9236591 100644 --- a/pages/config/config_migration.md +++ b/pages/config/config_migration.md @@ -22,7 +22,7 @@ where users were unable to view and modify the files to tune parameters for thei In the new process, the raw otel configs are exposed in the /services/otel_collector directory where they can be managed manually, or through continued use of a refactored config_helper script. -For additional detail on configuration management options in the post v0.6.0 scheme, please see [Config Management](https://github.com/f5devcentral/application-study-tool/blob/main/config_management.md) +For additional detail on configuration management options in the post v0.6.0 scheme, please see [Config Management]({{ site.url }}{{ site.baseurl }}config) ## Migrating From pre v0.6.0 Configs There's a python script in /src/config_helper.py which will convert the original big-ips.json schema