Metadata-Version: 2.4
Name: cm-setup-runai
Version: 2.5.4
Summary: Run:ai Cluster Manager Setup Plugin
Author-email: NVIDIA CORPORATION & AFFILIATES <sw-bright-tpsi-team@nvidia.onmicrosoft.com>
Maintainer-email: TPSI team <sw-bright-tpsi-team@nvidia.onmicrosoft.com>
License-Expression: LicenseRef-NvidiaProprietary
Project-URL: Homepage, https://www.nvidia.com
Project-URL: Bug Tracker, https://jirasw.nvidia.com/
Keywords: deployment,runai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: responses; extra == "test"
Provides-Extra: e2e
Requires-Dist: pytest; extra == "e2e"
Requires-Dist: pytest-cov; extra == "e2e"
Requires-Dist: responses; extra == "e2e"
Requires-Dist: ci @ git+https://gitlab-master.nvidia.com/bcm/ci/cilib.git@main ; extra == "e2e"
Dynamic: license-file

# CM Setup Run:ai Plugin

Run:ai decoupled plugin for BCM cm-setup

## Getting Started

### Prerequisites

- **[uv](https://github.com/astral-sh/uv)**: An extremely fast Python package installer and resolver.
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Docker**: For building and testing in containers.

### Checking Out a Branch

```bash
git checkout main
git pull
git checkout -b feat/YOUR-JIRA-TICKET
```

## Development Workflow

### Quick Start (Makefile)

The `Makefile` is the primary interface for local development:

```bash
make help           # List available targets
make lint           # Run pre-commit linters
make test           # Run unit tests locally
make plugin         # Build the debian package (using Docker)
make clean          # Clean build artifacts
make shell          # Debug: Drop into the builder container shell
```

**Note**: `make plugin` generates a package versioned as `0.0.0~dev-<timestamp>` to distinguish local builds.

### Running Unit Tests

```bash
# Using Makefile
make test

# Or manually with uv
uv venv --python 3.12
source .venv/bin/activate
uv pip install . pytest pytest-cov
uv run pytest --cov=cmsetup --cov-report=term
```

### Running Pre-commit Hooks

```bash
uv pip install pre-commit
pre-commit install          # One-time setup
pre-commit run --all-files  # Run on all files
```

### Type Checking with mypy

mypy is configured in `pyproject.toml` with strict mode.

CI fetches and installs cmsetup to provide type stubs, then auto-installs any additional missing stubs:

```bash
# CI downloads cmsetup wheel from bcm/cm/cm-setup artifacts using VERSION_BCM
CMSETUP_REF="$(cat VERSION_BCM).0"
curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  "${CI_API_V4_URL}/projects/bcm%2Fcm%2Fcm-setup/jobs/artifacts/${CMSETUP_REF}/download?job=build-python-package" \
  -o artifacts.zip
unzip -q artifacts.zip
uv pip install ./dist/*.whl

# Auto-install missing type stubs (workaround for https://github.com/python/mypy/issues/10863)
uv run mypy . > /dev/null 2>&1 || uv run mypy --install-types --non-interactive
uv run mypy cmsetup
```

To run locally (requires cmsetup installed):

```bash
uv pip install mypy pip  # pip is required for mypy --install-types
# Auto-install stubs if needed, then run type check
uv run mypy . > /dev/null 2>&1 || uv run mypy --install-types --non-interactive
uv run mypy cmsetup
```

> **Note**: The `cache_dir` option should NOT be set to `/dev/null` in `pyproject.toml` as mypy cache is required for auto stub install to work.

### Local Testing in Docker

```bash
# Build test container (includes cm-setup base + plugin)
docker build -f Dockerfile.test -t cm-plugin-test .

# Run plugin commands
docker run --rm cm-plugin-test cm-runai-setup --help --no-distro-checks --skip-headnode-check
```

Note:
- This plugin does not currently provide a `cm-runai-setup` entrypoint.
- The CI job `entrypoint-test` is set to `allow_failure: true` because a local entrypoint is not defined in this repo.

### Building the Debian Package

```bash
# Using Makefile (recommended)
make plugin

# Using Docker directly
docker build -f Dockerfile.build -t plugin-builder .
docker run --rm -v $(pwd):/shared plugin-builder sh -c "cp /build/deb/*.deb /shared/"
```

### Testing on Krusty

```bash
apt-get install ./<your-package-name>.deb
module load python3
cm-runai-setup
```

## Key Configuration Files

| File | Purpose |
|------|---------|
| `VERSION` | Semantic version aligned with NMC (e.g., `2.3.0`) |
| `VERSION_BCM` | BCM major version, coupled to NMC release (e.g., `11` for NMC 2.2) |
| `pyproject.toml` | Package metadata, entry points, dependencies |
| `nfpm.yaml` | Debian package configuration |
| `.gitlab-ci.yml` | CI/CD pipeline variables |
| `cmsetup/plugins/runai/` | Plugin implementation |

## CI/CD Pipeline

The pipeline is defined in `cds/cicd-pipelines/pipelines/ncp/nmc/cm-setup-plugin-pipeline.yml`.

### Package Naming

Packages include BCM version: `cm-setup-runai-bcm<VERSION_BCM>`

Example: `cm-setup-runai-bcm11_2.3.0_amd64.deb`

### Release Process

#### 1. Merge Request (MR)
- **Automatic**: Runs linting, type checking (mypy), unit tests, and security scans.
- **Build**: Creates a test package with version `0.0.1~mr.<sha>`.
- **Publish**: Manual publishing to **Dev** Artifactory for testing.

#### 2. Main/Release Branch (Pre-release)
- **Build**: Creates package with version `<VERSION>~pr.<pipeline_iid>.<sha>`.
- **Slack Notification**: Team is notified when pre-release is published to Dev Artifactory.
- **QA Verification**: QA tests the pre-release package.
- **Release Promotion**: After QA sign-off:
    1. Ensure the `VERSION` file contains the version you want to release.
    2. Go to the pipeline for the latest commit.
    3. Trigger the manual **`promote-release`** job.
    4. This creates a Git tag matching the `VERSION` file.
    5. Bump `VERSION` to the next version in a new MR.

#### 3. Release (Git Tag)
- **Build**: Final package with exact version (e.g., `2.3.0`).
- **Dev Publish**: Automatically publishes to **Dev** Artifactory.
- **Slack Notification**: Team is notified of the promotion.
- **Release Notes**: Generates changelog and GitLab Release page.
- **QA Final Verification**: QA verifies the release package.
- **Prod Publish**: Manual trigger to publish to **Prod** Artifactory.
- **Slack Notification**: Team is notified when published to prod.

## Versioning and Branching

### Version Files

- **`VERSION`** - Plugin semantic version (must align with NMC major.minor)
- **`VERSION_BCM`** - BCM major version (integer, coupled to NMC release)

> **Note**: `VERSION_BCM` is not independently bumped. BCM is a component of NMC and they are released together (e.g., NMC 2.2 → BCM 11).

### Branching Strategy

| Branch | Purpose |
|--------|---------|
| `main` | Latest NMC/BCM combination (active development) |
| `release/nmc-X.Y-bcmZ` | Maintenance branch for specific NMC/BCM combination |

### Version Alignment

- Plugin `VERSION` major.minor must match NMC version (e.g., `2.3.x` for NMC 2.3)
- Patch version can be bumped independently
- CI validates alignment on release branches

### Creating Release Branches

When a new NMC version is released (which includes a corresponding BCM version):

```bash
# Create release branch for current version
git checkout main
git checkout -b release/nmc-2.3-bcm11
git push origin release/nmc-2.3-bcm11

# Update main for next NMC/BCM version (both change together)
git checkout main
echo "2.4.0" > VERSION      # New NMC version
echo "12" > VERSION_BCM     # Corresponding BCM version for NMC 2.4
git add VERSION VERSION_BCM
git commit -m "Bump for NMC 2.4 / BCM 12"
```

### Hotfix on Release Branch

```bash
git checkout release/nmc-2.3-bcm11
# Make fix, bump patch version
echo "2.3.1" > VERSION
git commit -am "Fix: description"
# Create MR against release branch, then promote-release
```
