Jwiki - User contributions [en]

Connecting to a Kubernetes Pod for JMX Debugging

2026-01-05T10:33:26Z

Gyurci08:

= Connecting to a Kubernetes Pod for JMX Debugging (Rancher Environment) =

This guide provides a comprehensive walkthrough for developers to configure access to a Rancher-managed Kubernetes cluster for the first time and connect to a Java application for JMX monitoring.

The process involves three main stages:
# Installing the Kubernetes command-line tool, '''kubectl'''.
# Setting up cluster access using a '''kubeconfig''' file from Rancher.
# Forwarding a local port to the pod to establish a secure JMX connection.

== 1. Prerequisite: Install kubectl ==

'''kubectl''' is the command-line tool for interacting with the Kubernetes API. Before proceeding, you must install it on your local machine.

=== Windows ===
Open a PowerShell terminal '''as an Administrator''' and run one of the following commands.
<syntaxhighlight lang="powershell">
# Using Chocolatey package manager
choco install kubernetes-cli
</syntaxhighlight>
''Or, using Scoop package manager:''
<syntaxhighlight lang="powershell">
scoop install kubectl
</syntaxhighlight>

=== macOS ===
On macOS, use the Homebrew package manager.
<syntaxhighlight lang="bash">
brew install kubectl
</syntaxhighlight>

=== Linux (Debian/Ubuntu) ===
On Debian-based systems, use the native <code>apt</code> package manager.
<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y kubectl
</syntaxhighlight>

After installation, verify that '''kubectl''' is available in your path by running:
<syntaxhighlight lang="bash">
kubectl version --client
</syntaxhighlight>

== 2. Configure Cluster Access ==

Since this is your first time connecting, you will set up your local configuration from scratch. The kubeconfig file you get from Rancher is specifically configured for your user and its permissions.

=== Create the .kube Directory ===
'''kubectl''' expects its configuration to be in a hidden directory in your user's home folder.
''On Linux or macOS:''
<syntaxhighlight lang="bash">
mkdir -p ~/.kube
</syntaxhighlight>
''On Windows (in PowerShell or Command Prompt):''
<syntaxhighlight lang="powershell">
mkdir %USERPROFILE%\.kube
</syntaxhighlight>

=== Place the Kubeconfig File ===
You will receive a kubeconfig file from your DevOps team or download it directly from the Rancher UI. Rename this file to <code>config</code> and move it into the <code>.kube</code> directory.
''On Linux or macOS:''
<syntaxhighlight lang="bash">
mv /path/to/your/rancher-kubeconfig.yaml ~/.kube/config
</syntaxhighlight>
''On Windows (in PowerShell or Command Prompt):''
<syntaxhighlight lang="powershell">
move C:\path\to\your\rancher-kubeconfig.yaml %USERPROFILE%\.kube\config
</syntaxhighlight>
This will now be the default configuration file that '''kubectl''' uses for all commands.

=== Verify Cluster Access ===
Test that your configuration is working correctly. Your access is restricted to a specific project, so some cluster-wide commands will fail—this is expected.
<syntaxhighlight lang="bash">
# List all available cluster contexts (there should be only one)
kubectl config get-contexts
</syntaxhighlight>
<syntaxhighlight lang="bash">
# This command will likely FAIL. This is NORMAL.
# It fails because your role is scoped to a project, not the whole cluster.
kubectl get pods
</syntaxhighlight>
The <code>get pods</code> command fails because it tries to list pods in the <code>default</code> namespace, which you may not have access to. Your permissions are tied to the namespaces within your assigned project.

'''To properly test your connection''', you must specify the namespace you have access to.
<syntaxhighlight lang="bash">
# Replace <your-project-namespace> with the actual namespace name provided to you.
kubectl get pods -n <your-project-namespace>
</syntaxhighlight>
If this command returns a list of pods (or an empty list with no errors), your access is configured correctly.

== 3. Forward a Port for JMX Connection ==

With cluster access established, you can now create a secure tunnel from your local machine to the JMX port of the Java application running inside a pod.

=== Set Your Default Namespace (Optional but Recommended) ===
To avoid typing <code>-n <your-project-namespace></code> for every command, you can set it as your default for the current session.
<syntaxhighlight lang="bash">
kubectl config set-context --current --namespace=<your-project-namespace>
</syntaxhighlight>
Now, all subsequent <code>kubectl</code> commands in this terminal will automatically target your project's namespace.

