Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 137 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,139 @@
# Compose Tracking Service (CTS)

- Documentation
- [About CTS](./docs/about.rst)
- [API Doc](./docs/api.rst)
- [Development](./docs/dev.rst)
Compose Tracking Service stores metadata about Pungi composes, exposes a REST API,
and publishes change events to Kafka/UMB.

## Development

### Code style

Format with `black`, lint with `flake8`, and scan with `bandit`:

```bash
tox -e black,flake8,bandit
```

### Install and run locally

```bash
pip install -r requirements.txt
./create_sqlite_db
./start_cts_from_here
```

### Unit tests

```bash
tox -e py3
```

Unit tests bootstrap a full in-process Flask app via `tests/conftest.py` (no
`CTS_URL` required).

### Build documentation

```bash
tox -e docs
```

HTML output is in `docs/_build/html/`.

## Integration tests

Integration tests live in `tests/test_integration_api.py`. They call a **running**
CTS instance over HTTP and do not import the `cts` Python package (CI installs
only `pytest`, `requests`, and `kafka-python` in the test runner pod).

### Test environment

Local runs use [integration-tests/run-local.sh](integration-tests/run-local.sh),
which mirrors the Konflux EaaS pipeline on a **kind** cluster:

```mermaid
flowchart TB
subgraph cluster [kind cluster]
subgraph ns [ephemeral test namespace]
runner["cts-test-runner pod<br/>pytest + requests + kafka-python"]
subgraph ctsDeploy [CTS Deployment]
migrate["initContainer<br/>cts-manager db upgrade"]
cts["httpd / mod_wsgi :8080"]
migrate --> cts
end
pg[(PostgreSQL cts-db)]
ldap[OpenLDAP]
dex["Dex OIDC :5556 TLS"]
kafka[Kafka]
end
end

migrate --> pg
cts --> pg
cts --> kafka
cts --> dex
cts --> ldap
dex --> ldap
runner -->|"HTTP (CTS_URL)"| cts
runner -->|"OIDC tokens (DEX_URL)"| dex
runner -->|"Kafka assertions (KAFKA_URL)"| kafka
```

Manifests under [integration-tests/manifests/](integration-tests/manifests/)
define each service. Konflux CI uses the same layout in
[.tekton/integration-test-eaas.yaml](.tekton/integration-test-eaas.yaml).

### Run locally (recommended)

**Prerequisites:** `kind`, `kubectl`, `podman` or `docker`, `openssl`

```bash
./integration-tests/run-local.sh
```

Useful options:

```bash
./integration-tests/run-local.sh --skip-build # reuse existing images
./integration-tests/run-local.sh --keep-cluster # leave kind cluster running
./integration-tests/run-local.sh --no-tests # deploy only
CONTAINER_ENGINE=docker ./integration-tests/run-local.sh # force Docker instead of podman
```

With podman, images are loaded via `podman save` and `kind load image-archive`.
If image load still fails, try `CONTAINER_ENGINE=docker ./integration-tests/run-local.sh`.

### Run pytest manually

Against any reachable CTS (requires `pytest`, `requests`, and optionally
`kafka-python`):

```bash
CTS_URL=http://localhost:8080 \
pytest tests/test_integration_api.py -v -o addopts=
```

Full stack (auth + Kafka checks), matching CI:

```bash
REQUESTS_CA_BUNDLE=/path/to/dex-ca.crt \
CTS_URL=http://cts:8080 \
AUTH_BACKEND=oidc_or_kerberos \
DEX_URL=https://dex:5556 \
KAFKA_URL=kafka:9092 \
pytest tests/test_integration_api.py -v -s -o addopts=
```

When `CTS_URL` is set, `tests/conftest.py` skips local app bootstrap so pytest
does not need CTS Python dependencies.

### Environment variables

| Variable | Purpose |
|----------|---------|
| `CTS_URL` | Base URL of running CTS (**required**) |
| `AUTH_BACKEND` | `oidc_or_kerberos` or `openidc` for auth/workflow tests |
| `DEX_URL` | Dex base URL for OIDC token requests |
| `KAFKA_URL` | Enables Kafka message assertions |
| `REQUESTS_CA_BUNDLE` | Trust Dex self-signed CA |

