Inventory API

This repository implements a common inventory system.

Codecov test coverage
| main |
v1beta2 |
 |
 |
Table of Contents
Development Setup
Prerequisites
Debugging
See DEBUG for instructions on how to debug
Running locally
When running locally, the default settings file is used. By default, this configuration does the following:
- Exposes the inventory API in
localhost and using port 8000 for http and port 9000 for grpc.
- Sets authentication mechanism to
allow-unauthenticated, allowing users to be authenticated with their user-agent value.
- Sets authorization mechanism to
allow-all.
- Sets database implementation to Postgres (localhost:5435, database:
inventory, user: inventory_api)
- Sets the Inventory Consumer service to disabled
- Configures log level to
INFO.
NOTE: You can update the default settings file as required to test different scenarios. Refer to the command line help (make run-help) or leverage one of the many pre-defined Docker Compose Test Setups
for information on the different parameters.
Quick Start with Postgres
-
Clone the repository and navigate to the directory.
-
Install the required dependencies
make init
-
Build the project
make build
-
Setup and start the local Postgres database
make db/setup
-
Run migrations
make migrate
-
Start the development server
make run
Overriding commands in the Makefile
Due to various alternatives to running some images, we accept some arguments to override certain tools
GO binary
Since there are official instructions on how to manage multiple installs
We accept the GO parameter when running make. e.g.
GO=go1.25.7 make run
or
export GO=go1.25.7
make run
Podman / Docker
We will use podman if it is installed, and we will fall back to docker. You can also specify if you want to ensure a particular binary is used
by providing DOCKER parameter e.g.
DOCKER=docker make api
or
export DOCKER=docker
make api
[!IMPORTANT]
Note: The podman-compose provider struggles with compose files that leverage depends_on as it can't properly handle the dependency graphs. You can fix this issue on Linux by installing the docker-compose-plugin or also having docker-compose installed. When installed, podman uses the docker-compose provider by default instead. The benefit of the docker-compose-plugin is that it doesn't require the full Docker setup or Docker daemon!
Running Locally using Docker Compose
Testing locally is fine for simple changes but in order to test the full application, it requires all the dependent backing services.
The quickest way to run the full Kessel suite locally (Inventory API, SpiceDB, Inventory Consumer, Kafka, and Kafka Connect) is:
make kessel-up
This uses pre-built images so no other repos need to be cloned. The local full-Kessel configuration enables the Inventory consumer's load-reporter-representation setting (matching stage), so reporter-side relationship fields replicate to SpiceDB. To stop:
make kessel-down
For Inventory API only (without Consumer), use:
make inventory-up # start
make inventory-down # stop
Alternative ways of running this service
There are numerous ways to run Inventory API using Docker Compose for various testing and debugging needs. For more options, see our guide
The one-time common representations cleanup job is run separately from Compose.
See its runbook for
database configuration, CLI options, the OpenShift Job template, and required
writer fencing and replication drain checks.
The separate one-time reporter representations cleanup job
keeps the newest two existing versions per active reporter-resource. Execution
requires fenced resource writers and drained replication. It is not part of the
Compose startup targets.
Running in Ephemeral Cluster using Bonfire
See Testing Inventory in Ephemeral for instructions on how to deploy Kessel Inventory in the ephemeral cluster.
API/Proto files Changes
Once there is any change in the proto files (under /api/kessel) an update is required.
This command will generate code and an openapi file from the proto files.
make api
We can run the following command to update if there are expected breaking changes.
make api_breaking
Schema file changes
Once there are any changes in the schema files under /data/schema/resources an update is required.
The schemas are loaded in as a tarball in a configmap, to generate the tarball execute:
make build-schemas
The command will output the binaryData for resources.tar.gz.
binaryData:
resources.tar.gz: H4sIAEQ1L2gAA+2d3W7juBXHswWKoil62V4LaYG9mVEoUiTtAfbCmzg7xiRxNnZmd1ssDI2jJNqxpawkz05...
Copy this data to update the configmap resources-tarball in the ephemeral deployment file with the latest schema changes.
Build Container Images
Log in to the required registries, then run the docker-build-push target with your image destination. The base image is pulled from registry.access.redhat.com during the build, so both logins are required.
podman login quay.io # or: docker login quay.io
podman login registry.access.redhat.com # or: docker login registry.access.redhat.com
make docker-build-push IMAGE=quay.io/your-org/inventory-api
If the build fails with an authentication error mentioning registry.access.redhat.com, ensure you are logged in using your Red Hat Customer Portal credentials. See the Red Hat Registry Authentication guide for details.
podman is used automatically if available, otherwise docker is used. Override with DOCKER=docker make docker-build-push IMAGE=quay.io/your-org/inventory-api.
Example Usage
All these examples use the REST API and assume we are running the default local version
adjustments needs to be made to the curl requests if running with different configuration,
such as port, authentication mechanisms, etc.
Note: When testing in Stage, the current SpiceDB schema only supports notifications integrations and not any of the infra we have in our API (RHEL hosts, K8s Clusters, etc). Testing with any other resource type will throw errors from the relations subsystem but will still succeed in Inventory API.
Health check endpoints
The Kessel Inventory includes health check endpoints for readiness and liveness probes.
Readyz
The readyz endpoint checks if the service is ready to handle requests.
curl http://localhost:8000/api/kessel/v1/readyz
Livez
The livez endpoint checks if the service is alive and functioning correctly.
curl http://localhost:8000/api/kessel/v1/livez
Resource lifecycle
Resources can be added, updated and deleted to our inventory. Right now we support the following resources:
rhel-host
notifications-integration
k8s-cluster
k8s-policy
To add a rhel-host to the inventory:
To hit the REST endpoint use the following curl command
curl -X POST -H "Content-Type: application/json" --data "@data/testData/v1beta2/host.json" http://localhost:8000/api/kessel/v1beta2/resources
To hit the gRPC endpoint use the following grpcurl command
grpcurl -plaintext -d @ localhost:9000 kessel.inventory.v1beta2.KesselInventoryService.ReportResource < data/testData/v1beta2/host.json
To update it:
To hit the REST endpoint
curl -X POST -H "Content-Type: application/json" --data "@data/testData/v1beta2/host.json" http://localhost:8000/api/kessel/v1beta2/resources
To hit the gRPC endpoint
grpcurl -plaintext -d @ localhost:9000 kessel.inventory.v1beta2.KesselInventoryService.ReportResource < data/testData/v1beta2/host.json
and finally, to delete it, note that we use a different file, as the only required information is the reporter data.
To hit the REST endpoint
curl -XDELETE -H "Content-Type: application/json" --data "@data/testData/v1beta2/delete-host.json" http://localhost:8000/api/kessel/v1beta2/resources
To hit the gRPC endpoint
grpcurl -plaintext -d @ localhost:9000 kessel.inventory.v1beta2.KesselInventoryService.DeleteResource < data/testData/v1beta2/delete-host.json
To add a notifications integration (useful for testing in stage)
# create the integration (auth is required for stage -- see internal docs)
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -d @data/testData/v1beta2/notifications-integrations.json localhost:8000/api/kessel/v1beta2/resources
# delete the integration
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -d @data/testData/v1beta2/delete-notifications-integration.json localhost:8000/api/kessel/v1beta2/resources
Configuration
Enable integration with Kessel relations
The default development config has this option disabled. You can check Alternatives way of running this service
for configurations that have Kessel relations enabled.
Supposing Kessel relations is running in localhost:9000, you can enable it by updating the config as follows:
authz:
impl: kessel
kessel:
insecure-client: true
url: localhost:9000
enable-oidc-auth: false
If you want to enable OIDC authentication with SSO, you can use this instead:
authz:
impl: kessel
kessel:
insecure-client: true
url: localhost:9000
enable-oidc-auth: true
sa-client-id: "<service-id>"
sa-client-secret: "<secret>"
sso-token-endpoint: "http://localhost:8084/realms/redhat-external/protocol/openid-connect/token"
Testing
Tests can be run using:
# Short-mode tests, excluding E2E and Kafka test patterns; database-backed
# tests use PostgreSQL via Testcontainers (Docker or Podman required,
# detected automatically)
make test
# Same short-mode suite and exclusions, with database-backed tests on
# in-memory SQLite (no container runtime needed; PostgreSQL-specific tests
# are skipped and PostgreSQL behavior is not reproduced)
make test-sqlite
# Run resource lifecycle performance tests and print a summary (ensure Docker or Podman is running)
make test-performance
For end-to-test info see here.
Validating FIPS
Inventory API is configured to build with FIPS capable libraries and produce FIPS capaable binaries when running on FIPS enabled clusters.
To validate the current running container is FIPS capable:
# exec or rsh into running pod
# Reference the fips_enabled file that ubi9 creates for the host
cat /proc/sys/crypto/fips_enabled
# Expected output:
1
# Check go tool for the binary
go tool nm /usr/local/bin/inventory-api | grep FIPS
# Expected output should reference openssl FIPS settings
# Ensure openssl providers have a FIPS provider active
openssl list -providers | grep -A 3 fips
# Expected output
fips
name: Red Hat Enterprise Linux 9 - OpenSSL FIPS Provider
version: 3.0.7-395c1a240fbfffd8
status: active
For online cleanup of expired tombstoned reporters and their newly orphaned data,
see the tombstone cleanup runbook. The job is preview-only by default and is not started by Compose.