From 8f250cd750924985d069cd024cd9211831170f74 Mon Sep 17 00:00:00 2001 From: Miguel Caballer Date: Fri, 22 Jul 2022 12:47:37 +0200 Subject: [PATCH] Fix markdownlint --- CODE_OF_CONDUCT.md | 101 ++++++++++++++++++++------- CONTRIBUTING.md | 64 ++++++++++++----- README.md | 169 +++++++++++++++++++++++++++------------------ 3 files changed, 225 insertions(+), 109 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c6ee2d0a9..ff5aa9d3b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,24 +1,77 @@ -# IM Code of Conduct - -This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate. - -This code of conduct applies to all spaces managed by the IM project. In addition, violations of this code outside these spaces may affect a person's ability to participate within them. - -If you believe someone is violating the code of conduct, we ask that you report it by emailing im@grycap.upv.es. - -* Be friendly and patient. -* Be welcoming. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. -* Be considerate. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language. -* Be respectful. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. -* Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: - * Violent threats or language directed against another person. - * Discriminatory jokes and language. - * Posting sexually explicit or violent material. - * Posting (or threatening to post) other people's personally identifying information ("doxing"). - * Personal insults, especially those using racist or sexist terms. - * Unwelcome sexual attention. - * Advocating for, or encouraging, any of the above behavior. - * Repeated harassment of others. In general, if someone asks you to stop, then stop. -* When we disagree, try to understand why. Disagreements, both social and technical, happen all the time. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes. - -Original text courtesy of the Django project. +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, +body size, disability, ethnicity, sex characteristics, gender identity and +expression, level of experience, education, socio-economic status, nationality, +personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at [im-support](mailto:im@grycap.upv.es). +All complaints will be reviewed and investigated and will result in a response +that is deemed necessary and appropriate to the circumstances. The project team +is obligated to maintain confidentiality with regard to the reporter of an +incident. Further details of specific enforcement policies may be posted +separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at + +[homepage]: + +For answers to common questions about this code of conduct, see +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26bffa771..9d90fd796 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,59 @@ # Contributing -## Introduction +Contributions are welcome, and they are greatly appreciated! +When contributing to this repository, please first discuss the change you wish +to make via issue, email, or any other method with the owners of this +repository before making a change. -Thanks for considering contributing to Infrastructure Manager (IM). -Contributions to IM are welcome. -You can contribute by improving the documentation, submit bug reports, -provide feature requests, or writing code for IM. +Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it +in all your interactions with the project. -## How to report a bug +## Reporting bugs -If you find a security vulnerability, do NOT open an issue. -Email im@grycap.upv.es instead. +Report bugs at + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* If you can, provide detailed steps to reproduce the bug. +* If you don't have steps to reproduce the bug, just note your observations in + as much detail as you can. Questions to start a discussion about the issue + are welcome. + +### Submit Feedback + +The best way to send feedback is to file an issue at the follwing URL: -Other issues and or feature enhancements can be communicated on GitHub -## Code contributions +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +## Pull Request Process + +You are welcome to open Pull Requests for either fixing a bug, adding a new +feature, contributing to the documentation, etc. -* Perform pull requests against the devel or master branch. -* Please check you Python code with using tox: +1. The Pull Request should include tests. +2. For testing we use tox tool, update tox.ini file correspondingly. +3. The Pull Request should work for Python 3.6 and above. +4. Increase the version numbers in any examples files and the README.md to + the new version that this Pull Request would represent. The versioning + scheme we use is [SemVer](http://semver.org/). +5. If the Pull Request adds functionality, the docs should be updated. Put your + new functionality into a function with a docstring + ([Sphinx docstring format](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)), + and add the feature in the appropriate place in sphinx docs (`docs/source` directory). +6. Update the README.md with details of changes to the interface, this includes + new environment variables, exposed ports, useful file locations and container parameters. -```sh -tox -e py3,style -``` +## Coding Standards -* For new features please also provide unit tests. +* PEP8 with line length of 120 characters. +* Write new code in Python 3 +* [Sphinx docstring format](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) \ No newline at end of file diff --git a/README.md b/README.md index 8095e950d..91f680589 100644 --- a/README.md +++ b/README.md @@ -7,31 +7,34 @@ [![License](https://img.shields.io/badge/license-GPL%20v3.0-brightgreen.svg)](LICENSE) [![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://imdocs.readthedocs.io/en/latest/) -IM is a tool that deploys complex and customized virtual infrastructures on IaaS -Cloud deployments (such as AWS, OpenStack, etc.). It eases the access and the -usability of IaaS clouds by automating the VMI (Virtual Machine Image) +IM is a tool that deploys complex and customized virtual infrastructures on +IaaS Cloud deployments (such as AWS, OpenStack, etc.). It eases the access and +the usability of IaaS clouds by automating the VMI (Virtual Machine Image) selection, deployment, configuration, software installation, monitoring and -update of the virtual infrastructure. It supports APIs from a large number of virtual -platforms, making user applications cloud-agnostic. In addition it integrates a -contextualization system to enable the installation and configuration of all the -user required applications providing the user with a fully functional -infrastructure. +update of the virtual infrastructure. It supports APIs from a large number of +virtual platforms, making user applications cloud-agnostic. In addition it +integrates a contextualization system to enable the installation and +configuration of all the user required applications providing the user with a +fully functional infrastructure. Read the documentation and more at . -There is also an Infrastructure Manager YouTube reproduction list with a set of videos with demos -of the functionality of the platform: . +There is also an Infrastructure Manager YouTube reproduction list with a set of +videos with demos of the functionality of the platform: . -Please acknowledge the use of this software in your scientific publications by including the following reference: +Please acknowledge the use of this software in your scientific publications by +including the following reference: Miguel Caballer, Ignacio Blanquer, German Molto, and Carlos de Alfonso. "[Dynamic management of virtual infrastructures](https://link.springer.com/article/10.1007/s10723-014-9296-5)". Journal of Grid Computing, Volume 13, Issue 1, Pages 53-70, 2015, ISSN 1570-7873, DOI: 10.1007/s10723-014-9296-5. ## 1 DOCKER IMAGE (Recommended Option) -The recommended option to use the Infrastructure Manager service is using the available docker image. -A Docker image named `grycap/im` has been created to make easier the deployment of an IM service using the -default configuration. Information about this image can be found here: . -It is also available in Github Container registry `ghcr.io/grycap/im`: . +The recommended option to use the Infrastructure Manager service is using the +available docker image. A Docker image named `grycap/im` has been created to +make easier the deployment of an IM service using the default configuration. +Information about this image can be found here: . +It is also available in Github Container registry `ghcr.io/grycap/im`: +. How to launch the IM service using docker:: @@ -39,13 +42,15 @@ How to launch the IM service using docker:: sudo docker run -d -p 8899:8899 -p 8800:8800 --name im grycap/im ``` -To make the IM data persistent you also have to specify a persistent location for the IM database using the IM_DATA_DB environment variable and adding a volume:: +To make the IM data persistent you also have to specify a persistent location +for the IM database using the IM_DATA_DB environment variable and adding a volume:: ```sh sudo docker run -d -p 8899:8899 -p 8800:8800 -v "/some_local_path/db:/db" -e IM_DATA_DB=/db/inf.dat --name im grycap/im ``` -You can also specify an external MySQL server to store IM data using the IM_DATA_DB environment variable:: +You can also specify an external MySQL server to store IM data using the +IM_DATA_DB environment variable:: ```sh sudo docker run -d -p 8899:8899 -p 8800:8800 -e IM_DATA_DB=mysql://username:password@server/db_name --name im grycap/im @@ -59,7 +64,8 @@ sudo docker run -d -p 8899:8899 -p 8800:8800 -v "/some_local_path/im.cfg:/etc/im ## 2 Kubernetes Helm Chart -The IM service and web interface can be installed on top of [Kubernetes](https://kubernetes.io/) using [Helm](https://helm.sh/). +The IM service and web interface can be installed on top of [Kubernetes](https://kubernetes.io/) +using [Helm](https://helm.sh/). How to install the IM chart: @@ -87,8 +93,8 @@ All the information about this chart is available at the [IM chart README](https ### 3.1 REQUISITES -IM is based on Python, so Python 2.7 or higher (Python 3.6 or higher recommended) runtime and -standard library must be installed in the system. +IM is based on Python, so Python 2.7 or higher (Python 3.6 or higher +recommended) runtime and standard library must be installed in the system. If you use pip to install the IM, all the requisites will be installed. However, if you install IM from sources you should install: @@ -97,21 +103,29 @@ However, if you install IM from sources you should install: as the ``RADL`` package. * The paramiko ssh2 protocol library for python version 1.14 or later -(), typically available as the ``python-paramiko`` package. +(), typically available as the +``python-paramiko`` package. -* The YAML library for Python, typically available as the ``python-yaml`` or ``PyYAML`` package. +* The YAML library for Python, typically available as the ``python-yaml`` or + ``PyYAML`` package. -* The suds library for Python, typically available as the ``python-suds`` package. +* The suds library for Python, typically available as the ``python-suds`` + package. -* The Netaddr library for Python, typically available as the ``python-netaddr`` package. +* The Netaddr library for Python, typically available as the ``python-netaddr`` + package. -* The Requests library for Python, typically available as the ``python-requests`` package. +* The Requests library for Python, typically available as the + ``python-requests`` package. -* TOSCA parser library for Python, available as the ``tosca-parser`` package in pip. +* TOSCA parser library for Python, available as the ``tosca-parser`` package in + pip. -* Ansible () to configure nodes in the infrastructures. +* Ansible () to configure nodes in the + infrastructures. In particular, Ansible 2.4+ must be installed. - To ensure the functionality the following values must be set in the ansible.cfg file (usually found in /etc/ansible/): + To ensure the functionality the following values must be set in the + ansible.cfg file (usually found in /etc/ansible/): ```yml [defaults] @@ -138,51 +152,59 @@ pipelining = True ### 3.2 OPTIONAL PACKAGES The Bottle framework () is used for the REST API. -It is typically available as the ``python-bottle`` system package or ``bottle`` pip package. +It is typically available as the ``python-bottle`` system package or ``bottle`` +pip package. -The CherryPy Web framework (), is needed for the REST API. -It is typically available as the ``python-cherrypy`` or ``python-cherrypy3`` system package -or ``CherryPy`` pip package. -In newer versions (9.0 and later) the functionality has been moved to the ``cheroot`` library -() it can be installed using pip. +The CherryPy Web framework (), is needed for the REST +API. It is typically available as the ``python-cherrypy`` or +``python-cherrypy3`` system package or ``CherryPy`` pip package. +In newer versions (9.0 and later) the functionality has been moved to the +``cheroot`` library () it can be +installed using pip. Apache-libcloud () 3.0 or later is used in the -LibCloud, OpenStack and GCE connectors. It is typically available as the ``python-libcloud`` -system package or ``apache-libcloud`` pip package. +LibCloud, OpenStack and GCE connectors. It is typically available as the +``python-libcloud`` system package or ``apache-libcloud`` pip package. Boto () 2.29.0 or later is used as interface to Amazon EC2. It is available as package named ``python-boto`` in Debian based -distributions or ``boto`` pip package. It can also be downloaded from boto GitHub repository (). +distributions or ``boto`` pip package. It can also be downloaded from boto +GitHub repository (). Download the file and copy the boto subdirectory into the IM install path. -In case of using the a MySQL DB as the backend to store IM data. The Python interface to MySQL -must be installed, typically available as the package ``python-mysqldb`` or ``MySQL-python`` package. -In case of using Python 3 use the PyMySQL package, available as the package ``python3-pymysql`` on +In case of using the a MySQL DB as the backend to store IM data. The Python +interface to MySQL must be installed, typically available as the package +``python-mysqldb`` or ``MySQL-python`` package. In case of using Python 3 use +the PyMySQL package, available as the package ``python3-pymysql`` on debian systems or ``PyMySQL`` package in pip. -In case of using the a MongoDB as the backend to store IM data. The Python interface to MongoDB -must be installed, typically available as the package ``python-pymongo``package in most distributions -or ``pymongo`` pip package. +In case of using the a MongoDB as the backend to store IM data. The Python +interface to MongoDB must be installed, typically available as the package +``python-pymongo``package in most distributions or ``pymongo`` pip package. -In case of using the SSL secured version of the REST API pyOpenSSL () must be installed. -available as ``pyOpenSSL`` package in pip. +In case of using the SSL secured version of the REST API pyOpenSSL +() must be installed. available as ``pyOpenSSL`` +package in pip. -Azure python SDK () is used to connect with the -Microsoft Azure platform. The easiest way is to install all the required packages with pip: +Azure python SDK () is used +to connect with the Microsoft Azure platform. The easiest way is to install all +the required packages with pip: ```sh pip install msrest msrestazure azure-common azure-mgmt-storage azure-mgmt-compute azure-mgmt-network azure-mgmt-resource azure-mgmt-dns azure-identity ``` -The VMware vSphere API Python Bindings () are needed by the vSphere -connector. It is available as the package ``pyvmomi`` at the pip repository. +The VMware vSphere API Python Bindings () +are needed by the vSphere connector. It is available as the package ``pyvmomi`` +at the pip repository. ### 3.3 INSTALLING #### 3.3.1 From PIP -First you need to install pip tool and some packages needed to compile some of the IM requirements. -To install them in Debian and Ubuntu based distributions, do:: +First you need to install pip tool and some packages needed to compile some of +the IM requirements. To install them in Debian and Ubuntu based distributions, +do:: ```sh apt update @@ -197,7 +219,8 @@ yum install -y epel-release yum install -y which gcc python3-devel libffi-devel openssl-devel python3-pip sshpass ``` -Then you only have to call the install command of the pip tool with the IM package: +Then you only have to call the install command of the pip tool with the IM +package: ```sh pip3 install IM @@ -209,12 +232,13 @@ You can also install an specific branch of the Github repository: pip install git+https://github.com/grycap/im.git@master ``` -Pip will also install the, non installed, pre-requisites needed. So Ansible 2.4 or later will -be installed in the system. Some of the optional packages are also installed please check if some -of IM features that you need requires to install some of the packages of section OPTIONAL PACKAGES. +Pip will also install the, non installed, pre-requisites needed. So Ansible 2.4 +or later will be installed in the system. Some of the optional packages are +also installed please check if some of IM features that you need requires to +install some of the packages of section OPTIONAL PACKAGES. -You must also remember to modify the ansible.cfg file setting as specified in the -REQUISITES section. +You must also remember to modify the ansible.cfg file setting as specified in +the REQUISITES section. ### 3.4 START IM ON BOOT @@ -250,29 +274,35 @@ ln -s /etc/init.d/im /etc/rc6.d/K05im ``` Adjust the installation path by setting the IMDAEMON variable at /etc/init.d/im -to the path where the IM im_service.py file is installed (e.g. /usr/local/im/im_service.py), -or set the name of the script file (im_service.py) if the file is in the PATH -(pip puts the im_service.py file in the PATH as default). +to the path where the IM im_service.py file is installed (e.g. +/usr/local/im/im_service.py), or set the name of the script file +(im_service.py) if the file is in the PATH (pip puts the im_service.py file in +the PATH as default). ### 4 CONFIGURATION Check the parameters in $IM_PATH/etc/im.cfg or /etc/im/im.cfg. -See [IM Manual](https://imdocs.readthedocs.io/en/latest/manual.html#configuration) to get a full -reference of the configuration variables. +See [IM Manual](https://imdocs.readthedocs.io/en/latest/manual.html#configuration) +to get a full reference of the configuration variables. -Please pay attention to the next configuration variables, as they are the most important: +Please pay attention to the next configuration variables, as they are the most +important: DATA_DB - must be set to the URL to access the database to store the IM data. - Be careful if you have two different instances of the IM service running in the same machine!!. + Be careful if you have two different instances of the IM service + running in the same machine!!. It can be a MySQL DB: `mysql://username:password@server/db_name`, - SQLite: `sqlite:///etc/im/inf.dat` or MongoDB: `mongodb://username:password@server/db_name`, + SQLite: `sqlite:///etc/im/inf.dat` or MongoDB: + `mongodb://username:password@server/db_name`, #### 4.1 SECURITY -Security is disabled by default. Please notice that someone with local network access can "sniff" the traffic and -get the messages with the IM with the authorisation data with the cloud providers. +Security is disabled by default. Please notice that someone with local network +access can "sniff" the traffic and get the messages with the IM with the +authorisation data with the cloud providers. -Security can be activated both in the XMLRPC and REST APIs. Setting this variables: +Security can be activated both in the XMLRPC and REST APIs. Setting this +variables: ```sh XMLRCP_SSL = True @@ -284,4 +314,5 @@ or REST_SSL = True ``` -And then set the variables: XMLRCP_SSL_* or REST_SSL_* to your certificates paths. +And then set the variables: XMLRCP_SSL_* or REST_SSL_* to your certificates +paths.