Metadata-Version: 2.1
Name: fedcloudclient
Version: 0.0.0
Summary: EGI FedCloud client
Home-page: https://fedcloudclient.fedcloud.eu/
Author: Viet Tran, Enol Fernandez
Author-email: tdviet@gmail.com
License: UNKNOWN
Description: # FedCloud client: Command-line client and library for EGI Federated Cloud
        
        [![DOI](https://zenodo.org/badge/336671726.svg)](https://zenodo.org/badge/latestdoi/336671726)
        
        
        **fedcloudclient** is a command-line client and high-level Python package for
        interaction with EGI Federated Cloud. This package is an extension of the
        [egicli](https://github.com/EGI-Foundation/egicli) for OpenStack commands.
        
        The aim here was to create a simple client which would allow users to perform
        the various OpenStack operations in EGI Federated Cloud. Four modules are
        included: **fedcloudclient.checkin** for operation with EGI Check-in like
        getting tokens, **fedcloudclient.endpoint** for searching endpoints via GOCDB,
        getting unscoped/scoped token from Keystone, **fedcloudclient.sites** manages
        site configuration and finally **fedcloudclient.openstack** for performing
        OpenStack operations.
        
        A short presentation of the fedcloudclient is available at
        [Tutorial](https://docs.google.com/presentation/d/1aOdcceztXe8kZaIeVnioF9B0vIHLzJeklSNOdVCL3Rw/edit?usp=sharing).
        
        The full documentation, including installation, usage and API description is
        available at [https://fedcloudclient.fedcloud.eu/](https://fedcloudclient.fedcloud.eu/).
        
        ## Quick start
        
        - Install FedCloud client via `pip`:
        
          ```shell
          pip3 install fedcloudclient
          ```
        
          or use Docker container:
        
          ```shell
          docker run -it  tdviet/fedcloudclient bash
          ```
        
        - Get a new access token from EGI Check-in according to instructions from
          FedCloud [Check-in client](https://aai.egi.eu/fedcloud/), or from
          [oidc-agent](https://indigo-dc.gitbook.io/oidc-agent/user/oidc-gen/provider/egi)
          and set environment variable.
        
          ```shell
          export OIDC_ACCESS_TOKEN=<ACCESS_TOKEN>
          ```
        
        - Check the expiration time of the access token using `fedcloud` command:
        
          ```shell
          fedcloud token check
          ```
        
        - List the VO memberships of the access token:
        
          ```shell
          fedcloud token list-vos
          ```
        
        - List the OpenStack sites available in EGI Federated Cloud. That may take few
          seconds because all site configurations are retrieved from
          [GitHub repository](https://github.com/EGI-Foundation/fedcloud-catchall-operations/tree/master/sites)
        
          ```shell
          fedcloud site list
          ```
        
        - Save the site configuration to local machine at
          `\~/.config/fedcloud/site-config/` to speed up the client's start in the next
          time:
        
          ```shell
          fedcloud site save-config
          ```
        
        - Execute an OpenStack command, e.g. list images in fedcloud.egi.eu VO on
          CYFRONET-CLOUD site (or other combination of site and VO you have access):
        
          ```shell
          fedcloud openstack image list --site CYFRONET-CLOUD --vo fedcloud.egi.eu
          ```
        
        - Execute an OpenStack command on all sites, e.g. list VMs in eosc-synergy.eu VO
          on all OpenStack sites in EGI Federated Cloud
        
          ```shell
          fedcloud openstack server list --site ALL_SITES --vo eosc-synergy.eu
          ```
        
        - Learn more commands of `fedcloud` client and experiment with them:
        
          ```shell
          fedcloud --help
          fedcloud site --help
          ```
        
        - Read the
          [Quick start](https://docs.google.com/presentation/d/1aOdcceztXe8kZaIeVnioF9B0vIHLzJeklSNOdVCL3Rw/edit?usp=sharing)
          for more information about customizations and advanced usages.
        
        ## Using fedcloudclient as development library
        
        All functionalities offered by the _fedcloud_ client can be used as a library
        for development of other tools and services for EGI Federated Cloud. For
        example, performing openstack command as a function in Python:
        
        ```python
        
        from fedcloudclient.openstack import fedcloud_openstack
        ....
        error_code, result = fedcloud_openstack(oidc_access_token,
                                                site,
                                                vo,
                                                openstack_command)
        ```
        
        See a working example
        [_"demo.py"_](https://github.com/tdviet/fedcloudclient/blob/master/examples/demo.py).
        The documentation of fedcloudclient API is available at
        [https://fedcloudclient.fedcloud.eu/](https://fedcloudclient.fedcloud.eu/).
        
        ## FAQ
        
        1. The `fedcloud` client is slow.
        
           Execute command `fedcloud site save-config` to download site configurations
           from
           [GitHub repository](https://github.com/EGI-Foundation/fedcloud-catchall-operations/tree/master/sites)
           and save them on a local machine. That will significantly speedup site
           configurations loading.
        
           Some sites in the repository may not respond, and client has to wait for long
           time before report "Connection time out". You can remove the sites from your
           local repository to speed-up all-sites operations
        
           `libsodium` which is used by `oidc-agent` Python library may be frozen at
           initialization on VMs with low entropy. The problem is described
           [here](https://doc.libsodium.org/usage#sodium_init-stalling-on-linux). Check
           the entropy on the VMs by executing command
           `cat /proc/sys/kernel/random/entropy_avail`, and if the result is lower than
           300, consider installing `haveged` or `rng-tools` to increase entropy. On VMs
           with CentOS, you also have to start the daemon manually after installation
           (or reboot the VMs)
        
        1. The `fedcloud` client fails with error message
           `SSL exception connecting to <https://> ...` when attempts to interact with
           some sites.
        
           Some sites use certificates issued by national grid CAs that are not included
           in default distribution, so `fedcloud` client cannot verify them. Follow this
           [instruction](https://github.com/tdviet/python-requests-bundle-certs/blob/main/docs/Install_certificates.md)
           to install
           [EGI Core Trust Anchor](http://repository.egi.eu/category/production/cas/)
           and add certificates to Python request certificate bundle.
        
           In the case of using virtual environment for quick test, you can download and
           import bundle certificates by using the script from
           [this repository](https://github.com/tdviet/python-requests-bundle-certs)
        
        1. The `fedcloud` client fails with error message
           `"VO XX not found on site YY"`, but they do exist.
        
           Site configurations at
           [GitHub repository](https://github.com/EGI-Foundation/fedcloud-catchall-operations/tree/master/sites)
           may be incomplete. Check the site configurations stored in
           `~/.config/fedcloud/site-config/` if the VOs are included. If not, you can
           ask site admins to fix site configuration. You can also execute
           `fedcloud endpoint projects --site SITE --oidc-access-token ACCESS_TOKEN` to
           find project IDs of the VOs on the site and add the VOs to local site
           configuration on your machine manually.
        
        1. I would like to add supports for additional sites/VOs/identity providers that
           are not parts of EGI Federated Cloud.
        
           Other identity providers may be specified via option `--oidc-url` or
           environment variable `CHECKIN_OIDC_URL`. Additional sites and VOs may be
           added to local site configuration files.
        
        1. Why there are so many options for authentication: access token, refresh
           token, and oidc-agent? Which one should be used?
        
           Cloud operations need only access tokens, not refresh tokens. Access tokens
           have short lifetime (one hour in EGI Check-in), so they have lower security
           constraints. However, they have to be refreshed frequently, that may be
           inconvenient for some users.
        
           If a refresh token is given as parameter to `fedcloud` client (together with
           client ID and client secret), an access token will be generated on the fly
           from the refresh token and client ID/secret. However, using unencrypted
           refresh tokens is considered as insecure and will be removed in future
           versions in favor of oidc-agent.
        
           [oidc-agent](https://indigo-dc.gitbook.io/oidc-agent/) stores the refresh
           token securely and will automatically generate a new access token when the
           current one expires, so that is the recommended way to provide access token
           to fedcloudclient
        
        
Platform: UNKNOWN
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: OpenStack
Description-Content-Type: text/markdown
