Metadata-Version: 2.3
Name: qubership-external-cred-provision
Version: 1.0.1
Summary: Qubership EnvGene CLI that provisions external credentials into Vault, OpenBao, GCP Secret Manager, and AWS Secrets Manager from a YAML context file.
Keywords: envgene,credentials,secrets,vault,openbao,gcp,aws,provisioning,vals
Author: Qubership
Maintainer: Qubership
Requires-Python: ~=3.12
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Dist: click (==8.1.7)
Requires-Dist: pyyaml (==6.0.2)
Requires-Dist: qubership-pipelines-common-library (==2.0.12)
Project-URL: Documentation, https://github.com/Netcracker/qubership-envgene/blob/main/docs/features/external-creds-provisioning-cli.md
Project-URL: EnvGene external credentials, https://github.com/Netcracker/qubership-envgene/blob/main/docs/features/external-creds.md
Project-URL: Homepage, https://github.com/Netcracker/qubership-envgene/tree/main/python/external-cred-provision
Project-URL: Issues, https://github.com/Netcracker/qubership-envgene/issues
Project-URL: Source, https://github.com/Netcracker/qubership-envgene/tree/main/python/external-cred-provision
Description-Content-Type: text/markdown

# qubership-external-cred-provision

Command-line tool for [EnvGene](https://github.com/Netcracker/qubership-envgene/blob/main/README.md) that provisions external credentials into secret stores
from a declarative YAML context file.

EnvGene generates the context during Effective Set calculation. This CLI reads that file, connects
to the configured stores, and creates or verifies secrets according to each entry's strategy. It
supports dry-run mode for CI validation without writes.

## Features

- Provisions credentials into HashiCorp Vault, OpenBao, Google Cloud Secret Manager, and AWS Secrets
  Manager
- Idempotent strategies: verify presence, create when absent, or overwrite
- Generates secret values when a field is marked with the reserved `_generateValue` marker
- Dry-run mode for pre-flight checks before apply
- Structured logging to console and log files

## Requirements

- Python 3.12
- Network access to the target secret stores
- Store authentication via process environment variables (see
  [configuration](#configuration))
- Runtime dependency on `qubership-pipelines-common-library` for secret-store integration

## Installation

```bash
pip install qubership-external-cred-provision
```

The installed command is `external-cred-provision` (shorter than the PyPI package name).

## Quick start

Apply provisioning from a context file:

```bash
external-cred-provision path/to/external-credentials.yaml
```

Validate without writing to any store:

```bash
external-cred-provision --dry-run path/to/external-credentials.yaml
```

Set console log verbosity (full diagnostic log is always written to `full.log`):

```bash
external-cred-provision --log-level INFO path/to/external-credentials.yaml
```

## Command-line options

| Flag            | Default | Meaning                                     |
|-----------------|---------|---------------------------------------------|
| `--dry-run`     | off     | Run checks only; no writes to secret stores |
| `--log-level`   | DEBUG   | Console and `module.log` verbosity          |

Positional argument `<context-path>` is required. It must point to a YAML file that defines a
top-level `credentials` map.

## Supported secret stores

Store type is inferred from each credential's VALS reference scheme:

| VALS scheme prefix   | Store                         |
|----------------------|-------------------------------|
| `ref+vault://`       | HashiCorp Vault               |
| `ref+openbao://`     | OpenBao                       |
| `ref+gcpsecrets://`  | Google Cloud Secret Manager   |
| `ref+awssecrets://`  | AWS Secrets Manager           |

## Provisioning strategies

| Strategy           | Secret exists | Secret absent |
|--------------------|---------------|---------------|
| `fail_if_absent`   | skip          | fail          |
| `create_if_absent` | skip          | create        |
| `overwrite`        | overwrite     | create        |

Entries with `fail_if_absent` omit `data` because the CLI performs no write. Write strategies
require a `data` field (map or scalar, depending on the store).

## Minimal context example

```yaml
credentials:
  app-cred:
    vals: "ref+vault://kv/path/to/app-cred"
    strategy: create_if_absent
    data:
      username: app_user
      password: _generateValue

  monitoring-token:
    vals: "ref+vault://kv/path/to/monitoring-token"
    strategy: fail_if_absent
```

## Configuration

Authentication and store settings are read from environment variables. Variable names depend on
store type and optional `secret_store_id` query parameters in each VALS reference.

See the [External Credentials provisioning CLI](https://github.com/Netcracker/qubership-envgene/blob/main/docs/features/external-creds-provisioning-cli.md)
reference for the full variable list, input schema, value-generation rules, and runtime behaviour.

Broader EnvGene external-credentials design (context generation, Effective Set integration):

[External Credentials Management](https://github.com/Netcracker/qubership-envgene/blob/main/docs/features/external-creds.md)

## License

Apache License 2.0. See the [LICENSE](https://github.com/Netcracker/qubership-envgene/blob/main/LICENSE) file in the EnvGene repository.