=== Find the Target Pod Name ===
First, identify the exact name of the pod you want to connect to.
<syntaxhighlight lang="bash">
# If you set your default namespace, you can run this:
kubectl get pods
</syntaxhighlight>
''If you did not set a default, you must specify the namespace:''
<syntaxhighlight lang="bash">
kubectl get pods -n <your-project-namespace>
</syntaxhighlight>
Copy the full name of the pod from the output (e.g., <code>your-java-app-pod-name-xyz</code>).

=== Start the Port Forwarding Session ===
Use the <code>kubectl port-forward</code> command to create the tunnel. This command maps a port on your local machine to the JMX port on the pod (assuming the JMX service in the pod is configured to run on port '''9010''').
<syntaxhighlight lang="bash">
# The "-n <namespace>" is not needed if you set your default context
kubectl port-forward your-java-app-pod-name-xyz 9010:9010
</syntaxhighlight>
'''Note:''' This command will block your terminal and must be left running for the entire duration of your JMX session. The output will confirm the connection is active.

=== Connect with a JMX Client ===
While the port-forward is running, open your preferred JMX client (such as '''JConsole''' or '''VisualVM''').

# Select the option to connect to a remote process.
# For the connection address or service URL, enter: <code>localhost:9010</code>
# Do not specify a username or password unless the JMX service itself is configured to require them.

You should now be connected to the application's JVM, with access to its live performance metrics.

[[Category:Kubernetes]]

Set CPU Power Management on Linux

2025-11-22T21:04:40Z

Gyurci08:

[[Category:General Linux]]
[[Category:Proxmox VE]]
[[Category:Guides & Tutorials]]

== Prerequisites ==

Install `cpupower` if missing:

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y linux-cpupower
</syntaxhighlight>

Verify CPU frequency scaling support:

<syntaxhighlight lang="bash">
ls /sys/devices/system/cpu/cpufreq/policy0/energy_performance_preference
</syntaxhighlight>

== Installation ==

Create `/etc/systemd/system/cpu-thermal-control.service`:

<syntaxhighlight lang="ini">
[Unit]
Description=Apply powersave governor, balance_power EPP, and frequency limits
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/bin/sh -c 'cpupower frequency-set -g powersave && echo balance_power > /sys/devices/system/cpu/cpufreq/policy0/energy_performance_preference && cpupower frequency-set -u 4GHz'
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Enable and start the service:

<syntaxhighlight lang="bash">
sudo systemctl daemon-reload
sudo systemctl enable --now cpu-thermal-control.service
</syntaxhighlight>

== Usage & Power Save Mode ==

- The service sets CPU governor to powersave, EPP to balance_power, and caps max frequency.
- To enable more aggressive power saving, modify `ExecStart` to use:

<syntaxhighlight lang="ini">
ExecStart=/bin/sh -c 'cpupower frequency-set -g powersave && echo powersave > /sys/devices/system/cpu/cpufreq/policy0/energy_performance_preference && cpupower frequency-set -d 800MHz -u 2GHz'
</syntaxhighlight>

- Reload and restart service after changes:

<syntaxhighlight lang="bash">
sudo systemctl daemon-reload
sudo systemctl restart cpu-thermal-control.service
</syntaxhighlight>

- Check CPU frequency info:

<syntaxhighlight lang="bash">
cpupower frequency-info
</syntaxhighlight>

== For Proxmox Users ==

Proxmox defaults to performance mode causing higher CPU temps. This service:

- Switches to powersave governor,
- Applies balance_power or powersave EPP,
- Caps CPU frequency for cooler, quieter operation.

Ensure kernel supports CPU scaling and adjust frequency caps as needed for your hardware.

Start this service on Proxmox nodes to improve thermal management and power efficiency.

== Troubleshooting ==

Check service logs for errors:

<syntaxhighlight lang="bash">
journalctl -u cpu-thermal-control.service
</syntaxhighlight>

Verify permissions and CPU frequency scaling support.

== Sources ==

