{"id":20126476,"url":"https://github.com/sovereigncloudstack/gx-credential-generator","last_synced_at":"2025-05-06T17:35:24.410Z","repository":{"id":37407767,"uuid":"434561949","full_name":"SovereignCloudStack/gx-credential-generator","owner":"SovereignCloudStack","description":"Tools for creating Gaia-X Credentials (OpenStack, k8s, ...)","archived":false,"fork":false,"pushed_at":"2024-04-12T08:14:50.000Z","size":887,"stargazers_count":6,"open_issues_count":15,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-14T05:07:12.019Z","etag":null,"topics":["gaia-x"],"latest_commit_sha":null,"homepage":"https://scs.community/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SovereignCloudStack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-12-03T10:52:06.000Z","updated_at":"2024-04-15T14:06:30.253Z","dependencies_parsed_at":"2023-12-18T13:24:32.535Z","dependency_job_id":"9a07ba6b-5478-49ce-9362-d5bbd9a64d10","html_url":"https://github.com/SovereignCloudStack/gx-credential-generator","commit_stats":null,"previous_names":["sovereigncloudstack/gx-credential-generator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fgx-credential-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fgx-credential-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fgx-credential-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fgx-credential-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SovereignCloudStack","download_url":"https://codeload.github.com/SovereignCloudStack/gx-credential-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224517296,"owners_count":17324409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gaia-x"],"created_at":"2024-11-13T20:16:15.904Z","updated_at":"2024-11-13T20:16:16.978Z","avatar_url":"https://github.com/SovereignCloudStack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gx-credential-generator\n\n![Static Badge](https://img.shields.io/badge/version-1.0.0-green)\n![Static Badge](https://img.shields.io/badge/Gaia--X_Release-Tagus-blue?color=%23D901D9)\n![Static Badge](https://img.shields.io/badge/Gaia--X_Compliance-Conformity-blue?color=%23D901D9)\n![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)\n\nTool for creating compliant Gaia-X Credentials, previously known as Gaia-X Self-Description, for SCS-compliant cloud infrastructures.\nTo get familiar with Gaia-X Credentials, please consult the corresponding [documentation](https://docs.gaia-x.eu/).\n\n## Table of Contents\n\n 1. [Introduction](#introduction)\n 2. [Quick Start](#quick-start-guide)\n 3. [User Guide](#user-guide)\n 4. [Developer Guide](#developer-guide)\n\n## Introduction\n\nGaia-X Ontology defines classes and attributes, which Gaia-X offers to describe CSPs as well as services to be published in a Gaia-X catalogue.\n\nA service and/or CSP is supposed to be \"Gaia-X compliant\", if their Gaia-X Credential(s) fulfill a set of special requirements.\nThese requirements are defined in [Gaia-X Policy and Rules Documents](https://docs.gaia-x.eu/policy-rules-committee/policy-rules-conformity-document/23.10/) as well as [Gaia-X Trust Framework](https://docs.gaia-x.eu/policy-rules-committee/trust-framework/22.10/).\ngx-credential-generator automatically discovers a CSP's and service's properties and creates Gaia-X Credentials for\n\n- Cloud Service Provider of SCS-compliant cloud infrastructure\n- OpenStack as an IaaS Offering\n- Kubernetes as a CaaS Offering\n\nEach description may consist of several Gaia-X Credentials, each of them attesting other properties.\nAll credentials are bundled in a so called [Presentation](https://www.w3.org/TR/vc-data-model/#presentations-0) and send to the [GXDCH Compliance Service](https://gaia-x.eu/gxdch/), which issues a Compliance Credential to certify Gaia-X compliance of the given CSP and/or service.\n\nGaia-X defines several levels of compliance, each with a different trust level. gx-credential-generator supports the very basic level, called \"Conformity\" and is compliant with the Gaia-X Tagus release.\n\n### Cloud Service Provider\n\ngx-credential-generator outputs the following Gaia-X Credentials for a CSP in order to be Gaia-X compliant\n\n- Gaia-X Terms and Conditions signed by a CSP as an instance of Gaia-X class `GaiaXTermsAndConditions`\n- Legal Registration number issued by a Notary Service accredited by GXDCH as an instance of Gaia-X class `LegalRegistrationNumber`\n- Gaia-X mandatory attributes for a CSP as an instance of Gaia-X class `LegalPerson`\n- Compliance Credentials for a CSP issued by the GXDCH Compliance Service as an instance of Gaia-X class `compliance`\n\nA CSP's properties are not discoverable and read out from the configuration file. See the [configuration](#configuration) section for more details.\n\n### OpenStack\n\ngx-credential-generator collects discoverable information from an OpenStack cloud, bundles them to Gaia-X Credentials and requests for compliance at GXDCH.\n\nBesides the Gaia-X Credentials of a CSP of an OpenStack cloud, which are required by Gaia-X, the following Gaia-X Credentials will be created:\n\n- Mandatory properties for IaaS Offering as an instance of Gaia-X `ServiceOffering`\n- Detailed description of OpenStack cloud as an instance of Gaia-X `VirtualMachineServiceOffering`\n- Compliance Credentials for OpenStack cloud issued by GXDCH Compliance Service as an instance of Gaia-X class `compliance`\n\nTo discover cloud properties, gx-credential-generator requires access to the OpenStack cloud as normal tenant user.\n\ngx-credential-generator queries the OpenStack API to collect\n\n- public VM Images and their properties, such as operation system or hardware requirements\n- public Server Flavors, such as number and capability of virtual CPUs or size of root disk\n\n### Kubernetes (k8s)\n\nComing soon.\n\n## Quick Start Guide\n\n### 1. Clone the repository into a location of your choice\n\n```bash\ngit clone git@github.com:SovereignCloudStack/gx-credential-generator.git\ncd gx-credential-generator\n```\n\n### 2. Install scripts dependencies\n\nInstalling dependecies into a Python [virtualenv](https://virtualenv.pypa.io/en/stable/) is recommended\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\nPlease use python version 3.10!\n\n### Cloud Service Provider\n\n#### 1. Create configuration file\n\ngx-credential-generator requires some configuration options. See [configuration](#configuration) section for more details.\n\n#### 2. Run gx-credential-generator\n\nCreate Gaia-X Credential for a CSP without specifying a configuration file. This implies the default path at `/etc/gx-credential-generator/config.yaml`, which must exist:\n\n```commandline\npython3 -m generator.cli csp\n```\n\nGaia-X terms and conditions are displayed and you are prompted to agree to them. Type 'y' to agree or 'n' to disagree.\n\n**Note**: If you do not agree Gaia-X terms and conditions, the process will be aborted and no Gaia-X credential is created.\n\nEach Gaia-X Credential is serialized in [JSON-LD](https://json-ld.org/) and stored in a separate file prefixed as follows:\n\n- lp: Gaia-X Credential containing the CSP's legal address and headquarter address\n- lrn: Gaia-X Credential for the CSP's legal registration number issued by GXDCH Notary Service. gx-credential-generator reaches out to Notary Service by itself.\n- tandc: Gaia-X Terms and Conditions signed by the CSP\n- vp_csp: Presentation of all Gaia-X Credentials to be sent to GXDCH Compliance Service to assert compliance\n- cs_csp: Compliance Credential for the CSP as Gaia-X `LegalPerson` issued by GXDCH Compliance Service\n\nGaia-X Credential files are placed in the current working directory, by default. To change the output directory use the parameter `--out-dir`:\n\n```commandline\npython3 -m generator.cli csp --out-dir=my-output-dir\n```\n\nRunning the gx-credential-generator with a specified configuration file path using the parameter `--config`:\n\n```commandline\npython3 -m generator.cli csp --config=my-config.yaml\n```\n\nYou can avoid interactive prompt for Gaia-X terms and conditions agreement using the option `--auto-sign`. This implies you agree to them:\n\n```commandline\npython3 -m generator.cli csp --auto-sign\n```\n\n### OpenStack\n\n#### 1. Create `clouds.yaml` configuration file\n\ngx-credential-generator requires access to the OpenStack API as a normal tenant\n  user and has to be configured with these user credentials to access your\n  OpenStack cloud. This is done\n  using [clouds.yaml](https://docs.openstack.org/python-openstackclient/latest/configuration/index.html).\nA `clouds.yaml` is a YAML file containing several cloud access configurations. Each configuration is referred to by name.\n\nSMake sure the following keys exist in our `clouds.yaml`.\n\n- `auth.user_domain_name`\n- `auth.project_domain_name`\n- `region_name`\n\n#### 2. Create configuration file\n\ngx-credential-generator requires some configuration options. See [configuration](#configuration) section for more details.\n\n#### 3. Run gx-credential-generator\n\nThe command to run gx-credential-generator for OpenStack clouds is similar to the one to run gx-credential-generator for a CSP. The arguments `--config`, `--out-dir` and `--auto-sign` are also available and act like for the CSP command.\n\nCreate Gaia-X Credential for an OpenStack cloud\n\n  ```bash\n  python3 -m generator.cli openstack \u003cos-cloud\u003e\n  ```\n\n(`\u003cos-cloud\u003e` is a placeholder for the name of the desired entry in `clouds.yaml`)\n\nAs Gaia-X requires to define a provider for each published service offering, gx-credential-generator creates Gaia-X Credentials for the CSP at every run for an OpenStack cloud, too.\n\nEach Gaia-X Credential is serialized in [JSON-LD](https://json-ld.org/) and stored in a separate file. Credentials for CSPs correspond to the ones generated by the command `csp`. Credentials for OpenStack clouds are prefixed as follows:\n\n- so: Mandatory properties for the OpenStack cloud\n- vmso: Detailed description of the OpenStack cloud\n- vp_so: Presentation of all Gaia-X Credentials to be sent to GXDCH Compliance Service to assert compliance\n- cs_so: Compliance Credentials for the OpenStack cloud as Gaia-X `ServiceOffering` issued by GXDCH Compliance Service\n\n### Kubernetes (k8s)\n\nComing soon!\n\n## User Guide\n\n### Configuration\n\ngx-credential-generator is configured by `config.yaml`. The configuration\nincludes:\n\n- Values for mandatory attributes for CSP and service offering, which are not discoverable\n- Prerequisites to create and sign Gaia-X Credentials\n- Enpoints to GXDCH services\n\n### Mandatory Attributes\n\nThe Gaia-X Credential schema dictates mandatory attributes for some classes.\nIf values for mandatory attributes cannot be discovered from the OpenStack cloud or Kubernetes cluster, default values are taken from the configuration.\nProviders are able to change default values.\nIn doing so, attribute values for **ALL** instances of impacted cloud resource are modified.\n\n#### CopyrightOwner, License and ResourcePolicy of VM images and Operating System\n\n`copyrightOwner`, `license` and `resourcePolicy` are mandatory attributes for VM\nImages and their operating systems. As these values are not accessible from\nOpenStack cloud, default values are used. The values for operating system are\ndefined in the section ``software resources`` with one subsection for each operating\nsystem. Operating systems are referenced by name, e.g. for Alpine Linux:\n\n```yaml\nsoftware resources:\n  Alpine Linux:\n    copyright owner: \"Alpine Linux\"\n    resource policy: \"default: allow intent\"\n    license:\n      - https://gitlab.alpinelinux.org/alpine/aports/-/issues/9074\n```\n\nBy default, gx-credential-generator uses operating system values for VM Image as well. I.e. by\ndefault, VM Image and operating system have the same values\nfor `copyrigthOwner`, `license` and `resourcePolicy`. Providers are able to\nchange values for each VM image, individually. Therefore, the\nsection `own images` in `cloud resources` exists. To set individual values for a\nspecific VM image, add a new section, started by image's name (as defined in\nOpenStack cloud) to configuration file. The following example defines ìndividual\nvalues for `copyrightOwner`, `license` and `resourcePolicy` for VM image\ncalled `AlmaLinux 8`.\n\n```yaml\ncloud resources:\n  own images:\n    AlmaLinux 8:\n      copyright owner:\n        - \"AlmaLinux OS Foundation\"\n        - \"ACME Company\"\n      resource policy: \"allow: all\"\n      license:\n        - https://www.example.org\n```\n\n### Prerequisites to create and sign Gaia-X Credential\n\ngx-credential-generator creates Gaia-X Credentials, which refer to [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/). Verifiable Credentials require a proof, e.g. a digital signature of the credential's issuer. Therefore some settings, e.g. a private key to sign, are required and defined in the section `Credentials` of the configuration file.\n\n### Enpoints to GXDCH services\n\ngx-credential-generator interacts with GXDCH service, e.g. to retrieve a credential for a CSP's legal registration number or to assert compliance. To set the GXDCH endpoints use the options in the section `gxdch`. For a list of available GXSCH endpoints refer to [Gaia-X Framework](https://docs.gaia-x.eu/framework/?tab=clearing-house)\n\n### Docker\n\n----*outdated*---\n\nThe docker environment creates a general and portable environment for the\ngx-cred-generator module. Before running the container, don't forget to mount\nyour credentials for the correct path. OpenStack-related secret are located\nunder `~/.config/openstack`.\n\n**Example codes:**\n\nFirst of all, build the image:\n\n```shell\ndocker build -t gx-credential-generator .\n```\n\nRunning the `gx-cred-generator.py` on an example cloud:\n\n```shell\ndocker run -v \"\u003csecret_location\u003e:/root/.config/openstack\" gx-credential-generator ./gx-cred-generator.py --os-cloud gx-h61.1\n```\n\nRunning the container in an interactive mode:\n\n```shell\ndocker run -it -v \"\u003csecret_location\u003e:/root/.config/openstack\" gx-credential-generator bash\n```\n\nor you can use the following to create a temp location for the secrets:\n\n```shell\nmkdir -p os_secret \u0026\u0026 cp secret1 ./os_secret\ndocker run -v \"${PWD}/os_secret:/root/.config/openstack\" gx-credential-generator ./gx-cred-generator.py --os-cloud gx-h61.1\n```\n\n## Developer Guide\n\n### Running the tests\n\nFirst, install the test dependencies **in addition** to the main dependencies into your virtualenv as described above under [\"Quick Start Guide\"](#quick-start-guide):\n\n```shell\npip install -r test-requirements.txt\n```\n\nThen, tests can be run with:\n\n```shell\npython3 -m pytest tests/\n```\n\n### Updating the dependency pins\n\nWe pin dependencies with `pip-compile`\nfrom [pip-tools](https://pypi.org/project/pip-tools/),\nwhich can be installed with:\n\n```shell\npip install pip-tools\n```\n\nIf you change one of the `*.in` files, you need to regenerate the\nconcrete `requirements.txt`\nfiles as follows (the order is important):\n\n```shell\npip-compile requirements.in\npip-compile test-requirements.in\n```\n\nBy default, `pip-compile` doesn't update the pinned versions. This can be\nchanged by adding the\n`--upgrade` flag to the above invocations:\n\n```shell\npip-compile --upgrade requirements.in\npip-compile --upgrade test-requirements.in\n```\n\nWhenever the concrete `requirements.txt` file change you also shouldn't forget\nto re-run the\n`pip install -r ...` steps again.\n\n### Generate python classes for Gaia-X Ontology\n\nGX-Credential generator uses python classes to create Gaia-X compliant Gaia-X Credentials.\nThese classes mirror [Gaia-X Ontology](https://gitlab.com/gaia-x/technical-committee/service-characteristics-working-group/service-characteristics) and are generated automatically using [linkML's python generator](https://linkml.io/linkml/generators/python.html).\nLinkMl seems to have a bug, as creation of inlined objects fails with `TypeError: unhashable type: 'list'` (see comment in [#70](https://github.com/SovereignCloudStack/gx-credential-generator/issues/70#issuecomment-2122354334)).\nAs a quick workaround, we comment creation of inlined objects out.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereigncloudstack%2Fgx-credential-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsovereigncloudstack%2Fgx-credential-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereigncloudstack%2Fgx-credential-generator/lists"}