Skip to content

Commit

Permalink
Merge pull request #191 from tdviet/2.0-alpha1-docs-config
Browse files Browse the repository at this point in the history 
Update docs for config module
  • Loading branch information
@tdviet
tdviet authored Nov 9, 2023
2 parents 9c18eeb + 1b20d71 commit e825543
Show file tree
Hide file tree
Showing 3 changed files with 141 additions and 34 deletions.
6 changes: 3 additions & 3 deletions docs/cheat.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,9 +234,9 @@ Useful commands
FEDCLOUD_MYTOKEN=<mytoken> # created on https://mytoken.data.kit.edu/

# Pass it to OpenStack
EGI_SITE=IISAS-FedCloud
EGI_VO=vo.access.egi.eu
fedcloud openstack server create --site $EGI_SITE --flavor <flavor> --image <image> --user-data user.txt --key-name <keypair> testvm
FEDCLOUD_SITE=IISAS-FedCloud
FEDCLOUD_VO=vo.access.egi.eu
fedcloud openstack server create --flavor <flavor> --image <image> --user-data user.txt --key-name <keypair> testvm

# Once you log into the VM you can retrieve the "mytoken" with
curl http://169.254.169.254/openstack/latest/user_data/
Expand Down
4 changes: 3 additions & 1 deletion docs/intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,9 @@ The most notable features of FedCloud client are following:
or as a `Python library <https://fedcloudclient.fedcloud.eu/development.html>`_
for programming FedCloud services.

Six modules are included:
The following modules are included:

* **fedcloudclient.conf** for handling fedcloudclient configuration,

* **fedcloudclient.checkin** for operation with EGI Check-in like getting tokens,

Expand Down
165 changes: 135 additions & 30 deletions docs/usage.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
Usage
=====

**FedCloud client** has six main groups of commands:
**FedCloud client** has the following main groups of commands:

* **"fedcloud config"** for handling fedcloudclient configuration,

* **"fedcloud token"** for interactions with EGI Check-in and access tokens,

Expand All @@ -11,7 +13,7 @@ Usage

* **"fedcloud openstack"** or **"fedcloud openstack-int"** for performing OpenStack commands on sites,

* **fedcloud secret** for accessing secrets in
* **"fedcloud secret"** for accessing secrets in
`Secret management service <https://vault.docs.fedcloud.eu/index.html>`_,

* **"fedcloud ec3"** as helper commands for deploying EC3.
Expand All @@ -33,36 +35,139 @@ remember to check *"Allows obtaining OpenID Connect Access Tokens"*, and use the
to pass it to *FedCloud client"*. Environment variables can be use instead of the command-line options,
as explained in the table below.

The default protocol is *"openid"*. Users can change default protocol via option *"--openstack-auth-protocol"*. However,
The default protocol is *"openid"*. Users can change default protocol via option *"--os-protocol"*. However,
sites may have protocol fixedly defined in site configuration, e.g. *"oidc"* for INFN-CLOUD-BARI.

Environment variables
*********************

Most of fedcloud options, including options for tokens can be set via environment variables:

+-----------------------------+---------------------------------+------------------------------------+
| Environment variables | Command-line options | Default value |
+=============================+=================================+====================================+
| OIDC_AGENT_ACCOUNT | --oidc-agent-account | |
+-----------------------------+---------------------------------+------------------------------------+
| OIDC_ACCESS_TOKEN | --oidc-access-token | |
+-----------------------------+---------------------------------+------------------------------------+
| FEDCLOUD_MYTOKEN_SERVER | --mytoken-server | https://mytoken.data.kit.edu |
+-----------------------------+---------------------------------+------------------------------------+
| FEDCLOUD_MYTOKEN | --mytoken | |
+-----------------------------+---------------------------------+------------------------------------+
| OPENSTACK_AUTH_PROTOCOL | --openstack-auth-protocol | openid |
+-----------------------------+---------------------------------+------------------------------------+
| OPENSTACK_AUTH_PROVIDER | --openstack-auth-provider | egi.eu |
+-----------------------------+---------------------------------+------------------------------------+
| OPENSTACK_AUTH_TYPE | --openstack-auth-type | v3oidcaccesstoken |
+-----------------------------+---------------------------------+------------------------------------+
| EGI_VO | --vo | |
+-----------------------------+---------------------------------+------------------------------------+

For convenience, always set the frequently used options like tokens via environment variables, that can save a lot of
time.

Configuration
*************

Display the current configuration of *fedcloud* with:

::

$ fedcloud config show

This will show a list of configuration parameters:

