Skip to content

Commit d3ea02a

Browse files
Leon-hkfwilheNotTheEvilOneyeoldegrove
authored
docs: Add readme hint for library audience (#297)
* docs: Add readme hint for library audience * Include "no stable API" statement Co-authored-by: Florian Wilhelm <florian.wilhelm02@sap.com> * Revert "Include "no stable API" statement" This reverts commit e1d8e3c. * Underline semver API stability. Signed-off-by: Tobias Wolf <wolf@b1-systems.de> On-behalf-of: SAP <tobias.wolf@sap.com> * docs: shorten the README and link documentation --------- Signed-off-by: Tobias Wolf <wolf@b1-systems.de> Co-authored-by: Florian Wilhelm <florian.wilhelm02@sap.com> Co-authored-by: Tobias Wolf <wolf@b1-systems.de> Co-authored-by: Eike Waldt <waldt@b1-systems.de>
1 parent d417011 commit d3ea02a

File tree

1 file changed

+44
-47
lines changed

1 file changed

+44
-47
lines changed

‎README.md‎

Lines changed: 44 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,77 +3,74 @@
33
![Test](https://github.com/gardenlinux/parse_features_lib/actions/workflows/pytests.yml/badge.svg)
44
![security check](https://github.com/gardenlinux/parse_features_lib/actions/workflows/bandit.yml/badge.svg)
55

6-
# Parse features lib
6+
## Garden Linux Python Library
77

8-
This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux).
8+
Python tooling to work with [Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors, OCI artifacts, repositories, and releases.
9+
It is primarily targeted at Garden Linux developers and CI pipelines rather than end users.
910

10-
Features:
11+
The library follows the intent of [Semantic Versioning](https://semver.org) for its public APIs.
1112

12-
- compare APT repositories
13-
- parse features
14-
- parse flavors
15-
- push OCI artifacts to a registry
13+
### Features
1614

17-
## Quickstart
15+
- **Feature management**: parse, filter, and work with Garden Linux feature sets
16+
- **Flavor processing**: parse `flavors.yaml` and generate flavor combinations
17+
- **Repository utilities**: compare APT repositories and query package versions
18+
- **OCI operations**: push OCI artifacts and manifests to container registries
19+
- **S3 integration**: upload/download artifacts from S3 buckets
20+
- **GitHub integration**: create and manage GitHub releases
1821

19-
### Example: get a list of features for a given cname
22+
## Documentation
2023

21-
**Inclusion via poetry**:
24+
Full documentation is available at the **Garden Linux Python Library Documentation** site:
25+
[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
2226

23-
`gardenlinux = { git = "https://github.com/gardenlinux/python_gardenlinux_lib", rev="0.6.0" }`
27+
The docs include:
2428

25-
```python
26-
from gardenlinux.features import Parser
29+
- **Command-Line Interface**: `gl-features-*`, `gl-flavors-*`, `gl-oci`, `gl-s3`, `gl-gh-release`
30+
- **API Reference**: modules, classes, and functions (e.g. `Parser`, `CName`, `Container`, `Repository`)
31+
- **Release documentation**: versioning and release process
2732

28-
cname = "aws-gardener_prod"
29-
feature_list = Parser().filter_as_list(cname)
30-
print(f"features of {cname}:")
31-
for feature in feature_list:
32-
print(feature)
33-
```
34-
35-
## Developer Documentation
33+
## Installation
3634

37-
The library is documented with docstrings, which are used to generate the developer documentation available [here](https://gardenlinux.github.io/python-gardenlinux-lib/).
35+
### Using `poetry` (from Git)
3836

39-
## Push OCI artifacts to a registry
37+
Add the library as a dependency in your `pyproject.toml`:
4038

41-
this tool helps you to push oci artifacts.
39+
```toml
40+
[tool.poetry.dependencies]
41+
gardenlinux = { git = "https://github.com/gardenlinux/python-gardenlinux-lib", rev = "0.10.5" }
42+
```
4243

43-
### Installation
44+
Then install:
4445

4546
```bash
46-
git clone https://github.com/gardenlinux/python-gardenlinux-lib.git
47-
mkdir venv
48-
python -m venv venv
49-
source venv/bin/activate.sh
5047
poetry install
51-
gl-oci --help
5248
```
5349

54-
### Usage
55-
56-
The process to push a Gardenlinux build-output folder to an OCI registry is split into two steps: In the first step all files are pushed to the registry and a manifest that includes all those pushed files (layers) is created and pushed as well. An index entry that links to this manifest is created offline and written to a local file but not pushed to any index. This push to an index can be done in the second step where the local file containing the index entry is read and pushed to an index. The seperation into two steps was done because pushing of manifests takes long and writes to dedicated resources (possible to run in parallel). Updating the index on the other hand is quick but writes to a share resource (not possible to run in parallel). By splitting the process up into two steps it is possible to run the slow part in parallel and the quick part sequentially.
57-
58-
#### 1. Push layers + manifest
59-
60-
To push layers you have to supply the directory with the build outputs `--dir`. Also you have to supply cname (`--cname`), architecture `--arch` and version `--version` of the build. This information will be included in the manifest. You have to supply an endpoint where the artifacts shall be pushed to `--container`, for example `ghcr.io/gardenlinux/gardenlinux`. You can disable enforced HTTPS connections to your registry with `--insecure True`. You can supply `--cosign_file <filename>` if you want to have the hash saved in `<filename>`. This can be handy to read the hash later to sign the manifest with cosign. With `--manifest_file <filename>` you tell the program in which file to store the manifests index entry. This is the file that can be used in the next step to update the index. You can use the environment variable GL_CLI_REGISTRY_TOKEN to authenticate against the registry. Below is an example of a full program call of `push-manifest`
50+
### Local development setup
6151

6252
```bash
63-
GL_CLI_REGISTRY_TOKEN=asdf123 gl-oci push-manifest --dir build-metal-gardener_prod --container ghcr.io/gardenlinux/gl-oci --arch amd64 --version 1592.1 --cname metal-gardener_prod --cosign_file digest --manifest_file oci_manifest_entry_metal.json
53+
git clone https://github.com/gardenlinux/python-gardenlinux-lib.git
54+
cd python-gardenlinux-lib
55+
python -m venv venv
56+
source venv/bin/activate
57+
poetry install
6458
```
6559

66-
#### 2. Update index with manifest entry
60+
## Quickstart
6761

68-
Parameters that are the same as for `push-manifest`:
62+
### Example: list features for a given `cname`
6963

70-
- env-var `GL_CLI_REGISTRY_TOKEN`
71-
- `--version`
72-
- `--container`
73-
- `--manifest-file` this time this parameter adjusts the manifest entry file to be read from instead of being written to
64+
```python
65+
from gardenlinux.features import Parser
7466

75-
A full example looks like this:
67+
cname = "aws-gardener_prod"
68+
feature_list = Parser().filter_as_list(cname)
7669

77-
```bash
78-
GL_CLI_REGISTRY_TOKEN=asdf123 gl-oci update-index --container ghcr.io/gardenlinux/gl-oci --version 1592.1 --manifest_file oci_manifest_entry_metal.json
70+
print(f"features of {cname}:")
71+
for feature in feature_list:
72+
print(feature)
7973
```
74+
75+
For more examples and for all CLI tools, see the **Command-Line Interface** and **API Reference** sections in the docs:
76+
[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)

0 commit comments

Comments
 (0)