See [docs/integration.rst](https://github.com/release-engineering/cts/blob/main/docs/integration.rst)
for CI pipeline details and manifest reference.
50 changes: 31 additions & 19 deletions docs/dev.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,37 +2,49 @@
Development
===========

Code Convention
Developer setup, unit testing, and integration testing are documented in the
`README on GitHub <https://github.com/release-engineering/cts/blob/main/README.md>`_.

Quick reference
===============

The code must be well formatted via ``black`` and pass ``flake8`` checking.
Code style
----------

Format with ``black``, lint with ``flake8``, and scan with ``bandit``::

tox -e black,flake8,bandit

Unit tests
----------

Run ``tox -e black,flake8`` to do the check.
Run the unit test suite with coverage::

Install dependencies
====================
tox -e py3

.. sourcecode:: none
Build documentation
-------------------

$ pip install -r requirements.txt
Build the Sphinx HTML docs locally::

Initialize database
===================
tox -e docs

.. sourcecode:: none
Output is written to ``docs/_build/html/``.

$ ./create_sqlite_db
Local CTS
---------

Start cts
=========
::

.. sourcecode:: none
pip install -r requirements.txt
./create_sqlite_db
./start_cts_from_here

$ ./start_cts_from_here
Integration tests
-----------------

Testing
=======
::

.. sourcecode:: none
./integration-tests/run-local.sh

$ tox
See :doc:`integration` for the full integration-test environment and CI flow.
3 changes: 2 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,6 @@ It provides a REST API to manipulate these metadata and sends UMB messages on ev
about
api
dev
integration

.. _Compose Tracking Service (CTS): https://pagure.io/cts
.. _Compose Tracking Service (CTS): https://github.com/release-engineering/cts
103 changes: 103 additions & 0 deletions docs/integration.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
=================
Integration tests
=================

Integration tests validate the **built container image** against a real
PostgreSQL database, OIDC auth (Dex + OpenLDAP), and Kafka. They run in
Konflux CI after successful builds and can be reproduced locally with kind.

The Mermaid deployment diagram is in the
`README on GitHub <https://github.com/release-engineering/cts/blob/main/README.md#integration-tests>`_
(GitHub renders Mermaid there). The sections below describe the same layout in
prose.

Test suite
==========

``tests/test_integration_api.py`` uses pytest and plain HTTP (``urllib`` /
``requests``). Tests include:

- API root, about, composes, OpenAPI, tags, pagination, 404 handling
- Compose workflow (create, tag, respin) when write access is available
- OIDC auth (401/403/authorized writes) when ``AUTH_BACKEND`` is OIDC-enabled
- Kafka event assertions when ``KAFKA_URL`` is set

Tests run **inside the cluster** in CI (and in ``run-local.sh``) so they can
reach in-cluster DNS names (``cts``, ``dex``, ``kafka``) and trust the Dex CA
without port-forwarding.

Environment layout
==================

Each test run uses a dedicated Kubernetes namespace containing:

+------------------+----------------------------------------------------------+
| Component | Role |
+==================+==========================================================+
| PostgreSQL | CTS database; migrations via init container |
+------------------+----------------------------------------------------------+
| OpenLDAP | User directory for Dex |
+------------------+----------------------------------------------------------+
| Dex | OIDC provider (TLS, LDAP backend) |
+------------------+----------------------------------------------------------+
| Kafka | Message bus for compose event assertions |
+------------------+----------------------------------------------------------+
| CTS | Image under test; Apache + mod_wsgi on port 8080 |
+------------------+----------------------------------------------------------+
| cts-test-runner | Ephemeral pod; installs pytest deps and runs the suite |
+------------------+----------------------------------------------------------+

Manifests: ``integration-tests/manifests/``. Deploy scripts:
``integration-tests/scripts/``.

Konflux CI
==========

1. Build pipeline produces the CTS (and ldap-server) container images.
2. ``IntegrationTestScenario`` (``.tekton/cts-integration-test.yaml``) triggers
``.tekton/integration-test-eaas.yaml``.
3. EaaS provisions an ephemeral namespace and kubeconfig.
4. Pipeline deploys PostgreSQL, OpenLDAP, Dex, Kafka, and CTS.
5. A test-runner pod clones the repo and runs::

pytest tests/test_integration_api.py

with ``CTS_URL=http://cts:8080`` and related variables (see
``integration-tests/scripts/pytest-cmd.sh``).
6. EaaS tears down the namespace when the pipeline finishes.

