Metadata-Version: 2.4
Name: saltext.ceph
Version: 0.1.0
Summary: Salt Extension for interacting with Ceph through the Dashboard REST API
Author-email: glebrodionov94 <glebrodionov94@users.noreply.github.com>
Maintainer-email: glebrodionov94 <glebrodionov94@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/glebrodionov94/saltext-ceph
Project-URL: Source, https://github.com/glebrodionov94/saltext-ceph
Project-URL: Tracker, https://github.com/glebrodionov94/saltext-ceph/issues
Project-URL: Changelog, https://github.com/glebrodionov94/saltext-ceph/blob/main/CHANGELOG.md
Project-URL: Documentation, https://glebrodionov94.github.io/saltext-ceph/
Project-URL: Security, https://github.com/glebrodionov94/saltext-ceph/security/policy
Keywords: ceph,cephadm,configuration-management,infrastructure-as-code,salt,salt-extension,saltstack
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: salt>=3006
Requires-Dist: requests<3,>=2.32.4
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: check-wheel-contents>=0.6; extra == "build"
Provides-Extra: changelog
Requires-Dist: towncrier==25.8.0; extra == "changelog"
Provides-Extra: dev
Requires-Dist: nox[uv]!=2025.05.01,>=2024.3; extra == "dev"
Requires-Dist: pre-commit>=2.21.0; extra == "dev"
Provides-Extra: dev-extra
Requires-Dist: black==26.5.1; extra == "dev-extra"
Requires-Dist: isort==8.0.1; extra == "dev-extra"
Requires-Dist: coverage==7.14.3; extra == "dev-extra"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-prompt; extra == "docs"
Requires-Dist: sphinxcontrib-spelling; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: towncrier==25.8.0; extra == "docs"
Requires-Dist: sphinxcontrib-towncrier; extra == "docs"
Requires-Dist: myst_parser; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-inline-tabs; extra == "docs"
Provides-Extra: docsauto
Requires-Dist: sphinx-autobuild; extra == "docsauto"
Provides-Extra: lint
Requires-Dist: pylint==4.0.6; extra == "lint"
Provides-Extra: tests
Requires-Dist: pytest>=7.2.0; extra == "tests"
Requires-Dist: pytest-salt-factories>=1.0.0; extra == "tests"
Requires-Dist: pytest-instafail; extra == "tests"
Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "tests"
Dynamic: license-file

# Salt Extension for Ceph

`saltext.ceph` manages Ceph through the versioned Dashboard REST API. Cephadm
continues to place and reconcile daemons; Salt describes cluster resources,
calculates drift, invokes cephadm through Dashboard, and verifies the result.
This makes the extension suitable for reviewed GitOps and Infrastructure as Code
workflows without installing a Salt minion on every storage host.

**Status: alpha.** The package is available from PyPI. Its API surface and state
contracts can still change between early releases.

## What is included

- Typed execution modules and matching salt-ssh wrappers for the public Dashboard
  controllers: cluster and cephadm, hosts, services, OSDs, pools, CRUSH, CephFS,
  RBD, NFS, iSCSI, SMB, RGW, NVMe-oF, CephX and Dashboard administration,
  observability, tasks, feature availability, the current Dashboard MOTD,
  integrations, and multi-cluster management.
- Declarative states for resources whose current value can be read and compared
  reliably. States support Salt test mode, asynchronous Dashboard tasks, a
  post-write read, and explicit confirmation for destructive changes.
- Exact-target GitOps runners with expected-FSID checks and overlapping-job
  protection.
- Read-only health, task, and certificate beacons with bounded, redacted events.
- A shared synchronous HTTP client with TLS verification, strict profiles,
  request validation, safe errors, token refresh, and wrong-cluster protection.

The [support matrix][support] records the exact boundary between
declarative resources, imperative operations, Reef-compatible endpoints, and
current-only endpoints. The [controller inventory][controllers]
maps the upstream source tree and explains every reviewed exclusion. Private
`/ui-api` routes and CLI-only manager methods are deliberately excluded.

