From 7b8193d3bfe0a584b2f784e4b9edf2352610a9a1 Mon Sep 17 00:00:00 2001 From: Marco Donadoni Date: Wed, 7 Feb 2024 17:36:39 +0100 Subject: [PATCH] refactor(docs): move from reST to Markdown (#15) Convert docs from reStructuredText to Markdown so that the changelog file is compatible with Release Please. --- AUTHORS.md | 8 ++++++ AUTHORS.rst | 9 ------ README.md | 65 ++++++++++++++++++++++++++++++++++++++++++ README.rst | 81 ----------------------------------------------------- 4 files changed, 73 insertions(+), 90 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst create mode 100644 README.md delete mode 100644 README.rst diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..32718d3 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,8 @@ +# Authors + +The list of contributors in alphabetical order: + +- [Audrius Mecionis](https://orcid.org/0000-0002-3759-1663) +- [Diego Rodriguez](https://orcid.org/0000-0003-0649-2002) +- [Marco Donadoni](https://orcid.org/0000-0003-2922-5505) +- [Tibor Simko](https://orcid.org/0000-0001-7202-5803) diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index bc44762..0000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,9 +0,0 @@ -Authors -======= - -The list of contributors in alphabetical order: - -- `Audrius Mecionis `_ -- `Diego Rodriguez `_ -- `Marco Donadoni `_ -- `Tibor Simko `_ diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d3ad3d --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# REANA Authentication Kerberos5 + +[![image](https://github.com/reanahub/reana-auth-krb5/workflows/CI/badge.svg)](https://github.com/reanahub/reana-auth-krb5/actions) +[![image](https://img.shields.io/badge/discourse-forum-blue.svg)](https://forum.reana.io) +[![image](https://img.shields.io/github/license/reanahub/reana-auth-krb5.svg)](https://github.com/reanahub/reana-auth-krb5/blob/master/LICENSE) + +## About + +`reana-auth-krb5` provides a container image for creating and renewing Kerberos tokens. +The container image includes no additional logic or libraries, just the bare minimum to +support the Kerberos operations. + +`reana-auth-krb5` was developed for use in the [REANA](http://www.reana.io/) reusable +research data analysis platform. + +## Usage + +The `reana-auth-krb5` image is used internally in the REANA platform to refres the +Kerberos token for long running jobs. The end users can ask for Kubernetes authentication +by means of declaring `kerberos: true`, more information +[here](http://docs.reana.io/advanced-usage/access-control/kerberos/). + +If you want to try it locally, a Kerberos token can be obtained via: + +``` +$ docker run -i -t --rm docker.io/reanahub/reana-auth-krb5:1.0.1 /bin/bash +> kinit -k -t /path/to/keytab_file username@CERN.CH +> klist +``` + +## Configuration + +Running the `reana-auth-krb5` and successfully obtaining a shared token on a sidecar +container requires additional information and inputs: + +- [Kerberos cache](https://web.mit.edu/kerberos/krb5-1.12/doc/basic/ccache_def.html) + location to be shared, configured through the `KRB5CCNAME` environment variable +- [Kerberos configuration](https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html) + at `/etc/krb5.conf` (overridable) + +## Changes + +Version 1.0.1 (2020-08-12) + +- Add CERN Kerberos configuration. + +Version 1.0.0 (2020-08-05) + +- Initial release + +## Development + +If you would like to contribute to `reana-auth-krb5` development, you can take advantage +of the provided `Makefile`: + +``` +$ make build # build a new version of the container image +$ make test # test the built image +$ make push # push it to Docker Hub +``` + +## More information + +For more information about [REANA](http://www.reana.io/) reusable research data analysis +platform, please see [its documentation](http://docs.reana.io/). diff --git a/README.rst b/README.rst deleted file mode 100644 index 38cf9aa..0000000 --- a/README.rst +++ /dev/null @@ -1,81 +0,0 @@ -============================== -REANA Authentication Kerberos5 -============================== - -.. image:: https://github.com/reanahub/reana-auth-krb5/workflows/CI/badge.svg - :target: https://github.com/reanahub/reana-auth-krb5/actions - -.. image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/reanahub/reana?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - -.. image:: https://img.shields.io/github/license/reanahub/reana-auth-krb5.svg - :target: https://github.com/reanahub/reana-auth-krb5/blob/master/LICENSE - -About -===== - -``reana-auth-krb5`` provides a container image for creating and -renewing Kerberos tokens. The container image includes no additional -logic or libraries, just the bare minimum to support the Kerberos -operations. - -``reana-auth-krb5`` was developed for use in the `REANA -`_ reusable research data analysis platform. - -Usage -===== - -The ``reana-auth-krb5`` image is used internally in the REANA platform -to refres the Kerberos token for long running jobs. The end users can -ask for Kubernetes authentication by means of declaring ``kerberos: -true``, more information `here -`_. - -If you want to try it locally, a Kerberos token can be obtained via:: - - $ docker run -i -t --rm docker.io/reanahub/reana-auth-krb5:1.0.1 /bin/bash - > kinit -k -t /path/to/keytab_file username@CERN.CH - > klist - -Configuration -============= - -Running the ``reana-auth-krb5`` and successfully obtaining a shared -token on a sidecar container requires additional information and -inputs: - -- `Kerberos cache - `_ - location to be shared, configured through the ``KRB5CCNAME`` - environment variable -- `Kerberos configuration - `_ - at ``/etc/krb5.conf`` (overridable) - -Changes -======= - -Version 1.0.1 (2020-08-12) - -- Add CERN Kerberos configuration. - -Version 1.0.0 (2020-08-05) - -- Initial release - -Development -=========== - -If you would like to contribute to ``reana-auth-krb5`` development, -you can take advantage of the provided ``Makefile``:: - - $ make build # build a new version of the container image - $ make test # test the built image - $ make push # push it to Docker Hub - -More information -================ - -For more information about `REANA `_ reusable research data -analysis platform, please see `its documentation -`_.