Running locally
===============

From the repository root::

./integration-tests/run-local.sh

Prerequisites: kind, kubectl, podman or docker, openssl.

Options: ``--skip-build``, ``--keep-cluster``, ``--no-tests``. Set
``CONTAINER_ENGINE=docker`` to use Docker instead of podman with kind.

Point pytest at an existing deployment::

CTS_URL=http://localhost:8080 pytest tests/test_integration_api.py -v -o addopts=

Use ``-o addopts=`` to disable the default coverage options from ``tox.ini``.

``tests/conftest.py`` bootstraps ``create_app(mode="full")`` for unit tests only
(when ``CTS_URL`` is unset). Integration runs set ``CTS_URL`` so the test runner
does not need the ``cts`` package or Flask dependencies.

Adding tests
============

Add ``test_*`` functions to ``tests/test_integration_api.py`` and use the
``http_client``, ``write_http_client``, or auth fixtures as appropriate. No
manual registration is required.

Related files
=============

- ``.tekton/integration-test-eaas.yaml`` — CI pipeline
- ``.tekton/README-INTEGRATION-TESTS.md`` — Konflux-specific notes
- ``integration-tests/run-local.sh`` — local kind workflow
20 changes: 17 additions & 3 deletions integration-tests/run-local.sh
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,20 @@ if [ "$CONTAINER_ENGINE" = "podman" ]; then
export KIND_EXPERIMENTAL_PROVIDER=podman
fi

# kind load docker-image only talks to Docker; with podman, use a saved archive instead.
load_kind_image() {
local image="$1"
if [ "$CONTAINER_ENGINE" = "podman" ]; then
local archive
archive=$(mktemp)
podman save "$image" -o "$archive"
kind load image-archive "$archive" --name "$KIND_CLUSTER"
rm -f "$archive"
else
kind load docker-image "$image" --name "$KIND_CLUSTER"
fi
}

# ---------------------------------------------------------------------------
# Cleanup handler
# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -138,8 +152,8 @@ echo ""
echo "=========================================="
echo "Loading images into kind"
echo "=========================================="
kind load docker-image "$CTS_IMAGE" --name "$KIND_CLUSTER"
kind load docker-image "$LDAP_IMAGE" --name "$KIND_CLUSTER"
load_kind_image "$CTS_IMAGE"
load_kind_image "$LDAP_IMAGE"

# ---------------------------------------------------------------------------
# Create a fresh namespace (mirrors the ephemeral EaaS namespace in CI)
Expand Down Expand Up @@ -224,7 +238,7 @@ echo "=========================================="
TEST_RUNNER_IMAGE="docker.io/library/python:3.12-slim"

# Pre-pull the image into kind so the pod starts quickly
kind load docker-image "$TEST_RUNNER_IMAGE" --name "$KIND_CLUSTER" 2>/dev/null || true
load_kind_image "$TEST_RUNNER_IMAGE" 2>/dev/null || true

kube run cts-test-runner \
--image="$TEST_RUNNER_IMAGE" \
Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ def read_requirements(filename):
keywords="compose tracking service",
author="The Compose Team",
author_email="cts-owner@fedoraproject.org",
url="https://pagure.io/cts/",
url="https://github.com/release-engineering/cts",
license="MIT",
packages=find_packages(exclude=["tests", "tests.*"]),
include_package_data=True,
Expand Down