+----------------------------+------------------------------------------------------------------------------------+
| Parameter | Default value |
+============================+====================================================================================+
| site | IISAS-FedCloud |
+----------------------------+------------------------------------------------------------------------------------+
| vo | vo.access.egi.eu |
+----------------------------+------------------------------------------------------------------------------------+
| site_list_url | https://raw.githubusercontent.com/tdviet/fedcloudclient/master/config/sites.yaml |
+----------------------------+------------------------------------------------------------------------------------+
| site_dir | ${HOME}/.config/fedcloud/site-config |
+----------------------------+------------------------------------------------------------------------------------+
| oidc_url | https://aai.egi.eu/auth/realms/egi |
+----------------------------+------------------------------------------------------------------------------------+
| gocdb_public_url | https://goc.egi.eu/gocdbpi/public/ |
+----------------------------+------------------------------------------------------------------------------------+
| gocdb_service_group | org.openstack.nova |
+----------------------------+------------------------------------------------------------------------------------+
| vault_endpoint | https://vault.services.fedcloud.eu:8200 |
+----------------------------+------------------------------------------------------------------------------------+
| vault_role | |
+----------------------------+------------------------------------------------------------------------------------+
| vault_mount_point | /secrets/ |
+----------------------------+------------------------------------------------------------------------------------+
| vault_locker_mount_point | /v1/cubbyhole/ |
+----------------------------+------------------------------------------------------------------------------------+
| vault_salt | fedcloud_salt |
+----------------------------+------------------------------------------------------------------------------------+
| log_file | ${HOME}/.config/fedcloud/logs/fedcloud.log |
+----------------------------+------------------------------------------------------------------------------------+
| log_level | DEBUG |
+----------------------------+------------------------------------------------------------------------------------+
| log_config_file | ${HOME}/.config/fedcloud/logging.conf |
+----------------------------+------------------------------------------------------------------------------------+
| requests_cert_file | ${HOME}/.config/fedcloud/cert/certs.pem |
+----------------------------+------------------------------------------------------------------------------------+
| oidc_agent_account | egi |
+----------------------------+------------------------------------------------------------------------------------+
| min_access_token_time | 30 |
+----------------------------+------------------------------------------------------------------------------------+
| mytoken_server | https://mytoken.data.kit.edu |
+----------------------------+------------------------------------------------------------------------------------+
| os_protocol | openid |
+----------------------------+------------------------------------------------------------------------------------+
| os_auth_type | v3oidcaccesstoken |
+----------------------------+------------------------------------------------------------------------------------+
| os_identity_provider | egi.eu |
+----------------------------+------------------------------------------------------------------------------------+

The *fedcloud* configuration can be saved to a file with:

::

$ fedcloud config create

By default the configuration file is saved to **${HOME}/.config/fedcloud/config.yaml**
but this can be changed:

::

$ fedcloud config create --config-file /path/to/file.yaml

It is also possible to use the *FEDCLOUD_CONFIG_FILE* environment variable instead
of the *--config-file* option in the command line. This way users may save and load
multiple configuration files, one per project, with its own configuraion.

*fedcloud* parameters can be configured using:

#. comand-line options (highest priority); e.g.: *--site*

#. environment variables starting with the prefix *FEDCLOUD_*;
e.g.: *FEDCLOUD_SITE*.

#. configuration file; e.g. *site* in *config.yaml*

#. default configuration (lowest priority), `harcoded <../fedcloudclient/conf.py#L16>`_.

The order is important: the default configuration is overwritten by the
configuration file, and this is overwritten by values stored in environment
variables, and this is overwritten by values in the command-line. For example,
the default configuration comes with *site = IISAS-FedCloud* and
*vo = vo.access.egi.eu*. This can be changed with:

::

$ fedcloud openstack --vo training.egi.eu --site IFCA-LCG2 server list

or

::

$ export FEDCLOUD_VO=training.egi.eu
$ export FEDCLOUD_SITE=IFCA-LCG2
$ fedcloud openstack server list

Note the nomenclature referring to the same parameter:

* *--oidc-agent-account* in the command-line

* *FEDCLOUD_OIDC_AGENT_ACCOUNT* as environment variable

* *oidc_agent_account* in the configuration file

They all refer to the same. All configuration parameters follow this
consistent approach.

Additional parameters can also be configured:

+------------------------------+-----------------------+
| Environment variable | Command-line option |
+==============================+=======================+
| FEDCLOUD_OIDC_ACCESS_TOKEN | --oidc-access-token |
+------------------------------+-----------------------+
| FEDCLOUD_MYTOKEN | --mytoken |
+------------------------------+-----------------------+

For convenience, always set transient parameters like tokens via
environment variables, as it simplifies the call to *fedcloud*.


Shell completion
****************
Expand Down

0 comments on commit e825543

Please sign in to comment.