## Deployment model

Install the extension only where Salt calls the Dashboard API: one dedicated
control minion per cluster, a masterless `salt-call --local` node, or a salt-ssh
controller. Ceph cluster hosts do not need Salt for API-based management.

Configure a profile outside the state repository, for example in an encrypted
pillar or protected Salt configuration:

```yaml
ceph:
  profiles:
    default:
      url: https://ceph.example:8443
      username: salt-automation
      password_file: /run/secrets/ceph-dashboard-password
      verify: /etc/salt/pki/ceph-dashboard-ca.pem
      expected_fsid: 11111111-1111-1111-1111-111111111111
```

Keep credentials out of Git, command arguments, job caches, and event payloads.
Mutating calls verify `expected_fsid` before the first write. See the
[API client guide][api-client] for the complete profile contract and the
[permissions guide][permissions] for a least-privilege Dashboard role.

A resource can then be managed in ordinary SLS:

```yaml
archive-pool:
  ceph_pool.present:
    - name: archive
    - pool_type: replicated
    - pg_num: 32
    - application_metadata:
        - rbd
```

Plan and apply the same tree through the designated control minion:

```console
salt-run ceph_gitops.plan ceph-control \
  11111111-1111-1111-1111-111111111111 mods='[ceph.cluster]'
salt-run ceph_gitops.apply ceph-control \
  11111111-1111-1111-1111-111111111111 mods='[ceph.cluster]'
```

The [GitOps guide][gitops] covers repository layout, dependencies,
drift checks, explicit deletion, and CI gates. Removing an SLS declaration alone
does not remove the corresponding Ceph resource.

## Install and develop

Install the package in the Python environment that runs Salt:

```console
salt-pip install saltext.ceph
```

For development, install a checkout with its test dependencies:

```console
git clone https://github.com/glebrodionov94/saltext-ceph.git
cd saltext-ceph
uv venv --python 3.11
uv pip install -e ".[tests,dev,docs,build]" "salt==3006.27"
python -m pytest tests/unit -q
```

The distribution is named `saltext.ceph` and registers a `salt.loader` entry
point. Python 3.10+ and Salt 3006+ are supported package targets. CI exercises
Salt 3006 and 3008; live Dashboard smoke tests are opt-in because they require a
real cluster.

See [installation][installation], [development][development], [live cluster
testing][live-testing], and [release][releasing] for the complete workflows.
Security reports belong in a private [GitHub Security Advisory][security], not a
public issue.

## Project layout

```text
src/saltext/ceph/
  modules/          Salt execution modules
  states/           Declarative state modules
  utils/ceph/       HTTP client and typed controller adapters
  wrapper/          Controller-side salt-ssh functions
  runners/          Master-side operational and GitOps runners
  beacons/          Read-only transition detectors
tests/               Unit and opt-in live integration tests
docs/                Sphinx guides and generated API reference
changelog/           Towncrier news fragments
tools/               Development and distribution checks
```

The scaffold was generated with
[salt-extension-copier](https://salt-extensions.github.io/salt-extension-copier/),
using [saltext-vault](https://github.com/salt-extensions/saltext-vault) as a
structural reference. The project is licensed under Apache-2.0; see
[LICENSE][license] and [NOTICE][notice].

[api-client]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/api-client.md
[controllers]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/controller-coverage.md
[development]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/development.md
[gitops]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/gitops.md
[installation]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/installation.md
[license]: https://github.com/glebrodionov94/saltext-ceph/blob/main/LICENSE
[live-testing]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/live-testing.md
[notice]: https://github.com/glebrodionov94/saltext-ceph/blob/main/NOTICE
[permissions]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/permissions.md
[releasing]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/releasing.md
[security]: https://github.com/glebrodionov94/saltext-ceph/security/policy
[support]: https://github.com/glebrodionov94/saltext-ceph/blob/main/docs/topics/support.md
