insights-client is a wrapper for Insights Core (the egg).
Follow these instructions to prepare your system for development.
-
Fork both this and the insights-core repository.
-
Clone both of them to the same directory:
$ git clone git@github.com:$YOU/insights-client.git $ git clone git@github.com:$YOU/insights-core.git
-
Make sure your virtual environment uses system site packages.
- For existing one, set
include-system-site-packages = truein virtual environment'spyvenv.cfg. - For new one, create it with
--system-site-packagesflag. - Make sure both repositories share the virtual environment.
- For existing one, set
-
Install the
insights-coreas a Python package.First, make sure the following directories and files exist, otherwise the code will scream at you:
$ sudo mkdir -p /etc/insights-client $ sudo ln -s `pwd`/data/etc/cert-api.access.redhat.com.pem /etc/insights-client/Then you can install the package using pip:
$ cd insights-client $ python3 -m pip install --upgrade pip wheel $ python3 -m pip install -e ../insights-core/.[client-develop] -
Run the client.
$ sudo PYTHONPATH=./src:../insights-core python3 src/insights_client/__init__.py --help
- Every relevant change should have a test, if possible.
- Every commit containing Python code should be formatted with
black. - Every commit/PR will be checked for those in CI.
- Read TESTING.md for more information.
Integration tests (via pytest-client-tools) read their configuration with dynaconf from settings.toml at the repository root. The file is not committed: when SETTINGS_URL is set (most likely in .testing-farm.yaml), systemtest/tests/integration/test.sh downloads a sanitized settings.toml from the provided URL, backing up any pre-existing local file as settings.toml.bak. Locally you can instead provide your own git-ignored settings.toml and/or .secrets.toml.
The served file carries non-secret values (hosts, ports, URLs, client IDs, orgs) directly. Secret values appear in it as @vault: sentinels: at config load, pytest-client-tools authenticates to the Vault instance named by VAULT_ADDR with the AppRole pair delivered as VAULT_ROLE_ID + VAULT_SECRET_ID (encrypted Testing Farm secrets, see .testing-farm.yaml) and reads each sentinel's value from Vault. test.sh also exports PYTEST_CLIENT_TOOLS_VAULT_REQUIRED=1 when it downloads the served file, so a sentinel that cannot be resolved fails loudly at config load instead of degrading into a misleading validation error.
PYTEST_CLIENT_TOOLS_* environment variables (or a local .secrets.toml) remain the override path — use them for local runs and for real environments the delivered credentials do not cover; they take precedence over any resolved value. The secret keys consumed by this repository's integration tests are:
| Environment variable | Settings key | Used by |
|---|---|---|
PYTEST_CLIENT_TOOLS_CANDLEPIN__PASSWORD |
candlepin.password |
register_subman fixture (non-Satellite registration) |
PYTEST_CLIENT_TOOLS_CANDLEPIN__ACTIVATION_KEYS |
candlepin.activation_keys |
register_subman fixture (Satellite registration) |
PYTEST_CLIENT_TOOLS_AUTH_PROXY__USERNAME |
auth_proxy.username |
test_register_auth_proxy, test_auth_proxy_connection |
PYTEST_CLIENT_TOOLS_AUTH_PROXY__PASSWORD |
auth_proxy.password |
test_register_auth_proxy, test_auth_proxy_connection |
Note: Satellite environments (ENV_FOR_DYNACONF=satellite617, satellite618, satellite619, satellite-capsule) also require PYTEST_CLIENT_TOOLS_CANDLEPIN__PASSWORD. The value is never used for registration there — activation keys do the work — but the served settings.toml has username = "" in every Satellite section and pytest-client-tools validates that candlepin.password exists whenever candlepin.username exists; without it the config fails to load and every satellite test errors. Any non-empty dummy value satisfies the validator, though the real account password is recommended.
Notes:
- Nested keys use
PYTEST_CLIENT_TOOLS_<SECTION>__<KEY>(each.becomes__, uppercased); flat keys usePYTEST_CLIENT_TOOLS_<KEY>. Values are parsed as TOML, so lists must be quoted:'["key1", "key2"]'. - Precedence is environment variables >
.secrets.toml>settings.toml> defaults; no file needs to exist. ENV_FOR_DYNACONFselects the environment (section) to use:default(default),stage,prod,satellite617,satellite618,satellite619,satellite-capsule,testing.ENV_FOR_DYNACONF=testing(the containerized candlepin) is for manual runs only — no CI job sets it. When it is set and no explicit credentials are supplied,test.shfalls back to the container's well-knownadmin/admincredentials.
Secrets are neither committed nor served in plain text: the file served at
SETTINGS_URL carries them only as @vault: sentinels, resolved at config
load as described above. The environment variables (or a git-ignored local
.secrets.toml) override the resolved values. If a local settings.toml of
yours contains real secrets, delete it — keep secrets out of that file
entirely.
insights-client product consists of two parts: insights-client (wrapper) and insights-core. Historically, the Core (also named the Egg) has been distributed through CDN, with an older, frozen version packaged within insights-client itself. Later, the Core delivery model was changed to be RPM as well.
Wrapper is the entry point providing CLI on $PATH, and ensures phases are run.
Egg is a bundle that contains the insights package with all the main functionality. All flags and configurations are passed to the egg by the wrapper.
insights-client runs in four phases.
- pre-update: Execute flags that exit immediately (
--version,--test-connection,--checkin). - update: Download new Core from CDN. This phase is not used anymore.
- post-update: Process flags (like registration options), and exit if the operation requires registration and the system is not registered.
- collect & upload: Run data collection, compress the results and upload them to ConsoleDot.
The configuration uses the values in the following hierarchy:
- CLI flags
/etc/insights-client/insights-client.conf- environment variables (in a form of
INSIGHTS_xxxxxx, wherexxxxxxis the configuration variable name, in all caps)
The client utilizes several directories on the system for its operation:
/etc/insights-client/- The primary directory for configuration. It containsinsights-client.conf, redaction files (file-redaction.yaml,file-content-redaction.yaml), and security certificates./var/log/insights-client/- The default directory for log files./var/lib/insights/- Stores information about the core module (egg), includinglast_stable.egg./var/cache/insights-client/- The default location where the archive is stored when the--keep-archive,--no-uploadand--offlineflags are used./var/tmp/- Used as a temporary location for building the archive before upload.
The client logs its activity to provide a record of its operations, which is essential for troubleshooting. All of the following switches were already explained in the Configuration section.
By default, all log output is sent to /var/log/insights-client/insights-client.log.
The level of detail in the logs can be controlled.
- The
--verboseflag increases the verbosity toDEBUGlevel for a single run. (More logs) - The
--quietflag decreases verbosity to only showERRORmessages.
When you run insights-client, it connects to several Red Hat services. Connectivity to these services is required for a standard, non-offline execution.
These are the primary services the client communicates with.
Purpose: To upload the collected system data archive, download updated insights-core, and retrieve analysis results. It can also optionally connect to services for Compliance and Malware detection.
Hostnames: The default hostname is cert-api.access.redhat.com. For newer infrastructure, cert.cloud.redhat.com is also used.
If the system is registered to RHSM, the insights-client may reconfigure itself to use Satellite hostname.
If registered to a Red Hat Satellite server: The client will automatically reconfigure itself. It uses the Satellite's hostname as the destination for data uploads.
If not registered to a Satellite server: The client operates in its default mode. It connects directly to the primary Red Hat Insights API, which is the standard behavior for systems registered with Red Hat.
This entire auto-detection process is based on reading local config files only (managed by RHSM).
examples of what you could see in logs if auto_config=True:
DEBUG insights.client.auto_config:159 Connected to staging RHSM, using cert.cloud.stage.redhat.com
DEBUG insights.client.auto_config:81 Not connected to Satellite, skipping branch_info