* [Linux cpupower Documentation](https://www.kernel.org/doc/html/latest/admin-guide/pm/cpufreq.html)
* [systemd Service Files](https://www.freedesktop.org/software/systemd/man/systemd.service.html)
* [EPP Documentation](https://www.kernel.org/doc/html/latest/admin-guide/pm/energy_perf_bias.html)

Set CPU Power Management on Linux

2025-11-22T20:56:58Z

2025-09-02T20:19:22Z

Gyurci08:

== Solving VPN-Related Network Timeouts on OpenWrt ==
This guide documents the diagnosis and resolution of a common network issue: intermittent connection timeouts for specific services when traffic is routed through a VPN tunnel (e.g., WireGuard, ZeroTier) on an OpenWrt router. The root cause is a Path MTU Discovery (PMTUD) black hole, and the solution is to enable TCP MSS Clamping in the firewall.

=== 1. The Problem: Connection Timeouts and Stalls ===
The primary symptom is that certain TCP connections hang and eventually time out, while others work perfectly.

* '''Failing Services:''' Connections to complex websites or APIs that require a larger packet size for their TLS handshake.
* '''Working Services:''' Connections to simple websites that transfer very little data (e.g., `ifconfig.me`) and standard ICMP (ping) requests.

This issue arises because VPN encapsulation adds overhead to packets. If a router on the internet path has a smaller MTU (Maximum Transmission Unit) than the encapsulated packet, and it is misconfigured to silently drop oversized packets instead of sending a proper ICMP "Fragmentation Needed" message, a PMTUD black hole is created. The connection stalls because the client's server never learns that it needs to send smaller packets.

=== 2. The Diagnostic Process ===
A systematic approach using standard network tools can definitively identify a PMTUD black hole.

==== Step 1: Confirm the Scope ====
The issue was reproduced by running `curl` from a client whose traffic was routed through the VPN tunnel. Simple, low-data sites worked, while complex, high-data sites failed. This is a classic indicator of an MTU-related problem.

==== Step 2: Packet Capture with `tcpdump` ====
The definitive proof came from capturing the raw packet flow with `tcpdump` on the router. The capture showed a consistent pattern for failing connections:
# '''Successful Handshake:''' The initial TCP three-way handshake (`SYN`, `SYN/ACK`, `ACK`) completed successfully.
# '''TLS Negotiation Stall:''' The connection stalled immediately after the handshake when larger packets (like a TLS certificate) were expected.
# '''Selective Acknowledgment (SACK):''' The client's kernel sent `SACK` packets. This was the "smoking gun," as it proved the client was receiving ''some'' data but was acknowledging that other segments were missing.
# '''Timeout:''' The connection eventually hung and was closed by the client.

=== 3. The Solution: Enable TCP MSS Clamping in OpenWrt ===
While manually setting the MTU on the VPN interface (e.g., to `1420` for WireGuard) is a necessary first step, it does not always solve the problem if the internet path has a non-standard MTU. The most robust solution is to enable TCP MSS Clamping. This instructs the router to automatically resize TCP segments to prevent fragmentation.

On OpenWrt, this is accomplished easily through the LuCI web interface or by editing `/etc/config/firewall`. The key is to add the `mtu_fix` option to the firewall zone handling VPN traffic.

==== Corrected Firewall Zone Configuration ====
<syntaxhighlight lang="bash">
# In /etc/config/firewall

config zone
option name 'vpn_zone' #<-- Your VPN zone name
# ... other options ...
list network 'your_vpn_interface' #<-- e.g., 'wg_jgy_internal'
option mtu_fix '1' # <-- This line is the fix
</syntaxhighlight>
This setting is a best practice and should be enabled for '''all VPN-related firewall zones''' to ensure reliable network connectivity across any internet path.

[[Category:Networking]]
[[Category:OpenWRT]]
[[Category:VPN]]
[[Category:Troubleshooting]]

Solving VPN-Related Network Timeouts on OpenWrt

2025-09-02T20:17:43Z

Gyurci08: Created page with "== Solving VPN-Related Network Timeouts on OpenWrt == This guide documents the diagnosis and resolution of a common network issue: intermittent connection timeouts for specific services when traffic is routed through a VPN tunnel (e.g., WireGuard, ZeroTier) on an OpenWrt router. The root cause is a Path MTU Discovery (PMTUD) black hole, and the solution is to enable TCP MSS Clamping in the firewall. === 1. The Problem: Connection Timeouts and Stalls === The primary symp..."

Monitor Proxmox with Prometheus Exporter on Kubernetes

2025-08-29T17:26:05Z

Gyurci08: Gyurci08 moved page Monitor Proxmox with Prometheus Exporter on Kubernetes to Monitoring PVE 8 via Prometheus on Kubernetes

#REDIRECT [[Monitoring PVE 8 via Prometheus on Kubernetes]]

Monitoring PVE 8 via Prometheus on Kubernetes

2025-08-29T17:26:03Z

Gyurci08: Gyurci08 moved page Monitor Proxmox with Prometheus Exporter on Kubernetes to Monitoring PVE 8 via Prometheus on Kubernetes

== Monitor Proxmox with Prometheus Exporter (PVE 8) ==
This guide outlines a robust and secure method for deploying the `prometheus-pve-exporter` to a Kubernetes cluster. This architecture uses a single exporter instance that is dynamically configured at startup to use unique, per-host API tokens. This provides the operational simplicity of a single deployment with the enhanced security of per-host credentials.

=== 1. Create a Unique Read-Only API Token on Each Proxmox Host ===
This setup must be performed on '''each''' Proxmox host you wish to monitor (e.g., `pve-node-1`, `pve-node-2`). We will use a consistent user and token name across all hosts for simplicity.

Connect to each Proxmox host via SSH and run the following commands.

<syntaxhighlight lang="bash">
# On your FIRST Proxmox host (e.g., 'pve-node-1'), create the user and first token:
pveum useradd pve-exporter@pve
pveum aclmod / -user pve-exporter@pve -role PVEAuditor
pveum user token add pve-exporter@pve exporter-token
pveum aclmod / -token 'pve-exporter@pve!exporter-token' -role PVEAuditor

# On ALL SUBSEQUENT hosts (e.g., 'pve-node-2'), the user is synced by the cluster.
# You only need to create a new token with the same name.
pveum user token add pve-exporter@pve exporter-token
pveum aclmod / -token 'pve-exporter@pve!exporter-token' -role PVEAuditor
</syntaxhighlight>

'''Important:''' The `pveum user token add` command will generate a '''unique secret value''' on each host. You must copy the secret value for '''each''' host immediately, as you will not be able to see it again.

==== (Optional) Cleanup Script ====
If you need to re-run the setup on a host, first delete the old token.
<syntaxhighlight lang="bash">
pveum aclmod / -delete 1 -token 'pve-exporter@pve!exporter-token'
pveum user token remove pve-exporter@pve exporter-token
# Only run userdel after removing all tokens for that user from all hosts.
# pveum userdel pve-exporter@pve
</syntaxhighlight>

=== 2. Create the Kubernetes Manifests ===
On your local machine, create a single YAML file (e.g., `pve-exporter-full.yaml`). This file contains all the necessary Kubernetes resources.

'''Important:''' Before saving, populate the `Secret` with the unique token values you generated on each host. The keys in the secret (`pve-node-1-token`, `pve-node-2-token`) must match the environment variable names used in the `initContainer`.

<syntaxhighlight lang="yaml">
apiVersion: v1
kind: Secret
metadata:
name: pve-exporter-secrets
namespace: monitoring
type: Opaque
stringData:
# Populate with the UNIQUE secret values generated on each Proxmox host
pve-node-1-token: "UNIQUE_SECRET_VALUE_FOR_PVE_NODE_1"
pve-node-2-token: "UNIQUE_SECRET_VALUE_FOR_PVE_NODE_2"
---
apiVersion: v1
kind: ConfigMap
metadata:
name: pve-exporter-config-template
namespace: monitoring
data:
pve.yml: |
# --- Module for pve-node-1 ---
pve-node-1:
user: pve-exporter@pve
token_name: exporter-token
token_value: "${PVE_NODE_1_TOKEN}"
verify_ssl: false
# --- Module for pve-node-2 ---
pve-node-2:
user: pve-exporter@pve
token_name: exporter-token
token_value: "${PVE_NODE_2_TOKEN}"
verify_ssl: false
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: pve-exporter
namespace: monitoring
labels:
app: pve-exporter
spec:
replicas: 1
selector:
matchLabels:
app: pve-exporter
template:
metadata:
labels:
app: pve-exporter
spec:
volumes:
- name: config-template-volume
configMap:
name: pve-exporter-config-template
- name: processed-config-volume
emptyDir: {}
- name: tmp
emptyDir: {}
initContainers:
- name: init-config-secrets
image: busybox:1.36
command: ['/bin/sh', '-c']
args:
- |
sed -e "s|\${PVE_NODE_1_TOKEN}|${PVE_NODE_1_TOKEN}|g" \
-e "s|\${PVE_NODE_2_TOKEN}|${PVE_NODE_2_TOKEN}|g" \
/etc/config-template/pve.yml > /etc/processed-config/pve.yml
env:
- name: PVE_NODE_1_TOKEN
valueFrom:
secretKeyRef:
name: pve-exporter-secrets
key: pve-node-1-token
- name: PVE_NODE_2_TOKEN
valueFrom:
secretKeyRef:
name: pve-exporter-secrets
key: pve-node-2-token
volumeMounts:
- name: config-template-volume
mountPath: /etc/config-template
readOnly: true
- name: processed-config-volume
mountPath: /etc/processed-config
containers:
- name: pve-exporter
image: prompve/prometheus-pve-exporter:3.5.5
args:
- "--config.file=/etc/prometheus/pve.yml"
- "--web.listen-address=:9106"
ports:
- name: http-metrics
containerPort: 9106
protocol: TCP
livenessProbe:
httpGet:
path: /
port: http-metrics
initialDelaySeconds: 10
periodSeconds: 15
readinessProbe:
httpGet:
path: /
port: http-metrics
initialDelaySeconds: 5
periodSeconds: 5
securityContext:
runAsNonRoot: true
runAsUser: 1000
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
volumeMounts:
- name: processed-config-volume
mountPath: /etc/prometheus
readOnly: true
- name: tmp
mountPath: /tmp
resources:
requests:
cpu: '0'
memory: 128Mi
limits:
cpu: '0'
memory: 256Mi
---
apiVersion: v1
kind: Service
metadata:
name: pve-exporter
namespace: monitoring
labels:
app: pve-exporter
spec:
selector:
app: pve-exporter
ports:
- name: http-metrics
port: 9106
targetPort: http-metrics
</syntaxhighlight>

=== 3. Create the Prometheus Scrape Configuration ===
Create a final YAML file for the `ScrapeConfig`. This tells Prometheus how to scrape the single exporter for all your Proxmox hosts, dynamically setting the `target` and `module` parameters for each one.
<syntaxhighlight lang="yaml">
apiVersion: monitoring.coreos.com/v1alpha1
kind: ScrapeConfig
metadata:
name: pve-nodes
namespace: monitoring
labels:
# This label must match your Prometheus Operator's discovery selector
prometheus: my-prometheus
spec:
staticConfigs:
- targets:
- pve-node-1.your-domain.com
- pve-node-2.your-domain.com
# Add other hosts here
metricsPath: /pve
relabelings:
# Rule 1: Take the target address and use it as the 'target' URL parameter.
- sourceLabels: [__address__]
targetLabel: __param_target

# Rule 2: Extract the hostname (e.g., "pve-node-1") and use it as the 'module' URL parameter.
- sourceLabels: [__address__]
regex: '([^.]+)\..*' # Captures the part before the first dot
targetLabel: __param_module

# Rule 3: Set the 'instance' label to the Proxmox host's address.
- sourceLabels: [__param_target]
targetLabel: instance

# Rule 4: Rewrite the scrape address to point to our single exporter service.
- targetLabel: __address__
replacement: pve-exporter.monitoring.svc:9106
</syntaxhighlight>

=== 4. Apply and Verify ===
Apply the two Kubernetes manifests to your cluster.
<syntaxhighlight lang="bash">
kubectl apply -f pve-exporter-full.yaml
kubectl apply -f pve-scrape-config.yaml
</syntaxhighlight>

Check that the pod is running and that Prometheus is successfully scraping the targets.
<syntaxhighlight lang="bash">
# Check pod status
kubectl get pods -n monitoring -l app=pve-exporter
</syntaxhighlight>

After a minute, navigate to your Prometheus UI, go to '''Status -> Targets''', and verify that a target for each of your Proxmox hosts is present and has a state of '''UP'''.

[[Category:Proxmox VE]]
[[Category:Kubernetes]]
[[Category:Prometheus]]

2025-08-29T11:08:31Z

Gyurci08:

Create macOS gitlab-runner

2025-08-29T11:07:56Z

Gyurci08: Gyurci08 moved page Create macOS gitlab-runner to Create MacOS gitlab-runner

#REDIRECT [[Create MacOS gitlab-runner]]

Create MacOS gitlab-runner

2025-08-29T11:07:53Z

Gyurci08: Gyurci08 moved page Create macOS gitlab-runner to Create MacOS gitlab-runner

[[Category:MacOS]]
[[Category:GitLab]]
== Installing GitLab Runner with `brew services` (Simplified Method) ==
This guide details a simplified method for installing and configuring a GitLab Runner on macOS by using Homebrew's built-in service management. This is often easier than manually managing `launchd` files.

=== 1. Install GitLab Runner ===
First, install the GitLab Runner package using Homebrew:
<syntaxhighlight lang="bash">
brew install gitlab-runner
</syntaxhighlight>

=== 2. Note on Paths (Apple Silicon vs. Intel) ===
Installation paths depending on your Mac's architecture. The shell environment setup in a later step will handle this automatically by using `brew shellenv`, but it's good to be aware of the difference:

* '''Apple Silicon (M1/M2/M3):''' `/opt/`
* '''Intel:''' `/usr/local/`

=== 3. Create and Switch to the Runner User ===
For security and isolation, it is best practice to run the GitLab Runner under a dedicated user account. If you haven't created one, you can do so in '''System Settings > Users & Groups'''.

Once the user (e.g., `runner`) exists, '''switch to it for all subsequent steps''':
<syntaxhighlight lang="bash">
su runner
</syntaxhighlight>

=== 4. Configure the GitLab Runner ===
As the `runner` user, configure the runner's behavior by editing its `config.toml` file.
<syntaxhighlight lang="bash">
nano ~/.gitlab-runner/config.toml
</syntaxhighlight>

Add the following configuration. '''Note:''' GitLab Runner does not support Zsh as a shell for its jobs, so you must explicitly set the shell to `bash`.
<syntaxhighlight lang="toml">
concurrent = 3
check_interval = 30
[session_server]
session_timeout = 1800
[[runners]]
name = "Mac-mini-runner"
limit = 1
url = "https://gitlab.com/"
token = "masked"
executor = "shell"
shell="bash"
[runners.custom_build_dir]
[runners.cache]
[runners.cache.s3]
[runners.cache.gcs]
[runners.cache.azure]
</syntaxhighlight>

=== 5. Set Up the Shell Environment ===
This is the most critical step. For the runner's jobs to find tools and execute correctly, the `runner` user's shell environment must be configured properly.

==== Create and configure `.bashrc` ====
<syntaxhighlight lang="bash">
nano ~/.bashrc
</syntaxhighlight>

Add the necessary environment variables and path definitions.
<syntaxhighlight lang="bash">
### Brew ###
# This command sets up Homebrew's environment, including the correct PATH.
eval $(/opt/homebrew/bin/brew shellenv)

### Ruby ###
eval "$(rbenv init -)"

### Extra environments ###
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

# Android
export ANDROID_HOME="/Users/runner/Library/Android/sdk"

# Java
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

# Add any other required PATH exports here. The 'brew shellenv' command
# should handle the primary Homebrew paths for your architecture.
export PATH="/Users/runner/Library/Android/sdk/platform-tools:${PATH}"

# FASTLANE
export FASTLANE_SESSION=masked
export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="masked"
export FASTLANE_USER="mobil@example.com"
export FASTLANE_PASSWORD="masked"
export SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA=true
export SUPPLY_UPLOAD_MAX_RETRIES=5
</syntaxhighlight>

==== Create `.bash_profile` to source `.bashrc` ====
This ensures your `.bashrc` configuration is loaded for new shell sessions.
<syntaxhighlight lang="bash">
nano ~/.bash_profile
</syntaxhighlight>
Add the following lines:
<syntaxhighlight lang="bash">
#####
# USE "~/.bashrc" for configuration!
#####
### Import .bashrc ###
if [ -f ~/.bashrc ]; then
. ~/.bashrc
fi
</syntaxhighlight>

=== 6. Start and Manage the Runner with `brew services` ===
'''Crucial Point:''' You must run these commands as the `runner` user. This ensures the service runs under the correct user account.

To start the service and register it to run automatically at login:
<syntaxhighlight lang="bash">
brew services start gitlab-runner
</syntaxhighlight>

To stop the service:
<syntaxhighlight lang="bash">
brew services stop gitlab-runner
</syntaxhighlight>

To check the status of all your Homebrew services:
<syntaxhighlight lang="bash">
brew services list
</syntaxhighlight>

Category:GitLab

2025-08-29T11:06:03Z

Gyurci08: Created page with "Category:Automation & Tooling"

[[Category:Automation & Tooling]]

2025-08-29T10:45:43Z

Gyurci08:

[[Category:MacOS]]
[[Category:Prometheus]]
[[Category:Guides & Tutorials]]

= Monitoring a macOS Host with Prometheus Node Exporter =

This guide details the process of installing and configuring the Prometheus Node Exporter on a macOS machine, with a focus on filtering out irrelevant filesystems to ensure clean, actionable alerts. The primary challenge when monitoring macOS is handling the numerous OS-managed, virtual, and temporary filesystems that can trigger false positive alerts for high disk usage.

h2. Initial Setup and Problem Diagnosis
h3. Installation with Homebrew
The standard method for installing Node Exporter on macOS is via the [https://brew.sh/ Homebrew] package manager.

<syntaxhighlight lang="bash">
brew install node_exporter
</syntaxhighlight>

h3. The Problem: False Positive Alerts
After a default installation, Node Exporter will scrape metrics from all mounted filesystems. On macOS, this includes many volumes that are nearly full by design, leading to persistent, non-actionable alerts.

Common sources of these false positives include:
* '''Xcode Simulator Runtimes:''' Mounted under ''/Library/Developer/CoreSimulator/''.
* '''Virtual Filesystems:''' Such as ''/dev'' (devfs).
* '''Automounter Filesystems:''' Such as ''/System/Volumes/Data/home'' (autofs).
* '''Read-only System Snapshots:''' The main ''/'' volume is a sealed, read-only snapshot of the OS.

The goal is to filter these out and only monitor user-managed volumes where disk space is a real concern, primarily ''/System/Volumes/Data''.

h2. Configuration and Troubleshooting
The solution involves a two-part strategy: configuring Node Exporter to exclude noisy filesystems at the source, and writing a precise PromQL alert that only targets the user-managed data volume.

h3. Step 1: Configure Node Exporter Exclusions
Node Exporter can be configured to ignore specific mount points using a command-line flag. When installed with Homebrew, these flags should be placed in a dedicated arguments file.

# '''Create or Edit the Arguments File:''' This file is read by the `brew services` launch agent. It should contain one argument per line, '''without quotes'''.
<syntaxhighlight lang="bash">
nano /opt/homebrew/etc/node_exporter.args
</syntaxhighlight>

# '''Add the Exclusion Rule:''' To comprehensively filter out all known OS-managed, virtual, and temporary filesystems, add the following line to the file.
<syntaxhighlight lang="text">
--collector.filesystem.mount-points-exclude=^/(dev|private/var/folders|System/Volumes/(Preboot|Update|VM|Recovery|Hardware|xarts|iSCPreboot)|Library/Developer/CoreSimulator/.*)$
</syntaxhighlight>
This regular expression tells Node Exporter to ignore any filesystem whose mount point matches these patterns.

# '''Restart the Service:''' Apply the new configuration by restarting the Node Exporter service.
<syntaxhighlight lang="bash">
brew services restart node_exporter
</syntaxhighlight>

h3. Step 2: Validate the Configuration
After restarting, verify that the noisy filesystems are no longer being exported. The following command queries the metrics endpoint and greps for the excluded patterns.

<syntaxhighlight lang="bash">
curl -s http://localhost:9100/metrics | grep -E 'mountpoint="/(dev|private/var/folders|System/Volumes/(Preboot|Update|VM|Recovery)|Library/Developer/CoreSimulator/.*)"'
</syntaxhighlight>

'''A successful configuration will result in no output from this command.'''

h3. Step 3: Create a Precise PromQL Alert
With the metrics now clean, the final step is to create an alerting rule in Prometheus that is both simple and impossible to trigger with a false positive. Instead of excluding filesystems in the query, you should explicitly ''include'' only the volume you care about.

The most critical user-managed filesystem on macOS is ''/System/Volumes/Data''.

'''Recommended PromQL Alerting Rule:'''
This query calculates the percentage of used space for the '''Data''' volume and will fire only if it exceeds 90%.

<syntaxhighlight lang="promql">
100 - (node_filesystem_avail_bytes{mountpoint="/System/Volumes/Data"} / node_filesystem_size_bytes{mountpoint="/System/Volumes/Data"}) * 100 > 90
</syntaxhighlight>

By following this guide, you achieve a robust monitoring setup for macOS that provides clean data and generates alerts that are always actionable.