Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs for config module #191

Merged
merged 11 commits into from
Nov 9, 2023
Merged

Update docs for config module #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
c3d4944
document conf
sebastian-luna-valero Nov 9, 2023
9ff9c31
double quotes
sebastian-luna-valero Nov 9, 2023
252ab80
Merge branch '2.0-alpha1' into 2.0-alpha1-docs-config
sebastian-luna-valero Nov 9, 2023
87f9ed7
openstack_auth_type no longer there
sebastian-luna-valero Nov 9, 2023
9645bba
ordered list
sebastian-luna-valero Nov 9, 2023
c92585c
better phrasing
sebastian-luna-valero Nov 9, 2023
a8d2f84
better phrasing
sebastian-luna-valero Nov 9, 2023
764833f
better phrasing
sebastian-luna-valero Nov 9, 2023
a2c75d1
link to hardcoded default config
sebastian-luna-valero Nov 9, 2023
6581acd
link to hardcoded default config
sebastian-luna-valero Nov 9, 2023
1b20d71
update Cheat sheet accordingly
sebastian-luna-valero Nov 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/cheat.rst
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading